sdr-receiver
Skill235 starsChanged 3 months agoMITView on GitHub
Drive the Embedded AI Harness testbench's RTL-SDR receiver over `/api/sdr/*` — decode/analyze/power captures, the phased `acquire`, the interactive live rtl_433 console, "AI Sherlock" record→reverse-engineer, USB recovery, and the rtl_433 device database. Use this whenever the user wants to receive, sniff, decode, analyze, or reverse-engineer an RF signal (433/315/868 MHz remotes, sensors, TPMS), read RSSI/pulse timing, recover a wedged dongle, or add a device to rtl_433 — even if they only say "rtl_433", "rtl-sdr", "sniff a remote", "what frequency is this", "signal too strong", "no signal", "AI Sherlock", or "add this remote". This is the receive-side counterpart to the transmit-only `signal-generator` skill. Always GET `/api/sdr/status` first to confirm the dongle is detected.
In this repository17 other files it gives its agents.
- buildSkill
- commissionSkill
- defineSkill
- esp-idf-handlingSkill
- esp-pio-handlingSkill
- grill-meSkill
- harnessSkill
- setup-actionSkill
- signal-generatorSkill
- testbench-bleSkill
- testbench-debugSkill
- testbench-installSkill
- testbench-integrationSkill
- testbench-loggingSkill
- testbench-mqttSkill
- testbench-test-handlingSkill
- testbench-wifiSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
One dongle, one user: Every capture (and the whole live console) holds a single-instance lock.
- Very specific: line 22
GET
/api/sdr/status: before anything: - Distinctive: line 39
Every endpoint, with its request and response shape: FSD Appendix D.10.
- Very specific: line 42
Only the choice between them is this skill's: capture decodes, analyze gives raw pulse timing when nothing decodes, power measures a level, …
- Very specific: line 144
After that, plain decode mode reports the device by name.
- Very specific: line 160
If sample loss persists (rtl_test still loses ~everything), reboot the Pi — it clears the dwc_otg USB controller.
- Very specific: line 191
Start the live console at 433.92 in analyze mode with AGC, press the remote: the reported freq field is the true carrier, and the analyzer …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SDR Receiver (/api/sdr/*)
The testbench Pi has one RTL2832U dongle behind the rtl_433 toolchain. Every
receive operation goes through /api/sdr/*. It is the receive-side counterpart
to the transmit-only signal-generator skill — never SSH in to run rtl_433
yourself, drive the API.
One dongle, one user. Every capture (and the whole live console) holds a
single-instance lock. While one is running, the others return
"SDR busy — a capture is already running". Stop the live console before a
one-shot, and vice-versa.
Always check status first
GET /api/sdr/status before anything:
{"ok": true, "active": false, "mode": null, "freq_hz": 0,
"hardware": {"rtl_433": true, "rtl_test": true, "device": true},
"available": true}hardware.device: false/available: false→ the dongle isn't detected. TryPOST /api/sdr/reset(USB reset); if still absent, it's unplugged or the USB controller is wedged (see Dongle recovery).active: true→ something is already using the dongle; stop it first.
API summary
Every endpoint, with its request and response shape: FSD Appendix D.10.
Only the choice between them is this skill's: capture decodes, analyze gives
raw pulse timing when nothing decodes, power measures a level, and acquire
runs all three in sequence when you do not yet know what is on the air.
Common body fields: freq_hz (default 433.92 MHz), duration_s, gain
(number dB, or omit for AGC), sample_rate (default 250 kHz — keep low, it's a
Pi Zero 2 W), flex (an -X spec).
A dongle plugged in after boot is picked up automatically — status re-probes
while the SDR is idle, so there is no need to restart the portal. If device
stays false, the dongle really is absent or not enumerating.
Pin gain on anything you will compare. On AGC the tuner rescales from
whatever it saw recently, so the same quiet band reads tens of dB apart between
calls and a strong carrier compresses instead of standing clear. This bites
hardest on power, where the whole point is comparing numbers.
Is the dongle working at all? pytest pytest/ -k wt1909 transmits on
86.784 MHz (5th harmonic = 433.92 MHz) and requires the dongle to see a ≥15 dB
lift, then a drop. It needs no DUT and no operator. Run it before debugging a
"nothing decodes" complaint — it separates a dead receive path from a signal
problem in one step.
The two big signal traps (learned the hard way)
- AGC saturates a too-close source. With the tuner's default auto-gain, a
strong near-field transmitter rails the input to full scale and fills an OOK
signal's off-gaps — so a crisp remote reads as a continuous / misdetected
FSK carrier and slices to all-zero codewords. Fix: more distance or a
fixed
gain(e.g. 33–40 dB). The tell is RSSI pegged near 0 dB regardless of distance, andrtl_433reporting FSK for a known-OOK remote. - Decode mode is empty for unknown remotes. Plain
decodeonly emits for a known protocol. An unrecognised remote produces nothing — and no RSSI. Useanalyze(or the live console, which runs-Ain every mode) to see the signal regardless of decode. Signal presence ≠ decodability.
Live console (/api/sdr/live/*)
A persistent rtl_433 whose merged output a reader thread fans into a
sequence-numbered ring buffer the browser fast-polls (~500 ms; nothing dropped).
-A runs in every mode, so the RSSI meter shows every burst's strength even
when it doesn't decode.
POST /api/sdr/live/start body:
{"freqs": [433920000], "mode": "decode",
"gain": 33.8, "sample_rate": 250000, "squelch": false,
"hop_interval": 5, "flex": "n=r,m=OOK_PWM,s=340,l=2068,r=13936", "isolate": false}freqs: one = locked, several = hop (-H hop_interval). Bands: 433.92 / 315 / 868. Hop to find, then lock to a single freq to work (hopping listens to each band ~1/3 of the time and misses momentary presses).mode:decode(all built-ins) ·flex(-X,isolate:trueadds-R 0) ·analyze(-Aonly).gain: omit for AGC; a number sets a fixed tuner gain.- Poll
GET /api/sdr/live?since=<seq>; each entry is{seq, line, event}whereeventis the parsed JSON (or a synthetic{rssi,snr,noise,analyzer:true}from an analyzerRSSI:line). RSSI is burst-driven — it updates on a press, not continuously.
AI Sherlock — reverse-engineer an unknown remote
The record→analyze flow the console exposes as one toggle button:
- Start (
/api/sdr/log/start) — record the live stream (analyze+AGC). - Operator presses each key a few times.
- Stop (
/api/sdr/log/stop) — freeze the log. GET /api/sdr/log→ an assistant reads the bursts and derives: modulation/timing, the constant preamble/device-ID, and the per-key varying field, plus a decoder spec and button→code map.
start_log clears the previous recording (single in-memory buffer, lost on
restart) — it's a record-analyze-now loop, not persistent storage.
Device database (make a decode permanent)
Turn a reverse-engineered remote into a named rtl_433 device with one
decoder line per distinct code in pi/config/rtl_433.conf (installed to
/etc/rtl_433/rtl_433.conf, which rtl_433 auto-loads):
decoder n=Remote-auto,m=OOK_PWM,s=340,l=2068,r=13936,g=2000,t=691,match={18}7f480The flex decoder has no per-value name mapping — use one match={<bits>}<hex>
decoder per button, distinctly named. Verify offline (no signal needed):
rtl_433 -y '{18}7f480' → model : Remote-autoAfter that, plain decode mode reports the device by name. The shipped file
is empty apart from a commented worked example — the decoders that belong
in it describe the operator's own hardware, and one household's remote is of
no use on anybody else's bench.
Dongle recovery
Heavy use wedges the RTL-SDR: it still enumerates (lsusb shows 0bda:2838) and
rtl_433 opens it ("Allocating 15 zero-copy buffers") but exits 3 at the
streaming step, or streams with ~99% sample loss (rtl_test reports huge
"lost bytes"). Ladder:
POST /api/sdr/reset(or the console's Reset dongle button) — issuesUSBDEVFS_RESET.start_livealso auto-resets+retries once on a fast exit.- If sample loss persists (
rtl_teststill loses ~everything), reboot the Pi — it clears thedwc_otgUSB controller. This is the fix a soft reset can't do. (Verified: 99% loss → 12 ppm after reboot.) - Still bad after reboot + reseat → the dongle is failing; swap it.
Power is rarely the cause on a Zero 2 W (vcgencmd get_throttled = 0x0), and
rtl_433 at 250 kHz uses only ~5–6 % CPU — so exhaustion/undervoltage are
usually red herrings; suspect the USB link.
Driver methods (pytest/testbench_driver.py)
wt.sdr_status()
wt.sdr_capture(freq_hz=433_920_000, duration_s=10, flex="n=r,m=OOK_PWM,s=340,l=2068,r=13936", gain=33.8)
wt.sdr_analyze(freq_hz=433_920_000, duration_s=12, gain=33.8)
wt.sdr_power(freq_hz=433_920_000, duration_s=5, span_hz=500_000, bin_hz=10_000)
wt.sdr_acquire(freq_hz=433_920_000) # phased locate→level→decode→classifyThe tools/sdr_acquire.py CLI drives the phased acquire interactively with live
operator prompts (run it in a real terminal — the prompts don't stream through
Claude Code's ! prefix, which buffers until exit).
Recipes
"What is this remote / what frequency?"
Start the live console at 433.92 in analyze mode with AGC, press the remote:
the reported freq field is the true carrier, and the analyzer prints pulse
timing + a suggested -X. If nothing appears, it's likely 315 or 868 — hop, or
POST /api/sdr/power a wide span and read peak_freq_hz.
"It won't decode / signal too strong"
RSSI pegged near 0 dB + FSK on a known-OOK remote = overload. Turn AGC off,
set a fixed gain ~33 dB, back the transmitter off, retry. Then decode with the
right flex.
"Add this remote to rtl_433"
AI Sherlock → analyze the log → append decoder line(s) to pi/config/rtl_433.conf
→ rtl_433 -y to verify → deploy → it's recognised by name.
Behavior to be aware of
- Single dongle. Live console vs one-shots are mutually exclusive ("SDR busy").
-Ain every live mode → the RSSI/signal meter is decode-independent.- Burst-driven RSSI — a continuous level bar (to tune against the noise
floor with no transmission) would need a separate
rtl_powermeter; not built. - Pi Zero 2 W — keep
sample_rateat 250 kHz; wideband overloads it. Use-Y squelchto cut CPU. - Session log is ephemeral — cleared on Start, lost on portal restart.
Reference
- Functional spec:
docs/Harness-FSD.md§FR-028 (SDR Receiver). - Controller:
pi/sdr_controller.py. HTTP handlers:pi/portal.py(_handle_sdr_*, the SDR Console panel). - Driver:
pytest/testbench_driver.py(sdr_*). CLI:tools/sdr_acquire.py. - Device database:
pi/config/rtl_433.conf→/etc/rtl_433/rtl_433.conf.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

