The Web Site

The site is generated from the repository, like the PDF manual. It lists the radios, their screens and features, holds the documentation, and carries two tools that run in the browser with nothing sent to a server: the web flasher (back up, install, restore; web-flasher.md) and the Codeplug Editor (codeplug-editor.md). The site is the recommended way for users to install RadioFoundry and edit a codeplug (Installing); this page is for people who change it.

python3 site/build.py                       # build/site/
python3 site/build.py --serve               # build, then http://localhost:8000 (WebUSB needs localhost or https)
python3 site/build.py --firmware build/dist # with release images for the flasher (tools/release.py --out)
python3 site/build.py --strict              # any warning fails (CI)
site/tests/run.sh                           # the flasher's and the editor's tests (Node 20+)

The generator needs two Python packages, markdown-it-py and resvg_py (pip install -r site/requirements.txt, or prefix the command with uv run --no-project --with-requirements site/requirements.txt). The pages need no build step and no npm packages: plain HTML, CSS and ES modules. tools/ci.sh builds the site and runs the tests (Python step).

Cloudflare Pages builds and deploys it (see Hosting):

The pull request's unit tests job also builds the site (--strict) and runs the flasher's tests (tools/ci.sh's Python step).

Hosting

The site is static files on Cloudflare Pages, project radiofoundry, connected to this repository through Cloudflare's GitHub app. Pages builds in its own build image (Python and Node.js preinstalled) and switches the site to a new deployment in one step, so a deployment has no downtime.

Sources

Nothing on the site is copied by hand. Each page reads its source at build time:

The build fails when a source doesn't parse, and warns (an error with --strict) when a feature has no row in the feature matrix, a screen isn't in screens.json or names a group it doesn't list, a string is missing from the English catalog (a screen's caption included), the Screenshots page lacks a board or a screen that board's build has, or a page links to a file the build didn't write.

data/*.json is what the pages read and doubles as a public API for other tools: radios.json, features.json, variants.json, flash-boards.json, screens.json, releases.json, site.json.

The Screenshots page

/screenshots/ has a section per board, from the registry in its order, and a link per board at the top. Each section shows every shot in the board's gallery whose screens.json entry needs only switches the board's full build has (the radio page's six use the same test). A board's screens are one width: a gallery 160 pixels wide or less at twice its size, a wider one as it is. A color page's shots in other highlight colors and themes (<page>__<color>) follow the page, hidden until the visitor ticks "Also show other highlight colors and themes" (CSS :has(), no script). site.js switches sections without reloading and keeps the address #<radio>, so a link can name a radio (each radio page links to its own). Without the script, CSS shows the section the address names (:target), else the first.

Nothing on the page names a screen, a group or a radio:

Screenshot copies

The gallery holds each screen at its panel's size. The pages draw screens larger, at sizes that are rarely a whole multiple of it, on displays whose device pixel ratio may be fractional (125 %, 150 %). Nearest-neighbor scaling (image-rendering: pixelated) then makes some pixel rows wider than others, and a browser that ignores the property blurs them. So site/rfoundrysite/shots.py writes a copy of every gallery screen, static/img/screens/<gallery>/, scaled up a whole number of times with hard pixel edges, and the browser scales it down smoothly: every pixel keeps one width, at any size.

The build fails when one of those rules is gone from site.css. The copies carry no image-rendering. The docs pages still link the gallery's own files, shown with image-rendering: pixelated. A higher pixel ratio than 2 scales a copy up a little, smoothly. site/tests/shots_test.py checks the scaling.

Layout

Templates and design

Markup lives in site/templates/*.html and partials/, with four kinds of placeholder: {{ value }} (escaped), {{{ html }}} (as built), {{t key}} (a translated string) and {{> partial }}. ../../../ is the path to the site root (static files, data) and ../../../es/ the path to the root of the page's language (links between pages). Loops stay in Python, which renders a partial per item.

Every page's footer has two help cards: the community group (COMMUNITY_URL in site/rfoundrysite/build.py, also community in data/site.json) and the GitHub issues. The web tools' report line under an error (reportLine() in static/js/report.js) links the same two. Their icons are CSS masks (.icon-* in site.css), drawn in the text color.

Every page's footer ends with a faint build stamp: the firmware release the flasher installs (linked to its GitHub release; left out before the first release), a Changelog link to the GitHub releases, the commit the site was built from (-dirty with uncommitted changes, linked to the commit) and the build time in UTC. data/site.json has the same commit and the date, the release (release) and the pre-release offered (beta, below).

All visual decisions are variables in tokens.css: colors for light and dark, type sizes, spacing, radii. site.css only uses them. A redesign replaces tokens.css, then site.css and the templates; the generator doesn't change. Readability comes first (principles): 18 px base type, high contrast, nothing squeezed.

Glossary

docs/glossary.json is the one source. python3 tools/glossary.py --write generates the two glossary pages from it: user/22-glossary.md (entries with scope user) and glossary.md (scope dev). Never edit those pages by hand. tools/ci.sh fails when they are stale.

The site build (docs.py) wraps a term in <abbr class="gl" title="..."> at build time. The Markdown stays unmarked, so GitHub shows plain text. Rules:

• Whole words only. Not inside code, headings, link text, a table's first column, hyphenated words or paths.
• The first use in each section (a section ends at the next # or ## heading).
• <!-- glossary: off --> in a page turns marking off for that page. <!-- glossary: off TG, SFR --> turns off those terms.

site.js turns each <abbr> into a popover on hover, keyboard focus and tap, with a "More" link (Enter follows it from the keyboard). Without JavaScript the title shows the definition. site/tests/glossary_test.py tests the rules.

To add a term, add an entry to the file, run python3 tools/glossary.py --write and python3 tools/glossary.py --check. python3 tools/glossary.py --unexplained lists all-capital words the docs use that have no entry (pin names and identifiers with digits or underscores are skipped). Add an entry for each one that matters to a reader, or its name to excluded.

Translating

How to add a language, radio and site: translating.md. site/i18n/languages.json lists the languages. The default (English) is at the site root, others under /<code>/. The header's language menu (details.lang-switch) links the page in every language. On a first visit, when the browser's first language the site has isn't the page's, a bar under the header offers it, in that language (static/js/langhint.js; the words come from each catalog's nav.lang_* keys). It never redirects. Picking a language or dismissing the bar is remembered (localStorage rfoundry-lang). Each language has a flat catalog site/i18n/<code>.json; a missing key falls back to English, key by key. The flasher, the Codeplug Editor and the Tools page get their strings from the same catalog, embedded in the page (<script id="i18n">, read by static/js/i18n.js). Text that comes from the repository (feature help, variant reasons) is English at its source; a catalog can override it with feature.<SWITCH>.title, feature.<SWITCH>.help, variant.<id>.title, variant.<id>.summary or group.<slug>.

With more than one language, every page gets a language switcher in the header (a link to the same page in each language), <link rel="alternate" hreflang> for each language plus x-default, and its own 404.html in each language's tree. Links between pages use ../../../es/ (templates) or HOME (flasher/dom.js), so they stay in the visitor's language. With one language there is no switcher and no alternate links.

A translated documentation page goes in docs/i18n/<code>/<path under docs>. Pages without one are shown in English with a notice, the text marked lang="en".

Plurals, numbers and dates

To give an English string plural forms, replace its key with key.one and key.other in en.json, then the translations.

The check

Every build checks the catalogs (i18n.check() in site/rfoundrysite/i18n.py) and warns, an error with --strict:

• each file is valid JSON with no key twice;
• languages.json names its default among the languages, each with a code, a name and ltr or rtl;
• a catalog other than English has only keys en.json has. A plural form counts when en.json has the family;
• each string keeps the English placeholders ({name}, {{...}}) and HTML tags. A plural form other than other may leave {n} out ("one file").

python3 -m rfoundrysite.i18n (from site/) runs the check alone, and also fails on a key a language lacks (i18n.missing()): the site works without it, but a pull request leaves none (translating.md). site/tests/i18n_test.py tests the check and builds the site with a made-up second language: pages under /es/, the switcher, alternate links, English where the catalog has no string. site/tests/i18n.test.mjs tests the scripts' side. tools/ci.sh runs both.

Adding a language

1. Copy en.json to <code>.json and translate. Leave a string out rather than copy it: English fills in.
2. Add the language to languages.json.
3. If its plural rule differs from English's, add it to PLURAL_RULES in site/rfoundrysite/i18n.py.
4. Build and look: python3 site/build.py --serve, then http://localhost:8000/<code>/. --strict shows any catalog problem.

What stays English

Radio images

Each radio has an original illustration, site/static/img/radios/src/<radio>.svg, drawn from straight-on reference photos (the photos stay outside the repository: product photos are not ours to publish). Rules:

• viewBox 0 0 W H, transparent background, no external references or embedded images;
• exactly one <rect id="screen" x y width height/>, black, transform-free and not covered by anything, on the display's visible area, with the aspect ratio of the radio's gallery (5:4 for 160x128 and 160x120i5, 22:31 for 240x320i10x5);
• for the radio's web control page (docs/spec/tcp-services.md 5.1): each key it shows carries id="key-<name>", the name being the board's KEY_* in lower case without KEY_ (key-fn_left); the channel knob id="encoder" and a drawn LED id="led". Keys whose shape doesn't match a key (a d-pad drawn as one piece) get transparent hit rects (fill="none" pointer-events="all") at the end. A key off the front face (side keys, top keys) also carries data-edge="left|right|top|bottom", the drawing's edge it is on: the page puts a labeled button for it outside that edge. Every key of the radio is tagged, or named in data-undrawn="name ..." on the <svg> element when the drawing doesn't show it (a front view without the side keys); the page makes those buttons;
• tools/svg_keys.py check checks the tags: each key- id names one of the radio's keys, once, and no key is missing. The site build runs the same check, so a drawing that lost its tags fails CI. After drawing or redrawing a radio, tools/svg_keys.py tag <radio> adds the tags: by the labels in the drawing ("MENU", "1", "*"), then by the last tagged version in git, mapped onto the new drawing (edges, the LED, the knob and hit rects come along). It prints each tag and what it couldn't place. Check the result on the web control page before committing. A key's shape has no transform, its own or a group's: the build reads its box from its attributes (below), and the check fails one it can't read;
• a radio with a keyed hand microphone may have <radio>-mic.svg beside its drawing, for the web control page only: the same key- rule, the ids counted once across both files, and gradient ids of its own (the page puts both drawings in one document).

A look (board.toml looks) has its drawing in <radio>-<look id>.svg beside the board's, under the same rules and with the same keys. The build writes its frame and boot-screen files like the board's, and fails when the drawing is missing.

The build writes static/img/radios/<radio>-frame.svg (screen black), <radio>.svg (with the boot screen) and the screen's position in data/radios.json (frame_geometry: viewBox units and percentages), so any screenshot can be laid over the frame; the radio pages do that when a screenshot is clicked. frame_geometry.keys has each tagged key's box, as percentages of the picture. A radio without an illustration gets a generic drawing from board.toml [frame]; its handheld shapes tag their side PTT, and the caption names any other key.

The web flasher shows the same frame (frame_image) beside every update mode step, for every radio (flasher/radiotop.js): the bootloader entry steps as the picture alone, the HR_C7000 steps with what the screen shows laid over it at frame_geometry and an LED swatch that blinks as the real LED does, with a caption in words. Nothing in the flasher names a radio: a new board's picture appears with no flasher change. site/tests/radio_images_test.py (run by site/tests/run.sh) renders every board's picture and fails a board without a usable one.

On the bootloader entry steps (the STM32 radios' and the HR_C7000 update mode's), the flasher rings the keys to hold on the picture and names them under it ("Hold PTT and SK1"). The keys are [flash.bootloader] hold in board.toml, by key name, carried to the flasher as flash.bootloader_hold; the rings sit at frame_geometry.keys, and the labels are flash.key.<name> in the string catalog (a key without one reads as its name in capitals). The rings are decoration: the steps stay the instructions, and a key the picture doesn't show (in data-undrawn) is named in the caption only. radio_images_test.py checks every board: each key to hold is a key of the radio, tagged in its drawing and each look's or listed undrawn, with a label; site/tests/radiotop.test.mjs checks the marks and the caption.

Flasher notices

Two notices show on every step of the web flasher once a radio is picked, above the step:

One more shows on the start page and the first install step: Beta, when site.json names a pre-release newer than the release (--beta, from site/cloudflare-build.sh). It links to the same page with ?version=<beta>, so the user opts in through a version link and the build service builds the tag; the default install stays the release. It is hidden while a version link is in use. Text: the flash.beta.* strings.

Error logging and bug reports

The flasher and the Codeplug Editor log what they do in memory (static/js/diag.js). Neither keeps the log after the page closes.

Every error also goes to the browser console ([rfoundry] <stage> failed:). Failure messages carry Report a Problem (static/js/report.js). It downloads a zip with report.json (the log, the browser, the tool's state) and, if the user ticks them, the edited codeplug and the one last read from the radio.

Automatic error reports go to Sentry when the build has RFOUNDRY_SENTRY_DSN set (a production variable of the Pages project; site.json reports.sentry_dsn). Without it nothing is sent and the privacy note is left off the pages. With it:

Automatic reports go through diag.scrub(), which removes callsigns, DMR IDs and email addresses. The Sentry bundle is pinned with an SRI hash in report.js. It loads without breadcrumbs or other default integrations, so it sends only what diag.error hands it. ?reporting=0 turns sending off, as it does for the flash log. Ad blockers often block Sentry; the page then works the same and offers the download only.