8.2 KiB
chirpmodem on-air format, version 1
This is the normative description of what goes over the air. An
implementation that produces, for the same inputs, the bits and symbols in
vectors/*.json (generated by tools/make_vectors.py) and a waveform matching
vectors/*.cf32 to within ~1e-5 conforms. Where this text and the Python
reference disagree, the vectors decide, and the disagreement is a bug to fix.
Notation: bits are listed in transmission order; "MSB first" means the most
significant bit of each byte goes first. ⌈a/b⌉ is ceiling division.
1. Parameters
| Symbol | Meaning | Values |
|---|---|---|
| SF | spreading factor | 7–12 (5–6 and ≥ 13 reserved) |
| M | chips per symbol | 2^SF |
| BW | chip rate = occupied bandwidth, Hz | any; 62.5 kHz and 125 kHz in use |
| osr | samples per chip of the reference waveform | 2 (not part of the format) |
SF and BW are not signalled: the receiver knows them from the channel it is listening on.
2. Chirps
With chip time t (in chips, real-valued) and integer cyclic shift s, the reference up-chirp over one symbol is
u = (t + s) mod M
φ_s(t) = π (u²/M − u) − π (s²/M − s)
c_s(t) = exp(j φ_s(t)), 0 ≤ t < M
The second term makes the dechirped peak's phase equal to the symbol's QPSK value. A down-chirp is the complex conjugate of c₀. Each symbol is generated from t = 0. Phase is not carried from one symbol to the next. The reference waveform samples t at n/osr.
3. Frame
preamble 8 × c₀
sync c_{s1}, c_{s2} s1 = 3M/16, s2 = 4M/16 (sync word 0x34)
SFD 2 × conj(c₀), then the first M/4 chips of conj(c₀)
stream header symbols, then payload symbols, with pilots
The symbol stream starts (n_preamble + 4)·M + M/4 chips after the frame start. Pilots: slot 0 is a pilot, then every group of up to 8 data symbols is followed by a pilot (so the stream also ends with one). A pilot is c₀ with value 1. Data symbol d with index i and QPSK value a is a · c_i.
The sync word (0x34: shifts 3M/16 and 4M/16) is fixed in v1. Other values are reserved for future channelization.
4. Symbol mapping
Coherent symbol (SF + 2 bits): b₀…b_{SF−1} form v MSB first; the index is the Gray code i = v XOR (v >> 1). The next two bits (b_I, b_Q) give
a = ((1 − 2 b_I) + j (1 − 2 b_Q)) / √2
Non-coherent symbol (SF bits): the index the same way, with a = (1 + j)/√2 (b_I = b_Q = 0).
A bit stream is cut into symbols in order. A short last symbol is padded with zeros. That never happens in practice, because codecs pad to whole symbols.
5. PHY header
The header is always non-coherent (SF bits per symbol), in any mode.
32-bit word, sent as 4 bytes big-endian:
| Bits (MSB first) | Field | v1 values |
|---|---|---|
| 2 | version | 0 |
| 1 | profile | 0 licensed (amateur), 1 unlicensed (ISM) |
| 3 | mode | 0 coherent payload (SF + 2 bits/symbol), 1 non-coherent payload (SF bits/symbol); 2–7 reserved (K > 1 modes) |
| 2 | code rate | 0 = rate 1/2; 1–3 reserved |
| 11 | length | MAC frame bytes, 1–2047 |
| 1 | encrypted | MAC body is ciphertext (unlicensed only) |
| 12 | reserved | 0 (a receiver rejects the header otherwise) |
Coding: the 4 bytes plus CRC-16 (§7) = 48 info bits, LDPC with Z = 8 (§8): the 48 bits are followed by 48 zero filler bits (not sent), the codeword's 96 parity bits are all sent: 144 coded bits. The header uses n_hdr = 8·⌈⌈144/SF⌉/8⌉ symbols (16 for SF 9–12, 24 for SF 7–8), the rest zero padding. Then interleave (§9) and whiten with PN9 seed 0x0A5 (§10).
The header is a whole number of pilot groups, so its pilot positions don't depend on the payload.
6. Payload
The MAC frame (§11) of L bytes is split into C = ⌈L/572⌉ segments of near-equal size: segment i has ⌊L/C⌋ + (1 if i < L mod C else 0) bytes, taken in order. Each segment is coded independently and the coded symbol groups follow one another (segment 0 first) straight after the header.
Per segment of n bytes (bps = SF + 2 coherent, SF non-coherent):
- CRC: CRC-16 if n ≤ 32, else CRC-32 (§7), appended big-endian: n_info = 8n + 16 or 8n + 32 bits.
- Lift size Z: the smallest in §8's list with 12·Z ≥ n_info.
- Info block u: the n_info bits, then 12Z − n_info zero filler bits (not sent). Encode (§8) to the 24Z-bit codeword [u | p].
- Rate 1/2: send n_par = min(12Z, n_info) parity bits. The other n_punct = 12Z − n_par are punctured at parity positions drop_j = ⌊(2j + 1)·12Z / (2·n_punct)⌋, j = 0 … n_punct − 1. The kept parity bits are sent in order.
- Transmitted bits: u[0 … n_info − 1], then the kept parity, then zeros to n_sym = ⌈(n_info + n_par)/bps⌉ symbols.
- Interleave (§9), whiten (§10) with seed (0x1FF − 0x2B·i) mod 512 for segment i (0x1FF if that is 0).
A frame is delivered only if every segment's CRC passes.
7. CRCs
| Polynomial | Init | Reflect | Final XOR | |
|---|---|---|---|---|
| CRC-16/CCITT-FALSE | 0x1021 | 0xFFFF | no | 0 |
| CRC-32/MPEG-2 | 0x04C11DB7 | 0xFFFFFFFF | no | 0 |
Computed over the bytes MSB first.
8. LDPC code
Quasi-cyclic, base graph 12 × 24 (block rows × block columns), lifted by Z.
Allowed lift sizes: a·2^j ≤ 384, a = 8…15, j = 0…5 (45 values, 8 to 384).
The base matrices are normative: ldpc_tables.py / c/src/ldpc_tables.h
(entry −1 = all-zero block, otherwise the circulant shift s).
Block (r, c) with shift s connects check r·Z + t to bit c·Z + ((t + s) mod Z). Columns 0–11 hold u, columns 12–23 hold p. Encoding (all operations on Z-bit blocks, rot(x, s)[t] = x[(t + s) mod Z]):
S_r = XOR over c < 12 with B[r][c] ≥ 0 of rot(u_c, B[r][c])
P_0 = XOR over r of S_r
P_1 = S_0 XOR rot(P_0, 1)
P_{r+1} = S_r XOR P_r XOR (P_0 if r = 5 else 0), r = 1 … 10
The decoder is not part of the format. The reference uses layered normalized min-sum with α = 0.8.
9. Interleaver
For a codec of n_sym symbols with bps bits each, coded bit k (k = 0 … n_sym·bps − 1, in the order of §5/§6) goes to symbol k mod n_sym, bit position ⌊k / n_sym⌋ within the symbol.
10. Whitening
PN9, x⁹ + x⁵ + 1: with a 9-bit state, each step outputs state & 1, then state ← ((state << 1) | (((state >> 8) XOR (state >> 4)) & 1)) & 0x1FF. The output sequence is XORed onto the interleaved bits in modulator order, starting at the codec's first bit.
11. MAC frame
1 byte flags: bit 7 = source callsign present, bit 6 = destination present,
bits 5–0 = 0
6 bytes source callsign (if present)
6 bytes destination callsign (if present)
… body
Callsigns use M17's base-40 encoding, alphabet (index 0 first)
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-/., at most 9 characters:
v = 0; for each character from the last to the first, v ← 40·v + index;
6 bytes big-endian.
12. Profiles (policy, not PHY)
Licensed (amateur): a source callsign is required, encryption is forbidden.
Note: in the US, the callsign in the frame does not by itself satisfy
47 CFR 97.119 station identification; send a CW ID (tx_file.py --cw-id).
Unlicensed: neither rule applies. The encrypted flag says the body is
ciphertext. The cipher is not yet specified (v1 reserves it).
13. Reserved for later versions
- header modes 2–7 (K > 1 chirp-index modes), code rates 1–3
- sync words other than 0x34
- the cipher for the encrypted flag
- SF outside 7–12
Why these choices are frozen as they are
- Preamble 8 + 2 + 2.25. A 16-chirp preamble gained at most 7% delivery at SF7 (−12 dB) and nothing at −13 dB. The SF7 sync losses are in the receiver: the detector threshold, and the step that separates frequency from timing.
- Pilots every 8 data symbols in both modes. The non-coherent mode could live with 16 (about 6% more throughput), but a single layout keeps the header readable before the mode is known, and keeps implementations simple.
- Header always non-coherent. It must be readable by a moving station and before the mode is known. 600 identical SF7 trials delivered 500 frames against 501 with a coherent header.
- Segmentation in the PHY. Long frames stay one transmission with one preamble, and each segment has its own CRC, so a later retransmission scheme can resend only what failed.