The Web Flasher

The browser tool that backs up, installs, updates and restores a radio, from site/static/js/flasher/. For users it is the recommended way to install RadioFoundry (Installing); this page is for people who change it. The site that hosts it is described in website.md.

The flasher is plain ES modules. The logic ports rfoundry, and the tests check the two agree:

Add #sim=<radio>-stock to the flasher's address to run every step against a simulated radio on its stock firmware, #sim=<radio> against one that runs RadioFoundry (an STM32F4 radio updates through the STM32F4 loader, an HR_C7000 radio through the loader hand-over). #sim alone is the first radio on stock firmware. The fake comes from the radio's data (fakeC7000Options() and c7000Simulation() in fakec7000.js, simulation() in fake.js): a radio with a stock console gets one, with its first stock version. #sim=<radio>-romfail is an HR_C7000 radio on stock firmware whose boot ROM refuses the load, to practice the factory update mode; #sim=<radio>-slowcable one on a cable too slow for the boot ROM's 48 ms window, to check that the page's answer sent ahead gets through; a radio with the Baofeng updater enters it when switched on with "Hold the Keys and Turn On".

The beta notice

The page opens a dialog (templates/partials/beta_notice.html, opened by beta.js) before anything else: what can go wrong, that the radio can always be recovered, where to get help, and common questions folded into accordions (testing, damage, channels and settings, fixes, feedback). It shows once per browser session and again once 12 hours have passed since it was closed, so a tab left open still sees it (sessionStorage key rfoundry.betaNoticeSeen holds the time of the last close, set on any close); where storage is blocked it shows on every visit. The installation count in flash.beta.lead is written by hand: total successful installations from the backend's flashes table plus about 50 development installs, rounded down. Raise it now and then.

Vendor files

vendorfile.js opens whatever the user picks, the same way on every radio's page. The input can be:

• a firmware .bin;
• a program flash readout;
• a vendor's zip with updaters, manuals and several builds inside, or a zip inside a zip (three levels at most).

Files are set aside by their content, never their extension: Windows programs, Office documents, PDFs, text and anything under 64 KB. Each remaining file is identified against every radio the flasher knows, the most certain way first:

The best file for the chosen radio is used:

1. one with the codec;
2. then one that gives the key;
3. then the first by name.

The page lists what each file is: used, for another radio, set aside and why. A codec found by its signature alone is never taken. Moving the codec needs that build's map, because its calls into the rest of the vendor firmware differ per build (codec-placement.md).

When a file can't be used

explain.js sorts every failure with a vendor file into one problem. stockfw.js StockError and c7000.js CodecError carry its code; vendorfile.js marks each file it opened (problem on a file no radio claims, on anything set aside).

For unmapped the notice names the version when the file is known, says when the file's bootloader key still works, and lists every supported file (folded above 12). When the install goes on without the file's codec (a kept codec), keepNote() picks a second notice on the codec step that says what DMR voice then depends on: the radio's verified codec, an unverified one, or none. None also covers a radio on its original firmware when no stock version of that radio keeps the codec where RadioFoundry uses it (codec.installed empty).

Each notice gives what happened, why and what to do. The exact message is under Technical details and in the error report. The same notices come on the HR_C7000 pages (c7000ui.js gets problemNotice and failureNotice).

A radio that doesn't answer the debug link probe is told apart by what its port gave (link.js silence(), whyNoAnswer()): nothing (silent), debug link frames that weren't the reply (link), or other bytes (other). When the first byte is -, the open-firmware CPS's refusal (open-firmware-cps.md 2), the page reads the radio info (area 9, section 4) and checks its structure, with a revision or a build date. Only that read is sent, never a C control command. A match is openfw: a radio on another open firmware (the OpenGD77 family), or a RadioFoundry build with the CPS shim but without the debug link, which answers the same way and can't be told apart in general. Right after an install, the done step passes the written build's manifest: when the radio's revision is that build's commit, or its feature list leaves out DEBUGLINK, the kind is rfoundry-nodebug and the page says the build has no debug link.

Where the radio answered (openfw, rfoundry-nodebug), the connection worked, so the page gives the next step instead of the cable and driver tips: on the "current firmware" step a button that chooses Another open firmware (on a board openfw.js backs up from, an openfw answer goes straight to that choice with its backup); on the radio, done and backup steps one line (connectHelp()).

The "current firmware" step has four choices (explain.js NOW_CHOICES): RadioFoundry, original firmware, Another open firmware and Other / Not sure. The last two are the same to the install (S.now.kind unknown: the codec decision and the steps don't change); S.now.openfw marks the first, for the pressed button and the error report. On a board openfw.js supports, Another open firmware also offers Check the Radio and, once the probe recognized the radio (S.now.radioType, git), the backup below. Other / Not sure doesn't: its route is the stock file.

The browser's own USB and serial errors (NetworkError, InvalidStateError, a failed fetch) say little. errorText() puts what to do in front of them: close the program that holds the port, check the cable, the Windows driver or the Linux device permission, reload the page.

Sending a file

The page offers Send this file for further analysis for unmapped, wrong-key and internal, when what was picked holds a vendor firmware container: a file with the OutSecurityBin or the C-SKY stock header, 4 MB at most. For dump it offers Send This Firmware to the RadioFoundry Team to Be Mapped with the program memory dump itself (reason progmem-dump): the backend takes a dump by the bootloader ID in its first 48 KB. It comes both when the codec can't be taken from the file and when a later step fails on a file identified for this radio (placing the codec, restoring). Readouts, other files and a file identified as another radio's are never offered. The text asks for the manufacturer's original file only. The file goes to the backend only on the user's click, with:

• its name;
• the radio being flashed;
• what the page found (codec-unmapped, key, key-unknown, unknown-container, or the problem);
• the site version;
• an optional note (it asks where the file came from). For internal, the page's message is added to it.

The backend (POST /v1/samples, raw body, the rest as query parameters) checks the header (or a dump's bootloader ID) and the size itself. It rate-limits per address and per day, caps the total storage, keeps one copy per SHA-256 and never serves a file back. Simulations don't offer it.

What an error report says about the file

Every error report carries vendor_file (vendorContext()) once a vendor file was picked. It never holds the file's bytes:

The start page's privacy text says that a report names the stock firmware file, never its contents, and that the flash log includes the browser's language setting.

The flash log and the vendor file

A use reports its milestones to the flash log, each once: the build request (custom builds), the start, the first data on the radio (first_byte), the last (last_byte), the end of the write (result) and the check on the "Done" step (verify, with its outcome). flashMark() sends the three data events to POST /v1/flashes/{id}/events from each install route's progress callback and from doneView(). A row with first_byte and no last_byte is a write that stopped midway. A row with no started is a build nobody wrote.

The flash log (POST /v1/flashes, PATCH /v1/flashes/{id}) also records which vendor firmware a use involved, so a failed install can be traced to a file. Only lengths, SHA-256 hashes and a short id; never bytes (those go only through Sending a file, on the user's click):

flashStarted() adds the fields known then to the POST and flashFinished() adds them again to the PATCH; the backend keeps a field the PATCH leaves out. Opting out (?reporting=0) and simulations send nothing, as for the rest of the log. A backend without these columns ignores the extra fields.

The POST and the build request (POST /v1/builds, when it carries the use's id) also carry languages; the PATCH and the events don't. Both requests carry adapter, and the PATCH carries trail:

Breadcrumbs

diag.note() lines record what the page decided, built in trail.js (names, sizes, hashes and reasons; never bytes):

The cable log (logBox()) also goes to the trail, so a boot ROM load that fails leaves the bytes received.

Every Sentry event carries the newest 40 lines in contexts.rfoundry.trail, the adapter in contexts.rfoundry.adapter and the tag adapter_chip.

Report a Problem

report.js reportDialog(). With the backend configured (the flasher), Send posts to the project's backend (problemreport.js), not Sentry:

1. POST /v1/reports with {result, flash_id, tool, tool_version, board, task, step, decisions, trail, error, message, contact, adapter}. result is problem when the install verified and failed otherwise. decisions holds codec_mode, codec_source, key_source, plan and files (role, name, length, SHA-256, id). The answer is 201 with id and an upload token.
2. Each checked file: POST /v1/reports/{id}/files?kind=stock|backup|readout&name=&token=, application/octet-stream. A refused file (413, 409, 410, 429, ...) is listed under the result. The report still counts.

The files offered are the vendor file picked, the internal flash read and the last backup the page saved. All are checked by default. The message and the email address are optional. The dialog says what is sent and that files and the address are deleted within 90 days. It works with ?reporting=0, since the user sends it. #sim answers locally (practiceFetch) and sends nothing.

Where it is offered: the button under every failure notice (errorNotice(), problemNotice()), the failed checks of the install, cable radio and loader routes, and the quiet "Something wrong? Report a Problem" link on Verify.

Every failure says what to do next: the message itself, or errorNotice(text, { next }) beside it. Where the step can run again in place, { retry } puts Try Again in the notice. Pressing it removes the notice first, so a second failure replaces the first instead of stacking under it. A step that shows its result in a status area clears that area at the start of each run.

The Update task

Update reaches a radio that runs RadioFoundry with one port chooser (its USB port and the programming cables), probes it, and lets the radio's backend take the connection: the STM32 radios keep the debug link (S.link), the HR_C7000 radios hand the open cable to their connect step (c7000ui.js adoptCable), which enters the stub without asking for the port again. The steps are update, then the backend's: write, done on the STM32 radios (the loader route when it can, the bootloader otherwise), connect, check, write, done on the HR_C7000 radios, whose check reads only the codec slot unless the user asked for a backup. Edit Build (or a build the radio can't name) puts build after update. On the HR_C7000 radios an update that keeps the codec runs from the check to the write without another click, once per cable session; a failed write, and the step reached by Back, wait for the button.

Which build runs (update.js currentBuild), from VERSION (debuglink.md 3.1):

The release a radio's build came from is the one with its commit, else the newest one older than its git_time. What that release knew is its variants' features and its manifests' off lists (tools/release.py): a switch in neither is new. A release from before manifests carried off names only its variants' features, so a switch a custom build had on in no variant reads as new, once.

The Codeplug Editor's Update Firmware opens flash/index.html#update and closes its own connection.

The original firmware version

A board with [flash.original_version] (board-registry.md) has a hardware option RadioFoundry can't detect but its original firmware's version settles. The install learns it before the write and stores it after the first start, so nobody picks it. The web flasher (origversion.js) and rfoundry (origversion.py) do the same steps:

Only the requests of the read are sent: GETSTATUS, CLRSTATUS or ABORT to reach dfuIDLE, DNLOAD block 0 A2 02, two GETSTATUS, ABORT, UPLOAD block 0 of 1024 bytes. The fakes (fake.js with originalVersion, rfoundry's fakedfu.FakeOriginalFirmware) fail on any other request; site/tests/origversion.test.mjs and tools/rfoundry/tests/test_origversion.py check the sequence, the parse, the table and the store.

Backup before the install

A board with [flash.original_backup] (board-registry.md) is backed up before anything is written, through the DFU device its original firmware or its bootloader shows (origbackup.js). The Current firmware step offers it under Original firmware and Other / Not sure, above the version read: recommended, never required.

1. Back Up Now opens the WebUSB chooser on the bootloader's USB IDs. The interface strings say which device it is (deviceKind): the original firmware (original_version.interface), the bootloader (loader_interface), or neither (refused, nothing sent).
2. The info blocks (info), each a block 0 command A2 ss and an UPLOAD of block 0.
3. Before program mode, one snapshot of the internal flash from its start: 65535 bytes, then 32768, 16384, 8192 and 4096 until the host passes one (Linux stops at 4096). It holds the radio's bootloader.
4. Everything (spi, about 6 minutes) or Channels and settings only (quick): program mode (91 01), the address set to 0, then 1 KB blocks with a progress bar. Stop ends the read early; the part read is kept. The bootloader gives loader_spi at most, and the page says a full backup needs the radio switched on normally.
5. The original firmware is left with 91 05: it restarts and runs normally again. The bootloader stays in program mode: the page remembers that USB device, and a write to it starts at 91 31 (Dfu.run programMode), since the bootloader takes 91 01 once. A power cycle makes a new device and the whole sequence.
6. The bundle is a backup bundle (rfoundry-backup/1, below): info/info-<ss>.bin (info-<ss>), bootloader-<bytes>.bin (internal-flash-mirror, at 0x08000000), spi-flash.bin or spi-flash-0-<n>MB.bin (spi-flash, complete only when it is all of spi). backup.json carries original_backup (the device, the version, the bootloader's version, the choice, whether the radio restarted, the browser) and firmware_now / firmware_before (stock with the version when the original firmware answered). Named <model>_Original_<last 8 UID digits>_<date>.zip. The Codeplug Editor's import and the channel conversion read spi-flash from it as from any bundle; Restore offers only putting the original firmware back from a file.

Guard is an allowlist in front of the transport: GETSTATUS, CLRSTATUS, ABORT, UPLOAD (1024 bytes, or the one snapshot of block 2 before program mode), and DNLOAD block 0 with exactly A2 ss, 21 + address, 91 01, or 91 05 (original firmware only). Anything else throws before it is sent. The fake radio (fake.js) models both devices: the mode byte and its gates, the ignored block number of the snapshot, the bootloader's 1 MB, the restart on 91 05, a host's transfer cap (usbCap), and a list of every request outside the allowlist that reached it (forbidden). site/tests/origbackup.test.mjs checks the allowlist, the order, both devices, the bundle, and a write after a bootloader backup.

The bundle holds the radio's calibration and its bootloader. It is saved as a download only: it is not kept for the report attachments (S.lastBackup), and the flash log and breadcrumbs get only its size and part count.

Radio access backends

A radio's flash.backend in data/radios.json names how the page reaches it (from the board.toml [flash] family, tools/boards.py FAMILIES). app.js runs the tasks and the steps every radio shares (radio, build, bundle, symptom, recover); the backend supplies the rest. A new way to install or back up a radio, such as another bootloader protocol or a stock firmware's own read-back protocol, is a new module that calls register() from backends.js and is imported by app.js. The task flow doesn't change.

A radio without a backend the page knows gets none, so a family can come before its module. The contract tests are in site/tests/backends.test.mjs.

Bulk reads for a backup go through readers (readers.js). backup.js readRadio reads the small parts only the debug link has (radio info, security registers) first. It then tries the readers it is given, in order, and the debug link reads the memories when none opens. A reader may also have security(), the security registers or null: the STM32F4 loader's SREAD (stub-stm32f4.md 6.2), each register checked against the CRC the loader sends. A reader has open(progress) (false: not possible now, nothing changed), used, read(mem, addr, n) giving {data, complete}, close() and abort(). A new read-back protocol is a reader, and the bundle format and the backup step stay as they are.

Backup bundles (rfoundry-backup/1)

A zip the user keeps: backup.json (the radio, its chip UID, the firmware when the backup was taken and before RadioFoundry, each part's address, size, SHA-256 and whether the read completed), internal-flash.bin (from the application base; the bootloader is never read or written), spi-flash.bin, security-registers.bin (the factory calibration), radio-info.bin, and stock-firmware.bin when the user gave one.

spi-flash.bin is the radio's own memory chip: backup.spi_size, or less when the radio reports a smaller chip (spiBytes: the radio info's flash part id, or the loader's SPI flash size from HELLO). Some radios of a model came with a smaller chip, and a read past its end is refused or wraps around. A backup over another open firmware sizes its read the same way (newState). Restoring the codeplug and opening the backup in the Codeplug Editor need only the codeplug's regions (TFTP_SIZE), not the whole open-firmware span.

openBundle() also reads a backup whose files sit in one folder (bundleFolder()): what macOS's Compress makes of a backup it unpacked, __MACOSX/ ignored. The restore picker and the codeplug editor use the same test.

The user picks what to read, each with a time estimate: from a short timed read of this radio, or through the loader from its measured speeds (stub-stm32f4.md 11) plus the hand-over and the restart:

Reads ask for 32 KB at a time. RadioFoundry answers that much (open-firmware-cps.md 2.1); older builds answer 2045 bytes, and the reader takes what comes back.

What can be read depends on the firmware running:

A CPS read the radio doesn't answer is tried up to five times, 0.3, 1, 2 and 3 s apart (link.js cpsRead): a radio quiet for a few seconds must not end a backup halfway. A read answered after a retry goes on the trail. Reads a build may not answer at all (the radio info and security registers in backup.js, the openfw.js probe) keep 3 tries, and a probe asks once.

Channels after an install (migrate.js)

A radio installed from its stock firmware still holds the stock codeplug, in a layout RadioFoundry does not read. The last step of the install brings it over by default, on every radio whose stock codeplug the browser converts. The backup panel before it says so (flash.backup.after_channels). With a backup that holds the stock codeplug the step writes without asking; without one it asks first:

The backup's copy comes first because the backup ends by claiming the settings area. On a family whose stock tables lie inside that area (zones on the 256 KB layout), the live read no longer holds them.

It runs at once when the backup taken in this visit holds the stock codeplug (the SPI flash read covers readSpan). Without one it waits for the user and says that the original bytes may be lost: on a board whose stock codeplug shares sectors with RadioFoundry's codeplug, the write replaces them. A failure at any step leaves RadioFoundry running without channels and says so. With the backup, the Codeplug Editor converts the original codeplug from there; without one, the message says whether the original is still on the radio (a read or conversion failure writes nothing).

The boards whose stock codeplug the browser converts are those in the TYT family layouts of codeplug/stock_tyt.js, and those whose paged stock codeplug codeplug/stock_baofeng.js reads (feature-matrix.md).

HR_C7000 radios (c7000ui.js bringChannels)

The stock codeplug sits in its own pages of the data flash, below RadioFoundry's codeplug, and no step of the install writes there. So the step needs no backup and loses nothing:

Another open firmware (openfw.js)

A radio whose port answers the debug link probe with - and gives a valid radio info is on another open firmware (link.js whyNoAnswer(), kind openfw). Where the board supports it, the Another open firmware choice of the current-firmware step offers a full backup before the install, and the install then needs no stock file.

Not yet tested on a real radio.

Restore

The stock file's resource segment (SPI flash 0x60000) is not written back: how the vendor updater writes it is not documented, and RadioFoundry doesn't overwrite it unless an ID database is uploaded.

Protected regions

No write touches a board's protected regions (board-registry.md: [[flash.protect]], the factory calibration first). protect.js is the one check, with the data from flash-boards.json.

The error is a ProtectedError (code "protected") naming the region and the reason from board.toml. Nothing is erased before the check.

HR_C7000 radios (the boot stub)

Radios whose backend is c7000-stub (the serial-loader and serial-iap families; a board with a first stage adds the section below) are flashed over their programming cable with Web Serial, through the boot stub (stub/README.md, debuglink.md 3.18), or through the radio's factory update mode when the stub can't be loaded (below). No loader in the radio is ever written. The install has its own steps:

A cable whose USB vendor id is a CH340's (1a86) gets a warning on the connect, check, write, backup and restore steps: some of these cables fail the backup or the install. The boot ROM load drops an exact echo of each frame it sent (some cables loop TX back to RX). A frame not acknowledged logs the first 16 bytes received, and the error names the cable's chip.

The boot ROM waits about 48 ms for the answer to its greeting (measured; the radio pages have the timing), and the greeting in and the answer out both cross the cable and the browser's read loop. When the load fails, the ROM says it stopped waiting (00 10 00 03, error code rom-late, or rom-booted when no greeting was seen). Answering only after the greeting arrived failed often on the first try, so every wait for the ROM uses the slow cable mode (powerCycle() in c7000ui.js; it was once a choice offered after a failure, and a collapsed note on these panels says where it went): waitForRom({ repeat: ROM_REPEAT }) sends the answer every 30 ms, and on for 150 ms after the greeting, so one leaves within 30 ms of it whatever the cable's latency. The page then waits for the line to go quiet (the ROM NAKs the extra answers) before block 0. The firmware of a radio left on gets the answers too: RadioFoundry ignores them, stock firmware is untested. So on a radio not known to run RadioFoundry the sending starts only after the user selects "Radio Is Off"; RadioFoundry's soft reset and a power cycle of a radio it found running RadioFoundry start at once. When the load fails, the factory update mode is the main action. stubtool.py --slow-cable does the same.

The session holds a stub only once it answered HELLO. A cable whose reading stopped (the device lost) is dropped before a step uses it, and after a failed backup, restore or check read the page asks the stub for HELLO: one that no longer answers (the radio switched off or reset) is dropped too, and Try Again goes to the connect step, which says why. Breaks and framing errors never stop the reading: a radio switched off with the cable in gives one after another for as long as it is off.

A page of an SPI NAND whose bit errors its ECC can't correct reads the same every time: the stub answers status 0x0D for its sector, in a read (op 09) or a checksum (op 07). The page then reads that sector's two pages itself with SPI requests (page read, status, read from cache), twice, and keeps them as the chip holds them. The final checksum pass sums a window that holds one sector by sector and leaves it out, and backup.json lists those sectors as nand_ecc. stub/stubtool.py reads a NAND the same way (Radio.nand_raw) and prints the list after a --nand read.

The factory update mode

Every HR_C7000 board has one: update_mode in its data/radios.json flash entry, from the family in tools/boards.py (serial-iap: iap; serial-loader: baofeng), entered by the keys in flash.bootloader (the steps) and bootloader_hold (marked on the radio's picture). The registry check refuses a board on such a family with no steps.

The page offers it when the boot ROM load fails (above), in Troubleshooting (recovery.extra, "Reinstall in Factory Update Mode"), and where the stock console and the first stage routes offer it. Nothing is read from the radio this way, so the check step takes the codec from a file (factoryRoute() in c7000ui.js): the stock firmware file where a profile of the board names one, else a program memory backup (or a slot this browser kept). The decision is never "keep": the image is c7.target() with the slot, without the 0xFF tail (factoryInstallImage() in iapui.js). Restore writes a backup's application area and slot, or the original firmware from its file, the same way. A step the user leaves (Back, Start over) while the page listens for update mode stops listening, so a radio switched on with its keys later is not written (site/tests/iapui.test.mjs). The Baofeng updater answers steps 1-3 once per power-on, so the session keeps the BfLoader that found it (c.loader, ready) for the write and the next try; after a write started, a try waits for update mode again. After the end of transfer the radio starts RadioFoundry by itself, so the done step's first check waits 20 s before it asks for a power cycle.

bfloader.js and c7000.js have installed a radio this way from Node, over an FTDI cable (the radio's hardware page has the figures). The page around them is checked only in practice mode, and the route is untested on the other radios on this loader.

A board with a first stage

A board with a first stage has no boot ROM window on its cable until the first stage is installed, and may have no SPI data flash the page can read. The board's table entry in data/flash-boards.json (c7000.boards.<id>, from tools/hrc7000_codec.py BOARDS) carries the program flash size, data_flash and stub_board, the profile the page sends in CONFIG (stub/stubtool.py C7_BOARDS). Its data/radios.json flash entry, from board.toml and board.mk, names the rest: first_stage (BOOT_SIZE, BOOT_SIGNATURE), stock_console with the stock_versions the console route knows, update_mode (the serial-iap family), read_rate (the program memory read's time estimate) and codec_version (the stock file the page asks for). The steps are the ones above, with these changes:

The first stage is the only way into the stub from a radio that runs RadioFoundry without answering. site/tests/iap.test.mjs runs the console stub load and the IAP write against simulated radios (fakec7000.js) and compares the codec carve with tools/hrc7000_codec.py.

The codec decision (decide() in c7000.js), first match wins:

An install without the codec asks once more when Install is pressed (nocodec.js confirmNoCodec()), on every route: the cable write, the update mode write (decision none) and the bootloader write (a decision with expectCodec false). The dialog says DMR voice calls won't work and offers Go Back and Add the Codec (the step before, where a file is selected) and Install Anyway. Escape stays on the step. A bootloader route without a codec step before the write (an update) offers only Install Anyway. A retry after a failed write doesn't ask again.

The page never sends a STUB command to RadioFoundry except right before it enters the stub: any STUB command parks RadioFoundry's codec until the next restart.

The build writes the layout and the codec profiles to data/flash-boards.json (c7000, from stub/stubtool.py, tools/hrc7000_codec.py and tools/serial_loader.py) and the universal stub image (with its load address, run address and RAM end) to data/c7000-stub.json. Bundle parts:

Each board's [flash.stub] in board.toml says what there is to back up: the program memory's size (progmem), whether the data memory is SPI NOR flash or an SPI NAND (from the board's NAND driver: the stub's nand flag), and where the factory calibration is (calibration, required). The page lists the same three choices for every radio from that data: the program memory, the calibration and the whole data memory, each with its size and time.

The NAND is read through the stub's NAND path (stub.js MEM.nand: flags bit 2 on op 07 and 09, the stub configured for a NAND board): its 2 KB pages without the spare bytes, two to a 4 KB sector, never written. The whole chip (256 MB) reads in minutes because the stub sends a blank sector as its record alone. blankCount samples windows spread over the whole range, so the estimate holds for a chip whose data sits in a few areas.

The count gives how much of a memory is used, not how well it packs. readSeconds takes a used sector whole for its time and packed to BEST_PACK (0.3) for least. Where the two differ by a minute or more, the choice shows a range: a full data memory packs well with a codeplug and not with an encrypted image.

The calibration choice is on by default. Choosing the whole data memory includes it. Restore writes the program memory back from the application start up; the data memory is not written.

Without a backup, the original firmware comes back from its vendor file. The restore task takes the file in place of a bundle (vendorRestore) once vendorfile.js identifies it for this radio, mapped or not. c7.progmemFromFile() takes a whole program memory readout as it is. A firmware file it lays out as a program memory read holds it: the application after the file's header (256 bytes for a BFUV32-V2 file, none for a plain one) at the application start, everything else erased. The stub or update mode then writes it as it writes a backup. A file larger than the application area is refused as internal.

STM32F4 radios (the loader route)

An STM32F4 radio on stock firmware always installs through its bootloader (dfu.js): that is the only way into a stock radio. Once it runs RadioFoundry, an update can skip the bootloader. When the "current firmware" step finds RadioFoundry, the page asks for the STUB offer (command 0x1A op 0; on the STM32 it only reports the staging buffer and parks nothing). The loader route is used when all of these hold:

The codec step then needs no stock file or key. The write step sends the embedded stub (data/f4-stub.json, from stub/f4stub.py), finds it on the same port or, if it enumerated again, on the granted port with the same serial number (one click picks it when the browser didn't keep the grant), and sends it the radio's board record (stub-stm32f4.md 5.2: SPI flash bus, mode and pins, chip select, chip selects held high, crystal, the bootloader's end). It reads HELLO again and goes on only when the echo is the record byte for byte, the configured flag is set and the application base is 0x0800C000. Then it installs in the order of stub-stm32f4.md 7: sector 3 erased first and its first word written last. A sector that also holds bytes the firmware doesn't own (no radio has one since the codec moved) is downloaded as a file before anything is erased, and those bytes are written back unchanged. The bootloader route stays on the same step, folded, and opens by itself when the loader can't finish. An install cut short leaves the radio in its bootloader at the next power-on, which that route finishes.

data/flash-boards.json carries per board (f4stub, from the board registry's [flash.stub] through stub/f4stub.py BOARDS and config_record()): the owned flash, the stub's board id, the 24-byte record as hex, and v2_wiring, with the protocol version and record length at the top. data/f4-stub.json gives the image and its protocol. The page sends the record as it is and never builds one, so the page and stubtool.py can't drift; site/tests/f4stub.test.mjs checks the records and the HELLO layout against f4stub.py's simulated stub (f4-vectors.json, written by site/tests/fixtures.py), and a board with other SPI wiring against f4stub's test profile.

Firmware images and custom builds

The flasher gets every image, a prebuilt variant's included, by building it on request (requestBuild in app.js) when the build step continues. The page sends the radio, the newest release tag (main before the first release) and the feature list, waits for the build, and checks the image against its manifest. Release images on the site (firmware/<radio>/) are not used by the flasher. The make command that builds the same selection, and a picker for the image it produces, stay under "Build it yourself".

A radio whose image depends on more than the feature switches lists the choices in board.toml [[build_options]] (flash.build_options in data/radios.json, such as a band: BAND=uhf|vhf). The build step asks for each one before it builds, or takes it from a connected radio's debug link name (board_name), sends it with the request, and refuses an image whose manifest doesn't carry it (build_options). The current-firmware step refuses a radio whose name says another value.

The firmware's language packs are feature switches named LANG_<CODE> (CONFIG_LANG_ES, the code upper-cased). When the browser's languages (navigator.languages, primary subtag) include one the radio can have a pack for and the selection leaves it out, the build step offers it under the build cards: one button turns the switch on, another dismisses the offer until the page reloads. Only the first language the browser asks for that has a pack counts, and English (the firmware's own) never does. The code comes from the switch name alone (flasher/langsuggest.js), so a new pack needs no flasher change. Strings: flash.build.pack_*.

Radio language (LANG_DEFAULT_<CODE>) lists English and every pack the radio can have; one the build leaves out reads "(adds it to the build)". Picking it turns its pack on, and the pick holds across the build cards until the pack is turned off by hand (the radio then starts in English). Picking another language takes out a pack the pick added. On an installation it is preset to the page's language only when the build has that pack.

A build too big for the radio fails at the build service with too big: <region> overflowed by <N> bytes (the linker's region, flash first). The build step shows it as a notice, not an error to report: how many KB too big for the program memory (or the RAM), to turn features off in Custom or pick a smaller build, and, when the Radio language added a pack, that English leaves it out again (flasher/buildfit.js; strings flash.build.too_big*).

Version links

To have someone install a version that isn't a release (a commit to try out), send them the flasher with ?version=:

https://<site>/flash/?version=<full 40-character commit hash>
https://<site>/flash/?version=<full commit hash>#radio=<id>
https://<site>/flash/?version=v26.11
https://<site>/flash/?version=feature/my_radio

Without a link, a radio with no release is built from main. On a preview of another branch (data/site.json branch, from CF_PAGES_BRANCH or the checked-out branch), it is built from that branch instead, so a radio that exists only there can be tried.

The feature list comes from the site's own release data. A commit with other feature names makes the build fail with the service's error.

A failed install (the help task)

"My radio isn't working" on the start page asks for the radio and the symptom, then walks to a fix. Every screen keeps the reassurance that the page never writes the part of the radio that starts update mode.

The fix chooser offers installing again (the install steps without the current-firmware question), putting back a backup (the restore task with the target preselected) or the original firmware (STM32: the stock file, then update mode; HR_C7000: the restore task, with the backup or the original firmware file). Each failure message in the install steps links here (helpLink).

USB network mode

A radio in USB network mode (1FC9:0096, usb-network.md) has no serial port, and the flasher can't reach it another way: pages can't send UDP (port 3334 carries the debug link and CPS in that mode), an https page can't fetch from the radio's http status server, and the OS network driver owns the adapter's interfaces, so WebUSB can't claim them. WebUSB can still list the device, so the flasher detects it (a radio this page has seen before is found without a prompt; otherwise "Check for USB network mode" under every connect button) and tells the user to switch USB back to serial on the radio. The bootloader is unaffected: it is a separate USB device.

The manual install kit

Where the page can't install, manual.js builds a zip for installing from the command line with rfoundry (user view: installing). No release carries an rfoundry executable yet, and the tool must come from the site's own commit: manifest.verify refuses a codec profile or board it doesn't know. So the site build publishes downloads/rfoundry-tool.zip (site/rfoundrysite/toolzip.py): the rfoundry package, tools/serial_loader.py, tools/hrc7000_codec.py, stub/stubtool.py and stub/f4stub.py in the repository's layout (serialflash.py loads the tools by path from the package's grandparent), a root rfoundry.py launcher, requirements.txt and the license. The zip is reproducible: sorted entries, the commit's time. data/site.json tool is {zip, sha256, size}; the page refuses a download that doesn't match it.

The stock file is S.stock (the inner file of a vendor zip), else the file the C7000 codec step took (S.vendorPick); a file with a problem is left out. The line sits under a failed bootloader connect (not a cancelled chooser) or write, and under the C7000 connect's failed boot ROM wait or load (ctx.manualKitLine in c7000ui.js). Practice mode never offers a kit: its image is random bytes. Tests: site/tests/manual.test.mjs. Untested with a radio.

The README's setup (kitSetup()) names Python PYTHON_MIN and each package of PACKAGES; the test checks both against tools/rfoundry/pyproject.toml and the zip's requirements.txt. The packages are not bundled: pip picks the libusb-package build for the user's system, which a kit made in the browser can't know.

Browser support

WebUSB and Web Serial: Chrome, Edge and other Chromium browsers on a computer, over https or localhost. Windows needs the WinUSB driver for the bootloader (Zadig, once), as rfoundry does. On Windows the bootloader step shows the Zadig steps (installing), open until this computer has reached a bootloader once, and again with any failed connect: without the driver Chrome either doesn't list the bootloader or can't open it. The device name comes from [flash.dfu] product in the board's board.toml.

Other browsers (Safari, Firefox) can still choose and build the firmware; the step that needs the radio then offers the manual install kit.