qdmr YAML codeplug

qdmr and its command-line tool dmrconf save a codeplug as a YAML file, the "extensible codeplug". The Codeplug Editor opens and saves this file, so a codeplug can move between qdmr and the editor in both directions. This spec covers the file as qdmr 0.15 writes it, the editor's mapping to the open-firmware records (open-firmware-cps.md 7), and what each direction leaves out.

Sources: qdmr's published manual (the "Extensible Codeplug File Format" chapter), files written by qdmr 0.15.1, and dmrconf encode run on test files, with the binary it writes decoded by the editor's own decoder. qdmr's source is GPL and was not read (CLEANROOM.md).

Code: site/static/js/codeplug/yaml.js (the YAML subset), site/static/js/codeplug/qdmr.js (the mapping), site/static/js/editor/qdmrpart.js (the editor's Open and Save), tests in site/tests/qdmr.test.mjs.

1. Syntax

The file is one YAML 1.2 document. qdmr uses a small part of YAML, and yaml.js reads that part:

Anchors, aliases, complex keys and tabs in indentation are refused with an error. The writer quotes a string when the plain form would read back as something else (a number, true, empty, leading space, : or #).

2. Structure

The top-level keys, in qdmr's order:

Older qdmr versions and the manual name the element types digital and analog. The import accepts both spellings; the export writes dmr and fm, as qdmr 0.15 does.

2.1 References

Every element has an id that is unique in the file. Other elements refer to it by that id: a channel's contact, groupList, radioId and aprs, a zone's A and B, a group list's contacts, an APRS system's revert. qdmr writes ids as a prefix and a count (ch12, cont3, grp1, zone2, aprs1, id1), and the export does the same in table order. The import doesn't depend on the form. A reference to an id the file doesn't define is dropped.

2.2 Values

3. Elements

3.1 Radio IDs and settings

The export writes one radio ID for the radio (id1) and one more for each distinct channel DMR ID. Other settings (power, audio, tone, the boot logo and password, talker alias encoding and so on) are radio settings the codeplug image doesn't hold in the editor's model; the import ignores them and the export leaves them out, so qdmr uses its defaults.

3.2 Contacts

openGD77 is the name qdmr gives its block of per-contact and per-channel extension keys for the open-firmware radios.

In the export, DTMF contacts follow the digital contacts and continue their id count.

3.3 RX group lists

name and contacts map directly. A list keeps its first 32 contacts.

3.4 Channels

Both types:

DMR channels:

FM channels:

The SFR settings (flag, bytes A and B) have no qdmr counterpart; the export leaves them out and says so.

3.5 Zones

name and A map to a zone and its channels. qdmr's zones have two lists, A and B, while an open-firmware zone has one. A zone with an empty B list imports as one zone. A zone with channels in both imports as two, <name> A and <name> B, which is also what dmrconf encode writes for this radio. The export writes each zone as an A list with an empty B list. A zone keeps its first 80 channels.

3.6 APRS

An aprs element under positioning becomes an APRS configuration (open-firmware-cps.md 7.3.8):

The export builds source from the radio name (letters and digits, up to 6) and the SSID, or N0CALL and the SSID when the radio name has none. The silent and ambiguity settings have no qdmr counterpart.

dmr elements under positioning (position reports over DMR) have no counterpart and are dropped.

qdmr's icon names, each a symbol of the primary table (/), as dmrconf encode writes them:

A symbol from the alternate table, or /D and /J, exports as None with a note.

4. What each direction reports

The import returns the record counts and a list of notes, each a code and a count, for what it changed or left out: names shortened, scan lists, roaming, encryption keys, DMR position reporting, APRS periods, extra path entries, unknown icons, lists and zones over their limits, records over the table limits, unknown element types, channels without a valid frequency, sub-tones that aren't CTCSS or DCS. The editor lists them after the import.

The export returns notes for SFR settings, power levels qdmr has no name for, channel locations rounded to a locator, APRS frequencies with no FM channel to name, APRS symbols with no icon, and the silent and ambiguity flags. The VFOs and the DMR ID database are never part of a qdmr file.

An import replaces the channel, zone, contact, DTMF contact, RX group list and APRS tables and the settings in 3.1, as one undoable change. Everything else in the open codeplug (the VFO frequencies, the radio's other settings, the DMR ID database) stays. The VFOs lose their contact, list and APRS references, since those pointed into the old tables. Records are numbered in file order.

5. qdmr's own binary encoding

dmrconf encode -R openuv380 on the same file writes the same channels, contacts, lists, zones, DTMF contacts and boot settings as the editor, with these differences (qdmr 0.15.1):

The APRS symbol difference means the firmware reads no symbol from a codeplug qdmr wrote (it takes a byte below ! as none). A codeplug written by the editor carries the symbol characters.

6. Tests

site/tests/qdmr.test.mjs covers the YAML subset, the value formats, an import of a file written in qdmr's form, the round trips YAML to model to YAML and cpsSim's codeplug to YAML to model, and the Tools page converters. When dmrconf is installed, a test exports a codeplug, runs dmrconf encode -R openuv380 on it and compares the decoded binary with the editor's encoding, field by field, apart from the differences in section 5. Without dmrconf that test is skipped.

View the source of this page