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.
 
 
 
 
 
Daniel Peter Chokola 0e8e1d1b9d libchirpmodem: no failure report for a sync on the tail of a decoded frame 2 weeks ago
c libchirpmodem: no failure report for a sync on the tail of a decoded frame 2 weeks ago
hdl Import chirpmodem project 2 weeks ago
tools tools: SDRangel plugin helpers and live test metadata 2 weeks ago
vectors Import chirpmodem project 2 weeks ago
.gitignore Import chirpmodem project 2 weeks ago
CLAUDE.md Import chirpmodem project 2 weeks ago
FORMAT.md Import chirpmodem project 2 weeks ago
README.md Import chirpmodem project 2 weeks ago
channel.py Import chirpmodem project 2 weeks ago
dsp.py Import chirpmodem project 2 weeks ago
fec.py Import chirpmodem project 2 weeks ago
frame.py Import chirpmodem project 2 weeks ago
iq_io.py Import chirpmodem project 2 weeks ago
ldpc_tables.py Import chirpmodem project 2 weeks ago
live_tx.sigmf-meta tools: SDRangel plugin helpers and live test metadata 2 weeks ago
ota_cw.sigmf-meta Import chirpmodem project 2 weeks ago
ota_test.py Import chirpmodem project 2 weeks ago
ota_tx.sigmf-meta Import chirpmodem project 2 weeks ago
parallel.py Import chirpmodem project 2 weeks ago
phy.py Import chirpmodem project 2 weeks ago
rx.py Import chirpmodem project 2 weeks ago
rx_file.py Import chirpmodem project 2 weeks ago
sim.py Import chirpmodem project 2 weeks ago
sim_fec.py Import chirpmodem project 2 weeks ago
sim_frame.py Import chirpmodem project 2 weeks ago
soak_soak.ods Import chirpmodem project 2 weeks ago
soak_test.py Import chirpmodem project 2 weeks ago
soak_tx.sigmf-meta Import chirpmodem project 2 weeks ago
stream_rx.py Import chirpmodem project 2 weeks ago
sweep_sweep.ods Import chirpmodem project 2 weeks ago
sweep_test.py Import chirpmodem project 2 weeks ago
sweep_tx.sigmf-meta Import chirpmodem project 2 weeks ago
tx_file.py Import chirpmodem project 2 weeks ago

README.md

chirpmodem — on-air format v1, Python reference v0.10, C library v0.1

The on-air format is frozen as version 1 in FORMAT.md, with test vectors (tools/make_vectors.py). The C library in c/ (libchirpmodem, MIT licensed) is the reference for real use: one header, a streaming receiver and a frame transmitter that applications (the command-line tools, SDRAngel plugins, Python wrappers, GNU Radio blocks) build on. It runs the modem in real time with room to spare on modest hardware, and it is checked bit for bit against the vectors and frame for frame against this Python. hdl/ records the plan for an FPGA implementation. The Python (modulator, impairment simulator, receiver) remains the place to sketch and test ideas, and the golden model the C and later HDL ports are checked against.

Files

File What it does
phy.py Parameters, Gray/QPSK mapping, frame layout, modulator
channel.py Fractional delay + sample-clock error, flat Rayleigh/Rician fading, CFO, transverter-style LO offset, phase, CW/FM interferers, IQ imbalance, DC, AWGN, ADC quantization
rx.py Interference excision, detection, CFO/timing estimation, clock-corrected refinement, pilot tracking, hard and soft demod
fec.py CRC-16/32, QC-LDPC (encode + layered min-sum decode), rate matching, PN9 whitening, interleaver, iterative demap/decode
frame.py PHY header, MAC header with callsigns, licensed/unlicensed profiles, full frame TX and two-stage RX
dsp.py Kaiser-windowed sinc resampler (tabulated polyphase kernel; direct version kept as resample_at_reference), Jacobsen sub-bin estimator
parallel.py Runs Monte-Carlo trials across cores; results identical for any --jobs
sim.py Uncoded sweeps (detection rate, index SER, QPSK bit errors, BER)
sim_fec.py Packet error rate: uncoded vs LDPC vs LDPC with iterative demapping
sim_frame.py Full frames end to end, failures split into no-sync / header / payload, with processing speed vs. real time
iq_io.py SigMF and raw IQ files (cf32_le, ci16_le, cu8, ci8), streaming rate conversion with offset tuning
tx_file.py Frames → SigMF recording at an SDR's rate, ready to transmit
rx_file.py Decode every frame in a SigMF or raw capture; reports SNR, frequency offset, clock correction
tools/sim_capture.py Turn a transmit recording into a simulated RTL-SDR capture (two crystals, offset tuning, DC spike, noise, 8-bit)
tools/pluto_tx.py Transmit a recording with an ADALM-Pluto via pyadi-iio
ota_test.py One-command loopback: make a recording, transmit it with the Pluto in the background, capture with rtl_sdr, decode
sweep_test.py Steps the Pluto's TX gain down through a loopback until decoding stops; checks SNR-estimate linearity and finds the threshold
tools/ldpc_search.py Offline search that produced the LDPC seed table
tools/noise_metric.py Detection metric on pure noise, to check the false-alarm margin
soak_test.py Unattended hours-long loopback decoded live by c/cm_rx: delivery, wrong frames, load, SNR and offset per hour
stream_rx.py Streaming receiver: decodes live from rtl_sdr (or a pipe, or a file replayed at full speed), with load reports and automatic effort
FORMAT.md The frozen on-air format, version 1
ldpc_tables.py The normative LDPC base matrices (generated by tools/export_tables.py)
tools/export_tables.py Regenerates ldpc_tables.py and c/src/ldpc_tables.h from the construction; refuses to overwrite with different tables unless --force
tools/make_vectors.py Format-v1 test vectors (vectors/, ~24 MB, regenerated on demand)
tools/check_c.py C implementation against the vectors, transmit and receive
tools/compare_rx.py Python and C receivers on the same simulated frames: delivery, agreement, speed
c/ C library libchirpmodem (public API c/include/chirpmodem.h), tools cm_tx, cm_rx, CMake and Makefile builds (see c/README.md)
hdl/ FPGA implementation: intent, architecture sketch and open questions (see hdl/README.md)

Waveform (K = 1)

  • Symbol: cyclic shift of a base up-chirp, M = 2**SF chips at chip rate bw. Shift carries SF bits (Gray coded); in coherent mode a QPSK value on the chirp carries 2 more. Non-coherent symbols carry the SF index bits only and are sent with the QPSK bits fixed at 00, so once known they still serve a coherent receiver as phase references.
  • Frame: n_preamble up-chirps, 2 sync chirps (shifts from sync_word), 2.25 down-chirps, then header and payload symbols with a known pilot chirp every pilot_every data symbols (and one at each end).
  • Up/down pair separates CFO from timing. Pilots track carrier phase and drift.

Receiver

  1. Interference excision (excise, full-frame receiver only): average the spectrum over the buffer, zero any band standing more than 8 dB above the in-band median. A chirp's spectrum is flat, so only interferers trip it.
  2. Decimate to chip rate.
  3. Detect: non-coherent combining of 2× zero-padded FFTs over the preamble (zero-padding caps the between-bin loss at ~0.9 dB instead of 3.9 dB), with a consistency metric (geometric mean of per-window peak ratios) so a lone strong window can't masquerade as a preamble. Threshold 4.0; pure noise peaks at about 3.4–3.6.
  4. Coarse sync: windows realigned to the symbol boundaries the up-chirps imply. On that grid the sync chirps dechirp to their known shifts whatever the CFO, and both down-chirps dechirp to bin 2f and are combined. Each whole-symbol hypothesis is scored on all four.
  5. Fine estimate: fractional CFO from inter-symbol phase, Jacobsen sub-bin.
  6. Refine (3 iterations): resample onto the TX chip grid using the CFO-implied clock error (shared-crystal model) and re-estimate. Without this, clock drift across a long preamble biases timing (1.5 chips at SF12/50 ppm) and wrecks the QPSK bits.
  7. Dechirp + FFT per symbol. Pilot peaks are searched only within ±2 bins of the expected offset (running median); an unconstrained search sometimes locks onto a noise bin and corrupts alignment for the surrounding symbols.
  8. Channel tracking (_fit_channel): the complex channel gain at every symbol comes from the pilots in three steps:
    • remove a residual frequency estimated from pilot-to-pilot phase steps (near a fade the preamble's CFO estimate can be tens of Hz off);
    • fit a local line through the nearest W pilots, with W chosen per frame by leave-one-out prediction error (long windows on a static channel for noise averaging, short ones when it fades);
    • use the per-symbol gain for both phase and amplitude in the LLRs.
  9. Decision-directed retry (frame._decode_stage): if a stage fails to decode, the decoder's confident symbol decisions (and, for the payload, the already-decoded header symbols) become extra channel references, one per symbol instead of one per 9, and the stage is demodulated and decoded again, up to twice. Frames that decode the first time are untouched. 8a. Non-coherent payload (rx.demodulate_nc, mode 1): pilots give each symbol's frequency (sub-bin peak position, interpolated) and amplitude (pilot power minus noise, averaged over 3 pilots); each symbol is de-rotated by its own frequency before the FFT, so a fractional-bin offset costs no scalloping. Per-bin metric μₖ = log I₀(2A|Yₖ|/σ²), the Rice-vs-Rayleigh likelihood ratio, which does not care what the carrier phase does. No DD or carrier-drift retries (there is no phase to fix); the clock retry still applies.
  10. Carrier-drift retry (rx._freq_ramp, frame._run_stage): the preamble fixes the carrier frequency at the start of the frame, but an oscillator that is still warming up keeps moving. Pilot phase can only follow a frequency error up to ±1/(2 × pilot spacing), ±0.85 Hz at SF12 and 62.5 kHz (590 ms between pilots), before it wraps and the QPSK bits fail. Each symbol's peak position (Jacobsen sub-bin) shows the frequency unambiguously to ±½ bin (±7.6 Hz there). If a stage fails, the receiver fits a line through those positions over time (anchored at the preamble, pilots plus data symbols whose peak stands 6 dB above the next bin, two Huber reweightings, shrunk by c²/(c² + σ²)), removes the matching quadratic phase, and decodes again, before trying the clock correction.
  11. Clock-drift retry (rx.estimate_drift, frame._run_stage): steps 5–8 assume the sample-clock error equals the carrier offset divided by the carrier frequency, true when each radio derives its LO and sample clock from one crystal. A transverter LO, or a dongle whose tuner and ADC use different crystals, adds carrier offset with no clock error, so the frame slowly slips in time. If a stage still fails, the receiver fits a line through the pilots' sub-bin peak positions (anchored at the preamble, weighted by pilot power), shrinks it by d²/(d² + σ²) so noise-level estimates barely move anything, re-extracts the frame with the corrected clock and decodes again. A frame that decodes first time is never touched.

FEC

  • CRC: CRC-16/CCITT-FALSE for payloads ≤ 32 B, CRC-32/MPEG-2 above.
  • LDPC: quasi-cyclic, rate 1/2, 12×24 base graph lifted by 45 sizes Z = a·2^j (a = 8…15) from 8 to 384. Parity part in the 802.11n / 5G NR shape: a weight-3 first column plus a dual-diagonal staircase, so encoding is linear time. (A plain staircase ends in a weight-1 column and produced weight-7 codewords.) Irregular info-column degrees, 4-cycle-free shifts.
  • Code tables: the construction seed per Z is frozen in SEED_TABLE, chosen by tools/ldpc_search.py for the largest minimum weight over all codewords generated by one or two info bits (computed exactly with one FFT correlation per column pair). Minimum weight ≥ 14 at Z = 8, ≥ 30 from Z = 16.
  • Rate matching: unused info bits are shortened (known zeros, not sent); surplus parity is punctured evenly so the payload goes out at rate 1/2. The header sends all parity instead (effective rate 0.14–0.22).
  • Decoder: layered normalized min-sum (α = 0.8), early stop on zero syndrome. Alone on BPSK/AWGN: payload FER ≈ 1e-2 at 2.0 dB Eb/N0 from 64 B up.
  • Whitening: modulator bits XORed with PN9 (x⁹ + x⁵ + 1). Without it, zero bytes become runs of plain up-chirps, i.e. fake preambles.
  • Interleaver: codeword slot i → symbol i mod n_sym, so the SF+2 bits a symbol error damages land far apart in the codeword.
  • Soft demapper: exact log-sum-exp over all M × 4 (index, QPSK) hypotheses using the pilot-derived amplitude, phase and noise estimates.
  • Iterative demapping (BICM-ID): decoder extrinsics fed back as priors to the demapper (demap_extrinsic), LDPC warm-started between passes.

Frame layer (frame.py)

PHY header, 32 bits + CRC-16, sent right after the preamble at the frame's own SF/BW (the receiver knows those from the channel it listens on):

Bits Field Values
2 version 0
1 profile 0 licensed (amateur), 1 unlicensed (ISM)
3 mode 0 = K = 1 coherent (SF + 2 bits/symbol), 1 = K = 1 non-coherent (SF bits/symbol)
2 code rate 0 = 1/2
11 length MAC frame bytes, 1–2047
1 encrypted body is ciphertext (unlicensed only)
12 reserved 0

The header is a whole number of pilot groups (16 symbols for SF 9–12, 24 for SF 7–8), so the receiver decodes it before it knows the payload length. It is always non-coherent, so it can be read before the mode is known and by a moving station whose carrier phase won't hold still. Moving it from coherent (v0.8) cost nothing measurable: SF7 at −12 dB delivered 500 of 600 frames against 501 with the same random draws.

Segmentation: MAC frames longer than one codeword (572 B) are split into near-equal segments, each its own LDPC codeword with its own CRC and whitening seed, sent back to back after the header (fec.SegmentedCodec). Frames of up to 572 B are a single segment, identical to before. Tested to 1500 B coherent and 1200 B non-coherent.

Effort (receive_frame(effort=), stream_rx.py --effort): a compute budget per stage. 0 = one decode, no retries; 1 = plus one retry (carrier-drift removal when coherent, clock correction when non-coherent), at most 2x; 2 = everything (carrier drift, clock, decision-directed passes), the default. stream_rx.py lowers it automatically when decoding takes over 70% of real time and raises it again under 30%.

MAC header: a flags byte, then optional 6-byte source and destination callsigns in M17's base-40 encoding (up to 9 characters of A–Z 0–9 - / .).

Profiles are transmit policy above the PHY (PROFILES): licensed requires a source callsign and forbids encryption; unlicensed allows both. Bandwidth and bitrate caps per profile are placeholders to fill in per band. Encryption itself is only a flag so far; no cipher is implemented.

Status (all impairments on)

Impairments per trial: ±50 ppm shared-crystal mismatch (CFO ±11 kHz at 222.1 MHz plus matching sample-clock error), random fractional delay, random carrier phase, DC offset (σ≈0.42 rms relative to signal), 0.5 dB / 3° IQ imbalance, AWGN. SNR is measured in the signal bandwidth (LoRa convention).

Full frames (sim_frame.py: 24 B body + 7 B MAC header with callsign, licensed profile, 125 kHz). Fractions of frames lost at each stage:

SF7, ~0.10 s on air, 400 trials per point (v0.4 receiver → v0.5):

SNR Lost at sync Header fail Payload fail Delivered (v0.4 → v0.5)
−13 dB 26.8% 9.5% 19.8% 31.5% → 44.0%
−12 dB 6.8% 3.3% 2.0% 82.0% → 88.0%
−11 dB 1.8% 0.5% 0.3% 96.8% → 97.5%
−10 dB 0.3% 0% 0% 99.8% → 99.8%

SF12, ~2.43 s on air, 100 trials per point:

SNR Lost at sync Header fail Payload fail Delivered (v0.4 → v0.5)
−26 dB 11% 2% 6% 72% → 81%
−25 dB 4% 1% 0% 94% → 95%
−24 dB 0% 0% 0% 100%
−23 dB 0% 0% 0% 100%

The v0.5 channel tracker gains roughly 0.4–0.5 dB at threshold; what's left near threshold is mostly sync. 10% frame loss falls at about −11.8 dB (SF7) and −25.5 dB (SF12), against LoRa datasheet sensitivities of −7.5 dB and −20 dB. No undetected errors in any run. LoRa's figures are measured hardware and these are simulation without phase noise, ADC quantization or front-end filtering, so expect some of the gap to close on air.

False alarms (tools/noise_metric.py, 400 noise-only buffers per SF): the detection metric's noise peaks rise with SF because it takes the best of 2M bins. Max 3.37 (SF7), 3.56 (SF9), 4.03 (SF12) against the 4.0 threshold: one SF12 crossing in ~27,000 window positions, roughly one false trigger per 15 minutes of noise. Harmless for now: a noise "header" must pass LDPC, a CRC-16 and 12 zero reserved bits (false accept ~1e-8 per trigger).

Narrowband interference (sim_frame.py --itf, SF7, 100 trials per point). Without excision a chirp behaves as if the interferer were extra noise: SF7 at +10 dB SNR survives an interferer up to ~11 dB stronger than itself and fails by −15 dB SIR. With excision (on by default):

Signal Interferer Delivered, ideal ADC Delivered, 8-bit ADC
SF7, −5 dB SNR FM, +25 kHz, 20 dB stronger 100% (0% without excision)
SF7, −5 dB SNR FM, +25 kHz, 40 dB stronger 100% 100%
SF7, −5 dB SNR FM, +25 kHz, 45 dB stronger 100%
SF7, −5 dB SNR FM, +25 kHz, 50 dB stronger 99% 88%
SF7, −5 dB SNR FM, on channel center, 50 dB stronger 100%
SF7, −5 dB SNR CW, +20 kHz, 50 dB stronger 100%
SF12, −20 dB SNR FM, +25 kHz, 50 dB stronger 100% (40 trials)
SF12, −20 dB SNR FM, +25 kHz, 60 dB stronger 95% (40 trials)

The FM interferer is NFM with voice-band modulation (~11 kHz occupied). With an 8-bit ADC and an ideal AGC, quantization noise left behind by the interferer, which excision can't remove, sets the limit at roughly 45–60 dB. Without interference the 8-bit ADC costs nothing measurable. A real RTL-SDR will do worse: tuner intermodulation and reciprocal mixing (a strong carrier's LO phase-noise skirts landing in our band) are not modeled.

Fading (sim_frame.py --fading rayleigh, 150 trials per point for SF7, 100 for SF9/10). Delivered:

Mean SNR SF7 block fading (fixed) SF7, 20 Hz Doppler: v0.4 → v0.5 SF9, 20 Hz SF10, 20 Hz
−10 dB 58% 11% → 34% 28% 23%
−5 dB 86% 59% → 79%
0 dB 97% 83% → 91% 90% 71%
+5 dB 99% 94% → 97%
+10 dB 100% 97% → 100% 98% 76%

20 Hz is a car at ~100 km/h on 222 MHz. Block fading follows the textbook Rayleigh curve (10 dB more margin per decade of outage). With 20 Hz Doppler, SF7 now has no payload failures from 0 dB up; its remaining losses are frames whose preamble lands in a fade. The coherent limit is set by symbol length:

  • SF7 (1 ms symbols): pilots sample the channel at 111 Hz, ample.
  • SF9 (4 ms): pilots at 27 Hz are below the 40 Hz Nyquist rate for ±20 Hz Doppler; decision-directed re-estimation (one sample per symbol) rescues it at moderate SNR.
  • SF10 (8 ms): the phase turns by up to ~1 rad within a single symbol, so the coherent QPSK bits fail no matter how well the pilots track (~24% loss even at +10 dB). Mobile use at SF10 and above needs the non-coherent mode.

Clock mismatch (sim_frame.py --lo-offset, SF12, 40 trials per point): carrier offset with no matching clock error, as from a transverter LO. The receiver otherwise infers the clock error from the carrier offset, so 2 kHz at 222 MHz looks like a 9 ppm clock error that isn't there and slips the timing by ~2.7 chips over a 2.4 s SF12 frame.

LO offset Implied false clock error −25 dB −24 dB −22 dB −20 dB
none (100 trials) 0 95% 100%
500 Hz, v0.5 2.3 ppm 47.5% 100%
2 kHz, v0.5 9 ppm 0% 0%
2 kHz, v0.6 9 ppm 92.5% 100% 100%
−4 kHz, v0.6 18 ppm 97.5%
6 kHz, v0.6 27 ppm 90% 100%

SF7 frames are too short to notice (0.1 s): 98.5% at −11 dB with a 6 kHz offset. The remaining losses at 6 kHz are sync failures: a 27 ppm clock error smears the timing across SF12's 50,000-chip preamble before any pilot is seen.

Carrier drift (sim_frame.py --drift, SF12 at 62.5 kHz, −20 dB, 32 trials, random sign): a carrier offset changing linearly through the frame.

Drift v0.7 (no drift retry) v0.8
0.5 Hz/s 100% (also at −22 dB)
1 Hz/s 16% 100%
2 Hz/s 0% 97%
4 Hz/s 6% 22%

At 4 Hz/s the residual reaches ±8 Hz by the end of a 4 s frame, more than half a bin, and the peak positions alias too. No-drift thresholds are unchanged (SF7: 86% at −12 dB, 98% at −11; SF12 at 125 kHz: 95% at −25).

Non-coherent mode (sim_frame.py --noncoherent, 125 kHz, 24 B body, 64 trials; "x RT" is processing speed vs. airtime on one 2.1 GHz core, mean / slowest frame). Non-coherent symbols carry SF bits instead of SF + 2, so the same payload takes 16% more symbols at SF12.

Channel SNR Coherent Non-coherent
AWGN, SF12 −26 dB 77% 44%
−25 dB 94% 98%
−24 dB 100% 98%
Rayleigh, fd 20 Hz, SF10 −10 dB 23% 98%
0 dB 89% 100%
+10 dB 98% 100%
Rayleigh, fd 20 Hz, SF12 −10 dB 33% 100%
0 / +10 dB 25% 100%

Processing speed under fading: coherent 0.4–1.9x real time (failing frames run every retry), non-coherent 5–7x mean, 4–5x worst. In AWGN both run 4–6x. In plain noise the two land within ~1 dB of each other (non-coherent's cliff is steeper); in motion only the non-coherent mode works at SF10 and up, and it is the cheaper receiver. Use coherent for fixed stations with decent oscillators, non-coherent for mobile, portable or drifting rigs.

Large-sample reference (Ryzen 9 5900X, 2026-10-22; 2000 trials per point at SF7, 1000 at SF9, 400 at SF12, 300 under fading). Delivered fraction; 10% frame loss interpolated. 125 kHz rows: 24 B body. 62.5 kHz rows: the hardware sweep's own frame (15 B coherent, 14 B non-coherent) with 0.5 Hz/s carrier drift.

10% loss, coherent 10% loss, non-coherent Notes
SF7, 125 kHz −11.5 dB −11.3 dB coherent 83% / 79% at −12 dB
SF9, 125 kHz −17.1 dB −17.1 dB 64% / 34% at −18 dB: non-coherent's cliff is steeper
SF12, 125 kHz −25.3 dB −25.1 dB 78% / 53% at −26 dB
SF12, 62.5 kHz, drift −22.5 dB −25.0 dB coherent payload failures 4.5% even at −22 dB
Rayleigh, fd 20 Hz −10 dB coh / non-coh 0 dB +10 dB
SF7 32% / 28% 94% / 95% 100% / 100%
SF9 39% / 90% 98% / 100% 99% / 100%
SF10 29% / 98% 89% / 100% 95% / 100%
SF12 30% / 100% 27% / 100% 22% / (running)

At SF7 both modes are limited by sync in a fade (42% no-sync at −10 dB); from SF9 up only the non-coherent mode copes with motion. On a fixed link with ordinary oscillators at 62.5 kHz it is also 2.5 dB better at SF12: the coherent QPSK bits suffer from carrier wander between pilots 590 ms apart.

Uncoded symbol detection (sim.py): SF7 index SER 7.6e-2 at −10 dB and 8e-4 at −8 dB; SF9 error-free from −12 dB.

Working with SDRs

Files. tx_file.py writes a SigMF recording (.sigmf-meta + .sigmf-data) at the SDR's sample rate, with the signal --if-offset above the SDR's LO so the transmitter's LO leakage misses it, plus a short raised-cosine fade on each frame. It refuses to write anything that breaks the chosen profile (e.g. licensed without --src). rx_file.py reads SigMF, or raw files with --format/--fs/--lo; it shifts the signal to 0 Hz, decimates in two stages (FFT FIR to an integer rate, then the windowed-sinc resampler), excises interference over the whole capture, finds every preamble, and decodes them in time order. Frequency offsets up to ±bw/4 (±31 kHz at 125 kHz, i.e. ±140 ppm at 222 MHz) are found without help.

Simulated captures (tools/sim_capture.py, TX at 1 MS/s, RTL-style RX at 2.4 MS/s cu8, TX crystal +10 ppm, RX −35 ppm, RX tuned 250 kHz below the signal unless noted):

Test Frames decoded Notes
SF7, 0 dB 3/3 offset measured +9994 Hz vs +9995 true; SNR estimate within 0.4 dB
SF7, −10 dB 6/6
SF7, −11 dB, 30 frames 29/30 simulator gives 97.5% at −11 dB
SF7, −8 dB, tuned on the signal, DC spike 18 dB above it 6/6
SF7, raw .cu8 (no metadata) 3/3
SF12, −22 dB, 2 kHz transverter-style LO offset 2/2 clock corrected to +44.5 / +45.5 ppm (true +45)
SF9, 62.5 kHz at 223.58 MHz, −12 dB, 5 frames + CW ID 5/5 CW ID excised as a 1% notch; SNR estimates −11.7 to −12.5 dB

First over-the-air test (Pluto → RTL-SDR). Defaults put a 62.5 kHz signal at 223.580 MHz, inside the ARRL band plan's digital/packet segment (223.520–223.640 MHz). 222.100 MHz, the earlier default, is the national SSB/CW calling frequency in the weak-signal segment. --cw-id appends "DE " in 20 WPM Morse at the signal's center: CW is one of the identification methods in 47 CFR 97.119(b), and the callsign carried inside the frames is not. The ID alone is about 5.5 s ("DE KD2HSG"; 20 WPM is the ceiling for automatic CW ID), so at 1 MS/s even one frame plus the ID exceeds the Pluto's cyclic buffer (iq_io.PLUTO_MAX_SAMPLES, 6 M samples). With --cw-id, transmit at 600 kS/s (tx_file.py --fs 600e3, ota_test.py --tx-fs 600e3): three SF9 frames plus the ID are 5.35 M samples.

The one-command version, with every frequency derived from --freq so the transmitter, capture and decoder always agree:

./ota_test.py                      # SF9, 62.5 kHz, 223.580 MHz, 12 s capture
./ota_test.py --sf 12 --seconds 20 --rx-gain 25 --cw-id --tx-fs 600e3 --repeat 1
./sweep_test.py                    # SF9 decoder limit, ~10 minutes
./sweep_test.py --tx-gains -58 -60 -62 -63 -64 -65 -66 -68 --seconds 30   # finer, near threshold

Or step by step:

# 1. 3 frames, SF9, 62.5 kHz at 223.580 MHz, Pluto LO 100 kHz below, CW ID at the end
#    (600 kS/s so frames + ID fit the Pluto's buffer)
./tx_file.py hello --src KD2HSG --msg "test de KD2HSG" --sf 9 --repeat 3 --cw-id --fs 600e3

# 2. transmit it in a loop for 30 s (low gain by default)
./tools/pluto_tx.py hello --seconds 30

# 3. meanwhile, capture 15 s on the RTL-SDR, tuned 250 kHz below the signal
rtl_sdr -f 223330000 -s 2400000 -g 20 -n 36000000 cap.cu8

# 4. decode
./rx_file.py cap.cu8 --format cu8 --fs 2.4e6 --lo 223.33e6 --sf 9 -v

Start cabled through 30–40 dB of attenuation when you can. Over the air with small antennas, keep the Pluto's gain low.

First result (2026-10-22, Pluto → 40 dB attenuator → NESDR SMArt v5, SF9, 62.5 kHz at 223.580 MHz, Pluto gain −30 dB, RTL gain 29.7 dB): 10 of 10 complete frames decoded at +17.2 dB SNR. The offset was −14.4 ppm (−3.22 kHz), almost all of it the Pluto's crystal since the SMArt has a 0.5 ppm TCXO, drifting about −1 Hz/s as the Pluto warmed up. No clock correction or decision-directed retry was needed.

Finding the lower limit: ./sweep_test.py keeps one Pluto session transmitting and steps its gain down (default −30 dB in 3 dB steps), capturing and decoding at each step until two steps in a row decode nothing. It fits measured SNR against TX gain where the SNR is below +10 dB (slope 1.0 means the SNR estimate is trustworthy), uses the fit to put an SNR on every step, and compares the threshold with the simulator (SF9: 95% delivered at −17 dB, 74% at −18 dB, 3% at −19 dB). Results go to sweep_sweep.ods (needs odfpy; otherwise .csv).

Hardware threshold (2026-10-22, same setup, RTL gain 40 dB, 28 frames per step): measured SNR tracks the Pluto's TX gain at 0.98 dB/dB over 11 steps (SNR ≈ TX gain + 70.5 dB), so the receiver's SNR estimate is trustworthy below about +10 dB. Above that it saturates (+17 dB measured where the fit predicts ~+40 dB).

Pluto TX gain Measured SNR Delivered
−70 dB +0.4 dB 28/28
−80 dB −9.5 dB 28/28
−84 dB −13.2 dB 28/28
−86 dB −15.4 dB 28/28
−88 dB −17.2 dB 20/28 (71%)

The simulator gives SF9 95% delivered at −17 dB and 74% at −18 dB, so the hardware sits within about 1 dB of simulation.

The RTL's 8-bit quantization adds 1/12 LSB² per component to the noise floor: at RTL gain 30 / 40 / 49.6 dB the ADC ran at 0.70 / 1.15 / 1.83 LSB rms, i.e. quantization cost about 0.8 / 0.3 / 0.1 dB. At 49.6 dB the dongle's noise figure improved enough (SNR ≈ TX gain + 74.5 dB) that the Pluto's minimum gain (−89.75 dB) still gave −15.4 dB SNR with 28/28 frames; finding the threshold there needs ~10 dB more attenuation in line.

SF12 at 62.5 kHz (60 dB attenuation, RTL gain 49.6 dB, ~19 frames per step, 4.1 s per frame): SNR ≈ TX gain + 54.2 dB (slope 0.93), matching the extra 20 dB of attenuation.

Measured SNR −18.1 −20.2 −21.9 −23.8 −25.0 −25.5 −26.5 −27.5 dB
Delivered 93% 78% 72% 72% 78% 62% 26% 0%

The edge sits where the simulator puts it (10% loss at −25.5 dB), and delivery at −25 dB is ~5 dB beyond LoRa's SF12 datasheet sensitivity (−20 dB). But above the edge delivery plateaus at roughly 75% regardless of SNR. Nearly every frame was detected (decoded + failed-after-sync ≈ expected), so the losses are in header/payload decoding. The same frames decode 4/4 at −22 dB in simulation through the full capture path, so the cause is in the hardware.

Diagnosis (kept 60 s capture at TX gain −76 dB, −22 dB SNR): v0.7 decoded 9 frames, all failures in the first 25 s. The pilots showed the carrier drifting within each 4.1 s frame, by more than the 590 ms pilot spacing can follow: the Pluto's crystal warming up after the sweep started it. v0.8's carrier-drift retry (Receiver, step 9) decodes all 12 complete frames. The drift it removed fell as the oscillator settled: −0.72, −0.61, −0.27 and −0.07 Hz/s for the frames at 3.5, 7.9, 16.8 and 21.3 s, and the offset moved from −3344 to −3366 Hz over the minute. Practical note: let the Pluto transmit for a minute before a measurement.

Re-sweep with v0.8 (same setup, 60 s per step, ~12.6 complete frames per step): SNR ≈ TX gain + 53.9 dB (slope 0.98). The plateau is gone.

Measured SNR −16.0 −18.4 −20.0 −21.8 −24.2 −25.9 ~−28 dB
Delivered, v0.8 12 13 12 10 11 7 0
% of 12.6 96% 100% 96% 80% 88% 56% 0%
v0.7 at similar SNR 93% 78% 72% 72% 62% 0%

One frame is 8% at this sample size, so −22 and −24 dB are the same within noise (~85%).

Non-coherent sweep (same setup, 2026-10-22, desktop): SNR ≈ TX gain + 53.8 dB (slope 1.05).

Measured SNR −20.1 −22.1 −24.0 −26.5 ~−28 dB
Delivered (of ~11.8) 100% 100% 100% 25% 0%

The simulator gives this frame 97% at −24 dB and 50% at −26 dB, so the hardware matches it. On this link the non-coherent mode decodes everything down to −24 dB, where coherent delivered about 85%.

Fine non-coherent sweep (2026-10-23, same setup, 180 s per step, ~37.3 complete frames per step, Python v0.10 receiver): a coarse sweep first confirmed the link, SNR ≈ TX gain + 54.2 dB (slope 1.06, 100% down to −23.5 dB, 51% at −26.3 dB). The SNR below is from that fit: near threshold the median SNR of the frames that do decode reads high (only the luckier frames get through; the fine sweep's own slope came out 0.80), so the fit is the better axis.

Pluto TX gain −78 −79 −80 −81 dB
SNR (fit) −23.8 −24.8 −25.8 −26.8 dB
Delivered 37 (99%) 33 (88%) 20 (54%) 4 (11%)

10% frame loss at about −24.6 dB against the simulator's −25.0 dB for this frame; 50% at about −25.9 dB. From 99% to 11% in 3 dB. That is ~1.5 dB better than the coherent mode's −23 dB with the same 15 B frame on this link, and ~4.5 dB beyond LoRa's SF12 datasheet −20 dB.

Live C receiver (2026-10-23, same setup, SF9 62.5 kHz non-coherent, TX gain −64 dB, RTL gain 49.6 dB, SNR −10 dB): soak_test.py --decoder c, i.e. rtl_sdr at 1 MS/s piped into c/cm_rx. 3 minutes: 191 of 191 frames, none with a wrong source or body, 0 failed after sync, 39.6x real time on the desktop. The same capture path decoded by rx_file.py and cm_rx gave identical frames, SNRs and offsets (49 of 49 in a 60 s capture). Two receiver fixes came out of this run (see Streaming receiver below). The level check before it, TX −64 → −10 dB with the ADC at 1.98 LSB rms, reproduced the 2026-10-22 fit.

One-hour soak (2026-10-23, same setup and settings): 3824 frames in 3599.2 s of signal, every frame from the first to the last (spacing 0.941–0.942 s throughout, no gaps), none with a wrong source or body, and no retries needed (no carrier-drift, clock or decision-directed passes). SNR −11.2 to −8.9 dB, median −10.0 dB. The one "failed after sync" was a frame cut by the start of the capture (rtl_sdr joined the Pluto's loop mid-frame). Load 3% of one core in every 5-minute report, 39x real time, effort never lowered. The Pluto drifted 110 Hz (−2582 to −2692 Hz, ~0.5 ppm) over the hour.

Bench notes from that day: keep everything else off the Pluto during a run. Opening it in SDRAngel (even receive-only) reconfigures the AD9363 and silently stopped the transmitter mid-sweep (two steps of 0%, no preambles at all). And check which Pluto port the cable is on: with the cable on RX and a small antenna on TX, the signal still decoded over the leakage path, ~30 dB down. And rtl_sdr -n wraps past 2³¹ samples (it computes the byte count in 32 bits): a 1-hour soak at 1 MS/s stopped cleanly after 1452.5 s (1543 of 1543 frames delivered until then). soak_test.py now leaves -n off for runs over ~35 minutes and stops rtl_sdr with a timer.

Hardware matches simulation. The −25.5 dB simulator figure is for 125 kHz and a 24 B body; the sweep sends a 15 B body, whose shorter code is weaker. Simulated with the sweep's own frame (sim_frame.py --sf 12 --bw 62.5e3 --bytes 15 --drift 0.5, 64 trials): 95% at −22 dB, 84% at −24 dB, 44% at −26 dB, against 80–92%, 88% and 56% measured. A kept capture at −22 dB (11 of 12 complete frames) showed why nothing is left to chase: with each frame's linear carrier drift removed, the per-symbol channel phase (measured from the known transmitted symbols, every 65 ms) scatters by 6–9° rms, which is the thermal noise alone (7.5–8.1° expected). The Pluto→RTL channel is AWGN plus slow drift; no measurable phase noise. The receiver's SNR estimate reads 0.2 dB low in simulation, so the SNR axis is right. 10% frame loss for this frame is about −23 dB, 3 dB beyond LoRa's SF12 datasheet figure.

rx_file.py reports each frame's frequency offset in Hz and ppm: that's the two radios' combined crystal error, worth noting down. Don't pass rtl_sdr -p (ppm correction); the receiver measures it. If nothing decodes, -v shows preambles that were found but failed; try a different -g (gain) first, since an overloaded or starved 8-bit ADC is the usual cause.

Real time

The modem has to run in real time on modest computers and SDRs (an FPGA is a bonus); the C implementation is the reference for that, Python is for sketches and tests. Measured on one 2.1 GHz Xeon core (a slow 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, carrier drift 4.4x 31x
Streaming SF12 62.5 kHz from 1 MS/s RTL samples, everything 5.4x (stream_rx.py) 24x (cm_rx)

So live SF12 reception takes about 4% of one slow core in C. Python and C reach the same outcome on 337 of 338 comparison frames (tools/compare_rx.py).

Streaming receiver (stream_rx.py, c/cm_rx): reads blocks of 0.1 s, converts the rate with filter state carried across blocks (iq_io.StreamConverter, matching the file converter to ~1e-10 on white noise, for any block sizes), decimates and runs the detector on new windows only (each window's spectrum computed once), holds each candidate until its header and then its whole frame have arrived, and drops samples nobody needs. Candidates are decoded in time order, and one that falls inside an earlier frame still being received waits for it: that frame's pilots are up-chirps and can look like a preamble, and once it decodes the candidate is dropped unseen. A frame that starts exactly where the previous one ended is still taken (BUSY_SLACK, 8 symbols); before, about one frame in three sent with --gap 0 was lost, in rx_file.py too. A candidate the slack lets in from the last pilots of the previous frame is recognised after sync (its start falls inside that frame) and dropped silently rather than counted as a failure; without that check a live SF9 soak logged ~10 such "header fail" lines a minute. stream_rx.py reads the SDR on a separate thread so a slow decode never stalls rtl_sdr (which would silently drop USB transfers), and reports load and backlog. Fed a capture at exactly the live rate, it ran at 22% load with at most 0.3 s of backlog.

./stream_rx.py --rtl --sf 12 --gain 49.6                          # live
rtl_sdr -f 223330000 -s 1000000 -g 40 - | ./stream_rx.py - --format cu8 --fs 1e6 --lo 223.33e6
rtl_sdr -f 223330000 -s 1000000 -g 40 - | c/cm_rx --sf 12

Live input defaults to 1 MS/s, which makes the first decimation an integer ratio for every bandwidth in use and halves the front end's work against 2.4 MS/s.

Known gaps / next steps

  • Clock drift is now corrected by retry (step 10). Carrier drift faster than about 2 Hz/s at SF12/62.5 kHz still fails; a second, iterated ramp pass or a quadratic fit would extend it. Very large mismatches (≳ 25 ppm at SF12) still cost sync; re-running refine after a drift estimate would extend the range. The uncoded demodulate() path (used by sim.py) doesn't have the correction.
  • Extension parity for HARQ (the per-segment CRCs say what to resend), an actual AEAD for the unlicensed profile.
  • SF7 sync is the limiting stage near threshold (at −12 dB: 5% below the detector threshold, 6% the frequency/timing split picking a noise peak in the down-chirps). Both are receiver-side; a 16-chirp preamble gained at most 7%, so the format keeps 8.
  • C: port narrowband excision; a faster FFT (the radix-2 FFT and the resampler are now ~45% of decode time).
  • Tune the LDPC degree profile with EXIT charts for the orthogonal-symbol demapper (current profile was tuned for BPSK).
  • A sparser pilot pattern would win back some of the non-coherent mode's rate (pilots there only track frequency and amplitude), at the cost of a mode-dependent layout.
  • Default payload mode (since v0.10, frame.default_coherent): the transmit tools (tx_file.py, ota_test.py, sweep_test.py, soak_test.py, c/cm_tx) send non-coherent at SF ≥ 10 and on links of 62.5 kHz or narrower, coherent at SF 7–9 above 62.5 kHz; --coherent / --noncoherent override. A tool default, not format: the header carries the mode. The simulators stay explicit (coherent unless --noncoherent) so their reference numbers stay comparable.
  • Under fast fading most remaining coherent losses are frames whose preamble lands in a fade; the non-coherent mode largely removes them.
  • Front-end model: tuner intermodulation and LO phase noise (reciprocal mixing), which will limit interference rejection before the ADC does.
  • K > 1 (chirp-index modulation) and dense OCDM modes.
  • Per-SF detection thresholds, now that the receivers process a stream.
  • Frequency-selective multipath (tapped delay line) for the wide modes.

Usage

All simulators take --jobs N (default: all cores) and --seed. On a machine with hyperthreading, --jobs equal to the physical core count is usually as fast and uses half the memory.

./sim.py --sf 7 9 --snr -14 -12 -10 -8 --trials 200 --impaired
./sim_fec.py --sf 7 --snr -13 -12 -11 -10 --trials 400
./sim_frame.py --sf 7 --snr -13 -12 -11 -10 --trials 400
./sim_frame.py --sf 12 --snr -26 -25 -24 -23 --trials 100
./sim_frame.py --sf 7 --snr -5 --itf fm:25 --sir -30 -40 -50 --adc-bits 8
./sim_frame.py --sf 7 --snr -10 -5 0 5 10 --fading rayleigh --fd 20 --trials 300
./sim_frame.py --sf 7 --snr -10 0 10 --fading rayleigh --fd 20 --tracker legacy  # v0.4 tracker
./sim_frame.py --sf 12 --snr -25 -24 -20 --lo-offset 2000 --trials 100
./sim_frame.py --sf 12 --bw 62.5e3 --snr -22 -20 --drift 1 --bytes 8 --trials 64
./sim_frame.py --sf 12 --snr -10 0 10 --fading rayleigh --fd 20 --noncoherent --trials 64
./ota_test.py --sf 12 --noncoherent --seconds 20 --rx-gain 49.6
./tx_file.py t9 --src KD2HSG --msg "hello" --sf 9 --repeat 3 --cw-id
./tools/sim_capture.py t9 c9 --snr -10
./rx_file.py c9 --sf 9
./tools/ldpc_search.py --tries 32
./tools/noise_metric.py --sf 7 9 12 --trials 400
./stream_rx.py cap.cu8 --format cu8 --fs 2.4e6 --lo 223.33e6 --sf 12      # replay, measures speed
(cd c && make && make test)                                            # C build + conformance
./tools/compare_rx.py --sf 12 --bw 62.5e3 --bytes 15 --snr -23 --drift 0.5 --trials 24

Python-side defaults changed in v0.10: PhyParams.fc is 223.58 MHz (it was 222.1 MHz, the old calling-frequency default); it only ties the measured frequency offset to a clock error, and now matches the band plan and the C.