webchirp 📻

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

What is implemented

• chirp is included as a git submodule at chirp/
• 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 .img clone-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.

Run the prototype

From the repository root:

npm run dev

Open http://127.0.0.1:8000/.

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.serial but 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.ts and web/js/cp2102-webusb.ts for the pattern) and still require native Web Serial on desktop.

For radio cloning:

1. Type your radio's make, model or the name it is rebadged under into Search radios and pick it from the suggestions. The sidebar's Selected radio readout names what the rest of the app will act on.
2. Click Connect (baud is prefilled when available from selected driver).
3. Click Load from radio to read channels into the table.
4. Edit values and click Save to radio to write back.

Command-line codeplug read/write

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.json

Optional flags:

• --baud 9600 to override the driver's default baud.
• --chirp-dir /path/to/chirp (or WEBCHIRP_CHIRP_DIR=/path/to/chirp) to load CHIRP sources from a custom directory.
• --serial-timeout-s 2.0 to override serial read timeout used by the runtime bridge.

Supported formats:

• --format json: read/write a JSON object containing rows, headers, csvText, settings, and binary imageBase64.
• --format csv: read/write CHIRP-normalized CSV text.
• --format img: read/write CHIRP .img clone files.

Hardware E2E CLI test (read then write same codeplug)

The older live smoke test still exists:

npm run test:hw -- --port /dev/ttyUSB0 --module uv5r --class BaofengUV5R

Use radio:read / radio:write for deterministic agent workflows and format-specific codeplug files.

Adapter loopback test (no radio needed)

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.

Architecture

See the Core Architecture section of CLAUDE.md.

Important scope note

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.