Every Command a Benshi Radio Understands: A Complete Protocol Reference

The canonical implementation lives in src/lib/radio/gaia_protocol.dart, src/lib/radio/radio_models.dart, src/lib/radio/tnc_data_fragment.dart, and src/lib/radio/radio.dart. This document describes exactly what that code does.

The big picture

Everything the app and the radio say to each other is a command — a small binary message with a group, a command id, and an optional payload. The same message shape is used for requests, replies, and unsolicited notifications. On top of that single mechanism the radio layers three conceptually different kinds of traffic:

1. Control — read/write settings, channels, volume, GPS, FM radio, buttons, trusted devices, and so on. Request/reply.
2. Notifications — the radio pushes state changes (status, channel, position, incoming packet data) without being polled.
3. Bulk sub-protocols — TNC data fragments (carrying AX.25 packets) and the GAIA VM protocol (carrying firmware images). These reuse the command envelope but define their own internal formats.

flowchart TD
    A["App"] -- "command (request)" --> R["Radio"]
    R -- "command (reply, response bit set)" --> A
    R -- "EVENT_NOTIFICATION (unsolicited)" --> A
    A -- "HT_SEND_DATA (TNC fragments)" --> R
    R -- "RX_DATA / dataRxd (TNC fragments)" --> A
    A -- "VM_CONNECT/CONTROL (group 10)" --> R
    R -- "BT_EVENT_NOTIFICATION (VMU)" --> A

Layer 1: framing

Before a command reaches the radio it must be framed for the transport. There are two framings, chosen automatically by transport type.

GAIA serial framing (Bluetooth Classic / RFCOMM)

Used on macOS, Windows, and Android, where the radio is reached over an RFCOMM serial link. Each command is wrapped in a GAIA-style header:

FF 01 CS LEN  <command bytes...>

The encoder is deliberately minimal — see GaiaProtocol.encode():

bytes[0] = 0xFF;
bytes[1] = 0x01;
bytes[2] = 0x00;          // no checksum
bytes[3] = cmd.length - 4; // payload length (data only)
bytes.setRange(4, 4 + cmd.length, cmd);

On receive, GaiaProtocol.decode() walks the RX buffer looking for FF 01. It needs at least 8 bytes to decide anything (4 header + 4 command header), reads the payload length from byte 3, reads the checksum flag (bit 0 of byte 2), and computes the total frame length as payloadLen + 8 + hasChecksum. If the whole frame is present it returns the un-framed command ([group_hi, group_lo, cmd_hi, cmd_lo, data...]) and how many bytes it consumed; if the leading bytes are not FF 01 it returns -1 so the caller can skip one byte and resynchronise.

Raw GATT framing (Bluetooth LE)

Used on web, iOS, and Linux, where the radio is a BLE GATT peripheral. Here there is no FF 01 wrapper at all — the command bytes are written directly to the characteristic and arrive directly in notifications:

<group_hi> <group_lo> <cmd_hi> <cmd_lo> <data...>

The selector is a single getter in radio.dart:

bool get _useGattFraming =>
    kIsWeb || _transport?.connectedDevice?.type == BluetoothType.ble;

Compact BLE variants. Some UV-PRO web-BLE firmware speaks a compact dialect where the 16-bit group is collapsed to a single byte and/or the command is little-endian. HTCommander auto-detects this (a tell-tale FF 01 80 02 01 error reply) and rotates through six framings (cmd16-be, group+cmd8, cmd8, cmd16-le, group+cmd16-be, group+cmd16-le) until one answers. This is a compatibility shim; the logical command set below is identical.

Layer 2: the command envelope

Once un-framed, every message has the same 4-byte header followed by an optional payload. All multi-byte integers in the header are big-endian.

+--------+--------+--------+--------+-----------------+
| group_hi group_lo | cmd_hi  cmd_lo | payload ...    |
+--------+--------+--------+--------+-----------------+
     16-bit group       16-bit command

Groups

The response bit

Replies from the radio set bit 15 (0x8000) in the command field. That is the only structural difference between a request and its reply. The parser strips it back off:

final isResponse = (cmdValue & 0x8000) != 0;
final actualCmd  =  cmdValue & 0x7FFF;

So a GET_HT_STATUS request carries command 0x0014, and its reply carries 0x8014.

Building a command

GaiaProtocol.buildRawCommand(group, cmd, data) lays the header down big-endian and appends the payload:

cmdData[0] = (group >> 8) & 0xFF;
cmdData[1] =  group       & 0xFF;
cmdData[2] = (cmd   >> 8) & 0xFF;
cmdData[3] =  cmd         & 0xFF;
// data...

Convenience helpers exist for the common payload shapes: buildCommandByte (single byte) and buildCommandInt (a big-endian 32-bit int, via RadioUtils.setInt).

Endianness helpers

Almost every field in this protocol is big-endian, and the codec funnels through four helpers in utils.dart:

The notable exception is the BSS user id, which is little-endian — a wrinkle called out explicitly in the code.

Reply layout and status byte

For basic-group replies, the first payload byte (offset 4 of the whole frame) is a status byte:

Because the header is 4 bytes and the status byte is at offset 4, the model parsers consistently read their real payload starting at offset 5 — you will see RadioUtils.getByte(msg, 5) at the top of almost every fromBytes.

The complete basic command set (group 2)

These are the RadioBasicCommand opcodes. Opcode is the 16-bit command id (shown in decimal / hex). "R" = HTCommander sends it as a request; "N" = the radio sends it unsolicited; a reply always mirrors the request opcode with 0x8000 set.

Only a subset of these are actively used by HTCommander today; the rest are defined for recognition (so an unexpected reply is named rather than shown as raw hex). The next sections give the bit-level layout for the payloads the app actually encodes and decodes.

Payload deep-dives

GET_DEV_INFO (4) → RadioDevInfo

The request payload is a single byte [3]. The reply is a fixed capability block; fields are bit-packed starting at offset 5:

productId also drives the friendly name (0x0001 → VR-N7500, 0x0002 → VR-N76, 0x0003 → SA-888S, 0x0004 → HG-UV98, 0x0005 → HAM-AIO). This reply is what tells the app how many channels and regions to enumerate.

GET_HT_STATUS (20) → RadioHtStatus

A compact live-status block. Note how several fields straddle byte boundaries — a recurring theme in this protocol.

currChId is reassembled as (upper << 4) | lower. This status arrives both as a direct GET_HT_STATUS reply and inline inside the htStatusChanged notification.

READ_RF_CH (13) / WRITE_RF_CH (14) → RadioChannelInfo

A channel is a 25-byte record (offset 5 onward in a reply; offset 0 onward in a WRITE_RF_CH payload). The frequency fields cleverly pack the modulation in the top 2 bits of a 32-bit big-endian frequency, so the frequency mask is & 0x3FFFFFFF:

Writing rebuilds the record from the fields — see RadioChannelInfo.toByteArray() — re-inserting the modulation bits into the high 2 bits of each frequency word (r[1] = (r[1] & 0x3F) | ((txMod << 6))).

READ_SETTINGS (10) / WRITE_SETTINGS (11) → RadioSettings

The densest structure in the protocol: ~40 fields packed into ~20 bytes, many split across byte boundaries. A few representative examples (see radio_models.dart for the full list):

Because so many fields share bytes, HTCommander never builds a settings block from scratch. Instead toByteArray() copies the last-read raw block (minus the 4-byte header + status byte) and overwrites only the bytes it needs to change (channel A/B, dual-channel mode, scan, squelch). toByteArrayWith(...) is the copy-on-write wrapper the app calls. This preserves every field the app does not model. After a write, the radio may or may not push a htSettingsChanged notification, so the app re-reads settings to be safe.

GET_POSITION (76) / SET_POSITION (32) → RadioPosition

An 18-byte position payload (offset 5 onward in a reply). Latitude and longitude are 24-bit signed values in an unusual unit:

degrees = raw / 60.0 / 500.0        (i.e. raw = degrees × 60 × 500)

The 24-bit two's-complement sign is handled explicitly (subtract 0x01000000 when bit 23 is set) because Dart ints are 64-bit and naive sign-extension would produce a huge positive number.

toByteArray() emits exactly these 18 bytes for SET_POSITION. The radio only transmits APRS position beacons while a positionChange notification is registered — which is why the app (re)registers it on every connect whenever GPS sharing is on.

READ_BSS_SETTINGS (33) / WRITE_BSS_SETTINGS (34) → RadioBssSettings

Beacon / location-sharing configuration, 46 bytes. The one little-endian field in the whole protocol lives here (bssUserIdLower, a LE int32 at offset 9):

(toByteArray() produces a 46-byte payload — offsets above are shown relative to the received frame, which is 5 bytes higher because of the header + status byte.)

FM broadcast: RADIO_* (24–28) → RadioFmRadioStatus

The built-in FM broadcast receiver has its own little command family:

• RADIO_SET_MODE (25): payload [2] = on, [0] = off.
• RADIO_SET_FREQ (28): big-endian uint16 in units of 10 kHz, so 91.5 MHz → 9150 → 0x23BE.
• RADIO_SEEK_UP / RADIO_SEEK_DOWN (26/27): no payload; progress arrives via notifications.
• RADIO_GET_STATUS (24) reply / radioStatusChanged notification share a layout at offset 5: [flags, 0x00, freqHi, freqLo] where flags & 0x80 = FM on, flags & 0x10 = seeking, and the frequency is a BE uint16 in 10 kHz units (so 0x290E = 10510 → 105.10 MHz).

READ_STATUS (5): battery and power

The request is [0, type] where type is a RadioPowerStatus (batteryLevel=1, batteryVoltage=2, rcBatteryLevel=3, batteryLevelAsPercentage=4). The reply payload (relative to the status byte) is [status, type_hi, type_lo, value...]; voltage is a BE uint16 in hundredths of a volt (getShort/100.0), everything else is a single byte.

Programmable functions: GET_PF (55) / SET_PF (56)

The button table maps physical buttons to effects. The GET_PF reply is a status byte followed by two bytes per slot:

byte0 = (buttonId << 4) | actionType
byte1 = effectType

actionType is a PFActionType (short/long/double/edge transitions/…) and effectType is a PFEffectType (mainPtt, toggleRadioTx, nextChannel, sendLocation, …). SET_PF sends one effect byte per slot in the same order. Because the radio commits the write asynchronously, the app waits ~800 ms before re-reading so the cached table reflects the settled state.

Region names: READ_REGION_NAME (73) / WRITE_REGION_NAME (59) / SET_REGION (60)

• READ_REGION_NAME request [index]; reply [status, index, UTF-8 name…].
• WRITE_REGION_NAME payload [index] + UTF-8 name.
• SET_REGION payload [region] — this one gets no reply (it is in the "expected response = none" list alongside REGISTER_NOTIFICATION and WRITE_SETTINGS).

APRS path: GET_APRS_PATH (72) / SET_APRS_PATH (71)

A simple variable-length UTF-8 string, e.g. "WIDE1-1,WIDE2-1". The reply is [status] + UTF-8 path. The app updates its cache optimistically on write and re-reads to confirm.

Satellite tracking: SET_SATELLITE_INFO (77) + FREQ_MODE_SET_PAR (35)

These two commands are how the manufacturer app works an amateur satellite — telling the radio which bird it is looking at and continuously steering the VFO to follow the Doppler shift. They were reverse-engineered from a capture of the original app tracking the International Space Station through its FM cross-band voice repeater (uplink 145.990 MHz with a 67.0 Hz CTCSS tone, downlink 437.800 MHz). The two commands are always sent as a pair, once per update (roughly once a second), and each gets a one-byte [0x00] success reply.

HTCommander implements this same flow: a Satellite usage lock puts the radio into tracking mode, and the satellite handler pushes a fresh SET_SATELLITE_INFO + FREQ_MODE_SET_PAR pair every second for the length of the pass (see RadioFreqModePar / RadioSatelliteInfo in radio_models.dart and Radio._onSatelliteTrackUpdate in radio.dart).

FREQ_MODE_SET_PAR (35) — the Doppler-steered VFO

This is the important one: it puts the radio into "frequency mode" (a free-tuned VFO, not a stored channel) and sets the exact receive and transmit frequencies. Its 16-byte payload uses the same field layout as the freqModeStatusChanged notification — RX freq, TX freq, sub-audio, flags — which is what let us decode it. All multi-byte fields are big-endian.

Example (first update of the ISS pass):

1a 18 42 d7  08 b3 a4 93  00 00  1a 2c  0a 03  61 a8
└── RX ────┘ └── TX ────┘ └rxSA┘ └txSA┘ └flags┘ └const┘

The 0x0a flag is load-bearing. This was confirmed against HTCommander's own implementation: sending the frame with the flags word left at 0x0000 (frequencies, sub-audio and the 0x61a8 constant all correct) does drop the radio into frequency (VFO) mode and it happily ACKs every update — but it never switches to the satellite tracking screen. Only once the high byte is 0x0a does the radio show its satellite display. HTCommander therefore sends 0x0a03 on the first two updates of a session and 0x0a00 thereafter, mirroring the capture. See Radio._onSatelliteTrackUpdate in radio.dart.

The RX and TX frequencies are what carry the Doppler correction. The app runs the orbit propagator on the phone and, each second, recomputes:

• RX = downlinkHz × (1 − rangeRate/c) (receiver Doppler)
• TX = uplinkHz × (1 + rangeRate/c) (transmit pre-compensation)

with rangeRate in km/s (positive = receding) and c = 299 792.458 km/s — the exact formulas already used by satellite_models.dart. Both numbers agree: in the sample above the downlink is 2.4 kHz low and the uplink 0.8 kHz high, each corresponding to the same line-of-sight range-rate of +1.65 km/s (the ISS receding). Over the captured segment the downlink drifts up (437.797591 → 437.797662 MHz) while the uplink drifts down (145.990803 → 145.990779 MHz) — the classic mirror-image signature of a single range-rate shrinking as the pass progresses.

SET_SATELLITE_INFO (77) — the bird and its look-angle

Sent immediately before each FREQ_MODE_SET_PAR, this names the satellite and carries the live look-angle the radio shows on its own screen. The 30-byte payload is a 20-byte name field followed by a 10-byte tracking block (big-endian fields):

49 53 53 20 28 5a 41 52 59 41 29 00 00 00 00 00 00 00 00 00  39 00  b4 00  31 fb  01 b0  0c 12
└──────────────  "ISS (ZARYA)" + NUL padding (20 bytes) ──────────────┘ └az──┘ └el──┘ └dist┘ └alt─┘ └next┘

The tracking block was originally guessed from a single capture. It has since been pinned down by driving a real radio and reading the values off its on-screen satellite display — the radio simply echoes the fields we send, so comparing sent bytes to shown numbers gave the exact scales:

This capture was of the ISS while it was below the horizon on the far side of the Earth — hence elevation −76°, and a "distance" of ~12795 km (about one Earth diameter, the straight-line chord to the antipode). The values that were once thought to be constants (39 00, b4 00, 01 b0) were simply the azimuth, elevation, and altitude holding nearly steady over the short capture. The last field is the "Next Pass" countdown the radio shows: it decremented by exactly one per second across the capture (3090 → 3089 → 3088 …), which is what gives it away as a wall-clock seconds counter rather than a physical quantity. HTCommander encodes exactly these five fields — azimuth, elevation, distance, altitude, and seconds-to-next-AOS from the orbit propagator; see RadioSatelliteInfo.toByteArray() in radio_models.dart.

All five fields are now confirmed against the radio's on-screen read-outs.

The tracking session, start to finish

The whole ISS session in the capture unfolds like this:

1. Housekeeping / setup — before tracking, the app does its normal connect chores: GET_DEV_INFO, reads every channel (READ_RF_CH), reads settings and BSS settings, GET_APRS_PATH, SET_TIME (a big-endian uint32 Unix timestamp so the radio clock is current), SET_PHONE_STATUS, a READ_STATUS battery poll, and a READ_REGION_NAME sweep.
2. Tracking loop — once the bird is selected the app enters the steady state: every ~1 s it sends SET_SATELLITE_INFO (name + look-angle) immediately followed by FREQ_MODE_SET_PAR (Doppler-corrected RX/TX), and the radio ACKs each with [0x00]. This repeats for the whole pass — 25+ update pairs in the capture.
3. Teardown — to stop tracking, the app sends a single FREQ_MODE_SET_PAR with an all-zero 16-byte payload. That drops the radio out of frequency (VFO) mode, and the radio responds with a burst of htSettingsChanged (EVENT_NOTIFICATION type 6) events as it restores its normal channel state. No "stop" SET_SATELLITE_INFO is sent — clearing the VFO is what ends the session.

sequenceDiagram
    participant A as App (phone)
    participant R as Radio
    Note over A,R: setup (dev info, channels, settings, SET_TIME, region names)
    loop every ~1 s for the whole pass
        A->>R: SET_SATELLITE_INFO (name + az/el)
        R-->>A: 0x00
        A->>R: FREQ_MODE_SET_PAR (Doppler RX/TX + 67.0 Hz tone)
        R-->>A: 0x00
    end
    A->>R: FREQ_MODE_SET_PAR (16 zero bytes)  %% stop tracking
    R-->>A: 0x00
    R-->>A: EVENT_NOTIFICATION htSettingsChanged (×N)

Notifications (EVENT_NOTIFICATION, opcode 9)

The radio pushes state changes as EVENT_NOTIFICATION frames. Byte 4 (the first payload byte) is the notification type; the rest of the frame is that notification's inline payload.

To subscribe, the app sends REGISTER_NOTIFICATION (opcode 6) with a payload that is simply a list of notification-type bytes — e.g. on connect it registers htStatusChanged and freqModeStatusChanged in one call:

_sendCommand(RadioCommandGroup.basic, RadioBasicCommand.registerNotification,
  Uint8List.fromList([
    RadioNotification.htStatusChanged.value,      // 1
    RadioNotification.freqModeStatusChanged.value // 14
  ]));

positionChange is registered with a 4-byte form [0, 0, 0, 13]. A radio power cycle clears all registrations, so the app re-applies them on every connection.

freqModeStatusChanged (14) layout

Worth calling out because it packs several fields and has a subtle "authoritative bit". Relative to the frame start:

Only the low flags byte (offset 18) reliably indicates whether the radio is in frequency (VFO) mode — the high byte can remain set after leaving VFO mode.

Sub-protocol A: TNC data (AX.25 packet radio)

Packet data does not fit in a single command, so it is fragmented. Outgoing fragments use HT_SEND_DATA (31); incoming fragments arrive as either RX_DATA (57, BLE) or the dataRxd notification (hardware AFSK path). Both directions use the same fragment format defined in tnc_data_fragment.dart.

Fragment format

The payload begins with a single control byte, then the fragment data, then an optional trailing channel-id byte:

+----------+------------------+-----------------+
| control  | data ...         | [channelId]     |
+----------+------------------+-----------------+

Decoding (fromBytes) reads the control byte at offset 5, extracts the flags and fragment id, copies the data, and — if 0x40 is set — reads the last byte as the channel id. Encoding (toByteArray) is the mirror image.

Reassembly

Fragments are numbered sequentially starting at 0. The accumulator only starts on fragment id 0, and append() merges a fragment only when its id is exactly previous + 1 and the previous fragment was not marked final; anything out of order discards the partial and restarts. When the final fragment (0x80) arrives, the completed frame is dispatched.

sequenceDiagram
    participant App
    participant Radio
    App->>Radio: HT_SEND_DATA frag#0 (0x00 | id, data)
    Radio-->>App: HT_SEND_DATA reply (ack)
    App->>Radio: HT_SEND_DATA frag#1 (0x01, data)
    Radio-->>App: HT_SEND_DATA reply (ack)
    App->>Radio: HT_SEND_DATA frag#2 (0x82, data)  %% 0x80 = final
    Radio-->>App: HT_SEND_DATA reply (ack)

Outgoing sending is strictly one-fragment-in-flight: the next fragment is only sent after the previous HT_SEND_DATA is acknowledged, and only when the radio is not already transmitting (htStatus.isInTx == false and rssi == 0, i.e. the channel is clear). Each fragment carries at most _maxMtu data bytes.

What rides inside: AX.25

The reassembled fragment data is an AX.25 frame, decoded by ax25_packet.dart. AX.25 is its own topic, but the essentials of the encoding:

• Addresses (7 bytes each): 6 callsign characters shifted left by 1 bit, plus an SSID byte carrying the command/response (C) bits and the "last address" marker in bit 0.
• Control field (1 byte for modulo-8, 2 bytes for modulo-128): encodes the frame type (I / S / U), the send/receive sequence numbers N(S)/N(R), and the poll/final bit.
• PID (1 byte): present on I-frames and UI-frames (0xF0 = "no layer 3").
• Info: the payload (e.g. an APRS message).

The C/R bits are set so that address 0 (destination) carries the command bit and address 1 (source) carries its complement, per the AX.25 spec — see the toByteArray() address loop. Connected-mode sequencing (SABM/UA/DISC, I/RR/RNR/ REJ/SREJ, retries and windowing) is handled a layer up in ax25_session.dart.

Sub-protocol B: the VM firmware-update channel (group 10)

Firmware update uses the extended command group (10) and a different opcode space, the GAIA VM protocol. Only Bluetooth Classic transports support it.

The flow is: the app sends VM_CONNECT / VM_CONTROL (each carrying VMU protocol packets in the payload), and the radio replies asynchronously by pushing BT_EVENT_NOTIFICATION events that carry the VMU responses. The extended group is routed separately in _handleCommand → _handleExtendedCommand precisely because these opcodes fall outside RadioBasicCommand. The full firmware-update state machine — image assembly, chunking, and flashing — is a story of its own, told in How a Benshi Radio Updates Its Firmware, Step by Step and Where Does the Firmware Come From?.

Encoding for extended commands reuses buildRawCommand with the 16-bit opcode laid down big-endian, then wraps in GAIA serial framing (or sends raw for GATT).

Putting it together: connect handshake

The command set makes the most sense in the order the app actually uses it. A fresh connection runs roughly:

sequenceDiagram
    participant App
    participant Radio
    App->>Radio: GET_DEV_INFO [3]
    Radio-->>App: RadioDevInfo (channel/region counts, capabilities)
    App->>Radio: REGISTER_NOTIFICATION [htStatusChanged, freqModeStatusChanged]
    App->>Radio: READ_SETTINGS
    Radio-->>App: RadioSettings
    App->>Radio: READ_BSS_SETTINGS
    Radio-->>App: RadioBssSettings
    App->>Radio: GET_APRS_PATH
    Radio-->>App: path string
    App->>Radio: READ_STATUS [0, batteryLevelAsPercentage]
    Radio-->>App: battery %
    App->>Radio: GET_HT_STATUS
    Radio-->>App: RadioHtStatus
    loop each channel 0..N
        App->>Radio: READ_RF_CH [i]
        Radio-->>App: RadioChannelInfo
    end
    loop each region 0..M
        App->>Radio: READ_REGION_NAME [i]
        Radio-->>App: region name
    end

Channel and region reads are serialized through a queue with a response-timeout watchdog and a couple of retries, because firing them all at once overruns some radios. Everything after that is event-driven: the app reacts to notifications and issues writes as the user changes settings.

Quick reference: the rules that never change

• Two framings. GAIA FF 01 CS LEN … on Bluetooth Classic; raw group/cmd/data on BLE. Chosen by transport, invisible above the framing layer.
• 4-byte header. [group16, cmd16], big-endian. Group 2 = basic, group 10 = firmware.
• Response bit 0x8000 distinguishes replies from requests.
• Status byte at offset 4 of every basic reply; real payload at offset 5.
• Big-endian everywhere — except the BSS user id (little-endian) and the fragment control byte (bit flags).
• Frequencies pack modulation in the top 2 bits; mask with 0x3FFFFFFF.
• Notifications are opt-in via REGISTER_NOTIFICATION, and reset on power cycle.
• Bulk data fragments, one in flight at a time, reassembled by sequential fragment id with a final-bit terminator.

That is the whole language a Benshi radio speaks. Everything HTCommander does — tuning channels, sharing GPS, running packet radio, updating firmware — is one of these commands, encoded exactly as described above.

Source of truth: gaia_protocol.dart, radio_models.dart, tnc_data_fragment.dart, utils.dart, and radio.dart. The browser mirror in radio.js implements the same formats for the web client.