4.9 KiB
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 listshows 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-metafor 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 andfind_package(chirpmodem)). - Rx:
chirpmodem_rx_config_init, setsf,bw,fs(input rate),if_offset,freq,effort,on_frame;chirpmodem_rx_new, thenchirpmodem_rx_push(rx, samples, n, fmt)repeatedly. Callbacks run insidepush, on the caller's thread.bodyandmacare 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.excisein 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:
- The sink receives the channel's baseband at the channel sample rate.
- Convert SDRangel's integer
Sampleto float I/Q (or ci16) and callchirpmodem_rx_push. Setrc.fsto the channel rate andrc.if_offsetto the signal's offset within it. Use 0 if the channel is centred on the signal. - 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. - 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.
- Feed decoded frames into SDRangel's packet feature so MCP
get_packetsreturns them. Check howdemodpacketanddemodradiosondepublish 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:
get_instance_summary,list_channel_types(confirm the plugin loads).add_deviceset,set_device_settings(sample rate must be at least the channel rate),set_center_frequency.add_channelwith the chirpmodem type,set_channel_settings.start_device, wait (frames can be seconds apart), thenget_packetsandget_channel_report.- Replay: use the FileInput device with an
ota_tx.sigmf-datarecording, 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_rxon 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_rxbefore calling it done.