5.1 KiB
chirpmodem in HDL: intent
Nothing is implemented here yet. This folder is where an FPGA implementation of chirpmodem will live. This page records why, what it is to be checked against, and the questions to settle before writing any.
Why HDL
The C library (../c/) runs format v1 comfortably on a
CPU at today's bandwidths: live SF9 at 62.5 kHz took 3% of one desktop core,
and one slow server core streams SF12 at about 24x real time. Two things
push past that:
-
Data rate. The format's throughput grows in proportion to bandwidth. Net rates for a 255-byte body, computed from the frame layout (preamble, header, pilots and LDPC rate 1/2 included):
Bandwidth SF7 coherent SF9 coherent SF12 coherent 125 kHz 3.5 kbps 1.1 kbps 0.17 kbps 500 kHz 13.9 kbps 4.3 kbps 0.67 kbps 2 MHz 55.6 kbps 17.1 kbps 2.7 kbps 10 MHz 278 kbps 85 kbps 13 kbps Non-coherent is about 20% lower. A CPU core handles on the order of 1–2 MHz of chip rate with every retry enabled, so multi-MHz links, and receivers that watch several channels or spreading factors at once, want hardware.
-
A standalone radio. A modem in the FPGA next to the RF transceiver needs no host PC in the signal path, draws less power, and has fixed latency.
Beyond rate scaling, the reserved header modes 2–7 (K > 1 chirp-index modulation, dense OCDM) are the path to more bits per hertz. They are not part of format v1. They would be specified, simulated in Python and implemented in C before any HDL.
What an implementation is checked against
The same ladder the C library climbed:
- Bit-exact transmit: reproduce
../vectors/*.json(MAC frame, header word, coded bits, symbols) exactly, and the waveforms in../vectors/*.cf32to the precision of the datapath (the vectors are float; a fixed-point DAC path will set its own tolerance).../FORMAT.mdalone is enough to do this: an encoder written only from it reproduces every vector. - Receive: decode the vectors in noise, then match the simulator's
frame-error curves (
../sim_frame.py) within a stated margin for fixed-point losses. - Over the air: the same Pluto → attenuator → receiver tests as the
README's hardware results, with an SDR running
cm_rxon one side and the FPGA on the other, in both directions.
The Python reference is the golden model (cocotb testbenches can import it directly), and the C library is the fast reference for long runs.
Architecture sketch
Transmit is cheap. A chirp generator is a phase accumulator with a quadratic term (a DDS with a ramped frequency word). The cyclic shift is the start phase and frequency, and the QPSK value is a phase rotation. The QC LDPC encoder is linear-time: XORs of circulant-shifted Z-bit blocks (FORMAT.md §8). The interleaver, PN9 whitening and CRC are trivial.
Receive is where the work is:
| Block | Notes |
|---|---|
| Front end | DDC: NCO mix, CIC + FIR decimation to the chip rate |
| Detector | Dechirp + 2M-point FFT per window (M up to 4096), the consistency metric over the preamble |
| Sync | Coarse timing and CFO from the up/down chirps, sub-bin refinement |
| Demodulator | Dechirp + FFT per symbol, pilot channel tracking |
| Soft demapper | Per-bin metrics to LLRs (the log-sum-exp is the costly part) |
| LDPC decoder | Layered normalized min-sum on the QC structure (Z up to 384, 12 x 24 base graph) |
| Retries | Carrier-drift and clock-drift re-estimation, BICM-ID passes: probably a soft CPU or the host at first |
A sensible split for a first build keeps detection, demodulation and LDPC in fabric, and leaves frame control and the retry logic to a CPU core (Zynq PS, or a RISC-V soft core) running the C library's control code.
A practical radio build (to decide)
- First target: the ADALM-Pluto itself (Zynq-7010 next to the AD9363). It is already on the bench, and it is the cheapest way to get a modem into fabric beside a real RF front end. It is small, so it suits TX and a single-SF receiver.
- Bigger: a Zynq-7020-class or larger part with an AD9361/AD9363 or an LMS7002M, for several simultaneous SFs, wider bandwidths and full retries.
- Band and rules: where multi-MHz chirp links fit. Check the spread-spectrum and data-emission rules (47 CFR 97.305, 97.307, 97.311) per band before choosing widths and power, and keep the CW ID.
Open questions
- Fixed-point word lengths and their loss against the double-precision reference, per block.
- FFT sizes and throughput: one shared streaming FFT or several, and how many SFs at once.
- Toolchain: vendor (Vivado) vs open (Yosys/nextpnr where the part allows). Verilog/SystemVerilog vs VHDL vs a higher-level HDL (Amaranth, SpinalHDL).
- Verification: cocotb against the Python golden model, plus the vectors, as above.
- Interface to the host: IIO (fits the Pluto's existing stack) or a framed byte stream.
Data-rate figures above are computed with frame.frame_chips for a 255 B
body with a callsign. CPU figures are from the C library's README and the
2026-10-23 soak.