The bridge protocol

hackrf-web is two programs: a static page (this repo's web/, served from GitHub Pages or by the bridge itself) and the bridge, a small Python process on the computer the HackRF is plugged into. The bridge is the only thing that touches the device, and it does so through hackrfpy, which in turn runs the hackrf-tools binaries as child processes. The page never sees a binary, an argv, or a raw sample stream it did not ask for.

This document is the contract between the two. The Python (bridge/) and JavaScript (web/js/device/) sides are both written to it.

  page ──── WebSocket ws://127.0.0.1:8765/?token=… ────► bridge ──► hackrfpy ──► hackrf_sweep
       ◄─── JSON replies, JSON events, binary frames ────        ──► hackrf_transfer

Transport

• WebSocket, loopback only. The bridge binds 127.0.0.1 and never another address. The port defaults to 8765 (--port).
• A token is generated per launch and printed. The page sends it as the token query parameter on the WebSocket URL; any other token is closed with code 4401 before the first message. The bridge opens the page with the token in the URL fragment (#bridge=127.0.0.1:8765&token=…); fragments are never sent to any server.
• The bridge answers an HTTP GET / on the same port with the page (option B in the README) and GET /healthz with { "tool": "hackrf-web", "version": … }. It answers CORS preflights with Access-Control-Allow-Private-Network: true so a page on an https origin may reach loopback under Chrome's private network access rules.

Messages

Text frames are JSON. There are three shapes:

// call (page → bridge)
{ "id": 7, "method": "session.start", "params": { … } }
// reply (bridge → page)
{ "id": 7, "result": { … } }
{ "id": 7, "error": { "code": "device_busy", "message": "…", "detail": { … } } }
// event (bridge → page, unsolicited)
{ "event": "session", "data": { "state": "sweep", … } }

id is any JSON value the page chooses; it is echoed back unchanged. Calls are answered in order per connection, but a long call (a tx.tone with a duration, say) does not block events.

Error codes: bad_request, not_allowed (TX without --allow-tx, a call that needs confirm: true), busy (a session is running and this call needs idle), device_busy (another program holds the HackRF), device_missing, device_unresponsive, environment (tools missing, disk full), internal.

Binary frames

Spectrum frames and IQ snapshots are binary so the page can hand them to a typed array without parsing. Layout: a 4-byte little-endian uint32 header length, that many bytes of UTF-8 JSON header, then the payload.

spectrum  header { "kind": "spectrum", "seq": 120, "t": 1760731200.123,
                   "start": 88000000, "stop": 108000000, "points": 1024,
                   "bin_width": 19531.25, "level_unit": "dBFS",
                   "mode": "iq", "settings": { … }, "dropped": 0 }
          payload Float32Array[points]       level per bin, ascending frequency
iq        header { "kind": "iq", "seq": 3, "t": …, "center": 98100000,
                   "sample_rate": 8000000, "count": 16384, "settings": { … } }
          payload Int8Array[2*count]         interleaved I,Q as the HackRF sends them

level_unit is dBFS unless a calibration is loaded (not in v0.1); it is never silently dBm. In sweep mode the values are what hackrf_sweep prints, which are relative and depend on the gains; the unit string is still dBFS and the header carries the gains that produced them.

Calls

device

device.* runs only in the idle state; hackrf_info needs the device.

session

One session at a time. Every transition passes through idle; changing a setting while running is session.stop then session.start.

State machine, from the build plan:

iq

record

The recorder sits on the same decoded blocks the FFT uses and re-encodes them to int8 (round(x * 128) — exact, since hackrfpy normalises by 128). A session.stop while recording closes the file first.

tx

Transmit is behind three gates, all three required: the bridge must have been started with --allow-tx; the call must carry confirm: true; and a duration is mandatory. The page shows the Transmit section greyed with the reason when the bridge was started without --allow-tx.

tx.file is reserved for a later release. Firmware writes (spiflash_write, cpldjtag) are not reachable through any call.

Events

The fake device

hackrf-web --fake runs the whole bridge against a simulated HackRF: sweep rows and IQ blocks are synthesised (FM carriers at 98.1 and 103.7 MHz with the right deviation, a 433.92 MHz keyed transmitter, noise at the right level for 8-bit samples), every state transition is real, and recordings are real files. It exists so the page can be tested end to end on a machine without a board, and so the demo data shipped with the page comes from the same code path.

Versions

The page and the bridge each carry a version. hello reports the bridge's; the page compares major.minor and shows a notice if they differ. Pages updates on every push; the bridge updates on pip install -U hackrf-web.