OnAirOnAir remote-control API: HTTP and WebSocket
Off by default; local only unless you open it.
New in 0.2.6 (beta pre-releases), 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 foreignOriginor a non-loopbackHost(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