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 e243b54e09 Import chirpmodem project 2 weeks ago
..
README.md Import chirpmodem project 2 weeks ago

README.md

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:

  1. Bit-exact transmit: reproduce ../vectors/*.json (MAC frame, header word, coded bits, symbols) exactly, and the waveforms in ../vectors/*.cf32 to the precision of the datapath (the vectors are float; a fixed-point DAC path will set its own tolerance). ../FORMAT.md alone is enough to do this: an encoder written only from it reproduces every vector.
  2. 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.
  3. Over the air: the same Pluto → attenuator → receiver tests as the README's hardware results, with an SDR running cm_rx on 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.