# libchirpmodem: the C library for format v1 A dependency-free C99 library (libm only, MIT licensed) implementing the on-air format in [`../FORMAT.md`](../FORMAT.md), with one public header, [`include/chirpmodem.h`](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) ``` ```cmake 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`](examples/loopback.c)): ```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: ```c 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`, `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.