The MMDVM modem protocol, as a DMR-only radio must speak it

What a radio acting as an MMDVM modem (a "hotspot") must send and accept so that every host that will talk to it works: MMDVMHost (current master), the SDR bench's modem driver (rfoundry_sdrbench) and our bench tools (tools/bench/). Written from the public protocol and from what those hosts send and expect. Section 6 lists our own additions (the SFR debug command 0xD5 and the extra status bytes, and the split duplex command 0xD6). Section 7 is the test list for the host tests and tools/mmdvm_probe.py.

Conventions: byte values are hex. "Frame offset" counts from the 0xE0 start byte (offset 0). "Payload offset" counts from the first byte after the command byte (payload offset 0 = frame offset 3). Frequencies are in Hz, little endian. "Host" is the PC side, "modem" is the radio.

Related specs: gotchas.md section 8 (hotspot pitfalls), open-firmware-cps.md section 6 (how the programming port switches to hotspot mode), dmr-modem.md (the burst layer under all of this), capabilities.md ("Hotspot and repeater").

1. Framing

Frames the modem sends must be complete and in order; two frames must never interleave (a status reply written in the middle of a DMR frame corrupts both). The host parses one frame at a time and drops nothing it can't parse except up to the next 0xE0.

2. Commands and replies for a DMR-only modem

2.1 Summary

"None on success" for DMR_DATA: the MMDVM and MMDVM_HS firmwares stay silent and only NAK a refused frame; a modem may also ACK every DMR_DATA2. Every host here accepts both (MMDVMHost and rfoundry_sdrbench ignore an ACK of DMR data; the bench tools drop ACKs). Pick one and keep it; ACKing costs 4 bytes per 60 ms.

2.2 ACK and NAK

• ACK: E0 04 70 <cmd>.
• NAK: E0 05 7F <cmd> <reason>.

MMDVMHost logs every NAK it receives outside startup as a warning and otherwise ignores it; the refused frame is lost (no retry). rfoundry_sdrbench raises an error for a NAK of a command it waited for, reports a NAK of DMR data to its owner (SFR uses 6 and 2), and logs others.

2.3 GET_VERSION (00)

Request: E0 03 00. The reply must be a short frame (at most 255 bytes): MMDVMHost reads the reply at fixed frame offsets and would misread a long frame.

Protocol 1 (what MMDVM_HS sends and what RadioFoundry sends, see 2.3.1):

MMDVMHost with protocol 1 assumes the modem can do D-Star, DMR, YSF, P25, NXDN and POCSAG (there are no capability bytes in protocol 1). It will therefore send SET_CONFIG enable bits and SET_MODE values for modes RadioFoundry doesn't have if the user's configuration enables them; the radio must tolerate that (2.5, 2.6).

Protocol 2 (the MMDVM repeater board firmware):

rfoundry_sdrbench reads the description from frame offset 4 (protocol 1) or 23 (protocol 2). MMDVMHost refuses any version other than 1 or 2 ("unsupported by this version of the MMDVM Host") and stops.

2.3.1 Which version to answer

Answer protocol 1. Reasons: our bench tools (hotspot_test.py, hs_normal.py and their copies) send only the 23-byte protocol 1 SET_CONFIG and read the protocol 1 status layout (flags at frame offset 5, slot 2 space at offset 8); our status extension starts at the protocol 1 offset 13. Current MMDVMHost and rfoundry_sdrbench handle both versions. The cost of protocol 1: the host can't learn that the radio is DMR only, so a misconfigured host may try other modes (they get NAK 2 / NAK 4).

2.3.2 Description string rules

• ASCII, printable, no NUL, at most 120 bytes (keeps the frame short and under two 64-byte USB packets; an earlier buffer overflowed with a long build ID plus a suffix, gotchas 8.11).
• rfoundry_sdrbench classifies the modem from the description, case-insensitively: the firmware name its radio profile knows → the radio profile; one of MMDVM_HS, ZUMspot, Nano_hotSPOT, NanoDV, SkyBridge, D2RG, LoneStar, ADF7021 → mmdvm_hs; MMDVM → mmdvm; otherwise rfoundry_sdrbench refuses to start unless its config names the type. The radio profile selects: 1 voice header and 1 terminator per call from rfoundry_sdrbench (not 8 and 3), the radio's RSSI conversion (5.4), and simplex only. RadioFoundry's description isn't recognized by the current detection (it would be taken as mmdvm if it contained "MMDVM", which then needs a tuner and is refused), and the SFR mode is refused outright (next bullet). See section 4, row 1.
• SFR capability is announced by the suffix SFR TS<in>>TS<out> <framing> (framing MS, TS or BS), present whenever the firmware has SFR, on or not, giving the slots and framing it would use: e.g. ... SFR TS1>TS2 TS. rfoundry_sdrbench finds it with the regular expressions \bSFR\b, \bTS([12])\s*>\s*TS([12])\b and \bSFR\s+TS[12]\s*>\s*TS[12]\s+([A-Z]+)\b, and today also requires the firmware name its radio profile knows in the string. It refuses to run an SFR config whose slots differ from the radio's, and warns unless the framing is TS.
• Split duplex capability is announced by the suffix SPLIT<version> ( SPLIT1), present whenever the firmware has the extension, role or not (section 6.5). It contains no MMDVM, SFR or slot pattern, so none of the detections above change.
• Avoid the substrings MMDVM_HS, ADF7021, ZUMSPOT and the like (they'd make rfoundry_sdrbench take the radio for an MMDVM_HS board).

2.4 GET_STATUS (01)

Request: E0 03 01. MMDVMHost sends it every 250 ms, whether or not the last one was answered. rfoundry_sdrbench sends it every 60 ms while it has bursts to hand over or is listening before talk, every 2 s otherwise. The reply must come within a few tens of milliseconds even while transmitting (rfoundry_sdrbench allows 1 s per request and gives up after 2 s of misses; MMDVMHost resets the modem after 2 s without a status reply, 3.4).

Protocol 1 layout (send this one):

MMDVMHost (protocol 1) reads frame offsets 4 to 9 unconditionally, so the reply must be at least 10 bytes; send 13 (length 0D), or 14 like MMDVM_HS. rfoundry_sdrbench (protocol 1) reads offsets 5, 7 and 8 and refuses a reply shorter than 9 bytes. The bench tools read offsets 5, 7, 8 and, from 13 on, the SFR debug bytes.

Protocol 2 layout (for reference): offset 3 state, 4 flags, 5 reserved 00, 6 D-Star space, 7 DMR slot 1 space, 8 DMR slot 2 space, 9 YSF, 10 P25, 11 NXDN, 12 reserved, 13 FM, 14 POCSAG, 15-19 reserved; length 20 (14 hex).

Flags:

Space (offsets 7 and 8): the number of further 33-byte DMR bursts the modem will accept for that slot right now without a NAK. Unit: one burst, i.e. one DMR_DATA frame, i.e. 60 ms of air time in simplex. One byte, 0-255; never negative, never wrapped (a negative count once reported 255, gotchas 8.4).

How the hosts use it (both MMDVMHost and rfoundry_sdrbench do the same): take the value from each status reply, write a DMR_DATA frame only while their copy is above 1 (so the last free place is never used), subtract 1 per frame written, and overwrite the copy with the next status reply. Consequences for the modem:

• The value must be conservative. Frames written after the GET_STATUS was sent but before the reply was processed are still on the way when the host overwrites its copy, so with 250 ms polling the host can overcommit by several frames. Report the free count minus a margin of at least 2, or keep that slack in the buffer. A refused frame is lost for good (no host retries).
• Only frames that will occupy the buffer count. Frames the modem drops at once (idle bursts) need not consume space.
• Simplex: slot 1's byte is the constant 10 (0A) in MMDVM and MMDVM_HS; RadioFoundry reports 0 (both are accepted). Slot 2's byte is the real space. MMDVMHost may then write DMR_DATA1 frames if its network config enables slot 1; the modem refuses them (NAK 2) or drops them, and never transmits them.
• The initial value sets how much the host sends in one clump at the start of a network call: MMDVMHost queues 6 idle bursts (360 ms jitter, default) and 8 voice headers up front, so a space of at least 16 lets a call start without waiting for a status round trip. MMDVM_HS reports 25.
• In SFR mode both bytes carry the outbound slot's space (section 6).
• With no DMR mode (before SET_CONFIG, or in POCSAG / idle) the value may still be reported; MMDVM_HS reports 0 when DMR isn't enabled. Hosts only write after SET_MODE DMR.

2.5 SET_CONFIG (02)

MMDVMHost sends it once at startup (after SET_FREQ) and again after a modem reset; rfoundry_sdrbench sends it on every tune (after SET_FREQ, before SET_MODE). The modem answers ACK or NAK. A NAK at MMDVMHost startup stops MMDVMHost ("NAK to the SET_CONFIG command"), so NAK only for values that make DMR impossible.

Protocol 1 payload (MMDVMHost sends 23 bytes, frame length 1A; MMDVM_HS refuses fewer than 23; RadioFoundry accepts 7 or more; rfoundry_sdrbench and the bench tools send 23):

Protocol 2 payload (37 bytes, frame length 28; listed so the parser of a protocol 2 build or a probe knows it): 0 flags (as above), 1 modes (01 D-Star, 02 DMR, 04 YSF, 08 P25, 10 NXDN, 20 FM), 2 modes 2 (01 POCSAG), 3 TX delay, 4 state, 5 TX DC offset + 128, 6 RX DC offset + 128, 7 RX level, 8 CW ID level, 9 D-Star level, 10 DMR level, 11 YSF level, 12 P25 level, 13 NXDN level, 14 reserved, 15 POCSAG level, 16 FM level, 17-19 reserved, 20 YSF hang, 21 P25 hang, 22 NXDN hang, 23-24 reserved, 25 DMR flags (80 trunking), 26 color code, 27 DMR delay, 28 80, 29-36 reserved 00.

Effects to apply: color code (RX acceptance and TX framing), simplex / duplex, the state byte (as SET_MODE would), debug flag. SET_CONFIG must not reset a transmission in progress unless the color code or duplex flag changed. In SFR builds, re-evaluate the SFR trigger after it (section 6).

2.6 SET_MODE (03)

Payload: 1 byte, the state. E0 04 03 <state>. MMDVMHost doesn't wait for the reply; rfoundry_sdrbench waits up to 1 s for an ACK. The MMDVM firmwares ACK it.

MMDVMHost sends SET_MODE idle when its mode hang expires (default 3 s after network traffic, 10 s after RF traffic), when it enters its lockout or error modes, and at startup. It sends SET_MODE DMR before the first DMR frame of a call (network) or after the first RF frame in idle.

2.7 SET_FREQ (04)

Lengths: MMDVMHost and rfoundry_sdrbench always send 14 payload bytes (frame length 11 hex). Accept 9 (very old hosts: no RF level, take full power), 10 (with RF level) and 14. Protocol 1 and 2 use the same layout.

Rules:

• RX = TX is the normal simplex hotspot. RX ≠ TX in simplex is allowed (split simplex); tune both.
• Validate against the radio's hardware range only. Do not restrict to amateur bands: the SDR bench runs business-band channels (461-467 MHz), and a band check that refused them had to go (gotchas 8.7). A NAK at MMDVMHost startup stops it, which is the right outcome for a frequency the radio can't tune. Ignore the POCSAG frequency unless POCSAG TX is implemented (never NAK because of it).
• RF level: map 0-255 onto the radio's power steps; FF (the user never touched it) keeps the radio's own power setting. MMDVM_HS applies the new frequency only at the next SET_CONFIG; RadioFoundry retunes at once.
• SET_FREQ resets the hotspot's call state (gotchas 8.6): anything buffered for TX is dropped and the RF uplink call is closed. If an uplink call was open, send DMR_LOST2 before the ACK (recommendation: MMDVMHost has no RF watchdog, 3.7). After the ACK, every frame sent up must have been heard on the new frequency: rfoundry_sdrbench relies on this ("once the tune's last ACK is in, what follows was heard on the new channel") while it scans several channels a second.
• In SFR builds, re-evaluate the SFR trigger after it (section 6).

2.8 DMR_DATA1 / DMR_DATA2 (18 / 1A)

One DMR burst. Frame: E0 25 1A <control> <33 bytes> (length 37) for slot 2, 18 for slot 1. From the modem it may carry 2 more bytes of RSSI: length 27 (39).

The 33 bytes are the whole 264-bit burst, first bit in the top bit of byte 0: 108 bits of payload, the 48-bit sync / EMB / embedded-signaling field (bits 108-155: low nibble of byte 13, bytes 14-18, high nibble of byte 19), 108 bits of payload. For data-sync bursts the slot type (Golay(20,8), systematic) occupies the 10 bits on each side of the sync: color code in bits 98-101 (frame byte 12, mask 3C), data type in bits 102-105 (byte 12 mask 03, then byte 13 mask C0). Sync words (ETSI TS 102 361-1 table 9.2), 48 bits:

Control byte (frame offset 3):

Host to modem:

• MMDVMHost writes control byte 00 on every frame: header, voice, terminator, idle, data alike. The modem must classify each burst from its own content: the sync word (any of the eight above; MMDVMHost puts MS sync on simplex traffic, BS on duplex traffic, and BS data sync on its idle bursts even in simplex), then for data sync the slot type's data type. Voice B-F carry an EMB instead of a sync: their position follows from the count since the last voice A (MMDVMHost always sends whole superframes, filling gaps with silence bursts itself) and is confirmed by the EMB's LCSS (B first fragment, C and D continuation, E last, F single / reverse channel). Classifying from the control byte sent data as voice, ignored terminators and NAKed the idle bursts before each call (gotchas 8.2). rfoundry_sdrbench and the bench tools' _ctl cases set the control byte properly; when it is non-zero it may be trusted, but classification from the burst must give the same answer.
• What MMDVMHost sends for a network voice call in simplex: 6 idle bursts (its jitter buffer, 360 ms at the default Jitter=360; more for larger jitter), 8 voice LC headers, the voice superframes (A-F, silence bursts where the network lost frames), 3 terminators. A late-entry network call (no header) starts with the idle bursts and 8 headers it builds itself. A PI header, if the network carries one, follows the headers. Data: 2 idle bursts, the data header, the blocks; CSBKs with up to 15 preamble CSBKs before them. A simplex host sends 8 headers and 3 terminators; rfoundry_sdrbench sends 1 header and 1 terminator to a radio it detects as the radio profile, 8 and 3 to others.
• Idle bursts: accept (no NAK; the bench test net_voice fails on any NAK) and drop; the radio makes its own fill. MMDVM_HS transmits them as given.
• PI headers: a radio that transmits privacy calls passes them on; one that doesn't accepts and drops them.
• Voice LC header: starts (or keys up) a call. Repeated headers with the same LC are the same call. A header with a different LC while the previous call is still going out is the next call: hold its frames behind the current call, end the current call with its terminator, then key again with the new headers (gotchas 8.3). A different header while still buffering (nothing on air yet) replaces the LC.
• Terminator: ends the call now; send what is buffered, then the radio's own terminator; no network timeout, no extra delay (gotchas 8.1). Further terminators of the same call are accepted and dropped.
• Start of transmission: start as soon as a few bursts are buffered (more than 4, or the terminator of a short call), never pad the start with silence superframes (gotchas 1.1). If nothing arrives for about 360 ms while buffering, give up and return to receive.
• Lone CSBKs and data: key, send, unkey (rfoundry_sdrbench sends a radio check as a CSBK with preamble CSBKs, no header or terminator).
• Length must be exactly 37 (34 payload bytes): MMDVM firmwares NAK 4 otherwise.
• Full buffer: NAK 5 and drop the frame; never overwrite unsent frames (gotchas 8.4).
• Wrong mode: NAK 2 (state not idle / DMR, or DMR_DATA1 in plain simplex). A frame in idle state switches the modem to DMR (the MMDVM firmwares do this).

Modem to host (what was heard on air), plain simplex:

• Every burst goes up as DMR_DATA2, whatever slot or sync the sender used (MMDVM_HS and MMDVM do the same; MMDVMHost simplex configs usually enable only network slot 2, and MMDVMHost drops slot 1 traffic for the network then). rfoundry_sdrbench's simplex driver listens only to DMR_DATA2. SFR mode uses the inbound slot's command (section 6).
• Control byte as in the table: 41 for each voice header heard, 20 for voice A, 01-05 for B-F, 42 for the terminator, 40 + type for PI headers, CSBK, data headers and blocks. MMDVMHost takes a frame whose control byte is exactly 42 as the end of the call.
• The 33 bytes must be a well-formed burst: MMDVMHost decodes the full LC of headers and terminators (BPTC(196,96) and RS(12,9) with the header / terminator masks; an undecodable header is dropped), regenerates the voice FEC, reads the EMB (its color code must match the configured one for late entry) and collects embedded LC, talker alias and GPS from B-E. Send the embedded signaling for B-E made from the call's LC, or as received if it decoded.
• Sequence: after voice A (20), MMDVMHost accepts B-F only as 01, 02, 03, 04, 05 in order; a repeated or skipped number makes it drop the rest of that superframe up to the next voice A. Fill a missed burst with a silence burst at its position rather than skip it (gotchas 8.5).
• Headers: send every header heard (MMDVM radios and Motorola send up to 8; MMDVMHost ignores repeats once the call is open). Late entry (voice heard without a header): MMDVMHost can start a call itself from voice A plus the embedded LC of B-E, but RadioFoundry sends, once the embedded LC is known, a voice LC header made from it, then the superframe so far as silence from A so the sequence restarts cleanly. Either works with MMDVMHost; the bench tests (rf_late) expect this form.
• One terminator per call (repeated terminators heard on air are the same call). Then nothing until the next call.
• RSSI: 2 bytes after the burst, big endian, raw. MMDVMHost maps raw to dBm with the user's RSSI table; rfoundry_sdrbench converts with the radio formula of 5.4. Send 00 and the AT1846S RSSI register (0x1B) high byte on AT1846S radios so rfoundry_sdrbench's dBm stays right; on other RF chips, document the scale.

2.9 DMR_LOST1 / DMR_LOST2 (19 / 1B)

E0 03 1B (slot 2; 19 for slot 1). Sent when a call heard on air stops without a terminator. MMDVMHost has no watchdog for RF calls: without DMR_LOST it keeps the call open until its timeout (default 180 s) and refuses network traffic meanwhile. Timing: about 500 ms after the last burst of the call (RadioFoundry: 500 ms simplex, 300 ms in SFR mode; MMDVM_HS: 13 missed frame times, about 780 ms; the bench test rf_lost requires 0.4-0.8 s). Never send it during a long header run (8 headers take 480 ms: time the gap from the last burst of any kind) and never mid-call because of one missed burst (one header followed by a 300 ms timer produced DMR_LOST mid-call and split calls in two, gotchas 8.5).

2.10 DMR_SHORTLC (1C), DMR_START (1D), DMR_ABORT (1E), DMR_ALOHA (17)

• DMR_SHORTLC: E0 0C 1C <9 bytes>, the CACH short LC (activity per slot), encoded and interleaved. MMDVMHost sends it in simplex too, at the start and end of every call (it isn't gated on duplex). A direct-mode radio has no CACH: accept and ignore it, with no NAK (a NAK puts a warning in MMDVMHost's log per call). MMDVM_HS simplex builds ignore it silently.
• DMR_START: E0 04 1D 01 (key) / E0 04 1D 00 (unkey). Duplex only; MMDVMHost never sends it in simplex. Ignore it (ACK or silence). rfoundry_sdrbench doesn't send it in SFR mode.
• DMR_ABORT: E0 04 1E <slot> (01 or 02). Duplex only for MMDVMHost (sent when an RF call takes a slot from the network). rfoundry_sdrbench sends it in SFR mode for the outbound slot whenever it starts a new network voice call or an RF call takes the slot: drop what is queued for TX (SFR). ACK or silence. Never NAK.
• DMR_ALOHA: trunking only (MMDVMHost [DMR] Trunking); NAK 2 or ignore.

2.11 SEND_CWID (0A)

E0 <len> 0A <ASCII callsign>; MMDVMHost sends up to 200 characters, rfoundry_sdrbench up to 40 upper case. Accepted only in idle state (both MMDVMHost and rfoundry_sdrbench put the modem in idle first and wait for TX to clear): ACK, then key FM and send the Morse; TX flag set until done. In any other state NAK 5. rfoundry_sdrbench waits for the ACK (1 s); MMDVM_HS sends no ACK on success. After CW, restore the DMR setup fully (gotchas 8.13: the HR_C6000 tone configuration must be restored or DMR fails until a power cycle).

Ours: the hotspot's cw_id op (core/radio/radio_hotspot.c) hands the callsign (up to 40 characters) to the radio task, which keys it on boards whose hal_radio_t has tx_tone (tx_tone_key switches the tone without retuning): the DMR keying released, set_mode(FM), a carrier on the hotspot's TX frequency, 150 ms lead, the Morse (core/radio/morse.c: PARIS timing, dot = 1200 / wpm ms, settings_t cw_wpm, default 20 wpm, tone cw_tone_hz, default 800 Hz), 150 ms tail, then set_mode(DMR) (the modem set up again, 8.13), the receiver back on the hotspot's RX frequency and the DMR keying armed. The TX flag stays set meanwhile (cw_busy). Leaving hotspot mode or SET_FREQ cuts the ID. Boards without tx_tone ACK and count it (hs.cwid_unsent, nothing keyed). Debug link: hs.cw_* in the dmr_ext view section.

2.12 SERIAL (80), TRANSPARENT (90), QSO_INFO (91)

• SERIAL: MMDVMHost uses it to drive a Nextion display attached to the modem ([Nextion] Port=modem); it may arrive at any time. Drop silently (no NAK: it would flood the log). Never send it up.
• TRANSPARENT: drop silently.
• QSO_INFO: not sent by current MMDVMHost; older hosts / the CAST display send E0 2F 91 02 <slot> <20 char source> <G|I> <20 char destination> <type> for DMR, and E0 <len> 91 FA <IP address text> for the IP. Drop silently or ACK; never NAK.

2.13 DEBUG1-5 (F1-F5) and DEBUG_DUMP (FA), modem to host

Text is not NUL-terminated (the host prints it bounded by the frame length). MMDVMHost logs each one. Send them only when SET_CONFIG's debug flag (10) is set, never before the host has had its GET_VERSION reply (3.1), and never in a burst (each costs host log I/O and serial time). Optional; not needed by any host.

2.14 FM parameters (60-63) and other modes

Hosts only send FM_PARAMS1-4 when FM is configured; MMDVMHost waits for their ACK at startup like SET_CONFIG. The MMDVM firmware ACKs them even when built without FM; do the same (ACK, ignore) so a misconfigured host still starts. D-Star, YSF, P25, NXDN, M17 and POCSAG data: NAK 2.

3. Handshake and timing

3.1 MMDVMHost startup (current master)

1. Opens the port (serial at the configured speed, 115200 usually; or UDP).
2. Waits 2 s.
3. Sends GET_VERSION. Then reads for about 300 ms (30 reads 10 ms apart), consuming one frame per read; if a version reply is among them it continues, else it waits 1.5 s and repeats, 6 attempts in all (about 11 s), then gives up ("Unable to read the firmware version after six attempts") and stops. Any frame the modem sends before the version reply uses up one of the 30 reads: the modem must not send unsolicited frames (DMR uplink, DEBUG) until it has been addressed (send nothing up until the host has sent any command).
4. Sends SET_FREQ and waits for ACK / NAK.
5. Sends SET_CONFIG and waits for ACK / NAK.
6. (FM only) FM_PARAMS1-4, each waited on.
7. Starts polling GET_STATUS every 250 ms; sends SET_MODE idle.

"Waits for ACK / NAK" in steps 4-6 means: it reads one frame 10 ms after sending, then keeps reading while frames arrive that aren't ACK or NAK (up to 30). If nothing has arrived at the first read, it carries on as if ACKed; a late NAK is then only logged. So ACK quickly (within 10 ms is ideal), and in any case before any other frame.

The order is SET_FREQ before SET_CONFIG in current MMDVMHost. rfoundry_sdrbench and the bench tools also send SET_FREQ, SET_CONFIG, SET_MODE in that order, but rfoundry_sdrbench sends a SET_MODE DMR right after GET_VERSION too, and the bench tools skip GET_VERSION entirely. The modem must accept these commands in any order, repeated, at any time.

3.2 rfoundry_sdrbench startup and tuning

GET_VERSION up to 6 times, each waited on for 1 s (no initial delay); then SET_MODE DMR; then per tune: SET_FREQ, SET_CONFIG (with state 02 DMR), SET_MODE DMR, each waited on for 1 s (an error restarts the whole connection with backoff 1, 2, 4 ... 30 s). Status every 60 ms while it has traffic or listens before talk, every 2 s when idle (to keep the radio in hotspot mode). Scanning repeats the tune sequence several times a second.

3.3 Bench tools

hotspot_test.py and hs_normal.py (and their copies mmdvm_hotspot.py, hotspot_cases.py in this repo): no GET_VERSION; SET_FREQ, SET_CONFIG (protocol 1, 23 bytes), SET_MODE DMR, 150 ms apart, replies not waited on; then GET_STATUS every 250 ms. Over UDP they treat each datagram as one frame (command at datagram byte 2): the modem must send exactly one frame per datagram (5.3). hs_normal.py paces network calls like MMDVMHost (space above 1, minus one per frame).

3.4 What makes MMDVMHost declare the modem dead

• Startup: no version reply in 6 attempts, a protocol version other than 1 or 2, a NAK to SET_FREQ or SET_CONFIG, or a port write failure: MMDVMHost exits.
• Running: 2 s without a GET_STATUS reply (the timer starts at the first status reply and restarts on each): it logs "No reply from the modem for some time, resetting it", enters its error mode, closes the port, waits 2 s, and runs the whole startup (3.1) again, every 5 s until it succeeds. Only status replies restart this timer; DMR traffic does not.
• Port read / write errors are logged; a USB disconnect makes every read fail.

A modem that reboots (watchdog) while the host is running must answer the host's next GET_VERSION as at power on.

3.5 Playout and pacing (network to air)

MMDVMHost writes at most one DMR frame per slot per pass of its main loop, nothing within 10 ms of its last write (playout timer), and only while its space copy is above 1 (2.4). A call therefore arrives as a clump (idle bursts + headers, as far as space allows) and then at the network rate, about one frame per 60 ms, with jitter. rfoundry_sdrbench: one burst per 60 ms per slot after a prebuffer (6 by default), also gated on space above 1.

3.6 Simplex (Duplex=0) DMR behavior

• One timeslot on air. The host uses DMR_DATA2 / DMR_LOST2 only (slot 1 space is the constant 10).
• TX: MS-sourced framing on air regardless of the sync in the host's frames (MMDVMHost puts MS sync on simplex traffic; network traffic forwarded by rfoundry_sdrbench is regenerated to MS sync). The radio builds its own slot type, EMB and sync with the configured color code.
• The radio can't receive while it transmits; RF heard right after a transmission goes up normally.
• No DMR_START, no DMR_ABORT, short LC ignored, no CACH.
• After the host's terminator, the TX flag stays set until the radio's own terminator is on air (about 0.7 s after the host's terminator, measured, gotchas 8.6), then clears.
• SET_CONFIG with the simplex flag clear and RX ≠ TX: MMDVMHost then expects a duplex repeater (both slots, DMR_START, BS framing). RadioFoundry runs as a plain simplex hotspot in that case; with RX = TX it turns SFR on (section 6).

3.7 Calls and "space" around back-to-back traffic

• Back-to-back network calls: MMDVMHost may deliver call 2's idle bursts and headers while call 1 is still in the modem's buffer. Call 1 must end with its terminator before call 2 keys up under its own header (gotchas 8.3); frames held for call 2 count against the space so the host doesn't overrun.
• Space must stay consistent: buffer occupied + held frames + free = capacity; report the smaller of voice buffer and data list space when they're separate (gotchas 8.6).
• RX and TX buffers are separate; RF frames don't survive into a later transmission and are cleared at a direction change (gotchas 8.8).
• Uplink (RF to host) frames go into a lock-free queue from the interrupt; a full queue drops and counts (RX overflow flag), never overwrites (gotchas 8.4).
• A DMR_LOST or terminator must close every uplink call before the next one's first frame; MMDVMHost has no RF watchdog (2.9).

4. Client compatibility matrix

Columns: MMDVMHost (current master, Linux / Pi-Star / WPSD class hosts), rfoundry_sdrbench (the SDR bench's modem driver, simplex and SFR repeater) and bench (our hotspot_test.py, hs_normal.py, run_sfr_call.sh and copies).

Row 1 is the one compatibility break a new name causes. The fix is in rfoundry_sdrbench, which is ours: its detect() and sfr_slots() in rfoundry_sdrbench/mmdvm/radio.py must accept RadioFoundry's description.

5. Transport details

5.1 USB CDC ACM

• Don't gate anything on DTR / RTS / line coding: MMDVMHost on Windows opens the port with DTR cleared, and many USB stacks' "connected" test is DTR. Check that the USB stack doesn't discard or block TX data while DTR is clear (test 7, T-USB-2).
• Replies whose length is a multiple of 64 must be ended with a zero-length packet so the host sees them at once.
• Linux ModemManager probes new ACM ports with AT commands: the parser must skip those bytes (they aren't 0xE0) and answer the next real frame.
• The port may be shared with the programming protocol: the first byte 0xE0 selects MMDVM (open-firmware-cps.md section 6). Once in hotspot mode, programming commands aren't answered.

5.2 UART

115200 8N1 (the programming cable's UART on a board without USB). A 39-byte frame takes about 3.4 ms; status replies and uplink frames at 60 ms intervals fit easily. Write from task context, not from an interrupt handler (gotchas 8.10). Stream parsing with 0xE0 resync as in section 1.

5.3 UDP (MMDVMHost Protocol=udp, rfoundry_sdrbench protocol: udp)

• The modem listens on UDP port 3334 at its own address. The host sends from its LocalPort (3335 by default in rfoundry_sdrbench; configured in MMDVMHost).
• Replies go from the modem's address, source port 3334, to the address and port the host's last datagram came from. MMDVMHost and rfoundry_sdrbench both drop datagrams that don't come from exactly ModemAddress:ModemPort.
• One MMDVM frame per datagram in both directions (MMDVMHost writes each frame in one datagram; the bench tools need each reply in its own datagram). Still parse incoming datagrams as a stream.
• One host at a time (the last sender wins).
• RadioFoundry offers this over its USB network adapter (CDC-NCM, the radio's IP derived from the user's DMR ID; on the bench 12.47.82.93 with the Mac at 12.47.82.92). Gotchas 9.1-9.8 cover the network side.

5.4 RSSI scale

rfoundry_sdrbench's radio profile converts the raw RSSI to dBm as: dBm = raw − 151 at 300 MHz and above; dBm = −164 + raw × 32 / 27 below. The raw value is the 16-bit big-endian number after the burst; RadioFoundry puts 00 in the high byte and the AT1846S register 0x1B high byte in the low byte. MMDVMHost uses whatever RSSI table the user configured.

6. Our extensions (not part of MMDVM)

Both exist only for our single frequency repeater (SFR) in hotspot mode and for its on-air debugging. A standard host can't trigger either: SFR turns on only when SET_CONFIG has the simplex flag clear and SET_FREQ has RX = TX (both non-zero), evaluated after each of those commands in either order (gotchas 8.12). MMDVMHost with Duplex=0, and Pi-Star, never get there. (An MMDVMHost configured Duplex=1 with equal RX and TX frequencies would; that config makes no sense for a real duplex board.)

6.1 Detecting them

• The GET_VERSION description's SFR TS<in>>TS<out> <framing> suffix (2.3.2) says the firmware has SFR and with which slots and framing. It appears whether SFR is on or not.
• Sending 0xD5 to a modem without it gets NAK 1 (unknown command) from MMDVM, MMDVM_HS and any firmware without SFR; ours answers ACK (or NAK 4 if too short). Send it only to a modem whose description announces SFR.
• The extra status bytes appear only while SFR is on: a status reply longer than 13 bytes from a radio announcing SFR. A client must not assume them from the length alone (MMDVM_HS sends 14 bytes, with byte 13 its M17 space).

6.2 SFR mode behavior seen by the host

6.3 GET_STATUS extra bytes (SFR mode only)

The protocol 1 status (frame offsets 0-12) unchanged, followed by 108 bytes of SFR counters and state, frame offsets 13 to 120; frame length 121 (79 hex). Counters are modulo 256. Layout: drivers/modem/hrc6000/sfr_glue/hrcSfr.h (the hrcSfrDebug_t structure), first member at frame offset 13; the field list and meanings are also in tools/bench/mmdvm_hotspot.py. A host that doesn't know them reads only up to offset 12 and is not disturbed: MMDVMHost (protocol 1) reads at most offset 12; rfoundry_sdrbench reads offsets 5, 7, 8.

Keep the length and member order stable; add new members only at the end, and never change a member's meaning, so old bench tool versions stay correct.

The generic SFR layer (core/hotspot/hotspotSfr.c on core/dmr/sfrRunner.c, any modem behind hal_dmr_modem_t) fills the members it knows: 14 bursts written, 15 bursts heard, 16 repeated, 17 send rejected, 24 state (01 keyed, 02 own timing, 10 RF call, 20 busy), 25 flags, 28 echo, 29 ignored, 30 duplicate, 31 last burst, 32 its color code, 35 reg10, 36 reg12, 38 ignored on the outbound slot, 39 bad checksum, 55 rssiMin, 60 raw area (FF: not used), 99 LC rebuilt, 106 reg11, 107 flags2, 117 late entry held. The rest (register reads, RF switch timing, raw bursts) belong to an HR_C6000 driver level SFR and stay 0 until one fills them.

6.4 Command 0xD5 (SFR debug)

E0 <len> D5 <flags> <framing> [<reg10> [<reg12> [<rssiMin> [<reg11> [<flags2>]]]]], payload 2 to 7 bytes. ACK (E0 04 70 D5) when at least 2 payload bytes are present, NAK 4 otherwise. Not stored (all zero at power on). Missing optional bytes take their defaults: reg10 00 (the driver's), reg12 FF (the driver's), rssiMin 00 (default threshold), reg11 00, flags2 00. Meanings of each bit: the HRC_SFR_DEBUG_* and HRC_SFR_DEBUG2_* definitions in drivers/modem/hrc6000/sfr_glue/hrcSfr.h; framing 0 = the channel setting, 1 MS, 2 TS, 3 BS (GET_VERSION shows the result). In a firmware without SFR, 0xD5 is an unknown command (NAK 1). The generic SFR layer acts on the framing and on flags2 0x40 (data calls repeated as heard, no hold); it keeps and reports the other switches for a driver that uses them.

6.5 Command 0xD6 (split duplex)

Two radios run as one duplex repeater, each an MMDVM modem (docs/spec/split-duplex.md, the full definition). Built only with CONFIG_HOTSPOT_SPLIT; a firmware without it NAKs 0xD6 with 1, like any unknown command. Request E0 <len> D6 <sub> [<data>], reply E0 <len> D6 <sub> <result> [<data>] (result 0 done, 1 unknown sub-command, 2 wrong state, 4 invalid). Sub-commands: 00 INFO, 01 SET_ROLE, 02 TIME, 03 GET_EPOCH, 04 SET_EPOCH, 05 SET_AT, 06 STATUS. Nothing changes for a host that never sends 0xD6 except the SPLIT1 description suffix: a role starts only with SET_ROLE 1 (TX half) or 2 (RX half) and ends with SET_ROLE 0, the end of the session (the port closed with DTR, the 20 s timeout) or a 10 s lease that any 0xD6 refreshes. In a role the standard commands keep their framing and change meaning as a duplex MMDVM board's (split-duplex.md 4); no other status bytes are added.

7. Conformance checklist and test list

For the host tests (a fake transport feeding the protocol code) and tools/mmdvm_probe.py (against the radio). "→" is what the modem must answer; "(none)" means no frame within 100 ms. Payload bytes in examples are written in full where they matter; <33> is a 33-byte burst.

7.1 Framing

7.2 Version and status

7.3 Configuration

Example frames (typical MMDVMHost defaults: levels 50 %, CC 1, TX delay 100 ms, simplex, DMR only):

• SET_FREQ 461.6875 MHz, RF 100 %: E0 11 04 00 CC CA 84 1B CC CA 84 1B FF 40 0E CF 19 → E0 04 70 04
• SET_CONFIG v1: E0 1A 02 80 02 0A 00 80 80 01 00 80 80 80 80 80 80 80 80 04 80 80 05 05 00 00 → E0 04 70 02
• SET_MODE DMR: E0 04 03 02 → E0 04 70 03

7.4 DMR downlink (network to air)

7.5 DMR uplink (air to host)

Tests with the bench modem (bench_tx.py) or the host-test model of MMDVMHost's RF handling (tests/host/hotspotUplinkTest.c).

7.6 Timing and robustness

7.7 Our extensions

View the source of this page