# 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): 1. CRC: CRC-16 if n ≤ 32, else CRC-32 (§7), appended big-endian: n_info = 8n + 16 or 8n + 32 bits. 2. Lift size Z: the smallest in §8's list with 12·Z ≥ n_info. 3. 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]. 4. 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. 5. Transmitted bits: u[0 … n_info − 1], then the kept parity, then zeros to n_sym = ⌈(n_info + n_par)/bps⌉ symbols. 6. 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.