Remote control API

Off by default; local only unless you open it.

New in 0.2.6, not in 0.2.5.

Scripts and other programs can control OnAir over HTTP and WebSocket. It is off by default: turn it on in View > Data feeds > Remote control API (RX 1).

Security

• It listens on 127.0.0.1 (port 8765) only. Let other computers connect opens it to the network and then needs a token (at least 16 characters, made for you; the app shows it and can copy it).
• Programs on the same computer need no token; every other address must send Authorization: Bearer <token> (or ?token=<token>, which ends up in logs: prefer the header).
• A web page cannot drive it: no CORS headers are ever sent, a POST must be Content-Type: application/json, and a request with a foreign Origin or a non-loopback Host (on loopback) is refused.
• Limits: 8 KB header block, 4 KB body, 16 connections, 8 WebSockets. Plain HTTP, no TLS: on a LAN anyone who can sniff the traffic sees the token.

Endpoints

Endpoint	What it does
GET /api/v1/status	running, receiver, device, family and mode, frequency (Hz), sample rate (Hz), gain (dB), AGC, gain range
GET /api/v1/devices	the radios and sources: index, name, kind, board, serial, limits, selected
GET /api/v1/modes	the modes, with family (and sub for protocol entries)
GET /api/v1/telemetry	the active mode's report: standard, state (2 = locked), locked, snrDb, cfoHz, FEC blocksOk / blocksBad, quality, and details for DVB-T2, DVB-T, ATSC, DAB, FM, DVB-S/S2, DTMB and DVB-C
GET /api/v1/spectrum?bins=N	the latest spectrum line: dbfs, centerHz, sampleRateHz, rmsDbfs, peak, clipFraction
POST /api/v1/start, /stop	start (optionally {"device": 2}) or stop the receiver
POST /api/v1/mode	{"family": 5} or {"family": 25, "sub": "ft8"} (stopped receiver only)
POST /api/v1/frequency	{"hz": 1090000000} or {"mhz": 474}
POST /api/v1/samplerate	{"hz": 2400000} or {"msps": 2.4}; 0 = automatic
POST /api/v1/gain	{"db": 33}; turns the AGC off
GET /api/v1/ws	WebSocket (read-only) that pushes telemetry at most 10 times a second; send {"spectrum":true,"bins":512} for spectrum frames too

Replies are JSON; a refused or failed request gives {"error":"..."} with a status such as 400, 401 (token), 403 (Origin / Host), 404, 405, 413, 415, 431 or 503 (busy).

curl -s http://127.0.0.1:8765/api/v1/telemetry
curl -s -X POST -H 'Content-Type: application/json' -d '{"mhz": 474}' http://127.0.0.1:8765/api/v1/frequency
curl -s -H "Authorization: Bearer $TOKEN" http://192.168.1.20:8765/api/v1/status