Developers
Link protocol
The binary protocol between the radio and a PC, on the cable and over Bluetooth.
The binary protocol between the radio and a PC (Ferrite Console, ferrite_link.py), on the programming cable and over Bluetooth. Its rules are chapter 29 of the manual (LINK-1 and on); this is Appendix G, the wire format.
The wire format of chapter 29 (LINK-1, LINK-21 – LINK-23), as built Oct 6, 2026; protocol 3 since decision 333 (Nov 1, 2026: 2-byte zone numbers, the zone record's count, USED in parts, the raw data messages and the layouts; LINK-59 – LINK-62). Shared code: ferrite-core link.rs; the radio's side: ferrite-app link.rs; a PC reference: ferrite/tools/ferrite_link.py.
Frames. A frame on the wire is its body COBS-encoded, then a 0x00 delimiter (0x00 never appears inside). The body is type, seq, payload (up to 240 bytes), then the CRC-16/CCITT-FALSE (poly 0x1021, initial 0xFFFF) of type, seq and payload, little-endian. The PC sends a 0x00 first to take the cable (TERM-2). On Bluetooth the same bytes go over the BT513's FFE0 service, characteristic FFE1: writes (without response) of at most 20 bytes, paced for the module's 9600-baud UART (about 0.8 KB/s), and the answers as notifications in any chunking; FF31 is never used. The cable and Bluetooth each have their own session (LINK-28); a write while the other port's session is mid-write answers busy. Every request (type 0x01–0x7F) is answered with type | 0x80, the same seq, and a payload that starts with a status byte. Numbers are little-endian.
| Status | Status | ||
|---|---|---|---|
| 0 | ok | 6 | (not sent since decision 104; kept so the number isn't reused) |
| 1 | bad frame (COBS, length or CRC; type and seq echo what was readable) | 7 | busy: the store or the radio's own editor; try again shortly |
| 2 | unknown type | 8 | not found |
| 3 | bad argument | 9 | invalid: the reason follows as text (LINK-22) |
| 4 | refused: never over the link | 10 | cancelled: BACK on the progress screen; refused until END |
| 5 | not authorised: the radio's PIN lock is on; send AUTH first (LINK-30) |
| Type | Request | Answer after the status |
|---|---|---|
0x01 HELLO |
protocol (3), 8 reserved bytes (the first's bit 0: compression wanted, LINK-51), client name | protocol, largest payload, may go on (1) or AUTH first (0), firmware version (length, text), build (u8: 0 receive, 1 tx, 2 the retired tx-dry, 3 tx with Dry TX on (TX-48), plus 0x80 with the bench commands; LINK-35); then a capability byte (1 STREAM, 2 two WRITE_MANY frames in flight, 4 compressed, 8 WRITE_MANY deletes, 16 AUDIO, 32 TEXTS, 64 channel positions (what 7, LINK-53), 128 quick messages, waypoints, DTMF memories and the event log's events (what 8-10, SUBSCRIBE 8: LINK-54 – LINK-57); absent before decision 285: LINK-35.2); then a second capability byte (1 range preset skip lists, what 11: LINK-58; absent before decision 329; 2 the raw data messages and the layouts: LINK-59 – LINK-62; 4 satellites: what 12 and 13 and CLOCK, LINK-63 – LINK-65; 8 the radio record, what 14, and the APRS record with every MENU 0 5 value: LINK-66, decision 347; 16 the line commands: CMD answers, absent from a user build since decision 347); then, with that 2, the layout this firmware stores (u8: 3) and the layout the chip's data is in (u8: 3, or 2 / another version while it waits for Console, UPD-16; 255 from a raw write until the stamp and a restart, or after a move cut before its stamp: half moved, LINK-61, decision 339) |
0x02 INFO |
— | firmware version (length, text), channels (u16), zones (u16; one byte before protocol 3), presets (u8), settings record length (u16), region, callsign (length, text), build (u8, as HELLO's), the MCU's unique ID (12 bytes, LINK-35.1), then the two layout bytes (as HELLO's, LINK-62) |
| 0x03 | — | retired (TOKEN, approval tokens, until decision 104); not reused |
0x04 AUTH |
the radio's PIN, ASCII digits (4-6) | — ; refused if wrong (counted, LINK-31), busy during the 30 s wait; the cable and a radio with no PIN lock always ok |
0x10 READ |
what (1 settings, 5 APRS or 14 the radio record: read with READ, the records bigger than a frame or kept apart from the lists; LINK-21, LINK-66), index (u16), offset (u16), length (u8, up to 237) |
record length (u16), the bytes from offset; any other what (channels, zones and presets among them: READ_MANY): bad argument |
0x11 WRITE |
what (1, 5 or 14, as READ), index (u16), offset (u16), record length (u16), bytes |
— ; the parts come in order and the record is applied when the last arrives; any other what (channels, zones and presets: WRITE_MANY): refused (LINK-3) |
0x12 DELETE |
what, index (u16) | — (channels, zones, presets) |
0x15 USED |
what (2 channels, 3 zones, 4 presets, 6 contacts), first index (u16; absent: 0) | index count (u16: 4000 for channels), the first index answered (u16), then the bitmap from it, index first + i at bit i % 8 of byte i / 8, set where a record is, as many as fit (1,880; LINK-39): ask again from first + 1,880 until the count; a first index past the count: bad argument; the settings, and 7-11 (READ_MANY only): bad argument |
0x17 READ_MANY |
what (2-4, 6-11), first index (u16), count (u16; cut at the last index) | next (u16: the index to go on from; first + count, cut, when the range is done), then each record held, as many whole ones as fit: index (u16), length (u8), the record (LINK-40). Empty indexes are skipped; a channel (40 bytes) goes five to an answer |
0x18 WRITE_MANY |
what (2-4, 6-11), then records as READ_MANY gives them: index (u16), length (u8), the record, to the end of the frame |
applied (u8: how many records were applied), then for invalid the reason; busy (the record open in the radio's editor, LINK-22) and cancelled carry the count too, so the PC goes on from the one refused. A malformed frame: bad argument, nothing applied; refused before the first (busy from the other port, LINK-28; cancelled): no count. Applied one record a pass, so the answer can take a few tens of ms (LINK-41) |
0x19 STREAM |
an inner request's type (READ_MANY 0x17, HEARD 0x52, MSGS 0x53, LOG_READ 0x40, UI 0x33) and its payload (LINK-50) |
that request's answers in turn, each its own frame: type STREAM_MORE (0x1A) | 0x80 while more follow, STREAM | 0x80 for the last; seq the request's, then + 1 a frame; each payload as the inner request's answer |
0x7D Z |
(LINK-51, while compression is on) the inner request's type, the frame's count PC to radio (u8), the payload coded | answers and events likewise: type 0xFD (0x7D for an event), the inner type, the count radio to PC, the coded payload |
0x13 BEGIN |
records to come (u16) | — ; the radio shows the progress screen (LINK-9) |
0x14 END |
— | — ; the progress screen closes (a session also ends after 5 s without a frame) |
0x16 SLOT |
slot (0–2), then optionally a mask and the fields it names, in this order: 1 frequency (u32, 10 Hz, the VFO's), 2 mode (u8: 0 FM, 1 NFM, 2 AM), 4 power (u8: 0 low, 1 mid, 2 high), 8 RX tone (u16, CHAN-3's tone word), 16 TX tone (u16); 32 to the VFO (V/M) first and 64 make it the active slot, no bytes; 128 the offset: i32 and u8, the signed shift (10 Hz, 0 simplex) and 0, or the split's TX frequency and 1. No mask: a read (LINK-33, TERM-35) | slot, active (u8), channel (u16, 0-based; 0xFFFF on its VFO), frequency (u32), mode, power, RX tone (u16), TX tone (u16), offset (i32: the shift, or the split's TX frequency), flags (1 split, 2 the APRS slot, 4 scanning): 19 bytes, as it is after; invalid and the reason if refused (nothing changed) |
0x31 CMD |
a terminal command line, ASCII (LINK-34, chapter 37) | more (u8: 1, ask MORE for the rest), then the output as text, whole lines each ending \n; or invalid and the terminal's refusal. A new CMD ends one still running |
0x32 MORE |
— | as CMD's answer, the next lines; more 1 with no text: still working (a debug command waiting for the firmware), ask again shortly; nothing running: 0 and no text |
0x40 LOG_READ |
before (u32: records with a lower sequence number; 0xFFFFFFFF from the newest), optionally the most to send (u8; 0 or absent: as many as fit) | next sequence number (u32: the newest's + 1), records held (u16), how many follow (u8), then each, newest first (below; LINK-42). Nothing follows (0): no older ones |
0x20 BAUD |
rate (u32) | — ; then both switch; a HELLO at the new rate within 1 s keeps it (LINK-11) |
0x21 REBOOT |
— | — ; then the radio saves, goes quiet and resets into the bootloader (LINK-24); not authorised from Bluetooth before AUTH while a PIN lock is on, busy while transmitting |
0x30 KEY |
key (u8), action (u8), then the action's bytes. A keypad or side key (LINK-19) is stock's key code 0–21 (PF1 0, PF2 1, V/M 2, SLOT 3, ◀ 4, ▶ 5, MENU/OK 6, ▲ 7, ▼ 8, BACK 9, 1 10, 2 11, 3 12, * 13, 4 14, 5 15, 6 16, 0 17, 7 18, 8 19, 9 20, # 21), then the action: 0 up, 1 down, 2 short press, 3 long press (held 750 ms). 0x81 the knob (LINK-19): then the steps, i8, + clockwise, 1–20 either way. 0x80 remote PTT (LINK-20): action 1 on, then the slot (0xFF the active slot, 0–2 A–C); 2 keepalive, at least every 2 s; 0 off. Any other key (the PTT codes 24–26 too) or a malformed one: bad argument |
a key or the knob: — ; busy while a long press is held or the store writes (send it again), invalid and the reason while the radio transmits; on: the slot keyed (u8), or invalid and the reason; keepalive: — while keyed, else invalid and why it ended ("ended: no keepalive for 2 s", "ended: PTT pressed on the radio", ...), or "keyed from the other port" when the other port's session keyed (LINK-28: on too); off: — , always ok, from either port. Sent without waiting for earlier KEY answers: on the cable they leave only after the unkey (TX-43) |
0x33 UI |
optionally a byte: 0 (or nothing) what the screen shows, 1 the key names, 2 the compact status (LINK-19) | as CMD's answer: more (u8), then text lines, MORE for the rest; the terminal's ui / ui keys / ui status text (2: one line, more 0) |
0x50 SUBSCRIBE |
mask (u8: 1 stations heard, 2 messages, 4 Live View, 8 the event log (LINK-57, from radios whose HELLO says 128); 0 ends), optionally the UI's least gap (u8, 100 ms units; 0 or absent: 5 on Bluetooth, 2 on the cable), flags (u8: 1 renew: keep the subscription as it is, a keepalive; LINK-46) |
mask, the Live View dictionary's version (u8: 1). A mask with 4 and no renew starts Live View over with the whole state |
0x51 EVENT |
never sent by the PC (answered unknown type) |
radio to PC, unasked: a frame of type 0x51 itself (the radio sends no requests, so a type below 0x80 from it is always an event), seq the session's event counter, the payload a kind (u8) and its bytes, no status byte (below; LINK-46) |
0x52 HEARD |
first index (u8; absent: 0) | count (u8), then stations from that index, as many whole ones as fit (below; LINK-44) |
0x53 MSGS |
first index (u16; absent: 0) | count (u16), then messages from that index, newest first, as many whole ones as fit (below; LINK-44) |
0x54 MSG_SEND |
to (length, text: 1-9 capitals, digits, -), text (length, text: 1-67 printable, no vertical bar, tilde or open brace) |
APRS mode on (u8: 1 it goes at the next turn, 0 it waits for APRS mode); invalid and why: a receive-only build, no callsign, a bad address or text; busy: the queue is full (LINK-45) |
0x61 DATA_READ |
op (u8), then: 0 READ address (u32), length (u8, 1-232); 1 CRC address (u32), length (u32) |
READ: the bytes; CRC: the CRC-32 (u32; CRC-32/ISO-HDLC: reflected, poly 0xEDB88320, init and final XOR 0xFFFFFFFF, as the layout header's). A range touching calibration (0x00F000-0x00FFFF) or reaching 0x300000: refused; length 0 or over 232, another op or shape: bad argument; busy while the store has writes to make. Both ports (LINK-59) |
0x62 DATA_WRITE |
op (u8), then: 0 ERASE address (u32, a multiple of 4096); 1 PROGRAM address (u32), 1-64 bytes inside one 256-byte page; 2 STAMP layout (u16: 3) |
— , queued for the Storage task (done in order; a DATA_READ answers busy until it is). Calibration or the update area: refused; misaligned, across a page, empty: bad argument; STAMP of another layout: invalid and why; busy: the other port writes, or the queue is full (send it again). From Bluetooth: refused. The first one stops the store's own records until a restart (LINK-61). STAMP: the header sector erased and the layout 3 header written (below), then the radio restarts, as after REBOOT (LINK-62) |
0x63 CLOCK |
optionally UTC seconds (u32, 2020-2099) | UTC seconds now (u32; 0 no time yet), the clock's source (u8: 0 none, 1 GPS, 2 set by hand or over the link). With seconds: the clock set as 0 6 6 sets it by hand (GPS-23; GPS time takes over at the next fix while 0 6 6 says "from GPS"); out of range or another length bad argument. Only from radios whose second capability byte says 4 (LINK-65) |
0x60 STOCK_RESTORE |
op (u8), then: 0 START (nothing; the cable only, not while transmitting); 1 ERASE sector address (u32); 2 PROGRAM address (u32), 1-128 bytes within one 256-byte page; 3 CRC address (u32), length (u32); 4 FINISH |
START: chip size (u32), the calibration sector's CRC-32 (u32), range count (u8), each range's start and end (u32), then the MCU's unique ID (12 bytes, its three words little-endian, lowest first; decision 263): the radio stops and serves only these requests until it resets (other types: busy). ERASE/PROGRAM: refused outside the ranges, in calibration or the update area; bad argument misaligned. CRC: the CRC-32 (u32). FINISH: then the radio resets into the bootloader, saving nothing (BACKUP-7, decision 261) |
Records (what; the same layouts the radio stores):
| What | Index | Layout |
|---|---|---|
| 1 settings | 0 | The settings record (ferrite-app persist.rs, the Settings fields in order, the flag byte, then the power-on message), under 512 bytes; the PIN reads as zeros (32 spare bytes, once the approval tokens, are zeros too); protected fields kept on write (LINK-21) |
| 2 channel | 0–3999 | number (u16), zone (u16, 0xFFFF none; one byte, 255 none, before protocol 3), RX (u32, 10 Hz), name (16 bytes, 0-padded, printable ASCII; characters outside the name set are written as -, CHAN-31), the slot settings (mode, narrow, RX tone, TX tone, offset, power, step, squelch, busy, reverse and split flags), flags (skip 1, APRS 2, RX only 4), end tone and tail (1 byte as record byte 31, TONE-17; a writer may leave it off: Global): 41 bytes (40 before protocol 3). A zone with its 256 channels already (CHAN-35): invalid "zone: full (256 channels at most)" |
| 3 zone | 0–511 (the next one creates) | name (16 bytes), scan all, shown, by distance, resume, dwell, a reserved byte (0; it was smart scan), priority channels (2 × u16, 0xFFFF none), then (protocol 3) its channel count (u16, read only: a write may leave it off, and one sent is ignored; CHAN-36): 28 bytes read, 26 or 28 written |
| 4 range preset | 0–15 (the next one creates) | name (12 bytes), start, end (u32, 10 Hz), step, mode, narrow, resume (0 Global, 1–10 s, 11 carrier drop, 12 stop on hit; a record written without it reads as Global); its skips stay the radio's |
| 5 APRS settings | 0 | frequency (u16, 5 kHz units; 0 the region's), beacon mode (0 off, 1 manual, 2-9 every 1, 2, 5, 10, 15, 20, 30, 60 min, 10-16 every 0.1, 0.2, 0.5, 1, 2, 5, 10 km, 17 smart; bit 7 paused, the mode kept), power (0 low, 1 mid, 2 high), path (0 none, 1 WIDE1-1, 2 WIDE1-1,WIDE2-1, 3 custom, only once one is set), digipeater (bit 0 on, bit 1 my callsign too, bits 4-6 the wait 0-5 s), beacon after voice (0, 1), SSID (0-15), custom path (16 bytes, 0-padded), FX.25 on transmit (0 off, 16, 32, 64 check bytes; APRS-45), then (decision 347) the message sound (an index into the chimes, APRS-6.1), symbol (APRS-47), TX delay (10-100, 10 ms units, APRS-48), TX level (0-2, APRS-49), the comment (40 bytes, printable ASCII, 0-padded, APRS-50), ambiguity (0-4, APRS-51), Mic-E (0 off, 1-7, APRS-52), telemetry (0, 1, APRS-54): 72 bytes, written whole and checked as MENU 0 5's editors check (LINK-43; a 25- or 24-byte record keeps the radio's values past its end) |
| 6 contact | 0–1015, in callsign order (APRS-37) | callsign (10 bytes, 0-padded), name (12 bytes, 0-padded), flags (bit 0: delete). WRITE_MANY adds or renames by callsign whatever the index (use 0xFFFF) and deletes with bit 0; a full book answers invalid "1016 contacts" |
| 7 channel position | 0–3999, the channel's number | latitude, longitude (i32 each, little-endian, degrees x 1e7, north and east positive): 8 bytes, as the channel record stores them (CHAN-2). READ_MANY lists only the channels that have one (23 to an answer); WRITE_MANY sets it, or clears it with a record of length 0; out of range (latitude beyond ±90, longitude beyond ±180) answers invalid, another length bad argument; no channel at that number: nothing changes. USED of it: bad argument. Only from radios whose HELLO says 64 (LINK-53) |
| 8 quick message | 0–8 (TEXT-7) | flags (u8: 1 the owner's own text; 0 the factory text), then the text (0-67 bytes). READ_MANY lists all nine, with the text the radio uses. WRITE_MANY with flag 1 sets the text (printable, no vertical bar, tilde or open brace; empty stays empty), with flag 0 puts the factory text back (any text sent is ignored); a bad text answers invalid, an empty record bad argument, index 9 or more not found (LINK-54) |
| 9 waypoint | 0–2031, newest first (GPS-10) | name (16 bytes, 0-padded, printable ASCII, at least 1), latitude, longitude (i32, degrees × 1e7), source (u8: 0 marked, 1 APRS, 2 link, 3 grid): 25 bytes. WRITE_MANY at an index in the list replaces that waypoint in its place; at 0xFFFF adds one as the newest (invalid "2032 waypoints" when full); a record of length 0 deletes the one at that index. Each record is applied after the one before it is stored, so indexes are the list as the earlier records left it: delete from the highest index down, then replace, then add. Bad name, position or source: invalid and the reason; another length bad argument; an index past the list not found (LINK-55) |
| 10 DTMF memory | 0–15 (DTMF-12) | the symbols (length u8, then 1-16 of 0-9 A-D * # as ASCII; lower case is taken as capitals), then the name (the rest: up to 10 printable bytes; none for no name). READ_MANY lists only the memories set. WRITE_MANY sets both, writing each only when it changed; a record of length 0 clears the memory and its name; bad symbols or name: invalid and the reason (LINK-56) |
| 11 range preset skips | 0–15, the preset's index (as 4) | the skipped frequencies (u32 each, 10 Hz), 0-48 of them (SCAN-10), blank entries left out (LINK-58.1). READ_MANY lists the presets that have any. WRITE_MANY replaces the list (length 0 clears it); a frequency outside the preset's start and end, or twice, answers invalid and the reason; a length not a multiple of 4 bad argument; no preset at that index not found. The list is kept in the preset's record: it stays with its preset when another is deleted, and goes with it when it is (LINK-58) |
| 12 satellite | 0–31, the place (SAT-2) | status (u8: 0 active, 1 inactive, 2 unknown), flags (u8: 1 half duplex to start, 2 Doppler on the 70 cm side only to start), transponders used (u8, 0-5), 0, NORAD catalogue number (u32), name (16 bytes, printable ASCII, NUL-padded, at least 1), the elements: epoch (u32, seconds since 2000-01-01 00:00 UTC; u16 milliseconds; 2 bytes 0), inclination, RAAN, argument of perigee, mean anomaly (u32 each, 1e-7 degree), eccentricity (u32, 1e-7), mean motion (u32, 1e-8 revolution a day), B* (f32), 12 bytes 0; then 5 transponders of 16 bytes: uplink (u32, 10 Hz; 0 receive only), downlink (u32, 10 Hz), access tone, arming tone (u16 each, 0.1 Hz; 0 none), kind (u8: 0 voice, 1 APRS, 2 beacon), 3 bytes 0 (unused ones all 0): 152 bytes (ferrite-core sat::wire). READ_MANY lists the places held. WRITE_MANY puts a satellite in its place (its choices, trim, duplex, transponder and power, stay with its catalogue number); length 0 deletes the one there; length 0 at 0xFFFF deletes them all (one rewrite of the region, so the list written after it only programs erased bytes: Console writes a whole list as that, then places 0, 1, ... in order). A transponder outside 144–148 or 430–440 MHz (SAT-13), more than 5, a bad name, status, kind or elements: invalid and the reason; another length bad argument; busy while the record before is still being written (send it again). Only from radios whose second capability byte says 4 (LINK-63) |
| 13 satellites' info | 0 | declination at the radio (i16, 0.1 degree, east positive; 0x7FFF none, SAT-18), 2 bytes 0, the satellite data's build time (u32, UTC seconds: sats.json's built), when Console wrote it (u32, UTC seconds), 4 bytes 0: 16 bytes. READ_MANY gives it when one is kept; WRITE_MANY writes it, length 0 clears it; a declination past ±180° invalid (LINK-64, SAT-21) |
| 14 radio record | 0 | Watch (u8, 0 1 1: 0 off, 1 A+B, 2 A+B+C), Battery Save (u8, 0 7 7 1: 0 off, 1-3), the GPS fix (u8: 0 none, 2 2D, 3 3D; read only), the message sound (u8, 0 7 5 5: an index into the chimes), latitude, longitude (i32 each, degrees × 1e7, north and east positive: the fix, or the fixed position 0 6 9 when there is none and it is on, GPS-3; read only), the fix's age (u16, seconds; 0xFFFF none): 14 bytes (LINK-66, decision 347). READ and WRITE (index 0); a write takes Watch and Battery Save, and the message sound when it is 4 bytes or more, each as the menu changes it. |
Event log records (LOG_READ, LINK-42; the log screen's fields, INBOX-6): sequence number (u32), age (u32, seconds before the answer: the radio's clock has no date before GPS or a hand-set time, so the PC dates it from its own), source (u8: 0 APRS, 1 Pager, 2 SAME, 3 DSC, 4 AIS, 5 DTMF, 6 Selcall, 7 GPS), slot (u8), flags (u8: 1 unread, 2 a position follows), frequency (u32, 10 Hz), ID (u32), x (u16), y (u16): 23 bytes; then latitude and longitude (i32 each, degrees x 1e7) when flag 2 is set; then the name (length u8, up to 20 bytes) and the text (length u8, up to 64 bytes). At most 117 bytes, so an answer holds at least two. What ID, x, y, name and text hold depends on the source:
| Source | ID | x, y | name | text |
|---|---|---|---|---|
| APRS | from | the message | ||
| Pager | capcode | baud, function | the message | |
| SAME | the header | |||
| DSC | MMSI | category (0 routine, 1 safety, 2 urgency, 3 distress) | nature or the call | |
| AIS | MMSI | course (degrees), speed (0.1 kn) | vessel | |
| DTMF | the sequence | |||
| Selcall | unit ID | format | what it sent |
APRS records (HEARD, MSGS and their events; LINK-44). A station: flags (u8: 1 a position follows, 2 course and speed, 4 altitude), callsign (length, text), symbol (u8: 0 car, 1 home, 2 digi, 3 weather, 4 handheld, 5 iGate, 6 truck, 7 boat), age (u32, seconds), times heard (u16), then the latitude and longitude (2 × i32, degrees × 1e7), course (u16, degrees) and speed (u16, km/h), altitude (i32, m) as the flags say, the path (length, text: the digipeaters, the used one marked *; empty when heard direct), the comment (length, text, up to 40). A message: in (u8: 1 to us, 0 ours), state (u8: 0 unread, 1 read, 2 pending, 3 acked, 4 retrying, 5 failed, 6 rejected: APRS-34; a reader shows a value it doesn't know as unknown), tries (u8, while retrying), age (u32, seconds), who (length, text: from, or to), the text (length, text).
Events (EVENT's payload, LINK-46): kind 1 a station heard: the heard list's count (u8), the station. Kind 2 a new message, in or out: the count (u16), the message. Kind 3 a message's state changed: the count (u16), the message as it is now. Kind 4 Live View: below. Kind 5 an event logged (LINK-57): the record as LOG_READ gives it (below), its sequence number first; oldest first, each once.
Live View (kind 4, LINK-47, LINK-48; shared code: ferrite-core liveview.rs, a client in tools/ferrite_link.py's LiveView). The compact form is the UI readback's lines (up to 48) less state's frame= and ago=, each line cut after its last whole token that fits 230 coded bytes. A line's tokens are split at the spaces outside double quotes (inside them a backslash escapes the next byte); joining them with one space gives the line. Text on the wire is coded: a byte 0x01-0x1F stands for that entry of the dictionary (version 1), any other byte for itself:
1 row␣ |
2 "␣" |
3 ␣sel |
4 ␣dot |
5 ␣grey |
6 card␣ |
7 ␣active= |
8 ␣head=" |
9 "␣state=" |
10 ␣freq= |
11 ␣name=" |
12 "␣mode=" |
13 "␣tone=" |
14 "␣shift=" |
15 "␣power=" |
16 "␣s="S |
17 "␣meter= |
18 ␣rx= |
19 ␣scan= |
20 ␣kind=slot |
21 hints␣" |
22 screen␣ |
23 "␣title=" |
24 bar␣lock= |
25 ␣watch= |
26 ␣inbox= |
27 ␣battery= |
28 ␣clock= |
29 state␣dark= |
30 ␣keyed= |
31 qmenu␣" |
(␣ is a space.) An update: seq (u8), flags (u8: 1 the whole state: drop every line first; 2 more follows soon: the check isn't valid yet), check (u16: FNV-1a 32 over every line, each followed by \n, its low 16 bits), lines (u8: the count after; new lines start empty), then ops to the end, each led by a byte whose top two bits are the op and the low six the line:
- 0 LINE: length (u8), the line, coded.
- 1 TOKENS: the line's token count after (u8), entries (u8), then each entry: token index (u8; bit 7: the value only, the token's key up to its first
=is the one there), length (u8), the token or the value, coded. Tokens past the count go; new ones start empty. - 2 TOKENS with the count unchanged: as 1 without the count byte.
A client applies an update only if it carries the whole state or the seq after the last one it applied, then, unless more follows, checks its lines against the check; otherwise (a lost or late update, a mismatch) it sends SUBSCRIBE without renew and gets the whole state. The radio diffs against what it last sent this session (1 KB of the lines' text, longer screens' lines by hash and then sent whole), so an update is exact. A meter moving on one card is one op of 11 bytes (op 2 on the card's line, two entries: s='s value "S3" and meter='s), 17 with the kind and header, 23 on the wire.
Layouts and the update (LINK-59 – LINK-62, UPD-16, decision 333). What Console needs to move a radio's data from layout 2 to layout 3 with DATA_READ and DATA_WRITE alone; shared code: ferrite-core layout.rs (the map), ferrite-store records.rs (the records), store.rs (the header), logs.rs (the rings). Little-endian throughout; CRC-16 is CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF, no reflection, no final XOR), CRC-32 is CRC-32/ISO-HDLC (as DATA_READ's).
Layout 3, the chip by address (4 KB sectors; never written: calibration and the update area):
| Address | Size | Region | Address | Size | Region |
|---|---|---|---|---|---|
| 0x000000 | 4 KB | Layout header | 0x058000 | 32 KB | APRS contacts: 1,016 (127 a sector) |
| 0x001000 | 8 KB | Settings and slots, copies A and B | 0x060000 | 64 KB | APRS heard ring: 496 (31 a sector) |
| 0x003000 | 4 KB | User trims | 0x070000 | 64 KB | APRS message ring: 496 |
| 0x004000 | 4 KB | Range presets and DTMF memories | 0x080000 | 64 KB | GPS waypoints: 2,032 (127 a sector) |
| 0x005000 | 4 KB | HF state (planned) | 0x090000 | 64 KB | Text pack (an SPI part, UPD-21) |
| 0x006000 | 8 KB | Satellites (planned) | 0x0A0000 | 64 KB | Packet mailbox (held) |
| 0x008000 | 16 KB | SSB patch | 0x0B0000 | 64 KB | Dictionary: predictive text's words (decision 345); then 0x0C0000, 1,024 KB free |
| 0x00C000 | 8 KB | Free: config growth | 0x1C0000 | 512 KB | Language packs (planned) |
| 0x00E000 | 4 KB | Migration mark (decision 339) | |||
| 0x00F000 | 4 KB | Factory calibration: never written | 0x240000 | 256 KB | Boot animation and screens (planned) |
| 0x010000 | 256 KB | Channels: 4,000 (63 a sector) | 0x280000 | 256 KB | Fonts (planned) |
| 0x050000 | 20 KB | Zones: 512 (127 a sector) | 0x2C0000 | 128 KB | Event log ring: 992 |
| 0x055000 | 12 KB | APRS settings and quick messages, A and B (and a spare sector) | 0x2E0000 | 128 KB | Scratch ring (32 sectors) |
| 0x300000 | 1 MB | Update area: never written |
The layout header (20 bytes at 0x000000, the rest of its sector erased): magic (u32 0x54525246, the bytes 46 52 52 54), layout (u16: 3), 10 installer bytes (erased, 0xFF; bytes 6-9 later hold the calibration sector's CRC-32, which the firmware programs into them, CAL-7), CRC-32 (u32) of bytes 0-15 with bytes 6-9 taken as 0xFF. Layout 2 had the same header at 0x02C000 with layout 2. The radio writes it, never Console (raw writes to it are refused): the format, or the begin before a power-on's first raw write (decision 339).
The migration mark (decision 339; 16-byte records at 0x00E000, 256 places, raw writes refused): magic (u32 0x564D5246, the bytes 46 52 4D 56), the layout found (u16), this layout (u16: 3), 4 bytes erased, CRC-32 of bytes 0-11. Before the first raw write of a power-on the radio programs one into the first erased place (none left: the sector erased first) unless a valid one is there, then the layout 3 header at 0x000000 unless a good one is there (that sector erased first if it holds anything else), each read back. A valid mark means a move not stamped: the radio waits for Console (UPD-16) whatever the header says, and says the chip's layout as 255. STAMP checks the header and clears the mark, programming its 16 bytes to zero (no erase), taken only once the store has nothing queued or being written. So the chip always holds the old header, or the mark, or (stamped) the new header and all the data.
The channel record (64 bytes; channel n at 0x010000 + (n / 63) × 4096 + (n % 63) × 64; each sector's last 64 bytes free): 0 RX (u32, 10 Hz; 0xFFFFFFFF: empty), 4 TX (u32: 0 the same as RX; else the absolute TX frequency, a split when flag bit 10 is set), 8 mode (0 FM, 1 NFM, 2 AM, 3-5 HF modes, CHAN-23, CHAN-26), 9 narrow (0, 1), 10 power + 1 (0 default), 11 step + 1 (0 the band's), 12 RX tone (u16, CHAN-3), 14 TX tone (u16), 16 flags (u16: bits 0 skip, 1 APRS, 2 RX only, 3 busy lockout, 5 talkaround, 6 hidden, 7 has position, 8 priority, 9 reverse, 10 split; 4 and 11-15 kept as they are), 18 the zone's low byte, 19 squelch (0 Global, 1-10 levels 0-9), 20 latitude and 24 longitude (i32, 1e-7 degree; 0x7FFFFFFF none), 28-30 kept, 31 end tone (bits 0-2) and tail (bits 3-4), 32 name (16 bytes, 0-padded), 48-59 kept (48 is 0 in a new record, 49-59 0xFF), 60 version (2), 61 the zone's high byte, 62 CRC-16 (u16) of bytes 0-61. The zone is u16 0-511, 0xFFFF none. It holds a channel when the RX isn't 0xFFFFFFFF, the CRC agrees, byte 60 is 2 and the zone is 0-511 or 0xFFFF. Version 1 (layout 2): byte 60 1, byte 61 0xFF, the zone the one byte 18 (0-253, 255 none).
The zone record (32 bytes; zone z at 0x050000 + (z / 127) × 4096 + (z % 127) × 32): 0 name (16, 0-padded), 16 flags (bit 0 scan all, 1 shown in ◀▶, 2 sort by distance), 17 resume (0 Global, 1-10 s, 11 carrier drop, 12 stop on hit), 18 dwell, 19 0, 20 priority 1 and 22 priority 2 (u16 channel numbers, 0xFFFF none), 24 the channel count (u16, CHAN-36; 0xFFFF in layout 2), 26-29 0xFF, 30 CRC-16 of bytes 0-29. Empty when bytes 0-29 are all 0xFF or the CRC disagrees. Zones exist from 0 up to the last record held (a deleted earlier one stays as an empty, unnamed zone).
Layout 2 to 3 (Console, from its copy of 0x02C000-0x08CFFF and layout 2's scratch ring 0x1E0000-0x1FFFFF). First, layout 2's own recovery: a scratch sector whose last 32 bytes (at offset 4064) start with a valid footer (magic u32 0x52435346, the target address u32, the CRC-32 of the sector's first 4064 bytes, a CRC-16 of those 12 footer bytes) has its 4064 bytes put over its target sector in the copy. Then, region by region (each layout 3 region erased whole, then its bytes programmed; 64-byte pieces that are all 0xFF can be skipped):
| Layout 2 | Layout 3 | How |
|---|---|---|
| Header 0x02C000 | 0x000000 | Not copied: the radio writes layout 3's before the first raw write, behind the migration mark; STAMP clears the mark, last |
| Settings A 0x02D000, B 0x02E000 | 0x001000, 0x002000 | Each sector copied as it is (the record holds no address; the firmware reads its slots' one-byte zones, state version 1, and saves version 2 later) |
| Channels 0x02F000-0x03EFFF (0-999) | 0x010000-0x01FFFF | Each record holding a channel (version 1, as above): byte 61 the zone's high byte (0x00; 0xFF for none), byte 60 2, the CRC again; at the same offset from its region's start (the same number). Any other slot stays erased |
| Zones 0x03F000-0x040FFF (0-253) | 0x050000-0x050FFF | Each record held: bytes 24-25 its channel count after the translation, the CRC again; at the same offset. A zone with more than 256 channels (layout 2 had no limit; CHAN-35) keeps its first 256 by number; the rest go, 256 at a time, to new zones after the last (a copy of its record named with " 2", " 3" and so on, cut to 16 characters), their channels' zone set to it; with no zone number left (512), to no zone |
| Presets and DTMF 0x041000 | 0x004000 | Copied |
| Spare 0x042000 | (none) | Dropped |
| APRS settings A 0x043000, B 0x044000 | 0x055000, 0x056000 | Copied |
| APRS messages 0x045000-0x04AFFF (186) | 0x070000-0x07FFFF (496) | Each record held (128 bytes: seq u32 at 0, magic E7 01 at 8, CRC-16 at 126; record seq s sits at slot s % capacity, 31 a sector, the sector's last 128 bytes free) to slot s % 496 of layout 3's ring: sector slot / 31, offset (slot % 31) × 128, its bytes unchanged |
| Event log 0x04B000-0x06AFFF (992) | 0x2C0000-0x2DFFFF (992) | The 32 sectors copied in order (the same capacity, the same slots) |
| SSB patch 0x06B000-0x06EFFF | 0x008000-0x00BFFF | Copied (the firmware checks its SHA-256) |
| Trims 0x06F000 | 0x003000 | Copied |
| Waypoints 0x070000-0x073FFF | 0x080000-0x083FFF | Copied (packed from slot 0, 127 a sector, as before) |
| Contacts 0x074000-0x075FFF | 0x058000-0x059FFF | Copied |
| Mailbox (free) 0x076000-0x081FFF, stock's record 0x082000, satellites and HF state 0x083000-0x084FFF | (none) | Nothing (stock's record is in the install's backup) |
| Heard 0x085000-0x08CFFF (248) | 0x060000-0x06FFFF (496) | As the messages: each record held to slot seq % 496 |
| Voice prompts 0x200000-0x2FFFFF | (none) | Not read (in the install's backup); layout 3's event log and scratch ring are there: erase the scratch ring's 32 sectors too |
Then the sector of layout 3 that holds layout 2's header (0x02C000, channel sector 28) last, then STAMP with layout 3: the radio restarts, checks every zone's count against its channels (CHAN-36) and comes up with the settings, slots, channels and lists as they were.
Constants in the firmware
Every message type, record kind, capability bit and limit, as ferrite-core/src/link.rs defines them (its doc comment beside each). The text above is the spec; this table is what the firmware builds with.
(top level)
| Name | Value | Meaning |
|---|---|---|
PROTOCOL |
3 |
The protocol version in HELLO and its answer. 2: no approval tokens; AUTH with the radio's PIN (decision 104). 3 (decision 333): zone numbers are 2 bytes (the channel record, INFO's zone count), a zone record ends with its channel count, and the raw SPI data messages (DATA_READ, DATA_WRITE) are there. |
MAX_PAYLOAD |
240 |
The most payload in a frame (BLE chunks stay small: LINK-16). |
MAX_BODY |
MAX_PAYLOAD + 4 |
The most body bytes: type, seq, payload, CRC. |
MAX_WIRE |
MAX_BODY + MAX_BODY / 254 + 2 |
The most bytes a frame takes on the wire: COBS adds one byte per 254, plus the delimiter. |
ANSWER |
0x80 |
Answers carry the request's type with this bit set. |
LOG_FIXED |
23 |
A LOG_READ record's fixed part (LINK-42): sequence number (u32), seconds ago (u32), source (u8), slot (u8), flags (u8: LOG_UNREAD, LOG_POS), frequency (u32, 10 Hz), id (u32), x (u16), y (u16). |
LOG_UNREAD |
1 |
A LOG_READ record's flags: not yet read on the radio. |
LOG_POS |
2 |
The record has a position: latitude and longitude (i32 each, degrees x 1e7) follow the fixed part. |
SAT_LEN |
crate::sat::wire::REC_LEN |
A satellite record's length (LINK-63). |
SAT_INFO_LEN |
crate::sat::wire::INFO_LEN |
The satellites' info record's length (LINK-64). |
RADIO_LEN |
14 |
what::RADIO's length. |
SATS_MAX |
32 |
The most satellites (SAT-2). |
PRESET_SKIPS_MAX |
48 |
A range preset's skipped frequencies at most (SCAN-10, LINK-58). |
QUICK_OWN |
1 |
A quick message record's flags (LINK-54): the text is the owner's own (clear: the factory text). |
WAYPOINT_LEN |
25 |
A waypoint record's length (LINK-55). |
ADD |
0xFFFF |
WRITE_MANY's index for a new waypoint (LINK-55): added as the newest. |
BT_BAUD |
9_600 |
Bluetooth's UART rate (LINK-25, decision 152): the BT513 module's resting rate, 9600 8N1. Stock V0.27 sends its KISS(BLE) frames to the module at 9600 (0x08016EEC: USART1 restarted at 0x2580 through 0x08023F68, the frame written, then back to 115200); stock's own 115200 is for its CPS programming (most likely the vendor's app sets the module to 115200 first: its FF31 handshake carries a rate byte). |
BT_FAST |
115_200 |
Bluetooth's fast rate (LINK-25.1, decision 285): the module's UART after the per-connection speed unlock (FF31, selector 02), which a host writes once the radio has agreed to BAUD 115200 on Bluetooth. The module keeps it across BLE connections and loses it when powered off (bench, Oct 24, 2026: docs/research/ble-speed.md). |
BT_RATES |
[BT_BAUD, BT_FAST] |
The rates BAUD takes on Bluetooth (LINK-15.1): the module's resting rate and the unlocked one. |
DEFAULT |
BtPace { burst: 20, gap_ms: 50 } |
One notification's worth, then a 50 ms gap: about 280 B/s at 9600 (a burst is on the wire 21 ms). The BT513 sends what piled up only after its UART has been quiet for between 30 and 40 ms, and then only the last notification's worth: 30 ms lost every UI readback on the bench, 40 ms lost none (LINK-36). |
FAST |
BtPace { burst: 160, gap_ms: 100 } |
At BT_FAST (LINK-36.1): 160-byte bursts, 100 ms apart (about 1.6 KB/s). The module takes bursts of about 160 bytes at 115200 but passes on only about 1.6 KB/s on average to a Mac (6-8 notifications every ~30 ms interval, some intervals missed), and still forwards only after its UART has been quiet: 160 B every 50 ms lost about 1 reply in 3, and a steady trickle of 20-byte pieces at 1.6 KB/s lost 7 of 10; 80 B / 50 ms and 160 B / 100 ms passed 10 of 10 (bench, Oct 24, 2026). |
MAX_GAP_MS |
1_000 |
The longest gap bt pace takes. |
RATES |
[115_200, 230_400, 460_800, 921_600] |
Cable rates BAUD may ask for (LINK-11); the radio takes one only if its UART reaches it within 2 %. |
build
| Name | Value | Meaning |
|---|---|---|
RECEIVE |
0 |
Receive only: no transmit code (no tx feature). |
TX |
1 |
Transmits (--features tx). |
TX_DRY |
2 |
The retired tx-dry build (the PA drive held at 0 at build time; decision 193): no image sends it now, kept so the tools still name a radio that runs an older one. |
TX_DRY_ON |
3 |
A transmit build with Dry TX on (TX-48): the PA drive held at 0 until it is turned off on the radio, or (the tx build) the radio is powered off; the tx-bench build starts with it on (TX-48.1). |
BENCH |
0x80 |
Bit 7: the bench commands are in (the bench cargo feature: the bring-up and tx-bench builds; TERM-38). The low bits are the transmit kind above. |
msg
| Name | Value | Meaning |
|---|---|---|
HELLO |
0x01 |
Start a session: protocol version, then the client's name. The answer's third byte says whether the session may go on (1) or must send AUTH first (0: the radio's PIN is set and this is Bluetooth, LINK-30). |
INFO |
0x02 |
Firmware version and what the radio holds. |
AUTH |
0x04 |
The radio's PIN as ASCII digits (4-6), on Bluetooth while one is set (LINK-30, LINK-31): Ok, Refused (wrong; it counts toward the radio's lockout, PIN-3), or Busy (locked out: wait). |
READ |
0x10 |
Read part of a record: what, index, offset, length. |
WRITE |
0x11 |
Write part of a record: what, index, offset, total length, bytes; applied when the last part arrives. |
DELETE |
0x12 |
Delete a channel, zone or preset. |
BEGIN |
0x13 |
A write session of N records starts: the radio shows its progress (LINK-9). |
END |
0x14 |
The write session ends. |
USED |
0x15 |
Which indexes hold a record (LINK-39): what; the answer is the index count (u16), then a bitmap, index i at bit i % 8 of byte i / 8. |
READ_MANY |
0x17 |
Whole records from an index on (LINK-40): what, first index (u16), count (u16). The answer is the next index to ask from (u16), then each record held, as many as fit: index (u16), length (u8), the record; empty indexes are skipped. |
WRITE_MANY |
0x18 |
Several whole records in one frame (LINK-41): what, then each record as READ_MANY gives them (index, length, record). Applied in order, each as a WRITE of it would be; the answer's first byte after the status is how many were applied (a refusal is the next one's). |
STREAM |
0x19 |
One request, its answers back to back (LINK-50, decision 285): the payload is another request's type (READ_MANY, HEARD, MSGS, LOG_READ or UI) and its payload. The radio answers with that request's answers in turn, each as its own frame, the first with this request's seq and each next one seq + 1 (so a frame lost on the way shows as a gap, and the PC asks again from the last it has): STREAM_MORE (| ANSWER) while more follow, STREAM (| ANSWER) for the last, each payload exactly the inner request's answer would be. Frames go only while the port has room, so the stream is flow-controlled by the link itself; any new request from the PC ends it. bad argument for another type. Only from radios that say caps::STREAM in HELLO. |
STREAM_MORE |
0x1A |
A STREAM answer that more follow (radio to PC only, with super::ANSWER). |
LOG_READ |
0x40 |
The event log, newest first (LINK-42): before (u32: records with a lower sequence number; 0xFFFFFFFF from the newest), then optionally the most to send (u8, 0: as many as fit). The answer: the next sequence number (u32), the records held (u16), how many follow (u8), then each (LOG_FIXED bytes, the position if it has one, then the name and the text, each a length and the bytes). |
SLOT |
0x16 |
A slot's working fields, read or changed as the keypad would (LINK-33): the slot (0-2), then optionally a super::slot mask and its fields in bit order. The answer is the slot as it is after. |
BAUD |
0x20 |
Propose a faster cable rate (LINK-11). |
REBOOT |
0x21 |
Restart into the bootloader, for a firmware update (LINK-24): the cable, or a Bluetooth session that may go on (LINK-30); refused while transmitting. The answer goes out first, then the radio saves, goes quiet and resets. |
CMD |
0x31 |
A terminal command line (LINK-34, chapter 37): run as the terminal's command line runs it. The answer is its output: a byte, 1 if more follows (ask with MORE), then text, lines ending in \n; or invalid and the terminal's refusal. A new CMD ends one still running. |
MORE |
0x32 |
The running command's next output, as CMD's answer; 1 with no text: the radio is still working on it, ask again shortly. Nothing running: 0 and no text. |
KEY |
0x30 |
A key on the radio (LINK-19, LINK-20): the key, then what it does (super::key). The keypad and side keys by stock's key code with a press type (LINK-19), the knob (super::key::KNOB), or remote PTT (super::Ptt, LINK-20); anything else answers bad argument. |
UI |
0x33 |
What the screen shows (LINK-19's readback, decision 150): as CMD ui, its text in lines (the screen, the status bar, the home cards or the list's rows, the hint bar, a toast), MORE for the rest. An optional byte: 0 the state, 1 the key names (ui keys). |
SUBSCRIBE |
0x50 |
Events this session wants pushed (LINK-46): a super::event mask (0 ends them), then optionally the UI's least gap in 100 ms units and flags (super::event::RENEW). Answer: the mask, the Live View dictionary's version, the next UI sequence number. |
EVENT |
0x51 |
Radio to PC only, unasked: a frame of this type (below 0x80: the radio sends no requests, so it is never an answer) with the session's own event counter as its seq, the payload an super::event kind and its bytes (LINK-46). Sent by the PC as a request: answered unknown type as any other. |
HEARD |
0x52 |
The APRS heard list (LINK-44): from an index (u8); the count, then as many stations as fit. |
MSGS |
0x53 |
APRS messages, in and out, newest first (LINK-44): from an index (u16); the count (u16), then as many as fit. |
MSG_SEND |
0x54 |
Send an APRS message (LINK-45): to (length, text), the message (length, text); queued as the radio's compose queues it. |
MSG_STOP |
0x55 |
Stop sending one of our APRS messages (LINK-49, APRS-13.1): to (length, text), the message (length, text); the newest of ours to that station with that text still being tried stops, kept as cancelled. |
MSG_DELETE |
0x59 |
Delete one APRS message (LINK-52, APRS-46.1): flags (1: one to us), the station (length, text: from, or to), the message (length, text); the newest that matches goes, as the radio's own Delete message. |
AUDIO |
0x56 |
Receive audio to the PC (LINK-13.1, LINK-13.4): the cable only; payload one byte, 1 to listen (12 kHz µ-law, decision 330), 0 to stop (2 or 3: the bench's raw stream at 12 or 16 kHz, LINK-13.9). The answer carries the stream's rate (u16) and a block's samples (u16). Listening ends with the session (a HELLO, the session going quiet, a new connection): never on by itself (LINK-13.5). |
AUDIO_DATA |
0x57 |
A block of receive audio, pushed unasked while listening (crate::rxaudio): seq (u16), the slot heard (0xFF none), flags (1: squelch open), then the µ-law codes, a byte a sample; with no codes, a keep-alive while nothing is heard. Never compressed (LINK-51), nor counted there. |
AUDIO_RAW |
0x58 |
A block of the bench's raw receive audio (LINK-13.9, AUDIO 2 or 3 in a bench build; crate::rawaudio): seq (u16), the first sample's index (u32), the slot heard, flags, then 152 samples of 12 bits, two in three bytes. Pushed unasked, every block whatever the squelch; never compressed, as AUDIO_DATA. |
STOCK_RESTORE |
0x60 |
The way back to stock (BACKUP-7, LINK-4, LINK-8; crate::restore): the cable only. START stops the radio and hands the cable to the restore until it resets; erase, program and CRC requests follow, then FINISH. |
DATA_READ |
0x61 |
LINK-59 (decision 333): the SPI flash's data range read raw, bytes or a CRC (super::data): Console's backup before an update moves data to another layout. |
DATA_WRITE |
0x62 |
LINK-60: the data range written raw, a sector erased or bytes programmed, and the layout header stamped last (super::data): the cable only. |
CLOCK |
0x63 |
The radio's clock (LINK-65, GPS-23): with a payload, UTC seconds (u32) set it as 0 6 6 does by hand (GPS time takes over at the next fix while 0 6 6 says "from GPS"); empty, it is read. The answer either way: UTC seconds now (u32, 0 while the radio has no time), then its source (u8: 0 none, 1 GPS, 2 set by hand or the link). Only from radios that say super::caps2::SATS. |
data
| Name | Value | Meaning |
|---|---|---|
READ |
0 |
DATA_READ: address (u32), length (u8, 1 to READ_MAX); the answer is the bytes. |
CRC |
1 |
DATA_READ: address (u32), length (u32, up to the data range's end); the answer is the CRC-32 (u32) of the bytes, as the layout header's (CRC-32/ISO-HDLC: reflected, poly 0xEDB88320, init and final XOR 0xFFFFFFFF). |
ERASE |
0 |
DATA_WRITE: the 4 KB sector at an address (u32, a multiple of 4096) erased. |
PROGRAM |
1 |
DATA_WRITE: address (u32), then 1 to PROGRAM_MAX bytes programmed, all inside one 256-byte page, into erased bytes (NOR: a program only clears bits). |
STAMP |
2 |
DATA_WRITE: layout version (u16, this firmware's): the layout header written (its sector erased first; magic, version, CRC), then the radio restarts and mounts it. The last write of an update (LINK-62). |
READ_MAX |
232 |
The most bytes a DATA_READ answers. |
PROGRAM_MAX |
64 |
The most bytes one PROGRAM carries (a quarter page: an aligned chunk never crosses a page). |
PAGE |
256 |
|
SECTOR |
4096 |
caps
| Name | Value | Meaning |
|---|---|---|
STREAM |
1 |
STREAM (LINK-50). |
WINDOW |
2 |
Two WRITE_MANY frames may be in flight (LINK-41.1): the receive rings hold a whole second frame. |
LZ |
4 |
This session's frames are compressed from the HELLO answer on (LINK-51): set only when the HELLO asked (bit 0 of its first reserved byte) and the radio's one compression block was free. |
DELETE_MANY |
8 |
WRITE_MANY deletes channels (a record of length 0, LINK-41.2). |
AUDIO |
16 |
AUDIO (LINK-13.4): receive audio over this port (the cable only). |
TEXTS |
32 |
The readback with the screen as drawn (LINK-19.5): UI what=3, and SUBSCRIBE's super::event::TEXTS. |
POSITION |
64 |
Channel positions by READ_MANY and WRITE_MANY of super::what::POSITION (LINK-53, decision 325). |
LISTS |
128 |
The quick messages, waypoints and DTMF memories by READ_MANY and WRITE_MANY (super::what::QUICK, super::what::WAYPOINT, super::what::DTMF) and SUBSCRIBE's event log (super::event::SUB_LOG): LINK-54 – LINK-57, decision 327. The byte's last bit: a capability after these goes in a second byte after this one (a client that reads only the first sees none of them). |
caps2
| Name | Value | Meaning |
|---|---|---|
PRESET_SKIPS |
1 |
A range preset's skipped frequencies by READ_MANY and WRITE_MANY of super::what::PRESET_SKIPS (LINK-58, decision 329). |
DATA |
2 |
Protocol 3 (decision 333): 2-byte zone numbers, the zone record's channel count, USED in parts, and the raw data messages DATA_READ and DATA_WRITE (LINK-59 – LINK-62); HELLO and INFO end with the layout versions (the firmware's, the chip's). |
SATS |
4 |
Satellite mode's records (LINK-63 – LINK-65, decision 340): super::what::SAT, super::what::SAT_INFO by READ_MANY and WRITE_MANY, and super::msg::CLOCK. |
RADIO |
8 |
Decision 347: the super::what::RADIO record, and the APRS record with every MENU 0 5 value (LINK-43), so Console needs no line commands. |
LINE_CMDS |
16 |
The line commands answer: CMD (LINK-34) and the terminal's command line. Without it (a user build, decision 347) CMD is refused and Console uses the records alone. |
event
| Name | Value | Meaning |
|---|---|---|
SUB_HEARD |
1 |
Mask bits. |
SUB_MSGS |
2 |
|
SUB_UI |
4 |
|
SUB_LOG |
8 |
New event log entries (LINK-57): only from a radio that says super::caps::LISTS. |
RENEW |
1 |
SUBSCRIBE's flags bit: keep the Live View stream as it is (a keepalive); without it a UI subscription starts over with the whole state. |
TEXTS |
2 |
SUBSCRIBE's flags bit: the Live View carries the screen as drawn, its t lines (LINK-19.5); only from a radio that says super::caps::TEXTS. |
HEARD |
1 |
Kinds: a station heard (the count, then the station as HEARD gives it). |
MSG |
2 |
A new message, in or out (the count, then the message as MSGS gives it). |
MSG_STATE |
3 |
A message's state changed: acked, retrying, failed, read. |
UI |
4 |
Live View: the UI's compact state or what changed (crate::liveview). |
LOG |
5 |
A new event log entry (LINK-57): the record as LOG_READ gives it (its sequence number first). |
UI_GAP_BT_MS |
500 |
The UI's least gap by default: Bluetooth 500 ms, the cable 200 ms; at least 100 ms. |
UI_GAP_CABLE_MS |
200 |
|
RATE_BT |
200 |
Events' bytes a second at most, and the most saved up: Bluetooth leaves room for the answers in its ~280 (LINK-36). |
RATE_BT_FAST |
1000 |
Bluetooth at its unlocked 115200 (LINK-25.1): the module passes about 1.6 KB/s (research/ble-speed.md); the events take 1 KB/s of it, the rest for the answers. The screen as drawn (LINK-19.5) needs it. |
RATE_CABLE |
4000 |
|
RATE_CABLE_LISTEN |
3000 |
The cable while its session listens (LINK-13.6, decision 331): the audio's ~12.6 KB/s comes first, so the events (the Live View) take less of the ~23 KB/s 230400 carries, leaving room for the answers. |
BURST |
300 |
|
QUIET_MS |
10_000 |
Events stop when the session has sent nothing for this long (super::msg::SUBSCRIBE with RENEW keeps them going). |
slot
| Name | Value | Meaning |
|---|---|---|
FREQ |
1 |
The VFO's frequency, u32 in 10 Hz. |
MODE |
2 |
u8: 0 FM, 1 NFM, 2 AM. |
POWER |
4 |
u8: 0 low, 1 mid, 2 high. |
RX_TONE |
8 |
u16, CHAN-3's tone word (the tone decoded). |
TX_TONE |
16 |
u16 (the tone sent). |
VFO |
32 |
No bytes: to the slot's VFO (V/M), before the frequency. |
ACTIVE |
64 |
No bytes: make it the active slot (the SLOT key), after the rest. |
OFFSET |
128 |
i32 then u8, as the answer gives them: the signed shift in 10 Hz (0 simplex) and 0, or the split's TX frequency and 1 (MENU 5's paths; LINK-33). |
SPLIT |
1 |
The answer's flags byte. |
APRS |
2 |
|
SCANNING |
4 |
key
| Name | Value | Meaning |
|---|---|---|
UP |
0 |
A keypad key let go (as remote PTT's OFF). |
DOWN |
1 |
A keypad key pressed and held, until UP (or 30 s: HOLD_MAX_MS). |
SHORT |
2 |
Pressed and let go: a short press (KEY-3). |
LONG |
3 |
Held to the long press (KEY-3: 700 ms), then let go: the radio lets it go LONG_HOLD_MS after the answer, and answers busy to keys until then. |
LONG_HOLD_MS |
750 |
How long a remote long press is held. |
HOLD_MAX_MS |
30_000 |
A remote key held down longer than this is let go. |
KNOB |
0x81 |
The knob: then the steps, an i8. |
KNOB_MAX |
20 |
The most knob steps in one KEY. |
LAST_CODE |
21 |
The last keypad code (stock's 0-21); 24 up are the PTTs, never keys here. |
PTT |
0x80 |
Remote PTT (LINK-20). Actions ON (then the slot), ALIVE, OFF. |
OFF |
0 |
Unkey: always ok, keyed or not, so a PC can send it whatever happened. |
ON |
1 |
Key up, with every transmit check a PTT press has; then a byte: the slot (ACTIVE, or 0-2 for A-C). ok and the slot keyed, or invalid and the reason as text. |
ALIVE |
2 |
Keepalive: at least every KEEPALIVE_MS or the radio unkeys (no keepalive, no transmit). ok while keyed; invalid and why it ended once it has. |
ACTIVE |
0xFF |
The slot byte for "the active slot", as PTT A and the side connector key it (KEY-7). |
KEEPALIVE_MS |
2000 |
No keepalive for this long, and the radio unkeys (LINK-20). |
what
| Name | Value | Meaning |
|---|---|---|
SETTINGS |
1 |
The radio-wide settings, one record (index 0). |
CHANNEL |
2 |
A channel by number, 0-999. |
ZONE |
3 |
A zone by number. |
PRESET |
4 |
A range preset by number. |
APRS |
5 |
The APRS settings, one record (index 0; LINK-43): MENU 0 5's that aren't in the settings record. |
CONTACT |
6 |
An APRS contact, in callsign order (APRS-42): written by callsign whatever the index. |
POSITION |
7 |
A channel's position by channel number, 0-999 (LINK-53, decision 325): latitude and longitude (i32 each, little-endian, 1e-7 degree, north and east positive), 8 bytes. READ_MANY gives only the channels that have one; a WRITE_MANY record of length 0 clears it. Only from radios that say super::caps::POSITION. |
QUICK |
8 |
A quick message, 0-8 (LINK-54, TEXT-7): flags (bit 0 super::QUICK_OWN: the owner's own text; clear: the factory text), then the text (0-67 bytes). Only from radios that say super::caps::LISTS. |
WAYPOINT |
9 |
A waypoint, newest first, 0-255 (LINK-55, GPS-10): name (16 bytes, 0-padded), latitude and longitude (i32 each, 1e-7 degree), source (u8: 0 marked, 1 APRS, 2 link, 3 grid): super::WAYPOINT_LEN bytes. A WRITE_MANY record replaces the waypoint at its index, adds one at super::ADD, deletes with length 0. |
DTMF |
10 |
A DTMF memory, 0-15 (LINK-56, DTMF-12): the symbols (length u8, then 1-16 of 0-9 A-D * #), then the name (the rest, 0-10 bytes). Only the memories set are listed; a record of length 0 clears one. |
PRESET_SKIPS |
11 |
A range preset's skipped frequencies (LINK-58, SCAN-10), by the preset's index (as PRESET): u32 each, 10 Hz, 0-48 of them. READ_MANY lists the presets that have any; a WRITE_MANY record replaces the list (length 0 clears it). Only from radios that say super::caps2::PRESET_SKIPS. |
SAT |
12 |
A satellite, 0-31 (LINK-63, SAT-2): the record of ferrite_core::sat::wire (super::SAT_LEN bytes: status, flags, transponders used, catalogue number, name, elements, five transponders). READ_MANY lists the ones held; a WRITE_MANY record replaces the satellite at its index (the per-satellite choices stay with its catalogue number), length 0 deletes it, and length 0 at super::ADD deletes them all (one rewrite of the region, so the whole list's writes after it only program erased bytes). A transponder outside 144-148 or 430-440 MHz is refused (invalid, SAT-13). |
SAT_INFO |
13 |
The satellites' info, index 0 (LINK-64, SAT-18, SAT-21): declination (i16, 0.1 degree, east positive, 0x7FFF none), 2 bytes 0, the satellite data's build time (u32, UTC seconds), when Console wrote it (u32), 4 bytes 0: super::SAT_INFO_LEN bytes. |
RADIO |
14 |
The radio's own state the settings record doesn't hold, index 0 (LINK-66, decision 347): Watch (0 1 1: 0-2), Battery Save (0 7 7 1: 0-3), the GPS fix (0 none, 2 2D, 3 3D; read only), the message sound (0 7 5 5: an index into tonegen::CHIMES), latitude and longitude (i32 each, 1e-7 degree, north and east positive; the fixed position when there is no fix and it is on, GPS-3), the fix's age in seconds (u16, 0xFFFF none): super::RADIO_LEN bytes. A write takes Watch and Battery Save, and the message sound when it is 4 bytes or more, each as the menu changes it; the fix and position are ignored. Only from radios that say super::caps2::RADIO. |
Made from docs/manual/G-link-protocol.md, ferrite/crates/ferrite-core/src/link.rs by docs/tools/mkdev.py.