PROTOCOL_NOTES.md

NST Protocol Notes (Phase 1)

Transport

• UDP
• Default port: 7090
• Numeric fields are little-endian

Fixed Header (20 bytes)

uint32 fields in order:

1. MessageType
2. MessageSize (payload bytes)
3. MessageCounter
4. MessageDirection (0=request, 1=ACK success, 2=ACK failure)
5. Reserved (set to 0 on send)

Implemented Read Commands

1 Get Device Information

Request: header only.

Reply payload:

• uint device_type
• uint num_input_channels
• uint num_output_channels
• char[50] device_name (ASCII, null-terminated)

2 Get Channel Names

Request: header only.

Reply payload:

• uint total_channels (X)
• uint chars_per_name (Y)
• char[X][Y] ASCII null-terminated names

3 Get Channel Gain Values

Request: header only.

Reply payload:

• uint total_channels (X)
• int[X] gains in hundredths of dB

Known gain range for validation: -3000..1500 (-30.00dB..+15.00dB).

4 Get Channel Mute Values

Request: header only.

Reply payload:

• uint total_channels (X)
• char[X] (0x00=off, 0x01=on)

7 Get Preset Status

Request: header only.

Reply payload:

• uint preset_count (X)
• char[X] usage flags (0x00=unused, 0x01=used)

8 Get Preset Name

Request payload:

• uint preset_index_0based

Reply payload:

• uint preset_index_0based
• char[64] ASCII null-terminated preset name

Channel Indexing Rules in Integration

• Protocol arrays for channels are input-first, then output.
• Group definitions target output channels only.
• User-facing output indices are 1-based.
• Absolute protocol output index:
  • num_inputs + (output_index_1_based - 1)

Error/Retry Policy (Read Path)

• Timeout: 500ms
• Retry count: 1
• Strict payload length checks enforced