|
|
2 weeks ago | |
|---|---|---|
| .. | ||
| cmake | 2 weeks ago | |
| examples | 2 weeks ago | |
| include | 2 weeks ago | |
| src | 2 weeks ago | |
| tests | 2 weeks ago | |
| tools | 2 weeks ago | |
| CMakeLists.txt | 2 weeks ago | |
| LICENSE | 2 weeks ago | |
| Makefile | 2 weeks ago | |
| README.md | 2 weeks ago | |
| chirpmodem.pc.in | 2 weeks ago | |
README.md
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_txbuilds 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_rxis 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_complexandnumpy.complex64. Counts are in complex samples. - Return values: a negative return is a
CHIRPMODEM_E*code, andchirpmodem_strerror()explains it. Passingiq = NULLasks 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.bodyandmacare valid only during the callback. Withreport_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_apidecodes 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_sdrand printing belong to the application, as intools/. - 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_pushat the channel sample rate, withif_offset= the signal's offset in it. SDRAngel'sSampleis 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 pullschirpmodem_tx_frameoutput at the channel rate. - GNU Radio. A sink block wraps
chirpmodem_rx:work()pushesgr_complexinput asCHIRPMODEM_CF32and posts each frame as a PMT message. A source block, or a message-to-stream block, wrapschirpmodem_tx. Setfsto 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.complex64arrays, 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_txvstx_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_txalso leaves the per-frame message out of the SigMF annotations.- The library refactor (0.1.0) changed no output.
cm_txwrites 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_rxprints byte-identical output, including-vfailure 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.