# Chirpmodem: SDRangel plugin handoff Owner: Dan (KD2HSG). Machine: ender. This project is `~/mod`. This file hands work over from a cloud Claude session to Claude Code running on ender. ## Task Build an SDRangel **channel Rx demodulator plugin**, `demodchirpmodem`, on top of `libchirpmodem` (`~/mod/c`). Rx only for now. A Tx modulator is a later step. ## Setup that already works - SDRangel's MCP server is registered with this CLI: `sdrangel: http://127.0.0.1:8092/mcp` (`claude mcp list` shows Connected). It must be started in SDRangel (MCP Server feature, Start button, turns green). - Hardware: ADALM-Pluto (unlocked, 70 MHz-6 GHz) and an RTL-SDR (NESDR SMArt) as the receiver. - Existing captures for replay: `~/mod/ota_tx.sigmf-data`, `ota_cw.sigmf-data`, `sweep_tx`, `soak_tx` (SigMF, read the `.sigmf-meta` for rate, format and LO). Test vectors are in `~/mod/vectors/`. ## The library (read before coding) - Public API: `~/mod/c/include/chirpmodem.h`. Overview: `~/mod/c/README.md`. - On-air format: `~/mod/FORMAT.md`. Do not change it. - Build: `cd ~/mod/c && make` (in tree) or CMake (installable, pkg-config and `find_package(chirpmodem)`). - Rx: `chirpmodem_rx_config_init`, set `sf`, `bw`, `fs` (input rate), `if_offset`, `freq`, `effort`, `on_frame`; `chirpmodem_rx_new`, then `chirpmodem_rx_push(rx, samples, n, fmt)` repeatedly. Callbacks run inside `push`, on the caller's thread. `body` and `mac` are valid only during the callback. - Samples are interleaved float32 I/Q (`CHIRPMODEM_CF32`) or ci16/ci8/cu8. Counts are complex samples. - One handle per thread at a time. The library has no I/O, no threads, no globals. - Not yet ported to C: narrowband interference excision (`rx.excise` in Python). ## Plugin design Template: SDRangel `plugins/channelrx/demodselcal` (small channel demod with GUI, CMake, web API adapter). Also look at `demodchirpchat` for a chirp-spread-spectrum GUI. Obtain the SDRangel source (clone `https://github.com/f4exb/sdrangel` if not already present) and read the template files before writing anything. Follow the template's file set and naming: plugin, settings, baseband, sink, GUI, web API adapter, CMake. Data path: 1. The sink receives the channel's baseband at the channel sample rate. 2. Convert SDRangel's integer `Sample` to float I/Q (or ci16) and call `chirpmodem_rx_push`. Set `rc.fs` to the channel rate and `rc.if_offset` to the signal's offset within it. Use 0 if the channel is centred on the signal. 3. In `on_frame`, copy what is needed (src, dst, SNR, offset, body, status) and post it through SDRangel's message queue. Never touch the GUI from the DSP thread. 4. Reconfigure (free and new the rx handle) when SF, BW, rate or offset change. Do it off the hot path, and watch for races with the DSP thread. 5. Feed decoded frames into SDRangel's packet feature so MCP `get_packets` returns them. Check how `demodpacket` and `demodradiosonde` publish packets. Settings: SF 7-12, BW (default 62500), mode auto, effort 0-2, report failures, license profile display. GUI: frame table with time, src, dst, SNR, offset (Hz and ppm), status, body (text and hex); a clear button. Link `libchirpmodem` with CMake `find_package(chirpmodem 0.1 REQUIRED)`, with a path hint for a local install. Plugin CMake must still work when SDRangel is built in `SERVER_MODE` (no GUI sources). ## Testing through the SDRangel MCP server Always call `describe_settings` before setting keys, since key names differ by device and channel. Typical loop: 1. `get_instance_summary`, `list_channel_types` (confirm the plugin loads). 2. `add_deviceset`, `set_device_settings` (sample rate must be at least the channel rate), `set_center_frequency`. 3. `add_channel` with the chirpmodem type, `set_channel_settings`. 4. `start_device`, wait (frames can be seconds apart), then `get_packets` and `get_channel_report`. 5. Replay: use the FileInput device with an `ota_tx.sigmf-data` recording, or transmit from the Pluto (`~/mod/tools/pluto_tx.py`, `cm_tx`) into the receiver through an attenuator. Never radiate into an antenna without the right band and ID. Judge levels against the noise floor, not absolute numbers. Compare decoded frames with `./c/cm_rx` on the same capture. Do not conclude "nothing decoded" from one read right after tuning. ## Conventions and constraints - Dan prefers scripts with a shebang, made executable, run directly (`./script.py`). Spreadsheets as ODS. - License MIT for project code. Keep the SDRangel plugin's license consistent with SDRangel (GPL) where it links their code. - Amateur use: the licensed profile requires a source callsign (`KD2HSG`) and forbids encryption. CW ID is capped at 20 WPM (47 CFR 97.119). Do not add features that bypass this. - Ask before changing `libchirpmodem`'s public API. It is 0.x but other work depends on it. - Verify, don't assume: build the plugin, load it in SDRangel, decode a known frame, and compare with `cm_rx` before calling it done.