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:

{"command": "set_params", "api_version": 6, "seq": 123, "dsp": {"mute": true}}

{"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:

{"command": "device_info"}

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

{
  ...
  "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:

{"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:

• Waiting for SAP announcements. (Unless they are cached on flash; if they are not cached, not replicated by other devices, and the sender is a Dante device, it can take up to 30 seconds.)
• Waiting for PTP clock stabilization. (Requires receiving at least 2 PTP announcements, streaming may start before; can take about 2 seconds.)

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:

• Only 48000 Hz is supported.
• SAP is required, which is optional ion AES67. (Other session management protocols may be supported in the future.)
• Only Dante devices were available as sources for testing and development, and there are some workarounds that may not agree with the standards.
• The stream name (SDP "s" field) is used to uniquely identify sessions. Duplicate names are considered an invalid misconfiguration.
• ISAAC devices send out cached SAPs at a relatively high rate. The SAP was specified for old network technology and prioritized reducing traffic. ISAAC devices are likely used in settings where every second can count. This "SAP replication" can help if devices need to be setup very quickly.
• Likewise, SAP timeouts were reduced to avoid listing stale sessions.
• There is a workaround that is supposed to help against badly implemented IGMP-snooping in consumer switches. (See igmp_hack.)

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:

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:

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:

• The ordering of object members is arbitrary. Both the device and the client are required to deal with any ordering of members in an object. It is possible that members change their order on firmware updates, or randomly.
• Unknown object members should be ignored. The device will add a warning to the response object if an object member is unknown, but will otherwise ignore it.
• If new parameters are added to a command, it must be done in a backward compatible way.
• Any code handling commands or responses must be forward compatible, and ignore unknown parameters.

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

Response

Product IDs

The "product_id" field is encoded as follows:

DSP settings

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

Bank/Preset mapping

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

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:

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:

EQ type

The EQ "type" field is encoded as follows:

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:

UI fields

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

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:

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:

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

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:

The lock field can have the following values:

"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:

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.

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:

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

{"command": "device_info", "seq": 123, "api_version": 6}

{
  "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
  },
 ...

...
  "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:

{"command": "set_params", "dsp": { "mute": true }}

{"seq": 0}

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

{"command": "set_params", "dsp": { "mute": true, "eq3": {"en": true} },
"ui": { "memo": "hello" } }

{"seq": 0}

show_rtp_status

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

Parameters

None.

Response

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

{"command": "show_rtp_status"}

{
  "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

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

{"command": "rtc_get"}

{
  "seq": 0,
  "utc": 1544017789
}

rtc_set

Set RTC time.

Parameters

Response

Success/error only.

Description

Counter part of utc_get.

Example

{
  "command": "rtc_set",
  "utc": 1544017789
}

{
  "seq": 0,
}

rtc_ntp

Initiate NTP time synchronization.

Parameters

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

{
  "rtc_ntp": "rtc_ntp",
  "ntp_server_ip": "192.168.5.132"
}

{
  "seq": 0,
}

sap_purge

Remove sessions from the device's session cache.

Parameters

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