The Board Registry

The registry holds every fact about a radio that the build itself doesn't need: its identity, status, build options, flashing route, codec route and the web site's data. The tools, CI, the docs and the site read it. The build reads no TOML: make keeps its own facts in board.mk, config.mk and memory.ld, and the registry reads those through make.

tools/boards.py loads and checks the registry. It needs Python 3.11 or later (tomllib); scripts find one with tools/rfoundry_python.sh.

Where each fact lives

Each fact is in one file. A value another file already holds is derived from it, never typed twice.

Derived values:

board.toml

The schema in tools/boards.py (BOARD_SCHEMA) lists every key; check refuses an unknown or missing one. Copy a neighbor on the same platform.

Identity

[docs]

check fails when a page doesn't exist. The README's radio table links the board to its bringup page, else its hardware page.

[hardware]

One-line summaries for the site and the generated tables; the facts stay in docs.hardware.

A variant is { code, name, level, notice, runs }:

The web flasher reads the code before it writes (the stock console, the vendor identify reply) or asks the user, and refuses an image the variant doesn't run (site/static/js/flasher/variant.js). check requires a supported board to have a supported variant that runs its own image.

[status]

[[build_options]]

A hardware build option: one radio model sold in versions that need different images (one band per radio, for example). board.mk holds the build's side: BUILD_OPTIONS := BAND and BAND_VALUES := uhf vhf, the default first. board.toml holds the words. check requires the same names and values in the same order.

The Makefile defines RFOUNDRY_<NAME>_<VALUE> as 1 or 0 for every value. A value other than the default adds -<value> to the build directory and the image: make BOARD=<id> BAND=vhf writes build/<id>-vhf/rfoundry_<id>-vhf.bin. Building has the user side.

[ci]

[flash]

[flash.bootloader]:

[flash.dfu] (usb-dfu): vid, pid, string1, product (the USB identity) and key_sha256, key_prefix (the per-model XOR key's hash and first bytes, never the key). Optional layout: the bootloader's alt 0 interface string, added only once it was read on a radio in its bootloader. The flashers then accept no other device. Without it they refuse a layout that shows only the bootloader's sectors (from 0x08000000, at most 48 KB): that is the radio's own firmware switched on normally, which has the bootloader's IDs and strings but whose erase can reach the bootloader.

Original firmware version

[flash.original_version] (optional): a hardware option (board_t.hwopts, debuglink.md) that RadioFoundry can't detect but that the version of the radio's original firmware settles, such as a board revision when the manufacturer ships one firmware line per revision. The installers read that version before they ask for the bootloader, and store the choice over the debug link once RadioFoundry runs (rfoundry's origversion.py, the web flasher's origversion.js; web-flasher.md).

tools/boards.py check refuses a choice or option name that doesn't appear in the board's sources. A version whose major isn't listed settles nothing: the radio then uses its own fallback.

Backup before the install

[flash.original_backup] (optional, with [flash.original_version]): what the web flasher backs up through the original firmware's or the bootloader's DFU device before an install (origbackup.js, web-flasher.md). The commands are in the radio's hardware page.

[flash.stub] (a board on a platform with board_stub): id (the board id the stub echoes, unique per stub; 0xFE is reserved for the stub tools' test profiles) and tested (flashed through the stub on a radio), then the keys the platform's board_stub names:

A key of another platform's stub fails the check.

Protected regions

[[flash.protect]] lists flash that no tool erases or writes: factory data that can't be made again, the calibration first. One table per region:

[[flash.protect]]
mem = "data"
start = 0x1000
end = 0xC9000
what = "factory calibration: the page tagged 2 in the stock codeplug area (hardware-<radio>.md 6.4)"

tools/boards.py check refuses an entry:

• whose memory the board doesn't have (data and secreg need backup.spi_size and no NAND; nand needs a spi_nand_t in the board's sources)
• that runs past the memory's end
• that isn't on the memory's erase boundaries: the platform's sectors (or 4 KB) for progmem, 4 KB for data, a block for nand, a register for secreg
• that overlaps another entry, the application or the codec slot
• whose what cites no section

A region whose place moves (remapped by a bad-block table, for example) is protected over every place it can be. The registry carries the list as protect (registry.json, radios.json flash, flash-boards.json boards, c7000 and f4stub).

What the tools do with it. tools/rfoundry/rfoundry/protect.py and site/static/js/flasher/protect.js hold the one check each language uses:

The stub tools check every erase and program command they send, not only the high-level writes. RadioFoundry's own firmware keeps its own rules for what it writes (the CPS shim refuses its areas, cps-protocol.md 2.3).

[codec]

A board has either stock, or profile with a linker codec slot. With stock, the profile and sources come from the stock files' profiles. The files must hold the same codec; each may put its tables at other addresses. The board's codec windows are the union of every file's layout. The image must stay out of all of them, and keeping the codec keeps all of them. A merge writes and checks the layout of the file it merges (codec-placement.md).

[cps]

radio_types: the radio types the open-firmware CPS radio info reports for this radio (open-firmware-cps.md 4). RadioFoundry's CPS shim reports them, and the web flasher checks them before it backs up a radio that runs another open firmware. The registry carries them as cps_radio_types, with rom_base (the platform's flash_base, where the CPS's area 5 offsets start).

[frame]

How the site draws the radio: shape, body and accent colors, lens size.

platform.toml

[toolchain]:

The toolchain scripts read these values with tools/platform_toolchain.sh, which needs no Python. check fails when a script, Dockerfile or workflow under tools/ or .github/ sets <ID>_GCC_VERSION or <ID>_GCC_SHA256 (for example ARM_GCC_VERSION) to a literal other than the pin: take it from platform.toml.

Commands

make registry regenerates tools/rfoundry/rfoundry/registry.json when a source changed. make does too, before every build.

The views

The build view

tools/boards.py json --for build gives a tool that builds images from a checkout everything it needs, with nothing from outside the tree. It is a stable interface: a change that breaks a reader changes format.

Each build:

In the names, {variant} is empty for the full build and -<name> for a variant; {version} is the release tag. One rule makes all of these names: tools/rfoundry/rfoundry/names.py. The Makefile follows it too, and check compares make's BUILD and TARGET with the view for every build.

Radio names

AGENTS.md rule 4 says only a radio's own files carry its name. tools/check_generic.py (run by tools/boards.py check) enforces it. The names come from the registry: each board's id, model and also, matched without regard to case, hyphens or a letter suffix (XR-100UV, XR100, xr100). A maker's word in front is dropped.

Everything else fails, tests included, and so does a file whose own path names a radio. Fix it by naming the function, the chip or the platform, or by reading the value from the board. The allowlist holds the debt from before the check; don't add new code to it.

Changing the registry

• A new key goes in the schema, in this page and in the reader that needs it. If the build already knows the value, derive it instead.
• Run tools/boards.py check and make registry, and commit the regenerated registry.json with the change.
• A new board: Adding a radio.