Intona products are engineered and made in Germany. We ship daily worldwide.

IN3035UG: DPLMX ISAAC API

 

UDP Network API

Introduction

The device can be configured over network. It exchanges commands and responses as JSON objects in UDP packets. The main intention is that this is used as API by control programs, although you can also send and receive raw commands manually.

Each UDP packet contains one or multiple commands as JSON objects, formatted as single line of text. These UDP packets are sent to port 7054. The device will respond with an UDP packet containing JSON object, sent back to the sender's IP, MAC and UDP port.

Here is an example:

User => Device
{"command": "set_params", "api_version": 6, "seq": 123, "dsp": {"mute": true}}
Device reply
{"seq": 123}

Here the "set_params" command is used to mute audio output. The reply indicates success, because it does not contain an "error" field. The "seq" field is for free use by the sender (but must be a JSON number), and will be sent back with the reply. It can be used to associate responses with commands.

Erroneous requests (including JSON syntax errors etc.) will result in a response with the "error" field set.

Getting started

This section shows how to initialize the device and how to start audio streaming.

Finding the device on the network

Unless configured otherwise, each device uses an automatically assigned link-local IP address (RFC 3927). Addresses start at 169.254.1.0, but are generally unpredictable and unstable. For example, if a device is restarted, it may pick a different address. Usually, it will attempt to reuse the previous address, but you cannot rely on this. (You could use the set_params command to assign a static address to a device to avoid this.)

You should perform device discovery by sending device_info commands to the broadcast address (169.254.255.255). These commands can be sent periodically to provide live updates on settings, and whether the device is still up. To avoid overloading the device, an update period of no shorter than 500 ms is recommended. This is especially important if several clients are on the network.

Use the device_id field (queried with device_info) as unique, stable device identifier.

Sending and receiving commands (via CLI on Linux/macOS/msys)

Since the protocol simply sends and receives UDP packets containing JSON text, you can send and receive commands with common open source tools:

rlwrap -S '> ' nc -u 169.254.1.0 7054 | jq

nc sends and receives UDP packets (as text in this case), rlwrap provides line editing and a history, and jq pretty prints JSON responses.

Setting up audio streaming (via CLI)

The device supports SAP (Session Announcement Protocol, RFC 2974) AES67 session discovery. Passive discovery is always active. The device does by default not play any audio from network. The DPLMX network API can be used to play a specific stream.

All important settings and information can be queried with:

User => Device
{"command": "device_info"}

Which results in this reply (only AES67 relevant parts shown):

Device reply
{
  ...
  "stream": {
    "name": "BKLYN-II-0d0c9a : 31",
    "link_offset": 48,
    "nominal_level_dbu": 0,
    "ch0": 0
  },
  "streams": {
    "list": [
      {
        "n": "BKLYN-II-0d0c9a : 31",
        "i": "1 channels: Analog R",
        "c": 1
      },
      ...
    ]
  },
  "rtp": {
    "lock": 3
  },
  ...
}

This example run returned two AES67 sessions. The device is streaming the first one (according to the stream.name field).

A specific session can be selected with:

User => device
{"command": "set_params", "stream": {"name": "BKLYN-II-0d0c9a : 32"}}

The set_params command has a large number of parameters, which can be used to control every detail about the device. The stream.name parameter controls which session should be selected. Internally, the name is matched against the internal list of sessions, and the first matching session is selected. By default, the name is empty, and no session matches.

The streaming status is indicated by the rtp.lock field.

Using this command persists all set parameters to the device flash memory (see section below).

Persistence and reboots

Most device settings are persistent. They are written to flash memory. After boot, the settings are restored from flash. There is a delay of about 1 second before the device starts writing the changed settings to the flash. This delay counts since the most recent change. For this reason, the device should not be power cycled immediately after a change. (The device should survive power cycles at any possible moment, but recently changed settings will not be restored.)

It can take a while until a rebooted device recovers and streams audio. The following processes incur additional delays:

The processes listed above happen in parallel. For network API access, the device needs to negotiating a link layer IP address, which takes about about 7 seconds on average. If static IP configuration is used, the API is available as soon as the network link is up.

Firmware updates require a reboot. Firmware updates can reset all or some settings. Never apply firmware updates in a production setting.

AES67 support

The device follows the AES67 standard. The following design choices were made:

Firmware updates

The device runs a TFTP server for firmware updates. It accepts firmware binaries under the name "firmware.bin". All other files are rejected. Update can be done with any TFTP client, for example curl:

curl -T path/to/firmware.bin tftp://169.254.1.0

 

UDP API protocol definition and reference

Basics

Network layer

The protocol uses JSON encoded in UTF-8 text, encapsulated in UDP. Each UDP packet payload contains exactly 1 JSON object (a list of fields enclosed with "{" and "}"). A JSON object cannot span multiple UDP packets. A JSON object represents a single command. The convention is to add a trailing newline character ("\n", ASCII 0x0A) at the end of the JSON text.

UDP packets are exchanged between devices and API clients. Clients send commands as UDP packets to port 7054. The device will attempt to send a response packet back to the client immediately, using the command packet's source IP/port as destination IP/port for the response packet.

The device does not support receiving fragmented IP packets. All commands are assumed to fit within 1472 bytes of UDP payload. On the other hand, responses by the device may be sent as fragmented UDP packets if they exceed the MTU.

A MTU of 1500 bytes is assumed.

Be aware that UDP is an unreliable protocol. Packet loss and reordering is possible. The device sends exactly one response for each request, and this response could get dropped by the network. If you do not receive any response, you cannot know whether the request or response was dropped (or whether the device went offline). You may have to repeat the request until you get a response (assuming the command is idempotent - most are). Since the network has to reliably transport AES67 streams, it is assumed that everything operates with some headroom below the maximum possible network bandwidth, and packet dropping does not actually happen in practice.

JSON

JSON, as used by the DPLMX network protocol, is specified by RFC 8259 and RFC 7493. The protocol requires that all top-level JSON values are JSON objects, and that each UDP packet contains a single JSON object. In particular, it is assumed that JSON numbers use double floats (binary64 in IEEE 754-2008), which limits their integer precision to about 53 bits (see RFC 7493 section 2.2 for details).

The command reference will use the term "integer" for numbers which are representable as signed 32 bit integers (sometimes unsigned 32 bit integers).

Commands

The UDP payload consists of text that can be parsed as a single JSON object.There must be no 0 bytes or other non-text data. Whitespace can be present, but should be avoided to reduce the packet size. A final newline should be added at the end of the JSON text. (It's currently not required, but this is a threat that this may change.)

On the IP level, the command must be a single IP fragment.

Each JSON object sent to the device represents a single command. It can contain the following fields:

NameTypeMeaning
commandStringRequired. Name of the command to run.
seqNumberSent back with responses, and is otherwise not interpreted or changed by the device.
api_versionIntegerOptional, but passing this is highly recommended. The current protocol version is 6.
add_crcBooleanIf true, a CRC will be appended to the JSON data of the response. (See Responses
section below.)
(other)...Command specific parameters are located in the same top-level JSON object.

All fields except "command" are optional. The "api_version" should also be passed.

The most important commands are "device_info" and "set_params". All other commands are obscure and rarely needed.

Reponses

Responses indicate success or failure of a previously sent command. There is exactly one response per command. (Minus dropped network packets.)

The payload contains a single line of JSON text, with redundant whitespace trimmed (clients shouldn't rely on this) and a single newline character at the end (clients can rely on this).

On the IP level, large responses are sent as multiple IP fragments. These are reassembled to a large UDP packet, whose payload follows the described format. Large responses usually happen with with "device_info" commands, and can be mostly avoided by using the "select" parameter.

The responses JSON objects contain the following fields:

NameTypeMeaning
seqNumberAlways present. The same value as the command packet, or 0 if it was absent.
errorStringIf present, a protocol error of some kind has happened. This is usually used for
malformed commands only. It's a string value, that contains an error message.
It is not intended to be machine-readable.
warningStringIf present, warnings or errors. This is a string value and contains newline
characters (one message per line). This is not necessarily an error. It is not
intended to be machine-readable. The main use of this field and the "error"
field is to help with debugging.
(other)...Command specific response fields are located in the same top-level JSON object.

If "add_crc" was set to true in the command, the response packet uses a slightly modified format. The four byte sequence "\n//#" (0a 2f 2f 23 in hex) is appended after the JSON payload (instead of a final "\n" byte), followed by 8 ASCII digits representing the CRC32 of the payload before the four byte header. For example, the byte sequence " 0a 2f 2f 23 61 39 34 64 61 31 65 61" at the end of the packet indicates the CRC32 value 0x a94d a1ea. If present, this byte sequence will always be 12 bytes long and end with the packet's payload. The CRC32 uses the same polynomial as Ethernet and zlib. This can be useful if fragmented UDP packets occur, and the UDP checksum is not trusted. (In single fragment cases, the packet is protected sufficiently by the Ethernet CRC.) The format was chosen such that we can claim it's still a text based protocol. Naive clients can just not set this field. Then the "\n" byte is always the last byte of the payload, and the only one in the payload.

Extensibility

JSON was picked as base of the ISAAC protocol to make it easier to extend the protocol in the future. For this reason, both device and clients must make the following assumptions:

Packet drops and reordering

UDP can drop or reorder packets. Clients can use the "seq" field to avoid confusion due to reordering. It can also be used to detect packet drops (for example, if no response for a command is received, the client can issue a redundant command to check whether the device is still operating). If a response is lost, the client does not know whether the command was executed, or the result status. In this case the client needs to check the device state, or send the command again to be sure.

Retrieving updates and events from a device

There is no mechanism for receiving any kind of events with the API. Poll the device by sending device_info commands. A polling period of 500 ms or higher is recommended.

 

Reference

All commands can include standard parameter fields described in the section above. The same applies to responses. Only command-specific request/response fields are listed in the tables below.

device_info

Retrieve information about device firmware, DSP settings, AES67 settings/status/session list, and more.

Parameters

MemberTypeMeaning

select

JSON arrayOptional. Each array item must be a string. Each string can be the key of a
sub-object to include in the response. If missing, all sub-objects are returned.

Response

MemberTypeMeaning
productStringGeneral product ID. Always "ISAAC" (read-only).
firmware_versionString

Firmware version identifier, usually a release version string (read-only).
Note: never parse this in program code! Some firmware binaries use a
git hash instead of a version number.

api_versionInteger

API revision used by device, may be different from client's version in
"api_version" field (read-only).
Note: older firmware versions do not have this field.

fw_dateIntegerUNIX-time of firmware build date (read-only).
Note: older firmware versions do not have this field.
device_idString128 bit globally unique hardware identifier in hexadecimal, for example
"00313553504e52433033303436303535". This is the MCU's builtin
UUID. It never changes, unless the MCU is physically replaced. (Read-only.)
firmware_update_errorStringOptional. If present, a human readable error description on firmware
update errors. Always cleared on reboots. (Read-only.)
product_idIntegerProduct ID (see table below). (Read-only, normally.)
dspObjectDSP settings (see table below).
netObjectNetwork settings/state (see table below).
uiObjectInformational fields for Seeburg Network Manager (see table below).
streamObjectAES67 parameters (see table below).
streamsObjectAES67 stream list (see table below).
rtpObjectAES67 state (see table below).
loggingObjectLogging control (see table below).

Product IDs

The "product_id" field is encoded as follows:

Raw valueName
0(Never used, might happen on major device flash corruption.)
1Seeburg G Sub 1201 dp++
2Seeburg G Sub 1501 dp++
3Seeburg Trisonus 10 dp
4Seeburg X2 dp
5Seeburg X4 dp
6Seeburg X6 dp
7Seeburg X8 dp
8+Future products

DSP settings

The response "dsp" field is an object with the following fields:

MemberTypeMeaning
muteBoolean

Audio output muted setting.

presetIntegerPreset ID (starting from 0). Meaning and range depend on product_id and bank fields
(see table below).
npresetsIntegerPreset count (read-only).
bankIntegerBank ID (starting from 1). Meaning and range depends on product_id (see table below).
nbanksIntegerBank count (read-only).
levelIntegerAudio output level (see table below).
delayFloatAudio output delay in meters (range 0-1.8, out of range undefined).
eq_enBooleanEQ processing enabled.
eq0
eq1
eq2
eq3
eq4
ObjectEach of these 5 fields contains information for each EQ band.
See table below for EQ fields.

Bank/Preset mapping

The dsp bank and preset fields depend on the product_id as follows:

product_idbankpreset list
11"LP 120Hz/HP 120Hz"
"LP 160Hz/HP 160Hz"
"LP 160Hz/HP 120Hz"
"LP 120Hz/HP 120Hz + Aux"
"LP 160Hz/HP 160Hz + Aux"
"LP 160Hz/HP 120Hz + Aux"
12"LP 120Hz/L-Series HP 180Hz"
"LP 160Hz/L-Series HP 180Hz"
"LP 120Hz/L-Serie +Low"
"LP 120Hz/L-Series HP 180Hz + Aux"
"LP 160Hz/L-Series HP 180Hz + Aux"
"LP 120Hz/L-Serie +Low + Aux"
13"LP 120Hz + i5"
"LP 160Hz + i4"
"LP 120Hz + GL-Serie xov"
"LP 120Hz + i5 + Aux"
"LP 160Hz + i4 + Aux"
"LP 120Hz + GL-Serie xov + Aux"
21"LP 100Hz/HP 100Hz"
"LP 140Hz/HP 140Hz"
"LP 140Hz/HP 100Hz"
"LP 100Hz/HP 100Hz + Aux"
"LP 140Hz/HP 140Hz + Aux"
"LP 140Hz/HP 100Hz + Aux"
22"LP 120Hz/GL-Series xov Flat"
"LP 120Hz/GL-Series xov -Low"
"LP 120Hz/GL-Series xov +Low"
"LP 120Hz/GL-Series xov Flat + Aux"
"LP 120Hz/GL-Series xov -Low + Aux"
"LP 120Hz/GL-Series xov +Low + Aux"
23"LP 100Hz/K24 xov Flat"
"LP 120Hz/K20 60° Flat"
"LP 120Hz/K20 90° Flat"
"LP 100Hz/K24 xov Flat + Aux"
"LP 120Hz/K20 60° Flat + Aux"
"LP 120Hz/K20 90° Flat + Aux"
31"Flat"
"HP 100Hz"
"Low-Boost"
"Flat (soft)"
"HP 100Hz (soft)"
"Low-Boost (soft)"
32"Flat on-wall"
"HP 100Hz on-wall"
"Low-Boost on-wall"
"Flat on-wall (soft)"
"HP 100Hz on-wall (soft)"
"Low-Boost on-wall (soft)"
33"Flat in-wall"
"HP 100Hz in-wall"
"Low-Boost in-wall"
"Flat in-wall (soft)"
"HP 100Hz in-wall (soft)"
"Low-Boost in-wall (soft)"
41"Flat"
"HP 120Hz"
"Low-Boost"
"Flat (soft)"
"HP 120Hz (soft)"
"Low-Boost (soft)"
51"Flat"
"HP 100Hz"
"Low-Boost"
"Flat (soft)"
"HP 100Hz (soft)"
"Low-Boost (soft)"
61"Flat"
"HP 100Hz"
"Low-Boost"
"Flat (soft)"
"HP 100Hz (soft)"
"Low-Boost (soft)"
71"Flat"
"HP 100Hz"
"Low-Boost"
"Flat (soft)"
"HP 100Hz (soft)"
"Low-Boost (soft)"

In the table above, the third column specifies the list of presets (starting from preset ID 0) for a specific product_id and bank field ID. For example, with product_id=3 and bank=2, preset=0 selects "Flat on-wall", preset=4 selects "HP 100Hz on-wall (soft)", etc. For product_id=3, the range of the bank field is 1-3, and the range of the preset field is 0-5 (each bank has always the same number of presets for a given product). Setting out of range values lead to undefined behavior.

Audio output levels

The "level" field is encoded as follows:

Raw valueGain
0-12 dB
1-9 dB
2-6 dB
3-3 dB
40 dB
5+3 dB
6+6 dB

Out of range values when setting the field lead to undefined behavior.

EQ fields

Each of the eqN fields is an object with the following fields:

MemberTypeMeaning
enBoolean

Enable this band. (If the dsp.eq_en field is false, the EQ is disabled regardless of
the value of the en field.)

typeIntegerEQ type ID (see table below.)
freqFloatEQ band frequency (range 10-24000, out of range undefined).
qFloatEQ Q value (range 0.1-100, out of range undefined).
gainFloatEQ gain value in dB (range: -25-25, out of range undefined).

EQ type

The EQ "type" field is encoded as follows:

Raw valueNameMeaning
0NoneSame function as "en" field set to false.
1LSHELF
2PEQ
3PEQ2
4HSHELF

Out of range values when setting the field will lead to an error response.

Network settings/state

The response "net" field is an object with the following fields:

MemberTypeMeaning
macStringCurrent MAC address, formatted as 6 groups of 2 hexadecimal numbers
separated by ":", for example "AB:CD:12:34:56:7E". (Read-only.)
ipStringCurrent IP address formatted as quad-dotted IP address, for example
"169.254.1.0". (Read-only.)
static_ipStringConfigured static IP address (the same format as the "ip" field), or
"0.0.0.0" if the IP address should be dynamically allocated. Applied after
device reboot.
igmp_hackBooleanIf true, enable an IGMP workaround, that is supposed to help with
broken IGMP-snooping switches. (Enabled by default.)

UI fields

The response "ui" field is an object with the following fields:

MemberTypeMeaning
orderIntegerOrder ID (used for GUI device list sort order).
nameStringUser-assigned device name (max. 127 bytes).
locStringUser-assigned device location text (max. 127 bytes).
memoStringText field for free use (max. 127 bytes).

The strings are supposed to be encoded as UTF-8 (usually enforced by JSON), though the device will accept any encoding in JSON or these fields.

None of the values in this object are actually interpreted by the firmware. They are for use by GUI tools.

AES67 settings

The response "stream" field is an object with the following fields:

MemberTypeMeaning
nameStringStream name, used to select session.
link_offsetIntegerLink offset in samples.
nominal_level_dbuFloatNominal level in dBu.
ch0IntegerSource channel to play to stream, counting from 0.

All current devices support mono only, and ch0 is the only channel. Should more channels be supported in the future, fields like ch1, ch2, ... will be added.

AES67 session list

The response "streams" field is an object with the following fields:

MemberTypeMeaning
listJSON arrayActual session array, see below.

Each item in the "list" array is an object with the following fields:

MemberTypeMeaning
nStringSession name
iStringSession info
cIntegerChannel count

This is the list of discovered sessions. The session name is the "s" field in the SDP, and is compared to stream.name to select a session. The session info is the "i" field in the SDP. The channel count is also as indicated in the SDP, and gives the upper range of the stream.ch0 field (exclusive).

RTP state

The response "rtp" field is an object with the following fields:

MemberTypeMeaning
lockIntegerAES67 streaming state

The lock field can have the following values:

Raw valueMeaning
0No PTP, no RTP data
1PTP locked, but no RTP data
2No PTP, but RTP locked
3PTP and RTP locked

"Locked" in this context means "synchronized to". Streaming is possible at state 2 or 3. State 2 is indicated by a blinking yellow Ethernet port LED, at state 3 it glows normally. RTP is for Real-Time Transfer Protocol, the part of AES67 that transports actual audio data over network.

Logging state

The response "logging" field is an object with the following fields:

MemberTypeMeaning
enBooleanWhether logging is enabled

Logging is a debug feature. The log is useful to firmware developers only. Technically inclined people may be able to interpret parts of the log, but it's not recommended. Logging makes the device broadcast UDP packets to IP 255.255.255.255 on port 7055. The log state is off by default, and is not restored across firmware reboots.

Log packets have a format that is slightly different from normal protocol messages. The first part of the UDP payload consists of JSON text, like in normal messages. This is followed by a 0 byte, a binary length field, and the log text.

PositionLengthField
0NJSON text of length N bytes
N + 01Literal 0 byte (N found by searching for the first 0 byte)
N + 12Little endian uint16_t log text length
N + 2lengthASCII log text, using length field above

This binary length field and log payload is found by searching for a 0 byte. JSON cannot legally contain a 0 byte.

This format was chosen because we wanted to continue using JSON for its positive properties, all while reducing device MCU load by not having to turn the log message into a legal JSON string value (escaping).

The JSON text is an object with the following fields:

MemberTypeMeaning
commandStringContains the string "raw_log", otherwise it's not a log message
posIntegerLog byte position, can be used to detect dropped log messages
overflowBooleanInternal overflow flag (not always present)

The "pos" field is the number of log bytes output so far. The log receiver can add the packet's log text length to the "pos" field to know the "pos" field of the next log packet. If the values mismatch, a log packet must have been dropped or reordered. The value of this field is an unsigned 32 bit integer and rolls over.

"overflow" indicates that the device log buffer (which is of limited size) overflowed before the contents could be sent to the network. The "pos" field is also discontinuous in this case.

Description

This command reports general information about device, network status, and DSP settings. This command should be used for device discovery.

The "set_params" command is an important companion command. It mirrors most fields in the "device_info" command, and can be used to set the corresponding fields. All references to setting fields in the parameter description above is in context of the "set_params" command.

The "select" field can be used to retrieve only some information. It is an array of strings, where each string is the name of a JSON sub-object. Only sub-objects mentioned in this list are sent in the response. For example, if you send select:[ "dsp"], then other sub-objects like "streams" are not sent, only the "dsp" sub-object. If the field is missing, everything is sent.

Example

User => Device
{"command": "device_info", "seq": 123, "api_version": 6}
Device reply (prettified)
{
  "seq": 123,
  "product": "ISAAC",
  "firmware_version": "v1.5.2",
  "api_version": 6,
  "fw_date": 1654077358,
  "device_id": "00313753384d37373038303432303139",
  "product_id": 3,
  "net": {
    "mac": "1A:7D:9C:4F:26:3A",
    "ip": "169.254.225.237",
    "static_ip": "0.0.0.0",
    "igmp_hack": true
  },
  "stream": {
    "name": "AVIOUSB-5346cb : 2",
    "link_offset": 48,
    "nominal_level_dbu": 0,
    "ch0": 0
  },
  "streams": {
    "list": [
      {
        "n": "AVIOUSB-5346cb : 2",
        "i": "1 channels: Left",
        "c": 1
      }
    ]
  },
  "rtp": {
    "lock": 0
  },
  "ui": {
    "order": 0,
    "name": "",
    "loc": "",
    "memo": ""
  },
  "logging": {
    "en": false
  },
 ...
Device reply (continued)
...
  "dsp": {
    "mute": false,
    "preset": 1,
    "npresets": 2,
    "nbanks": 1,
    "bank": 1,
    "level": 4,
    "peak": 0,
    "gr": 0,
    "eq_en": true,
    "delay": 0,
    "eq0": {
      "en": true,
      "type": 2,
      "freq": 100,
      "q": 1,
      "gain": 0
    },
    "eq1": {
      "en": true,
      "type": 2,
      "freq": 200,
      "q": 1,
      "gain": 0
    },
    "eq2": {
      "en": true,
      "type": 2,
      "freq": 500,
      "q": 1,
      "gain": 0
    },
    "eq3": {
      "en": true,
      "type": 2,
      "freq": 2000,
      "q": 1,
      "gain": 0
    },
    "eq4": {
      "en": true,
      "type": 2,
      "freq": 4000,
      "q": 1,
      "gain": 0
    }
  }
}

set_params

Write various device settings.

Parameters

This command mirrors a number of fields in the device_info response. All fields are optional, and only parameters sent with the command are actually set.

See the device_info command for type and meaning of each field, and whether it can be written.

Response

Success/error only. If an error happens, and the request contains multiple parameters, it's possible that the request is partially applied. In this case, it's unpredictable which parameters were applied and which not. Use the device_info command to confirm the new values.

Description

This command can set most fields which appear in device_info. Name, location, JSON data type, and meaning are exactly the same as the fields in device_info.

If the client needs to change multiple parameters, it's recommended to set all parameters at once, using a single "set_params" command.

Example

This mutes the DSP, and leaves all other parameters untouched:

User => Device
{"command": "set_params", "dsp": { "mute": true }}
Device reply
{"seq": 0}

This sets multiple fields (enable mute, enable EQ 3, set memo to "hello"), and leaves all other parameters untouched:

User => Device
{"command": "set_params", "dsp": { "mute": true, "eq3": {"en": true} },
"ui": { "memo": "hello" } }
Device reply
{"seq": 0}

show_rtp_status

Show information about current AES67 streaming (network to device).

Parameters

None.

Response

MemberTypeMeaning
ipString

IP address of source stream.

portIntegerUDP port of source stream.
clock_offsetIntegerSDP mediaclk parameter (0 if unset)
link_offsetIntegerOffset chosen with set_session command.
samplesizeIntegerAudio sample size in bits per channel
samplerateIntegerAudio sample rate
channelsIntegerNumber of channels sent by source stream.
output_channelsArrayChannels used, as chosen with set_session command.
packet_dropsIntegerNew packet drops since last command.
packet_drop_last_msIntegerAbsolute device time of last packet drop in ms. Can wrap around.
rtp_received_last_msIntegerAbsolute device time of last RTP audio packet received. Can wrap around.
clock_lockedIntegerComplete lock. (device_info rtp.lock has more detailed information.)

Description

This shows the status of AES67 streaming, as well as some of the selected parameters.

This command is for debugging, and you should probably not rely on it being present or compatible in the next firmware version.

Example

User => Device
{"command": "show_rtp_status"}
Device reply
{
  "seq": 0,
  "ip": "239.69.214.91",
  "port": 5004,
  "clock_offset": -1479386051,
  "link_offset": 64,
  "samplesize": 24,
  "samplerate": 48000,
  "channels": 1,
  "output_channels": [
    0
  ],
  "packet_drops": 2147483647,
  "packet_drop_last_ms": 693922,
  "rtp_received_last_ms": 823747,
  "clock_locked": true,
  "ptp_sync_last_ms": 823543
}

rtc_get

Read RTC time.

Parameters

None.

Response

MemberTypeMeaning
utcInteger

Current time in UTC

Description

Report the current time in UTC from the internal RTC (Real Time Clock). This is maintained independently from the PTP time, and is less precise, but continues progressing while the device is turned off.

Example

User => Device
{"command": "rtc_get"}
Device reply
{
  "seq": 0,
  "utc": 1544017789
}

rtc_set

Set RTC time.

Parameters

MemberTypeMeaning
utcIntegerNew current time in UTC

Response

Success/error only.

Description

Counter part of utc_get.

Example

User => Device
{
  "command": "rtc_set",
  "utc": 1544017789
}
Device reply
{
  "seq": 0,
}

rtc_ntp

Initiate NTP time synchronization.

Parameters

MemberTypeMeaning
ntp_server_ipStringNTP server, formatted as IP address.

Response

Success/error only (this is sent before the NTP server is contacted - it indicates correctness of the command formatting only).

Description

Synchronize with an explicitly specified NTP time server once. This is not like normal NTP operation. The firmware won't attempt to periodically synchronize the time. Instead, the operation ends once a single NTP server packet has been received. whether the time was correctly set should be checked with rtc_get, and there is no event or any other indication whether the time server could even be reached.

Example

User => Device
{
  "rtc_ntp": "rtc_ntp",
  "ntp_server_ip": "192.168.5.132"
}
Device reply
{
  "seq": 0,
}

sap_purge

Remove sessions from the device's session cache.

Parameters

MemberTypeMeaning
ageFloatMaximum session age in seconds that should be preserved (older sessions
are deleted). (Default: 60)
blocktimeFloatTime in seconds during which new SAPs should be ignored. (Default: 0)

Response

Success/error only.

Description

The device caches previously discovered sessions (using the SAP protocol) and hold them in RAM and on the flash. There is currently a session timeout of 100 seconds, after which a session is automatically deleted. This command can be used to remove a session immediately. Sometimes, it can help resolving playback problems by removing broken cache entries.

The "blocktime" parameter can be set if sap_purge is supposed to be run on all devices in the network. The problem is that the devices will never execute the command at exactly the same time, and bogus SAP packets still could be propagating through the network. In particular, devices will send their own bogus cached/replicated SAPs to all other devices. To avoid that devices immediately readd bogus sessions, this parameter can disable SAP processing temporarily.

reset_settings

Wipe all settings.

Parameters

None.

Response

None.

Description

This resets all user settings, and reboots. Like with the "reboot" command, no response is sent. The device_id is not changed.

reboot

Reboots the device.

Parameters

None.

Response

None.

Description

The device is reset, as if power-cycled. There is no response, because the hardware is reset before a response can be sent out.

 

Document version: 19 / Jun 23, 2022 11:08

Download this document as PDF

.
.