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.
 
 
 
 
 

9.9 KiB

libchirpmodem: the C library for format v1

A dependency-free C99 library (libm only, MIT licensed) implementing the on-air format in ../FORMAT.md, with one public header, include/chirpmodem.h:

  • chirpmodem_tx builds a frame (callsigns + body) as complex samples at any sample rate, shifted to an IF and with raised-cosine edges, ready for an SDR, plus a Morse CW ID.
  • chirpmodem_rx is a streaming receiver. Push SDR samples in any common format (cu8, ci8, ci16, cf32), at any rate and block size, and get a callback for every decoded frame.

It is what the command-line tools here are built on, and what SDRAngel plugins, Python wrappers and GNU Radio blocks are meant to build on. Inside, it is a function-by-function port of the Python receiver (rx.py, frame.py, stream_rx.py) in double precision, checked against it frame by frame.

Layout

Path What it is
include/chirpmodem.h The public API, the only header applications use
src/ The library; src/cm.h is the internal header (not installed, not stable)
tools/ cm_tx, cm_rx (public API only), cm_txvec, cm_rxvec (conformance, use the internals)
tests/ test_api.c (API, round trips, threads), test_cpp.cpp (the header from C++)
examples/loopback.c The smallest complete program: transmit, add noise, receive
CMakeLists.txt, Makefile Installable build, quick in-tree build
LICENSE MIT

Building

Quick, in-tree. The tools land in c/, where the Python scripts expect them:

make                 # libchirpmodem.a/.so, cm_tx, cm_rx, cm_txvec, cm_rxvec, tests, example
make test            # vectors (../tools/check_c.py) + API tests + C++ test + example

Installable, for other projects:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build
cmake --install build --prefix /usr/local      # or anywhere: the install is relocatable

That installs libchirpmodem.so.0 and libchirpmodem.a, chirpmodem.h, cm_tx and cm_rx, a pkg-config file and a CMake package. Options: -DCHIRPMODEM_NATIVE=ON adds -march=native (off by default so packages run anywhere; the Makefile uses it), and CHIRPMODEM_BUILD_TOOLS, _TESTS and _EXAMPLES are all on by default.

Using it from another project:

cc app.c $(pkg-config --cflags --libs chirpmodem)
find_package(chirpmodem 0.1 REQUIRED)
target_link_libraries(app PRIVATE chirpmodem::chirpmodem)   # or chirpmodem::chirpmodem_static

The shared library exports only the chirpmodem_* functions.

The API in brief

Transmit (from examples/loopback.c):

chirpmodem_tx_config tc;
chirpmodem_tx_config_init(&tc);          /* SF9, 62.5 kHz, licensed, amp 0.7 */
tc.fs = 1e6;                             /* the SDR's rate */
tc.if_offset = 250e3;                    /* signal 250 kHz above its LO */
chirpmodem_tx *tx = chirpmodem_tx_new(&tc, &err);
long n = chirpmodem_tx_frame(tx, "KD2HSG", NULL, body, len, 0, NULL, 0);  /* size */
float *iq = malloc(2 * n * sizeof(float));                                /* I, Q, I, Q, ... */
chirpmodem_tx_frame(tx, "KD2HSG", NULL, body, len, 0, iq, n);

Receive:

static void on_frame(void *user, const chirpmodem_frame *f)
{
    printf("%s: %.*s (SNR %+.1f dB)\n", f->src, f->body_len, (const char *)f->body, f->snr_db);
}

chirpmodem_rx_config rc;
chirpmodem_rx_config_init(&rc);          /* SF9, 62.5 kHz, 1 MS/s, signal at +250 kHz */
rc.on_frame = on_frame;
chirpmodem_rx *rx = chirpmodem_rx_new(&rc, &err);
chirpmodem_rx_push(rx, samples, n, CHIRPMODEM_CU8);     /* repeatedly, any block size */
chirpmodem_rx_finish(rx);                               /* end of stream */

The conventions:

  • Samples are interleaved float pairs. That's the same memory as std::complex<float>, gr_complex and numpy.complex64. Counts are in complex samples.
  • Return values: a negative return is a CHIRPMODEM_E* code, and chirpmodem_strerror() explains it. Passing iq = NULL asks for the size needed.
  • Policy: the licensed profile refuses a frame without a source callsign, or with the encrypted flag, with CHIRPMODEM_EPOLICY. The CW ID is capped at 20 WPM (47 CFR 97.119(b)(1)).
  • Callbacks run inside chirpmodem_rx_push(), on the caller's thread. body and mac are valid only during the callback. With report_failures, frames whose preamble was found but that didn't decode are reported too (status).
  • Threads: handles share no state. Different handles can run on different threads at once (test_api decodes on two threads, and is clean under ThreadSanitizer). One handle must not be used from two threads at once.
  • No I/O: the library does no I/O and starts no threads. Files, SigMF, rtl_sdr and printing belong to the application, as in tools/.
  • 0.x: the API and ABI may still change between minor versions. The soname is libchirpmodem.so.0.

Notes for the planned integrations

  • SDRAngel (channel plugin). Feed the channel's baseband to chirpmodem_rx_push at the channel sample rate, with if_offset = the signal's offset in it. SDRAngel's Sample is integer I/Q, so convert to float or ci16 first. The frame callback runs on the DSP thread. Copy what the GUI needs and hand it over through SDRAngel's message queue. For the TX side, a channel source pulls chirpmodem_tx_frame output at the channel rate.
  • GNU Radio. A sink block wraps chirpmodem_rx: work() pushes gr_complex input as CHIRPMODEM_CF32 and posts each frame as a PMT message. A source block, or a message-to-stream block, wraps chirpmodem_tx. Set fs to the flowgraph's rate and let the library resample, or run the block at the modem rate (2 x bw, if_offset = 0).
  • Python. The API is ctypes and cffi friendly: plain structs, opaque handles, float buffers that map onto numpy.complex64 arrays, and one callback type.
  • Windows. The public header has no C99 complex types and is fine for MSVC and C++ callers. Building the library itself needs C99 complex arithmetic, so GCC, Clang or MinGW. MSVC is not supported yet.

Command-line tools

Program What it does
cm_rx Streaming receiver: raw I/Q from rtl_sdr (stdin, or --rtl runs it), or a capture file replayed at full speed (SigMF: format, rate and LO from the .sigmf-meta; raw files need --fs and --lo)
cm_tx Frames to a SigMF recording at an SDR's rate (tx_file.py equivalent; ../tools/pluto_tx.py transmits it)
cm_txvec Prints every intermediate of one frame, for the test vectors
cm_rxvec Decodes buffers of modem-rate samples, for comparison with Python
rtl_sdr -f 223330000 -s 1000000 -g 40 - | ./cm_rx --sf 12
./cm_rx --rtl --sf 12 --gain 49.6
./cm_rx cap.cu8 --fs 2.4e6 --lo 223.33e6 --sf 9          # replay, raw
./cm_rx cap --sf 9                                        # replay, SigMF (cap.sigmf-meta)
./cm_tx hello --src KD2HSG --msg "test de KD2HSG" --sf 9 --repeat 3 --cw-id --fs 600e3

Conformance and parity

  • ../tools/check_c.py: rebuilds every test vector bit for bit (MAC frame, header word, header and payload bits, symbols), with the waveform within 1.2e-7, and decodes each vector from noise at −3 dB.
  • ../tools/compare_rx.py: Python and C on the same simulated frames (float32 samples, no excision on either side). Outcomes were identical on 337 of 338 frames: SF7 −12 dB, SF9 non-coherent −17 dB, SF10 with 20 Hz Rayleigh fading, and SF12 at 62.5 kHz with 0.5 Hz/s carrier drift.
  • cm_tx vs tx_file.py: frames match to 1.3e-7. With --cw-id, the Morse tail differs by up to ~3e-4, because the tone's phase accumulates differently over seconds. cm_tx also leaves the per-frame message out of the SigMF annotations.
  • The library refactor (0.1.0) changed no output. cm_tx writes byte-identical cf32 recordings for 8 test configurations (CW ID, 600 kS/s to 2.4 MS/s, IF offsets, coherent, unlicensed, long bodies). ci16 differs in 0.005% of values by 1 LSB, because the tool now rounds from the library's float output instead of from double. cm_rx prints byte-identical output, including -v failure lines, on 13 captures: the 2026-10-23 Pluto capture, the soak replay, back-to-back frames, and effort 0/1/2.

Speed (one 2.1 GHz Xeon core, the slow cloud machine)

Python C
SF7 −12 dB, frame decode 3.7x real time 34x
SF9 non-coherent −17 dB 5.8x 34x
SF10, Rayleigh 20 Hz 2.0x 15x
SF12 62.5 kHz −23 dB, drift 4.4x 31x
cm_rx streaming SF12 62.5 kHz from 1 MS/s cu8, all stages 5.4x (stream_rx.py) 24x

On the desktop, live SF9 at 1 MS/s ran for an hour at 3% of one core (39x real time).

The demappers avoid transcendental functions per bin and pass: log(2 cosh x) = log(eˣ + e⁻ˣ), so each symbol's scaled exponentials are computed once, and every BICM-ID pass is multiplications plus SF exponentials for the bit priors (built by doubling). An exact log-domain path remains as the fallback when scaled values would underflow. What's left is ordinary DSP: the resampler and the radix-2 FFT (~45%). A better FFT is the next easy factor.

Not yet ported

  • Narrowband interference excision (rx.excise). Use the Python receiver near strong carriers or FM until it is.
  • The legacy pilot tracker (comparison only).
  • A reader thread in cm_rx. It relies on rtl_sdr's own buffers (about 2 s at 1 MS/s), which a C decode never comes close to filling.

Known quirk: a recording with no noise at all (a transmit file fed straight back in, half its samples exact zeros) gives hundreds of spurious "failed after sync" candidates in the silences, though every real frame still decodes. Any SDR capture has a noise floor and doesn't do this.

-DCM_DEBUG adds stage printouts and two test hooks used to cross-check freq_ramp and frame extraction against Python.