You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

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 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.