RFC-0023: Repeater-Class Firmware Provenance

[kn4oqw-clint]

• Status: draft — decision taken on building and signing; the upstream-divergence half is open
• Author: KN4OQW
• Implements requirements: #25 (full-size MMDVM repeater-class support), the firmware half
• Depends on: RFC-0019 (built-in firmware flashing — the catalog, the GPIO ROM-bootloader path, and the "not from a third party's directory layout" rule this extends); RFC-0013 (the verifier every artifact passes through); RFC-0020 (board identity — what the wire can and cannot tell us)

Summary

The repeater-class tier (Repeater Builder STM32_DVM, MMDVM_RPT_Hat, ZUM Radio,
F4M/F7M, Nucleo) is implemented in feat/full-size-modem-tier — detection,
board table, the capability gate, the analog surface, the die guard, and the
manual-jumper flash path — with one hole: no firmware in the catalog.

RFC-0019 already settled where firmware comes from: a Waypoint-published,
CI-built, minisign-signed catalog, because "a host system that treats another
project's file layout as an API has taken a dependency it cannot maintain". That
rule applies here unchanged, and the decision is to build and sign these
images ourselves.

This RFC exists for the part RFC-0019 did not have to think about, because in
the hotspot tier it was not true: for these boards there is an active
third-party firmware supply, and it is ahead of upstream in places. If
Repeater Builder, dvswitch.org or WPSD publishes a build for a board we also
publish for, an operator has two images with the same version string and no way
to tell which is on their board. Worse, ours may be the one missing features.

Why this is not the hotspot situation

In the MMDVM_HS tier the firmware supply is effectively one tree (CA6JAU's) and
the version string is a reliable identity. The repeater tier is not like that:

Upstream ships features a plain g4klx/MMDVM build does not. Repeater
Builder's MTR2K page offers a firmware "V.1.6+" adding M17 compatibility and
possible AllStar FM linking, and says it "requires an update to Pi-Star as
well" — which is the 500000-baud modem entry WPSD carries. That is a fork with
features in it. If Waypoint builds from g4klx/MMDVM master, calls it "the
firmware for your MTR2K", and an operator flashes it, we can take M17 away
from a board that had it. A firmware update that silently removes a mode is the
worst outcome in this whole document, and it is the realistic one.

The identity string cannot tell two builds apart. SerialPort.cpp:107-123
composes it as HW_TYPE " " VERSION " " TCXO " GitID #" GITVERSION, and
VERSION is a date literal in the source tree (Version.h), not a build
identity. Two builds of the same commit by different people report the same
string. The GitID is the only provenance the wire carries, and it only
appears when the build defines GITVERSION.

A wrong build flag is not a loud failure. HW_TYPE is selected by
DRCC_DVM_446 / DRCC_DVM_722 / DRCC_DVM_HHP446 / DRCC_DVM_NQF at compile
time. Build the wrong one and the board reports itself as a product it is not —
which, now that Waypoint resolves the board from that token, means our own
detection would confidently name the wrong row.

The parts differ in ways the tooling notices. Pi-Star ships stm32flash 0.5
for rpt_builder_v3/_v4 and 0.7 for _v5. Waypoint asks the bootloader
which erase command it has rather than hardcoding one, and ParseCatalog now
requires every variant to name its die — but that split is a standing reminder
that "the F4 path" is not one path.

What is already in place

• Catalog.ProductID is required, and Flash refuses an image whose die
  does not match the part the bootloader reports (F103 0x0410, F446 0x0421,
  F722 0x0452, named in internal/flash/parts.go).
• Boards with no host BOOT0/nRST wiring (RB v1/v2) flash through a
  manual-jumper path that touches no GPIO and says what to do when nothing
  answers.
• Every artifact still passes RFC-0013's verifier: SHA-256 plus a minisign
  signature over the catalog.

Options

A. Waypoint-built and signed only. RFC-0019's rule, applied literally. We
pin a source tree per variant, build in CI, sign, publish. Clean provenance;
carries the risk of shipping a build that is behind a vendor fork.

B. Mirror and re-sign upstream images. Take Repeater Builder's .bin,
record its digest at review time, sign our copy. Keeps feature parity with the
vendor; makes us a redistributor of a binary we did not build and cannot
reproduce, which is the dependency RFC-0019 refused.

C. A + an explicit operator-supplied path. Publish our own images, and let
an operator flash a file they provide, with the UI stating plainly that it is
not signed by us and recording what was flashed. The die guard and the
manual-jumper flow already work on any image.

Proposal (for comment)

C, with A as the default, plus three requirements that come out of the
divergence problem rather than the flashing problem:

1. Build with GITVERSION set, always. It is the only thing that makes
   "whose firmware is this?" answerable from the wire, and Waypoint already
   parses and stores it (Identity.GitID). Without it every build of a given
   date is indistinguishable.
2. Catalog rows carry their source. Tree URL and commit alongside the
   digest, so a variant is reproducible by a third party and comparable against
   a vendor image.
3. Never publish a variant for a board whose vendor firmware we have not
   feature-compared. Specifically: no MTR2K variant until somebody has
   established whether g4klx/MMDVM master carries what RB's V1.6+ carries. A
   variant we cannot make that claim about does not ship, and the board keeps
   whatever it came with — which is a working repeater.

Open questions

• Do we publish for boards nobody here owns? Everything in the branch is
  tested against an emulated part. An unflashed board is a working board; a
  wrongly-flashed one is a repeater off the air. My inclination is that a
  variant ships only after somebody has flashed that die on a bench.
• What does the UI say when the firmware is not ours? The re-probe after a
  flash reads the identity string back; a GitID that is not in the catalog is
  detectable, and "this board is running firmware Waypoint did not publish" is
  useful, neutral information — but it must not read as an error, because it
  is a legitimate state.
• If upstream starts publishing for a board we publish for, does the
  catalog step aside, or do we carry both and label them? This is the question
  this RFC exists to keep visible.

Watch items

• Repeater Builder firmware releases, and whether the dvswitch.org/files/HAM/MMDVM/
  layout stays as it is (sbin Cross mode gateways #55 is what happens when it does not).
• Whether the RB MTR2K fork's M17 support lands in g4klx/MMDVM upstream. If it
  does, most of the divergence risk here evaporates and option A is simply correct.
• WPSD's modem list for new repeater-class entries, particularly further baud
  rates — 500000 was already an entry we had to go and find.