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.

Contents

Overview
Packets and messages
Data Transfer Transactions
Error Handling
Device Discovery
Device Access Control
Connection Modes
Session Keepalive
Controller Opcodes
Device Opcodes
Status Messages
Commands
Reports
Presets
Factory Settings
Remote Firmware Upgrade

Overview

The Glensound protocol enables remote control and monitoring of selected networked devices.

A remote application, called controller sends control data to a single device using unicast UDP datagrams. A device sends device data to one or more controllers using unicast or multicast UDP datagrams. It is possible to have multiple controllers on the same network accessing the same devices.

Control and device data may be transmitted on the same network with audio. For this reason, the protocol attempts to minimise data size and packet rate. A controller application should do its best to avoid creating excessive network trafic.

Glensound provides C++ header files containing declarations common for all device types. For each supported device model, separate header files are provided, declaring the device-specific types.

Packets and messages

A data packet is the payload of a network UDP datagram. For devices using Brooklyn and Broadway modules the maximum packet size is 1448 bytes and for Ultimo-based devices it's 500 bytes. The packet's size must be a multiple of 4 bytes and zero-padding is used if necessary. A packet begins with the standard 16-byte Glensound (GS) header. The packet size is indicated in the header for error-detection purposes.

Numerical data is in little-endian order, unless explicitly documented otherwise.

A message is a unit of information with a dedicated single purpose. Examples are control command, status or report.

The simplest message consists of one data packet starting with the GS header containing a command in its opcode field. A message may have data payload following the header.

A data packet may contain multiple messages. These messages may have a fixed size (inferred from its opcode or type) or variable size. In the latter case, the message is pre-pended with a BlockHeader structure.

If a message is longer than the maximum packet size then it is sent using multiple UDP datagrams.

Data Transfer Transactions

A transaction consists of one or more related packets sent in one direction. The GS header in each packet contains a bit indicating whether the packet is part of a single- or multi-packet transaction. Because UDP is not reliable, Glensound uses a simple transaction protocol to enable detection of packets lost, duplicated or arriving out of order.

Packet Sequence Number

Each packet sent from a device to a controller has an 8-bit sequence counter that is incremented (modulo 256) before transmission. It allows the controllers to detect packet delivery problems. Packets sent from the controller to the device do not use sequencing. Devices are servers responding to the controller's commands, so it is the controller's responsibility to detect missing or invalid responses.

Single-packet Transactions

If the 'multipacket' bit in the GS header is clear, the transaction consists of this packet only. The data payload, if any, follows the header, and its maximum size is 1432 or 484 bytes, depending on device type.

Multi-packet Transactions

If the 'multipacket' bit in the GS header is set then the packet is part of a multi-packet transaction. The transaction payload is split into up to 32 partial packets and re-assembled at the destination.

The GS header is followed by a 4-byte multi-packet info header, which is followed by the packet payload. The maximum packet payload size is 1428 or 480 bytes, resulting in the maximum transaction payload sizes of 45696 and 15360 respectively. Depending on memory capacity, devices may further limit this size. Transferring larger data sets (like firmware updates) is possible using multiple transactions.

The multi-packet info contains a sequential transaction number, transaction part number and total (transaction) payload size. The transaction number is incremented (modulo 256) for each new transaction. Transaction part number starts with zero for the first part of a multi-packet transaction and is incremented for each next part. The total payload size information allows a receiver to calculate the required number of parts and the payload size of each part.

All parts of a multi-packet transaction must use the maximum multi-packet payload size, except for the last part, which can be smaller.

A receiver of multi-packet transaction might use a state machine with the following algorithm:

  1. Initially, the receiver is in Idle state and it stores the number of the last transaction (or a marker indicating "none").
  2. In Idle state, any received packet with the same transaction number as the stored one is ignored. If the number is different, it is made current and the receiver switches to Receiving state.
  3. The Receiving state is initialised by calculating the required number of parts (knowing the total payload size and the maximum packet payload size) and marking all parts as pending, except for the part just received.
  4. In the Receiving state, any arriving part with the current transaction number is collected and marked as received. When all parts are received, the entire transaction payload is saved and the receiver switches to Idle state.
  5. If, in Receiving state, a part arrives with a different transaction number, the receiver re-initialises and remains in Receiving state.

Unicast and Multicast Transactions

A Glensound device only accepts unicast datagrams on the port 41161.

The Info and Config response messages are always unicast from the device to the IP address and port of the controller that issued the GetInfo and GetConfig commands.

By default, a device multicasts Status and Report messages to the standard Glensound group address of 239.254.50.123, port 6111. A remote controller may request exclusive connection to have the Status and Report messages unicast instead.

Controller ID

Packets transmitted from controller to device must contain a (reasonably) unique 32-bit identifier that allows the device to identify different controllers on the same network. Typically it is assembled using the last four bytes of the MAC address of one of the computer's network interfaces.

Audio Meter Updates

Most Glensound devices send audio metering data in the Status Messages. The frequency of meter updates is by default 10 Hz and this implies that the device will send at least 10 UDP packets per second when connected to a controller.

In some scenarios a connected controller is not monitoring audio meters and the packet rate on the network can be reduced. In the header of every control packet sent to the device the controller indicates whether it requires frequent meter updates. If the noMeter bit is set the device reduces the status update rate to once per second. The Status packet contains meter data in any case.

Error Handling

Devices verify all data received from the network. They are required to ignore all opcodes and commands that they do not understand or support. They should also ignore any malformed packets or protocol failures. If a received parameter is out of range the device has a choice to either reject the message or coerce the value into valid range.

Devices do not report any message verification failures. If a message can't be accepted the device must not change its visible state. State changes are normally reported through the Status and/or Report messages. It is the controller's responsibility to check whether a command succeeded by examining the device response, or lack thereof.

Legitimate error conditions, such as loss of clock lock or failure of one of the power supplies are always reported if a controller is connected.

Device Discovery

A controller needs to know the target device's IP address for communication. There are several ways to find Glensound devices on a network:

Once the device's IP address is known the controller should send a GetInfo message to the port 41161. The device will respond with a unicast Info message, revealing the device's identity.

Device Access Control

NOTE: The protocol is designed to help controlling legitimate user access and is NOT hacker-proof.

Each Glensound device stores an 8-character password in its non-volatile memory. By default, the password is null (it contains eight bytes of 0x00) and it can be remotely changed. For all control data transactions a remote controller must bit-wise XOR the password with the first 8 bytes of each packet (the 'magic' field of the GS header). Packets with invalid password are rejected, except for GetInfo and GetConfig commands.

The device always responds to GetInfo with an Info packet, which has a bit indicating whether the password in GetInfo was correct. Similarly, GetConfig always returns a Config packet, indicating whether the password was valid.

Password Change Protocol

To change the password for a device the controller must connect in Exclusive mode. Then, it needs to do the following:

  1. Send a SetPassword message, using the current valid password.
  2. Send another SetPassword message, using the new password.
  3. Send a GetConfig message (also using the new password).

The device should respond with a Config message, indicating whether the password is correct. If desired, the controller can then switch to Shared mode.

Connection Modes

A Glensound device can be in one of three connection states:

In standalone state the device does not send any packets onto the network, except for the Info and Config messages in response to GetInfo and GetConfig commands.

In connected state the device sends periodic Status and asynchronous Report messages. In Shared mode valid messages are accepted from any controller and Status and Reports are multicast. In Exclusive mode messages are only accepted from the current unique controller and Status and Reports are unicast to that controller.

The device becomes connected after accepting any of the valid message types except GetInfo. A valid message must use the correct password. The remote controller indicates the desired access mode in the header of each packet. If the controller requests exclusive access mode while the device is not connected or is connected in shared mode then the exclusive mode is granted. Any other currently connected controller will stop receiving Status and Report messages.

The connection status is reported to controllers in the headers of Info and Config messages. The accessGranted bit indicates whether the controller has control over the device. The exclusiveAccess and passwordValid bits provide additional information that can be shown in the controller's UI.

Session Keepalive

As stated above, a device becomes connected after receiving any valid message (with a valid password), other than GetInfo. The device disconnects automatically if it didn't accept a connecting message for 7 seconds.

To avoid being disconnected a controller must send a valid message (other than GetInfo) to the device, with a period shorter than 7 seconds. Typically, controllers send a GetConfig message every 5 seconds as keepalive, so they can also monitor the connection status bits.

In Shared mode any number of controllers may send periodic messages to the device. The device will disconnect about 7 seconds after the last controller stopped transmitting. In Exclusive mode only messages from the connected exclusive controller work as keepalive. If the controller times out the device disconnects and switches to the default Shared mode.

A controller can keep track of the connected devices by monitoring the time elapsed between messages received from each device. A connected device is guaranteed to send asynchronous Status messages at least every second (or 100 ms if fast meter monitoring is enabled.)

Ad-Hoc Control

It is possible to control Glensound devices without using a dedicated application by simply sending unicast UDP messages containing valid commands to the port 41161. After receiving such message, the device executes the command and switches to Connected mode for 7 seconds. While connected, it responds with status and report messages and, if there is no new command, it disconnects.

This feature allows controlling devices from a universal control console application by assigning UDP messages to UI widgets, like buttons or pots.

Controller Opcodes

The Opcode enumeration is defined in the file GsProtocol.h.

A controller can send the following opcodes:

The message has no payload and must use null password. The device responds with a unicast Info message sent back to the controller, using the sender's IP address and port.

Any controller can send this message regardless of the current connection mode (Shared or Exclusive). It does not affect the device's connection state and it doesn't count as a session keepalive.

The message has no payload. The device responds with a unicast Config message to the sender's IP address and port.

Any controller can send this message regardless of the current connection mode (Shared or Exclusive). If the controller has access granted, the message will set (or keep) the device in connected state. Otherwise it will not affect the device's connection state. This message is typically used as keepalive and is sent every 5 seconds.

The returned Config message indicates the connection status in the header bits:accessGranted, passwordValid and exclusiveAccess. If a connected controller loses access to the device (because another controller has set Exclusive mode or changed the password) the device will still respond with a Config message so that the controller will be notified about the fact. Any further communication from the evicted controller will not act as keepalive.

The message has no payload. It requests the device to send the Status message, using either unicast (in Exclusive mode) or multicast (in Shared mode). Typically there is no need to explicitly query for status, as it is sent periodically and asynchronously when the device is connected.

The message payload is a Query structure, indicating the requested report type. The device responds with an appropriate Report message, using either unicast (in Exclusive mode) or multicast (in Shared mode). Typically there is no need to explicitly query for reports, as the device sends reports asynchronously when it is connected and the report contents changed. For more details, see Reports.

The payload contains one or more control messages. Typically, a command changes the device state and the device responds with updated status and/or report. For more details, see Commands.

NOTE: with this opcode the transaction type must be single-packet - meaning that all the commands must fit in a single UDP packet payload. For changing many device parameters at once consider using Presets.

Currently, this opcode is not implemented and must not be used.

The message payload is a Password structure. See Password Change Protocol for more details.

The payload contains one or more preset structures. For more details, see Presets.

The payload contains firmware update data. For more details, see Remote Firmware Upgrade.

Device Opcodes

A device can send the following opcodes:

The payload is struct Info. This message is a unicast response to a GetInfo message from a controller. The fields in the Info structure are:

uint16_t firmwareVersion
Main device firmware (.DFU) file version in the format MMMMmmmm ssssssss (M=major, m=minor, s=subminor).
A device may contain several firmware components, each using an individual version numbering. This version number, along with the protocolVersion, productId and variantId fields, should be used by the controller to determine whether the device is supported.

uint16_t statusPortBe, uint32_t statusIpBe
Port number and IPv4 address used by the device for multicasting, in big-endian (network) order.
Currently, Glensound devices use a fixed multicast group address and port of 239.254.50.123:6111, which cannot be configured.

uint16_t productId, uint8_t variantId
Glensound-assigned unique device type identifiers.

uint8_t protocolVersion
helps the controller to determine whether (and how) it can communicate with the device. If a device's firmware is updated but the control protocol did not change this number should remain unchanged. It should be incremented if there is a breaking change in the protocol.

uint16_t flags
Bit 0: dntUpdateable. A value of 1 indicates that the device's DNT file can be updated online, using the GS protocol (currently not implemented).
Bit 1: dfuUpdateable. A value of 1 indicates that the device's main firmware can be updated online.
Bit 2: dfu2Updateable. A value of 1 indicates that the device's secondary firmware can be updated online (currently not implemented).

uint16_t danteProcessId, uint64_t danteId
Audinate-assigned identifiers of the device instance. Officially the fields are not documented but the process ID is usually zero and the Dante ID contains the MAC address of the device's primary Dante interface. Do not rely on this information.

char hostName[32] (NUL-terminated ASCII)
Host name of the device for the purposes of DNS. It is partially assigned by Audinate and considered "sufficiently" unique on the network. It contains part of the device's MAC address. Example: "Paradiso_0af9c0".

char friendlyName[32] (NUL-terminated UTF-8)
Friendly device name that can be assigned using Audinate Dante Controller or Glensound Controller. Example: "My Paradiso".

char domainName[32] (NUL-terminated UTF-8)
Name of the Audinate Dante Domain, if the device is enrolled.

Some devices also provide additional fields, appended at the end of the Info structure. Controller software receiving the Info packet should check the size of the packet to determine whether these fields are present:

uint16_t dntVersion
Dante (.DNT) file version in the format MMMMmmmm ssssssss (M=major, m=minor, s=subminor).

uint16_t dfu2Version
Version number of a secondary firmware (.DFU) file, for devices that use more than one CPU.

The payload is struct Config. It contains a copy of the statusPortBe and statusIpBe fields in the Info message. The connection status bits in the header are useful for determining whether the controller has access to the device.

The payload is a Status message, which has a device-independent and device-specific parts. This message always uses a single-packet transaction type. For more details, see Status Messages.

The payload is a sequence of one or more report structures. For more details, see Reports.

The payload is firmware upgrade progress message. For more details, see Remote Firmware Upgrade

Status Messages

When the device is connected it periodically sends asynchronous Status messages. In Shared mode this message is multicast and in Exclusive mode it is unicast. If any connected controller requests fast metering updates (see Audio Meter Updates) the status messages are sent 10 times per second, and otherwise, once per second. Status messages must fit in one UDP packet and their main purpose it to send audio metering data and current report generation numbers. Larger data structures containing device state are transmitted using Reports instead.

Status Message Format

The Status structure contains standard device-independent part and, optionally, a device-specific part defined in the device's protocol header.

uint32_t flags
uint8_t generations[4]
(device-specific generations[4 * n])
(device-specific meter data[])
(device-specific status[])
(padding to a multiple of 4 bytes)

A device type may add fields to the Status structure. In particular, it can:

Standard Status Fields

The standard fields of the Status structure are defined in GsStatus.h.

flags.identify : 1
Indicates whether the Identify button is being pressed on the device. Most Glensound devices have a button on the front or rear panel that can be pressed to identify a particular device instance on the network. A controller app (like Glensound Controller) may use this bit to highlight a UI element when the bit is set.

flags.clockLocked : 1
Indicates whether the device's main audio clock is locked and operational.

uint8_t generations[4]
Array of the current standard report generation numbers. For more details, see Reports.

Meter Data

Meter data table typically follows the report generations table. The level value format uses the Audinate convention for Brooklyn II modules and is referred to as "Dante meter format".

A level value uses one byte per audio channel. The value is expressed as the number of 0.5 dB steps down from 0 dBFS, except for 0xFF, which is reserved. For example, 0x00 is 0 dBFS, 0x01 is -0.5 dBFS and 0xFE is -127.0 dBFS.

Mapping of audio level table entries to audio channel numbers is device-specific and is documented per device.

Commands

Commands are sent (unicast) from a controller in control messages, with the purpose of setting parameters or triggering actions in the destination device. Multiple control messages may fit in a single packet. Most have a fixed size of 4 or 8 bytes and a few have variable size.

Command Message Format

Command messages may only be sent in a single-packet transaction using Opcode::SetControl. The transaction payload contains a sequence of one or more messages. A message's size is a multiple of four, with zero-padding if necessary. The command opcode indicates the message size category in its two upper bits (MSb).

Four-byte command messages:

Command opcode (0xxxxxxx)
uint8_t content[3]

Eight-byte command messages:

Command opcode (10xxxxxx)
uint8_t content[7]

Variable size command messages:

BlockHeader
uint8_t content[payloadWords * 4]

The type field in the BlockHeader structure for variable-size commands is the Command opcode (11xxxxxx). The payloadWords field is the number of 32-bit words in the message content.

Standard Commands

Standard commands are defined in GsCommands.h and are either supported or reserved by each device type (so the same opcode is never reused for a different command). Devices are not required to support all standard commands and they ignore the unsupported opcodes (see Error Handling).

Sets audio sample rate. Depending on the device type it may mean the sample rate of different components. Most devices have a single global clock but others may have a choice of clock sources with settable rate.

The message is a Value8<Srate> structure.
Note: The Srate enumeration may be extended by some devices.

Selects audio clock source.

The message is a Value8<ClockSource> structure.
Note: The ClockSource enumeration may be extended by some devices.

Sets global parameters of the AD converters.

The message is a Value8<AdcFilter> structure.
Note: The AdcFilter enumeration may be extended by some devices.

Sets global parameters of the DA converters.

The message is a Value8<DacSettings> structure.
Note: The DacFilter enumeration may be extended by some devices.

Restores factory defaults for selected components of the device.

The message is a RestoreDefaults structure with the following fields:

command = Command::RestoreDefaults
settingParts = a combination of bits defined in enum PresetSelections

Note: The PresetSelections enumeration may be extended by some devices.

Sets the name of a Dante audio channel of the device. Channel names can also be set (and examined) using the Audinate Dante Controller application.

The message is a ChannelName structure with the following fields:

command = Command::ChannelName
channelId = 7 bits of channel index in LSb and direction in the MSb (struct DanteChannelId)
header.param = 0 (reserved)
header.payloadWords = number of 32-bit words in the payload

Channel indices start from zero and are independent for input channels and output channels.

The payload is the channel name in UTF-8 encoding, limited to 32 bytes and zero-padded if necessary to the nearest multiple of four bytes. A zero-length string is allowed and it will reset the name to the default for this device type.

Reports

The reporting mechanism is used for sending infrequently changing data from device to controller. Not all device types must support it.

Reports are messages containing state of specific sub-systems within a device. They are sent asynchronously if any part of the state data changed (and a controller is connected) or can be sent in response to an explicit GetReport query. The protocol uses report generation numbers, allowing controllers to detect missing reports.

Every report type maintains an 8-bit generation number. The number is contained in the report header and also in the generations table in the periodic Status message. The table contains generation numbers for all report types. When a monitored value changes, the device increments the generation number for the relevant report type (modulo 256) and sends the report. Then it copies the report generation number to the status packet.

When a remote controller receives a report it updates the internal device model (and the UI) and records the current generation number for this report type. When a status packet arrives, the controller compares the generations of all report types with the ones contained in the status and so it can detect missing or duplicate reports. If a report is missing the controller can query the device for the missing report type, update the UI from the last received value or indicate in the UI that the value is unknown.

Report generation numbers are only incremented if there is a value change. If a report is sent as a result of an explicit query and the report contents did not change since it was last sent, its generation number remains unchanged.

Report Queries

Devices send reports asynchronously to the connected controllers whenever the relevant device state changes. A controller may also send an explicit report query message when it connects for the first time or when it detects that a report was lost or corrupted. The query may refer to a specific report type, or use ReportId::All to have the device send all the reports.

Report Format

Devices send reports using single- or multi-packet transactions using Opcode::Report. The transaction payload contains a sequence of one or more reports as follows:

BlockHeader
[report content]
BlockHeader
[report content]
...

The BlockHeader structure for report messages defines its fields as follows:

uint8_t type = enum ReportId (report type)
uint8_t param = report generation number
uint16_t payloadWords = number of 32-bit words in the report content

The enumeration ReportId has standard fields and may be extended by devices. The report content has a format depending on the report type.

Standard Reports

Standard report types are defined in GsReports.h and are either supported or reserved by all device types. Devices are not required to support standard reports but they never re-purpose their opcodes.

The content is the standard device report in the DeviceReport structure. It contains the following fields:

uint32_t sampleRate
The actual sample rate of the main device's component in Hz. Most devices use one global sample rate, typically derived from the Dante network. Some devices may have different sample rates for different components.

Srate srateChoice
The sample rate choice for the device, possibly requested from the device's user interface or a controller application. The Srate enumeration may be extended by some devices.

ClockSource clockSource
The actual clock source for the main device's component. Most devices have one global clock source - typically the Dante clock. Some devices may have several clock sources to choose from or separate clock sources for different components. The ClockSource enumeration may be extended by some devices.

ClockSource clockSourceChoice
The clock source choice for the main component of the device, possibly requested from the device's user interface or a controller application. The ClockSource enumeration may be extended by some devices.

AdcFilter adc
Global ADC settings for the device. The AdcFilter enumeration may be extended by some devices.

DacFilter dac
Global DAC settings for the device. The DacFilter enumeration may be extended by some devices.

DeviceFlags flags
Global device status flags. The DeviceFlags union, which may be extended by some devices.

The contents are Dante names of all the device's input channels ordered by channel index.

Each channel name is a Pascal-style string, in which the first byte value is the string size in bytes. If the size is non-zero, it is followed by a string of UTF-8 characters (unterminated). The message must be zero-padded after the last channel name, if necessary, so that the payload length is a multiple of four.

The contents are Dante names of all the device's output channels, in the same format as for the input channels.

Report Generations Table in Status

The standard Status structure contains a table with the current generation numbers. The entries in the table can be indexed with the values of ReportId enumeration.

The value of ReportId::Preset refers to the first entry in the table, which is the sequence number of the last applied preset (see Presets).

For standard devices, the next three entries contain report generation numbers for ReportId::Device, ReportId::InChannelNames and ReportId::OutChannelNames.

Presets

A preset is a collection of device settings that can be saved by a remote controller application and sent to the device at a later time. Devices with multiple internal components may support saving and restoring presets individually per each component. A collection of component presets is called preset set.

After connecting to a device, a remote controller receives the current device settings in Report messages and updates its internal model of the device. This model can be used for updating the application's UI and can also be saved to a file as a preset set. The application can later load the file and send one or more presets back to the device.

In most cases, the format of a preset is the same as the format of the corresponding Report. It means that a received report can be saved in binary format and later sent back to the device. There are documented exceptions to this rule. Not all Report types can be used as presets.

Preset Message Format

Presets are sent to a device in a single- or multi-packet transaction using the Opcode::SetPreset. The transaction payload contains a sequence of one or more presets as follows:

BlockHeader
[preset content]
BlockHeader
[preset content]
...

The BlockHeader structure for preset messages defines its fields as follows:

uint8_t type = enum ReportId (preset type)
uint8_t param = 0 (reserved)
uint16_t payloadWords = number of 32-bit words in the preset content

Standard Presets

Standard preset types are defined in GsPresets.h.

NOTE: Format of this preset is not the same as the Device report.
The content is the DevicePreset structure.

AdcFilter adcFilter
Global ADC settings for the device. The AdcFilter enumeration may be extended by some devices.

DacFilter dacFilter
Global DAC settings for the device. The DacFilter enumeration may be extended by some devices.

Srate srateChoice
The sample rate choice for the device. The Srate enumeration may be extended by some devices.

ClockSource clockSourceChoice
The clock source choice for the device. The ClockSource enumeration may be extended by some devices.

NOTE: There is no corresponding standard report.
The contents are Dante names of all the device's input and output channels. Input channel names are stored first, followed by output channel names, both ordered by the channel index. Devices that only have input or output channels include only the channels they have.

Each channel name is a Pascal-style string, in which the first byte is the string size in bytes. If the size is non-zero, it is followed by a string of UTF-8 characters (excluding NUL). The message must be zero-padded after the last channel name, if necessary, so that the payload length is a multiple of four. The following pseudocode shows this:

// Pseudocode!
struct ChannelNamesPresetContent
{
	struct
	{
		uint8_t length;		// Pascal-style string
		char name[length];	// UTF8, NOT null-terminated
	} rxNames[numRxChannels];
	struct
	{
		uint8_t length;		// Pascal-style string
		char name[length];	// UTF8, NOT null-terminated
	} txNames[numTxChannels];

	uint8_t padding[];		// zeroes if necessary, to the next 32-bit boundary
};

Preset Generation Number

After applying a preset, the device increments the current preset generation number and puts it in the first entry of the generations table in the Status packet. This allows remote controllers to verify that the preset was applied. The controller can check that after sending a preset to the device the preset generation number is incremented.

Factory Settings

Most devices support restoring factory settings for individual internal components. A remote controller can send a command message using Opcode::SetControl and a command of Command::RestoreDefaults. The settingsParts field of the RestoreDefaults message is an OR-ed combination of bits indicating which components to reset.

Standard Factory Settings

Standard components that can be restored to factory defaults are defined by the SettingsPart enumeration defined in GsPresets.h. Devices may extend this enumeration. Its values can be OR-ed together and used for the settingsParts field of the RestoreDefaults message.

Resets standard device settings. They include:

Resets channel names of all the Dante inputs and outputs. This restores the default names defined by the device manufacturer.

Remote Firmware Upgrade

Devices that support online firmware upgrading handle the SetUpdate and UpdateProgress opcodes. Other devices ignore them.

The process involves the following actions:

At any time before the changes are committed, the controller can cancel the update by simply not sending the remaining data.



Updated 05/May/2024