MQTT
SIP

SIP

⚠️
NOTE: This part of the API is still under construction, yet the interface as described below is expected to be somewhat stable.

Livy devices run a SIP (telephony) client. Other SIP clients connected to the same IP-PBX (SIP server, e.g., Asterisk) can make calls to a given Livy.
Livy supports two-way audio as well as video streams.

The SIP client on the device must be configured so that it can connect to the SIP server.

The SIP client uses TLS exclusively to communicate with the server, as well as SRTP to encrypt the media channels.
Unencrypted traffic is not supported.

Set SIP Config

Topic

Publish to: api_client/<client_name>/<location_id>/<device_id>/sip/set

Payload 

{
  "registrar": "registrar.example-org.com",
  "registrar_port": 5061,
  "client_id": "79001@sip.example-org.com",
  "username": "79001",
  "password": "s3cr3t",
  "speaker_volume": 75,
  "mic_volume": 70
}
  • registrar: domain or IP address of the IP-PBX (SIP server) with which the Livy should register
  • registrar_port: the port on which the IP-PBX listens for client registrations
  • client_id: the SIP client ID to be used by this device in the format <extension>@<host> (host can be a URI or an IP address)
  • username: the username to be used during registration (it often is the same as the extension, but may differ)
  • password: the password used to authenticate during registration
  • mic_volume: controls the volume of the Livy’s microphone (capture), in percent, i.e. 0 = 0% (silent), 75 = 75%, 100 = 100% (max)
  • speaker_volume: controls the volume of the Livy’s speaker (playback), in percent, i.e. 0 = 0% (muted), 75 = 75%, 100 = 100% (max)

Note: speaker_volume only applies to the SIP client itself. There is a global (OS-level) volume control for the entire Livy. If it is set to 0, this will supersede the SIP client speaker_volume setting.

Once the device has received the new config, it will send it back to the client on the api_client/<client_name>/<location_id>/<device_id>/sip topic.
This can be used as an acknowledgment after writing.

Get SIP config

Topic

Publish to: api_client/<client_name>/<location_id>/<device_id>/sip/get
Subscribe to: api_client/<client_name>/<location_id>/<device_id>/sip

Payload

Publish with an empty payload.

Response

Not retained
QoS: 1

The device will respond with the current SIP configuration in the same format as in Set SIP Config.

Supported Codecs

Audio

The following audio codecs are supported with given priority (higher number = higher priority). If the device is given multiple supported codecs in the SDP offer, it chooses the one with the highest priority.

# primary
opus/48000/2 priority=254
speex/32000/1 priority=253
speex/16000/1 priority=252
PCMA/8000/1 priority=251
PCMU/8000/1 priority=250
speex/8000/1 priority=249

# secondary
GSM/8000/1 priority=128
G722/16000/1 priority=128
G7221/16000/1 priority=128
G7221/16000/1 priority=128
G7221/32000/1 priority=128
G7221/32000/1 priority=128
G7221/32000/1 priority=128
iLBC/8000/1 priority=128

Video

The following video codecs are supported.

H264/90000 baseline profile
NetworkSound Classification