Open-firmware CPS interoperability

This spec describes the serial protocol and the codeplug memory layout that the open-firmware CPS and qdmr's GD-77/UV380 open-firmware drivers use. A new implementation can use it to build an interop shim, so that existing PC tools can read and write our radios. It covers wire formats and stored data formats only. How the new firmware stores its own data internally is a separate decision. The shim can translate between the image described here and our own storage, or it can keep this image as the storage.

Sources: qdmr's open-firmware drivers for the GD-77 and the UV380 family (GPL-3, github.com/hmatuschek/qdmr; only protocol facts were taken from it) and the behavior of RadioFoundry's own implementation (core/cps/cps_openfw.c, core/codeplug/). The open-firmware CPS is closed source. What it reads and writes is what the radio accepts and what qdmr does.

Conventions: "BE" is big endian and "LE" is little endian. Offsets are hexadecimal unless they are plainly decimal counts. "Image address" means the address the PC tool puts on the wire. Strings in the codeplug are padded with 0xFF, not NUL terminated, unless stated otherwise.

1. Transports and framing

| STM32 radios in our USB network mode | USB CDC-NCM (VID 0x1FC9 PID 0x0096, no serial port). The serial protocol is carried in UDP datagrams to port 3334 at the radio's address | one datagram is one USB packet. Replies go back to the address and port that sent last. One client at a time | | MK22 radios in our USB network mode | Composite device VID 0x1FC9 PID 0x0095: CDC-ACM (interfaces 0-1) plus CDC-NCM (interfaces 2-3) | as USB |

qdmr finds radios only by VID 0x1FC9 and PID 0x0094. A radio in network mode, or one behind a generic USB-serial adapter, has to be picked by port.

1.1 USB reassembly (STM32 and MK22)

Every request is handled to completion, and the reply is sent, before the next request is taken. Bytes that arrive while a request is being handled are dropped. The PC waits for each reply before it sends again.

• A packet shorter than the endpoint size (64 bytes) completes a request, unless more bytes are expected (below).
• If the first packet of a request is exactly 64 bytes long, the radio works out the expected total length from it:
  • R (read): 8 bytes.
  • W or X with sub command 1: 5 bytes.
  • W or X with sub command 3: 2 bytes.
  • W or X with sub command 2, 4 or 7: 8 bytes plus the length field in bytes 6-7.
  • Anything else: the packet alone. Packets are then appended until the expected count is reached or a short packet arrives.
• The request buffer is 2048 bytes on the STM32 radios and 1536 bytes on the MK22. A request that would overflow it is discarded, and the radio answers with a single - (0x2D).
• The radio clears the request buffer before each new request. The text command (C 2) relies on this for NUL termination.

1.2 UART framing (radios without USB)

• The receive interrupt appends bytes to a 2048 byte request buffer. While a request is being handled, received bytes are dropped.
• When 3 ms have passed since the last byte, the main loop takes the bytes as one request. It handles the request, writes the reply on UART0 from the main loop, and clears the buffer.
• If the request overflowed the buffer, the reply is -.
• For 10 s after a request a "CPS session" is active. Debug text on UART0 (a build option) is suppressed during the session, so it can never land in the middle of a reply.
• In hotspot mode the bytes go to a separate 1024 byte ring instead, and are split into MMDVM frames by the frame length byte (section 6).
• The radio info reports the board's radio type (4); a board without a radio_type hook reports 6.

1.3 Addresses and lengths

All multi-byte fields in the request and reply headers are big endian. Data payloads are raw memory bytes. Most structures inside them are little endian (section 8).

2. Requests

The first byte of a request selects the command.

qdmr sends W to the MK22 family (its variant "GD77": radio types 0-4) and X to the STM32 family (its variant "UV380": radio types 5-10). It reads and writes in 32 byte blocks.

2.1 R: read

Reply on success:

On failure the reply is a single -. The original firmware clips the length to its reply buffer size minus 3 (2045). RadioFoundry streams the reply in small pieces instead of building it in a buffer, so it clips at 32768: a client that reads large areas (the web flasher's backup) asks for 32 KB at a time and takes what comes back, which is 2045 bytes from the original firmware and older RadioFoundry builds. qdmr checks that the returned length equals the requested one, and asks for 2045 or less. The radio info area always returns its own structure length, whatever length was asked for.

Send the header and the first data in one USB write. qdmr (0.15) reads a reply as soon as part of it has arrived and doesn't wait for the rest. A 32-byte block sent as the header and then the data reached it short. qdmr then read the late data byte as the next reply's first byte, reported an error and asked the radio to reboot. One write of 35 bytes fits a single full-speed USB packet, as the original firmware sends it.

2.2 W / X: write

The reply on success is 2 bytes: byte 0 and byte 1 of the request echoed. On failure it is a single -, and any pending sector is dropped. Data lengths are clipped to the request buffer size minus 8.

Special cases the radio applies to sub commands 1-3 (and 4 on the MK22). An interop shim must reproduce them:

2.3 C: control

The reply to every C request is a single -. It means "done", not "error". qdmr sends every C request as a 23-byte packet: the command, then zeros. The radio takes the command at its own length and drops the zeros, since no request starts with a zero byte (cps-protocol.md 2.1, cps.junk).

C 6 options:

RadioFoundry takes C 6 0 and C 6 1 only in programming mode: after a C 0, with no quiet longer than the session time (10 s) since. Without it the reply is - and nothing happens (cps.reboots_ignored on the debug link). On a radio whose debug link shares the CPS's serial port, any three bytes "C 6 1" would otherwise reboot it (bench 2026-10-15). qdmr sends C 0 first (the typical session below).

A typical session, as qdmr does it:

• Read: C 0, C 1, three C 2 lines, C 3, C 6 3, C 6 2, the reads, then C 5.
• Write: the same opening with C 6 4 instead of C 6 3, then C 6 2, the writes as prepare/data.../commit for each sector, then C 5, and finally C 6 0 (or C 6 1).

3. Memory areas (R byte 1)

4. Radio info (area 9)

The structure is little endian, packed, 46 bytes in struct version 3.

qdmr chooses its "extended callsign DB" layout when features bit 1 is set and bit 2 is clear.

5. D: DMR data service host commands (ours)

This is our protocol: it has no open-firmware counterpart and no other users yet. It is available in programming mode on the serial port, and on the STM32 radios also over UDP 3334 in network mode. It doesn't run in hotspot mode.

Each request is one USB packet (64 bytes at most) or one UART frame: D, the sub command, then the arguments. Every reply starts with D, the sub command, and a result byte: 1 means OK; 0 means failed, busy or nothing available.

Send kinds:

Send flags:

• bit 0: group destination (a talkgroup, not an individual).
• bit 1: request a TMS acknowledgement (kind 1).
• bits 2-3: block rate for kinds 1-3 (0 Rate 1/2, 1 Rate 3/4, 2 Rate 1). The value 3 is refused.

Data types are the ETSI TS 102 361-1 values: 0 PI header, 1 voice LC header, 2 terminator with LC, 3 CSBK, 4 MBC header, 5 MBC continuation, 6 data header, 7 Rate 1/2 data, 8 Rate 3/4 data, 9 idle, 10 Rate 1 data.

6. Hotspot mode switch (0xE0)

The MMDVM protocol itself is public and is specified separately. The switch works as follows:

• Entering. In programming mode, a request whose first byte is 0xE0 and that is at least 3 bytes long switches the radio to hotspot mode, if a hotspot type is configured (MMDVM or BlueDV) and DMR isn't disabled. There is no CPS reply. The request is queued as the first MMDVM frame. The radio also stops GPS NMEA output, so MMDVMHost doesn't see stray text.
• USB (STM32, MK22). From then on, every USB packet starting with 0xE0 and at least 3 bytes long is taken as one MMDVM frame. The radio does not parse the MMDVM length byte. A packet that doesn't fit in the frame ring is dropped and counted.
• UART (radios without USB). Bytes are split into frames by the MMDVM length byte, resynchronizing on 0xE0. MMDVMHost may send frames back to back, so gaps can't be used. Bytes that came with the first request are split the same way.
• UDP 3334 (network mode). A datagram is treated like a USB packet.
• Leaving. In MMDVMHost mode the radio leaves after 20 s without traffic from the host. In BlueDV mode the user leaves. The radio then returns to programming mode. While in hotspot mode, R, W, X, C and D are not answered.

7. The codeplug image

The PC tools see two images, "EEPROM" and "flash", in the GD-77's terms. The GD-77 has a 64 KB I2C EEPROM and a 1 MB SPI flash. The STM32 radios and the HR_C7000 radios have no EEPROM: both images live in one large SPI flash. The tools address it with the per-family offsets below. A new firmware can store the data any way it likes, as long as the shim presents these addresses.

7.1 Per-family address mapping

The rest of this section gives flash image addresses without the offset. For the STM32 family, add 0x20000 to get the address on the wire.

Flash regions that qdmr transfers:

EEPROM image part 1 ends at 0x6060. It therefore includes the first 0x15 bytes of the radio's own settings block at 0x604B (7.2). A tool that writes back what it read restores those bytes unchanged. A shim must accept writes to that range without letting them corrupt the live settings. It can ignore the range, or validate it against the magic.

7.2 EEPROM image map

Zone layout detection: the firmware reads the 16 bytes at 0x8060 and looks at the last one (0x806F). In the 16-channel layout, 0x806F is the last byte of the second zone's name, so it is 0xFF. In the 80-channel layout, it is the high byte of a channel number (at most 0x04). A value 0x00-0x04 therefore selects 80 channels per zone. Current tools always write the 80-channel layout.

7.3 Records

7.3.1 Device info (EEPROM 0x0080, 96 bytes)

The firmware treats all of these as informational (inherited from the vendor layout). The shim should store and return them unchanged.

7.3.2 General settings (EEPROM 0x00E0, 40 bytes)

Only the callsign and the DMR ID matter to the firmware. The rest is vendor layout and should be kept. The group and private hang bytes (0x18, 0x19) have no unit here. Our firmware reads them as the reply window, assuming 500 ms steps (codeplug.c GEN_HANG_UNIT_MS, dmr-voice.md 7); that unit is not confirmed.

7.3.3 Channel (56 bytes; EEPROM 0x3790 + 56 x (n-1) for n = 1..128, flash banks for 129..1024; VFOs too)

Location: each coordinate is 24 bits, assembled from its high, middle and low bytes. Bit 23 is the sign (1 = south or west). Bits 22-15 are whole degrees. Bits 14-0 are the fraction in 1/10000 degree (0..9999). The location is used for distance sorting and the like when flag 1 bit 3 is set.

Flag 1 (offset 0x26):

SFR bytes (ours; the CPS doesn't know them and leaves them as read; they are only read when flag 1 bit 1 is set):

The repeater's timeout is the channel TOT, or 180 s when the TOT is 0.

Channel banks in the flash image: banks 1-7 (channels 129-1024) start at flash image 0x7B1B0. Each bank is a 16 byte in-use bitmap followed by 128 channels of 56 bytes (0x1C10 bytes per bank), so channel n (n >= 129) is at 0x7B1C0 + 16 x ((n-129) / 128) + 56 x (n-129). Bitmaps: bit (k % 8) of byte k / 8 marks the bank's channel k (0-based) in use. The flash image from 0x7B000 to 0x7B1AF is unused by the firmware; keep it as read.

7.3.4 Zone (EEPROM 0x8030 + 0xB0 x slot)

The firmware counts zones by walking the in-use bitmap. Slots need not be packed. The radio adds a virtual "All Channels" zone after the real ones.

7.3.5 Contact (flash image 0x87620 + 24 x (n-1), n = 1..1024)

7.3.6 RX group lists (TG lists)

7.3.7 DTMF contact (EEPROM 0x2F88 + 32 x (n-1), n = 1..63)

The record is a name (16 bytes, 0xFF padded; a first byte of 0xFF or 0x00 means empty) followed by a code of 16 bytes: one digit per byte (0x00-0x09 the digits, 0x0A-0x0D A-D, 0x0E *, 0x0F #), ended by 0xFF. qdmr assumes 64 contacts, but a 64th would overlap the channel bank 0 bitmap at 0x3780. Use 63.

7.3.8 APRS configuration (EEPROM 0x1588 + 64 x (n-1), n = 1..8)

7.3.9 DTMF signaling (EEPROM 0x1400, 120 bytes)

The firmware uses only the five duration bytes at 114-118. qdmr reads this block starting at 0x1470.

7.3.10 LUCZ (EEPROM 0x6000)

7.4 Custom data, calibration and the data flash offset

Flash image 0x00000 holds the custom data area:

A block's length can't change once written; the firmware rewrites a block only when the length is the same.

Calibration: on the STM32 and HR_C7000 radios, the window at flash image 0x10000..0x101FF is the working calibration copy (2.2). This address is physical, not offset. On the GD-77, calibration is at 0xF000 (working copy) and 0x8F000 (factory; 0x6F000 on type 2), read raw.

HR_C7000 specifics:

• Physical offset. Every flash address the CPS uses (the EEPROM image, the flash image, the DMR ID DB, voice prompts) is placed at +0x700000 in the 16 MB data flash (board.openfw_eeprom 0x700000, board.openfw_flash 0x720000, end 0xF00000). Below that is the radio's own data (settings, contacts, fonts, voice prompts, recordings, factory calibration), which is never touched. The window therefore covers 9 MB (to 0xFFFFFF).
• Collision with the radio's own firmware. The window sits inside a region (0x6DC000..0xFFFFFF) that the original firmware may use for recording and extended contacts. Going back to the original firmware and recording can overwrite the codeplug.
• Flash image offset. The build uses the STM32 mapping: the EEPROM image at 0x700000 and the flash image at +0x20000 from it, so the custom data area and the EEPROM image don't overlap.

7.5 DMR ID database

Header (12 bytes):

Records follow the header in area 1, sorted by ascending ID, with no gaps. Area 1 holds as many whole records as fit in 256 KB minus the header. The rest continue at the start of area 2. Each record is:

• An ID: 3 bytes LE binary (formats N and n) or 4 bytes BCD.
• The text. With N and n, the text is packed at 6 bits per character, 4 characters in 3 bytes, most significant first. The 64-character alphabet is, in order: space, 0-9, A-Z, a-z, . (codes 0-63). Trailing spaces are trimmed after unpacking. The text is "callsign name [city state country]" (qdmr's convention). The record size is 3 + 3/4 of the text length. qdmr's default text length is 16 characters (15 byte records) on the GD-77 and 32 (27 byte records) on the UV380 family.

The radio looks IDs up by binary search, using a cache of 14 evenly spaced IDs once there are more than 40 records.

7.6 Voice prompts file

Layout:

Prompt numbering, fixed part:

• 0 silence, 1 "point", 2-11 digits 0-9, 12-37 letters A-Z, 38 an alternate Z.
• 39 onward: channel, contact, milliseconds, megahertz, kilohertz, talkgroup, degrees, VFO, seconds, minutes, volts, watt, watts, milliwatts, percent, receive, transmit, mode, DMR, FM, plus, minus, the three VFO exchange and copy phrases, power, channel mode, scan mode, timeslot mode, filter mode, zone mode, power mode, color code mode, hertz, settings update, star, hash, VOX, sweep scan mode, eco mode, duration, reverse repeater, distance, km/h, kilometers, then three unused slots.
• That gives 88 fixed prompts. Entries from 88 onward follow the order of the language strings of the firmware the CPS targets; the mono builds skip the theme strings.

The voice prompt files are made with the AMBE codec, and the new firmware carries no codec. Whether the new firmware reads this file at all is a product decision. If it does, the language-string index list has to be supplied as interop data, which is an open question.

7.7 The radio's own settings block

At EEPROM image 0x604B, right after the LUCZ, the firmware keeps its own non-volatile settings. This block is not a CPS codeplug structure, and the CPS doesn't interpret it. The first field is a 32-bit LE magic, which changes whenever the layout changes; on a mismatch the radio resets the block to defaults.

The new firmware should keep its settings elsewhere, and treat bytes 0x604B..0x605F of a codeplug write as noise (7.1).

8. Byte order summary

9. Version differences to handle

• structVersion. Version 3 (46 bytes, with features). qdmr reads version 1 (44 bytes, no features field) as well.
• radioType 11 (HR_C7000). Known to the open-firmware CPS since E2026.07.13, unknown to qdmr (checked against its current source). RadioFoundry reports 6 on HR_C7000 boards, which qdmr accepts because the image mapping matches (7.4); qdmr then shows the UV380 model.
• Panel types 8 and 10. The type follows the panel's color order. The CPS needs it only for screenshots. qdmr treats the two alike.
• APRS magic. 0x4153 now, 0x4152 in older records (7.3.8).
• Voice prompt versions. 8 for mono radios, 9 for color radios. A version mismatch makes the radio fall back to beeps.
• Our additions. The SFR bytes and flag 1 bit 1, the D commands, and the network mode USB identities (PID 0x0095 / 0x0096) don't exist in R20260131. They are invisible to the CPS, which round-trips the bytes it read.

10. Open questions

1. Which flash image offset does the open-firmware CPS use for radio type 11? RadioFoundry reports type 6 and uses the STM32 mapping (7.4), which works with qdmr.
2. Which radio type the HR_C7000 boards should report: 11 for the open-firmware CPS, or an STM32 type (today 6) so that qdmr works, or a qdmr change to add type 11.
3. Exactly which EEPROM and flash ranges the closed open-firmware CPS reads and writes, beyond the qdmr ranges above (themes, boot image, calibration, security registers). This needs a USB capture of a full CPS read and write.
4. Whether to support voice prompt files (they need the language-string index list and AMBE playback).
5. Whether the shim answers area 8 (AMBE compress) and area 10 (security registers) at all, or always with -.

View the source of this page