Web-based CPS for amateur transceivers which runs CHIRP's drivers in a browser and uses WebSerial to communicate.
This is live and running on webchirp.org
chirpis included as a git submodule atchirp/- Browser UI with a CHIRP-inspired Channels table and a Settings editor, switchable with tabs.
- Python runtime in-browser (Pyodide) running unmodified CHIRP driver code.
- Radio picked by searching CHIRP's driver catalog — including the alternate
vendor/model names a driver is rebadged under — served from a prebuilt static
catalog (
web/radio-catalog.json) with live enumeration as a fallback. The sidebar names the radio in use. - Selection-aware Load from radio / Save to radio using the selected CHIRP
clone-mode driver (
sync_in/sync_out). - Radio settings read and validated through the selected driver
(
get_radio_settings/validate_radio_settings). - Channel editing: insert / remove / move, copy / cut / paste, plus GMRS, FRS, MURS and PMR446 band-preset generators.
- Repeater imports from external directories (RepeaterBook, przemienniki.net, RSGB ETCC, IRTS).
- CSV import/export and CHIRP
.imgclone-file import/export, all round-tripped through CHIRP Python code. - Web Serial bridge (browser serial in JS, called from Python in Pyodide) with a WebUSB fallback path (FTDI / PL2303 / CH340 / CP2102 chip drivers) for browsers without native Web Serial.
- Upload preflight that validates edited rows before any bytes are written.
From the repository root:
npm run devOpen http://127.0.0.1:8000/.
RepeaterBook queries against api.webchirp.org need a Cloudflare Turnstile
token, which the dev page cannot get. Set TURNSTILE_BYPASS_TOKEN to the API's
token of that name and the dev page sends it in place of one:
TURNSTILE_BYPASS_TOKEN=0123456789abcdef0123456789abcdef npm run devTo try it on an Android phone, turn on USB debugging, plug the phone in and run:
npm run phoneIt opens the dev server in Chrome on the phone over adb reverse, starting
npm run dev first if nothing is running. Pass a page to open another one
(npm run phone -- serial-test.html), and inspect the tab from desktop Chrome
at chrome://inspect/#devices.
The default and ?drivers=chirp use the pinned upstream CHIRP drivers. Use
?drivers=quansheng-unofficial to load only the bundled unofficial Quansheng
F4HWN driver catalog. Choose the firmware release in the radio picker to load
its driver. Release labels belong to the catalog;
the driver's original CHIRP
identity and image metadata are preserved.
In unofficial mode, select the matching firmware release before opening a CHIRP image. Changing releases starts a fresh Python runtime and discards the cached clone image, so download from the radio or import an image again before uploading. Image detection uses the selected driver's native CHIRP metadata matching; these drivers cannot identify metadata-less images or create a blank clone image. Real-radio download/upload with the bundled unofficial drivers has not been verified.
Serial access requires a browser with Web Serial support and a secure context
(http://localhost works).
There are two connect buttons:
- Connect uses native Web Serial when available, otherwise WebUSB.
- Connect via WebUSB forces the WebUSB path. Use this when native Web Serial
exists but cannot drive your adapter — notably Chrome on Android, which now
exposes
navigator.serialbut only supports a limited set of devices (not FTDI/PL2303-class USB UART chips). There is no way to detect this in advance, hence the explicit button.
Over WebUSB a single device chooser is shown and the selected adapter is dispatched to a chip-specific driver:
- FTDI adapters (FT231X, FT232R, ...) use a built-in FTDI-over-WebUSB driver, verified end-to-end on Android Chrome with an FT231X cable and a Baofeng UV-5R.
- Prolific PL2303 adapters use a built-in PL2303-over-WebUSB driver that detects the chip generation (01/HX/TA/TB and the newer HXN family: GC/GB/GT/GL/GE/GS) and applies the matching init and register map. Also verified end-to-end on Android Chrome.
- WCH CH340/CH341 adapters use a built-in CH340-over-WebUSB driver that reads the chip version to pick the right register map and probes for the clone-silicon prescaler quirk. Enumeration and baud/line configuration are verified against a real adapter; a full clone against a radio has not been exercised yet, so the bulk read path is still untested.
- Silicon Labs CP2102 adapters use a built-in CP2102-over-WebUSB driver that reads the part number to pick the right baud generator, disables every handshake and byte transformation the chip can do on its own, and is the one WebUSB driver that can also read the input control lines. Verified on Android Chrome against a real CP2102 cable. Its scope is the single-UART parts that speak the vendor protocol — CP2101/2/3/4/9 and CP2102N; the multi-UART CP2105/CP2108 are turned away, and the CP2102C enumerates as USB CDC-ACM so it is handled by the polyfill path below instead.
- USB CDC-ACM devices are dispatched to Google's
web-serial-polyfill. This path is wired up but untested — most radio programming cables are not CDC-ACM. - Other vendor-specific UART bridges are not supported over WebUSB; they
need chip-specific drivers that have not been written yet (see
web/js/ftdi-webusb.ts,web/js/pl2303-webusb.ts,web/js/ch340-webusb.tsandweb/js/cp2102-webusb.tsfor the pattern) and still require native Web Serial on desktop.
For radio cloning:
- Type your radio's make, model or the name it is rebadged under into
Search radiosand pick it from the suggestions. The sidebar'sSelected radioreadout names what the rest of the app will act on. - Click
Connect(baud is prefilled when available from selected driver). - Click
Load from radioto read channels into the table. - Edit values and click
Save to radioto write back.
You can read or write a real-radio codeplug from the command line using the same
runtime bridge (web/python/webchirp_bridge/) and local CHIRP source loading
path used by the Node tests. This is the intended agent-facing CLI for scripted
radio access.
From the repository root:
npm run radio:read -- --port /dev/ttyUSB0 --module uv5r --class BaofengUV5R --format json --output /tmp/uv5r.json
npm run radio:write -- --port /dev/ttyUSB0 --module uv5r --class BaofengUV5R --format json --input /tmp/uv5r.jsonOptional flags:
--baud 9600to override the driver's default baud.--chirp-dir /path/to/chirp(orWEBCHIRP_CHIRP_DIR=/path/to/chirp) to load CHIRP sources from a custom directory.--serial-timeout-s 2.0to override serial read timeout used by the runtime bridge.
Supported formats:
--format json: read/write a JSON object containingrows,headers,csvText,settings, and binaryimageBase64.--format csv: read/write CHIRP-normalized CSV text.--format img: read/write CHIRP.imgclone files.
The older live smoke test still exists:
npm run test:hw -- --port /dev/ttyUSB0 --module uv5r --class BaofengUV5RUse radio:read / radio:write for deterministic agent workflows and
format-specific codeplug files.
web/serial-test.html checks a USB-serial adapter and the driver behind it —
FTDI, PL2303, CH340, the CDC polyfill or native Web Serial — by writing bytes
and requiring them straight back. Bridge TX to RX on the adapter, then open
the page (npm run dev, then http://localhost:8000/serial-test.html). It is
not linked from the app: it is a bench tool, not a user feature.
It cannot verify baud rate — both directions clock off the same divisor, so a
wrong one still echoes perfectly. The same cases run against fake hardware in
npm run test:webusb, with no adapter attached.
See the Core Architecture section of CLAUDE.md.
The file-backed workflows (CSV, .img, settings) run unmodified CHIRP Python
logic in the browser and are the most exercised paths.
Live browser serial executes the selected CHIRP clone-mode driver
(sync_in/sync_out) through a generalized pyserial-like bridge, and has been
verified end-to-end (e.g. Baofeng UV-5R). Compatibility with any given radio
still depends on that driver's expectations and on browser transport limits, so
treat an untested radio as unverified.