Disclaimer

Copyright © Glensound Electronics Ltd and individual contributors. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of Glensound nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Content based on github.com/github/opensource.guide used under the CC-BY-4.0 license.

Binary protocol for DARK8MAI

Getting device information

The GetInfo message can be sent to any device, regardless of its connection state. The message header must not include a password.

This should be done only once, when the device is discovered on the network. The device returns an Info structure containing various items, of which most important are Product ID and device name. The DARK8MAI's PID is 28.

1) Host controller sends a GetInfo message to the device.

------------------------------------------------------
0000   47 53 20 43 74 72 6c 00 10 00 05 00 b1 ee 2f 01   GS Ctrl...... /.
------------------------------------------------------

GS Header:
0000   47 53 20 43 74 72 6c 00                           Magic
                               10 00                     Size
                                     05                  Opcode
                                        00               Flags
                                           b1 ee 2f 01   Controller ID

    Magic: 4753204374726c00                              (Must not use password)
    Size: 0x0010 (Payload 0 bytes)                       Packet size, including this header
        .000 0000 0001 0000 = Packet size: 16
        0... .... .... .... = Multipacket: False         Message has one packet (this one)
    Opcode: 5 (GetInfo)
    Flags: 0x00                                          (set to zero)
    Controller ID: 0x012feeb1                            Unique value on this network, identifies the sender

2) DARK1616M responds with Info.

------------------------------------------------------
0000   47 53 20 43 74 72 6c 00 90 00 04 0c 00 a8 e1 23   GS Ctrl........#
0010   00 22 17 df ef fe 32 7b 1c 00 01 01 02 00 00 00   ."....2{........
0020   00 1d c1 ff fe 23 e1 a8 44 52 4b 38 4d 41 49 2d   .....#..DRK8MAI-
0030   32 33 65 31 61 38 00 00 00 00 00 00 00 00 00 00   23e1a8..........
0040   00 00 00 00 00 00 00 00 44 52 4b 38 4d 41 49 2d   ........DRK8MAI-
0050   73 6e 2d 34 32 34 00 00 00 00 00 00 00 00 00 00   sn-424..........
0060   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ................
0070   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ................
0080   00 00 00 00 00 00 00 00 00 21 00 00 00 00 00 00   .........!......
------------------------------------------------------

GS Header:
0000   47 53 20 43 74 72 6c 00 90 00 04 0c 00 a8 e1 23

    Magic: 4753204374726c00
    Size: 144 (Payload 128 bytes)
        .000 0000 1001 0000 = Packet size: 144
        0... .... .... .... = Multipacket: False
    Opcode: 4 (Info)
    Flags: 0x0c                                          (ignore)
    Sequence: 0                                          Sequence number for Info packets
    Device ID: a8e123

Info:
0010   00 22                                             Firmware version
             17 df                                       Status port
                   ef fe 32 7b                           Status IP
                               1c 00                     Product ID
                                     01                  Variant ID
                                        01               Protocol version
                                           02 00         Flags
                                                 00 00   Dante process ID
0020   00 1d c1 ff fe 23 e1 a8                           Dante ID
                               44 52 4b 38 4d 41 49 2d   Host name
0030   32 33 65 31 61 38 00 00 00 00 00 00 00 00 00
0040   00 00 00 00 00 00 00 00
                               44 52 4b 38 4d 41 49 2d   Friendly name
0050   73 6e 2d 34 32 34 00 00 00 00 00 00 00 00 00 00
0060   00 00 00 00 00 00 00 00
                               00 00 00 00 00 00 00 00   Domain name
0070   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0080   00 00 00 00 00 00 00 00
                               00 21                     DNT version
                                     00 00               DFU2 version
                                           00 00 00 00   reserved

    Firmware version: 0x2200                             Version of the main DFU firmware file (2.2.0)
    Status port: 6111                                    The port to which the device sends multicast packets
    Status IP: 239.254.50.123                            The multicast group address the device sends to
    Product ID: 28 (DARK8MAI)                            Product identifier (28 = DARK8MAI)
    Variant ID: 1                                        Product variant
    Protocol version: 1                                  Network protocol version
    Flags: 0x0002
        .... .... .... ...0 = DNT updateable: False      Capability to update the main DNT file online (no)
        .... .... .... ..1. = DFU updateable: True       Capability to update the main DFU file online (yes)
        .... .... .... .0.. = DFU2 updateable: False     Capability to update the secondary DFU file online (no)
    Dante process ID: 0x0000                             (Audinate process ID, in practice always zero)
    Dante ID: 0x001dc1fffe23e1a8                         Globally unique device identifier
    Host name: DRK8MAI-23e1a8                            Fixed device name
    Friendly name: DRK8MAI-sn-424                        User-assignable device name
    Domain name:                                         Dante domain name (none)
    DNT version: 0x2100                                  DNT file version (2.1.0)
    DFU2 version: 0x0000                                 Secondary DFU file version (unused)

Maintaining connection state

If the host controller wants to keep the device connected it should send it messages (other than GetInfo) at least every 5-6 seconds. While connected, the device sends periodic Status messages and state change reports to the controller. If the device doesn't receive a message (other than GetInfo) for 7 seconds it disconnects and stops sending any data.

Typically a controller sends a GetConfig message every 5-6 seconds as keepalive, because the Config response indicates the connection state. The GetConfig message also contains bits that indicate whether the controller wishes to establish an exclusive connection and whether it wants the Status messages sent 10 times per second or once per second.

If the controller prefers to send ad-hoc commands to the device it doesn't need to keep the device connected. Sending any command, other than GetInfo, will set the device in Connected state (if access is granted) for 7 seconds.

The device responds with a Config message, which contains bits indicating the connection state.

1) Host controller sends a GetConfig command to the device.

------------------------------------------------------
0000   47 53 20 43 74 72 6c 00 10 00 07 01 b1 ee 2f 01   GS Ctrl.........
------------------------------------------------------

GS Header:
    Magic: 4753204374726c00
    Size: 0x0010 (Payload 0 bytes)
        .000 0000 0001 0000 = Packet size: 16
        0... .... .... .... = Multipacket: False
    Opcode: 7 (GetConfig)
    Flags: 0x01
        .... ...1 = Exclusive: True                      Desired exclusive connection (unicast responses)
        .... ..0. = No meter: False                      Desired Status period of 10 Hz
    Controller ID: 0x012feeb1

2) Device responds with a Config message.

------------------------------------------------------
0000   47 53 20 43 74 72 6c 00 18 00 06 0d 01 a8 e1 23   GS Ctrl.........
0010   ef fe 32 7b 17 df 00 00                           ..2{....
------------------------------------------------------

GS Header:
0000   47 53 20 43 74 72 6c 00 18 00 06 0d 01 02 00 2c

    Magic: 4753204374726c00                              Can be XORed with a 8-byte password value
    Size: 0x0018 (Payload 8 bytes)
        .000 0000 0001 1000 = Packet size: 24
        0... .... .... .... = Multipacket: False
    Opcode: 6 (Config)
    Flags: 0x0d
        .... ...1 = Exclusive: True                      Device is in Exclusive connection mode
        .... .1.. = Password valid: True                 Password used in GetConfig was valid
        .... 1... = Access granted: True                 Access granted to this host controller
    Sequence: 1                                          Sequence number for Config packets
    Device ID: a8e123

Config:
0010   ef fe 32 7b                                       Status IP, if in Shared mode
                   17 df                                 Status port, if in Shared mode
                         00 00                           reserved

    Status IP: 239.254.50.123
    Status port: 6111

Receiving periodic Status messages

When the device is in Connected state it sends periodic Status messages. In Exclusive connection mode it unicasts the packets to the host controller which has the connection granted. In Shared connection mode the device multicasts the packets to the group address and port indicated in the Config message.

The frequency of the Status messages is controlled by the NoMeter bit in the GetConfig command. If the bit is cleared, the device sends Status 10 times per seconds. This is useful if the host controller displays live audio metering data provided in the Status messages. If NoMeter is set, the device sends Status once per second.

------------------------------------------------------
0000   47 53 20 43 74 72 6c 00 2c 00 01 00 01 a8 e1 23   GS Ctrl.,......#
0010   02 00 00 00 00 01 00 01 b8 9f ba a6 a1 a0 b1 86   ................
0020   08 08 08 08 08 08 08 08 aa aa 00 00               ............
------------------------------------------------------

GS Header:
0000   47 53 20 43 74 72 6c 00 2c 00 01 00 01 a8 e1 23

    Magic: 4753204374726c00
    Size: 44 (Payload 28 bytes)
        .000 0000 0010 1100 = Packet size: 44
        0... .... .... .... = Multipacket: False
    Opcode: 1 (Status)
    Flags: 0x00
    Sequence: 1
    Device ID: a8e123

GS Status:
0010   02 00 00 00                                       Flags
                   00                                    Preset report generation
                      01                                 Device report generation
                         00                              In channel names report generation (unused)
                            01                           Out channel names report generation

    Flags: 0x00000002
        .... .... .... .... .... .... .... ...0 = Identify: False
        .... .... .... .... .... .... .... ..1. = Clock locked: True
    Preset rep. gen.: 0
    Device rep. gen.: 1
    In ch. names rep. gen.: 0
    Out ch. names rep. gen.: 1

DARK8MAI Status:
0010                           b8 9f ba a6 a1 a0 b1 86   Meters
0020   08 08 08 08 08 08 08 08                           Gains
                               aa aa                     Input modes
                                     00 00               Reserved

    Meters: b89fbaa6a1a0b186
    Gains: 0808080808080808
        CH1 Gain: 8
        CH2 Gain: 8
        CH3 Gain: 8
        CH4 Gain: 8
        CH5 Gain: 8
        CH6 Gain: 8
        CH7 Gain: 8
        CH8 Gain: 8
    Input modes: 0xaaaa
        .... .... .... ..10 = In 1 mode: 2 (Mic)
        .... .... .... 10.. = In 2 mode: 2 (Mic)
        .... .... ..10 .... = In 3 mode: 2 (Mic)
        .... .... 10.. .... = In 4 mode: 2 (Mic)
        .... ..10 .... .... = In 5 mode: 2 (Mic)
        .... 10.. .... .... = In 6 mode: 2 (Mic)
        ..10 .... .... .... = In 7 mode: 2 (Mic)
        10.. .... .... .... = In 8 mode: 2 (Mic)

Audio meter values are in Dante format. The value is interpreted as the number of half-decibel steps below 0 dBFS. For example:

00 = 0 dBFs
01 = -0.5 dBFS
02 = -1 dBFs
...
fe = -127 dBFs
ff is reserved

Audio meters ordering for DARK8MAI:
0-7: Dante Out 0-7

Analogue input modes:
0: reserved
1: Line
2: Mic
3: Mic+Phantom

Receiving device state reports

If the device is in Connected state it sends a report whenever its internal state has changed, or as a response to an explicit Query message. The internal state may change as a result of a user manually operating the units UI, a command received from a controller, or an independent event.

Reports are sent using one or more packets of type Report. If the message size is greater than the packet size the Multipacket bit is set in the GS header and the message has to be re-assembled from multiple packets (DARK8MAI only sends single-packet messages). A Report message may contain one or more reports. Each report is prefixed with a Block Header indicating its type and size.

DARK8MAI uses no device-specific reports.

The example below shows the full report, consisting of a Device, Input Channel Names and Output Channel names. In practice, the device can send any of these reports in any combination, so the host controller must parse the message and extract the reports from it.

------------------------------------------------------
0000   47 53 20 43 74 72 6c 00 44 00 0a 00 02 a8 e1 23   GS Ctrl.D......#
0010   01 01 04 00 80 bb 00 00 00 00 00 00 00 00 00 00   ................
0020   11 00 00 00 02 00 00 00 03 01 06 00 02 30 31 02   .............01.
0030   30 32 02 30 33 02 30 34 02 30 35 02 30 36 02 30   02.03.04.05.06.0
0040   37 02 30 38                                       7.08
------------------------------------------------------

GS Header:
0000   47 53 20 43 74 72 6c 00 40 00 0a 00 00 a8 e1 23

    Magic: 4753204374726c00
    Size: 64 (Payload 48 bytes)
        .000 0000 0100 0000 = Packet size: 64
        0... .... .... .... = Multipacket: False
    Opcode: 10 (Report)
    Flags: 0x00
    Sequence: 0
    Device ID: a8e123

Block Header:
0010   01                                                Type
          01                                             Generation
             04 00                                       Length in words


    Type: 1 (Device)
    Generation: 1
    Length in words: 4 (16 bytes)

Device Report:
0010               80 bb 00 00                           Sample rate in Hz
                               00                        Srate choice (N.A. for DARK8MAI)
                                  00                     Clock source (N.A. for DARK8MAI)
                                     00                  Clock source choice (N.A. for DARK8MAI)
                                        00               ADC filter code
                                           00            DAC filter code (N.A. for DARK8MAI)
                                              00 00 00   reserved
0020   11 00 00 00                                       Flags

    Sample rate: 48000
    Sample rate choice: 0 (Unknown)
    Clock source: 0 (Dante)
    Clock source choice: 0 (Dante)
    ADC filter: 0 (Normal)
    DAC filter: 0 (Normal)
    Flags: 0x00000011
        .... .... .... .... .... .... .... ...1 = Link 1: True
        .... .... .... .... .... .... .... ..0. = Link 2: False
        .... .... .... .... .... .... .... .0.. = PSU 1: False
        .... .... .... .... .... .... .... 0... = PSU 2: False
        .... .... .... .... .... .... ...1 .... = POE 1: True
        .... .... .... .... .... .... ..0. .... = POE 2: False

ADC filter codes:
0: Normal
1: Slow roll-off

Block Header:
0020               02                                    Type
                      00                                 Generation
                         00 00                           Length in words (no data)

    Type: 2 (In Channel Names)
    Generation: 0
    Length in words: 0 (0 bytes)

Block Header:
0020                           03                        Type
                                  01                     Generation
                                     06 00               Length in words

    Type: 3 (Out Channel Names)
    Generation: 1
    Length in words: 6 (24 bytes)

Out Channel Names Report:
0020                                       02 30 31 02   Output channel names
0030   30 32 02 30 33 02 30 34 02 30 35 02 30 36 02 30
0040   37 02 30 38

Sending commands

Commands are contained in messages with opcode 3 (SetControl). A SetControl message may include one or more commands. The message header indicates the desired connection type and status update frequency.

The structure of a SetControl message is:

GS Header
Command
Command
... (up to the packet capacity)

Input Gain Index (5)

------------------------------------------------------
0000   47 53 20 43 74 72 6c 00 14 00 03 01 b1 ee 2f 01   GS Ctrl......./.
0010   05 00 09 00                                       ....
------------------------------------------------------

GS Header:
0000   47 53 20 43 74 72 6c 00 14 00 03 01 b1 ee 2f 01

    Magic: 4753204374726c00
    Size: 20 (Payload 4 bytes)
        .000 0000 0001 0100 = Packet size: 20
        0... .... .... .... = Multipacket: False
    Opcode: 3 (SetControl)
    Flags: 0x01
    Controller ID: 0x012feeb1

Command:
0010   05                                                Opcode
          00                                             Channel index
             09                                          Gain index
                00                                       reserved

    Opcode: 5
    Channel: 0                                           0 to 7
    Gain: 9                                              In Line input mode: 0 to 6, other modes 0 to 17

The Input Gain Index command sets the gain index for the selected input and for the currently selected analogue input mode. For example, if the input is currently in Mic mode, the gain index is set for the Mic mode only.

The range of analogue input gain indices depends on the input mode:
Line: 0 to 6
Mic: 0 to 17
Mic+Phantom: 0 to 17

The actual gain in dB has a step of 3 dB and the ranges are as follows:
Line: -9dB to +9dB
Mic: +10dB to +61dB
Mic+Phantom: +10dB to +61dB

Analogue Input Mode (6)

------------------------------------------------------
0000   47 53 20 43 74 72 6c 00 14 00 03 01 b1 ee 2f 01   GS Ctrl......./.
0010   06 00 01 00                                       ....
------------------------------------------------------

GS Header:
0000   47 53 20 43 74 72 6c 00 14 00 03 01 b1 ee 2f 01

    Magic: 4753204374726c00
    Size: 20 (Payload 4 bytes)
        .000 0000 0001 0100 = Packet size: 20
        0... .... .... .... = Multipacket: False
    Opcode: 3 (SetControl)
    Flags: 0x01
    Controller ID: 0x012feeb1

Command:
0010   06                                                Opcode
          00                                             Channel index
             01                                          Input mode
                00                                       reserved

    Opcode: 6
    Channel: 0                                           0 to 7
    Mode: 1 (Line)                                       1 to 3

Analogue input modes:
0: reserved
1: Line
2: Mic
3: Mic+Phantom



Updated: 19/Jun/2023