"""Chirp-domain modulation PHY, reference modulator (sparse end: K = 1). One symbol = M = 2**SF chips. The symbol is a cyclic shift ("index") of a base up-chirp, carrying SF bits in the shift and, in coherent mode, 2 bits in a QPSK value multiplied onto the chirp. A non-coherent symbol carries the SF index bits only; it is sent as a coherent symbol whose QPSK bits are 00, so a coherent receiver can still use it as a phase reference once it is known. Dechirping (multiply by the conjugate base chirp) and an M-point FFT turns the shift into a peak in bin ``index`` whose complex value is M * a (a = the QPSK symbol). Frame layout (all in whole symbols of M chips unless noted): preamble : n_preamble x base up-chirp sync : 2 x up-chirp with fixed cyclic shifts (from sync_word) SFD : 2.25 x base down-chirp payload : P d d d d d d d d P d d d ... P (P = pilot, d = data) Waveform samples are produced at ``osr`` x the chip rate (``bw``). """ from dataclasses import dataclass import numpy as np @dataclass(frozen=True) class PhyParams: sf: int = 9 # spreading factor, M = 2**sf bw: float = 125e3 # chip rate (Hz) == occupied bandwidth osr: int = 2 # samples per chip at the SDR fc: float = 223.58e6 # carrier (Hz); only used to tie CFO to clock error n_preamble: int = 8 sync_word: int = 0x34 pilot_every: int = 8 # data symbols between pilots @property def M(self): return 1 << self.sf @property def fs(self): return self.bw * self.osr @property def bits_per_symbol(self): return self.sf + 2 @property def sync_shifts(self): return ((self.sync_word >> 4) * self.M // 16, (self.sync_word & 15) * self.M // 16) @property def payload_start(self): """Chip offset of the first payload symbol from frame start.""" return (self.n_preamble + 4) * self.M + self.M // 4 @property def raw_bitrate(self): return self.bw * self.bits_per_symbol / self.M # ---------------------------------------------------------------- mappings def gray(n): n = np.asarray(n) return n ^ (n >> 1) def inv_gray(g): n = np.asarray(g).copy() s = 1 while s < 32: n ^= n >> s s <<= 1 return n def qpsk_map(b_i, b_q): b_i = np.asarray(b_i, dtype=np.int64) b_q = np.asarray(b_q, dtype=np.int64) return ((1 - 2 * b_i) + 1j * (1 - 2 * b_q)) / np.sqrt(2) def qpsk_demap(a): return (a.real < 0).astype(np.uint8), (a.imag < 0).astype(np.uint8) def payload_layout(n_data, pilot_every): """Return (is_pilot[bool], data_index[int, -1 for pilots]) per payload slot.""" is_p, di = [True], [-1] d = 0 while d < n_data: for _ in range(min(pilot_every, n_data - d)): is_p.append(False) di.append(d) d += 1 is_p.append(True) di.append(-1) return np.array(is_p), np.array(di) # --------------------------------------------------------------- waveforms def _chirp(p, shift=0, down=False, n_chips=None): """Continuous-phase chirp sampled at osr; ``shift`` in chips (integer).""" M, osr = p.M, p.osr n = (n_chips if n_chips is not None else M) * osr t = (np.arange(n) / osr + shift) % M ph = np.pi * (t * t / M - t) if shift: ph = ph - np.pi * (shift * shift / M - shift) # make peak phase == a x = np.exp(1j * ph) return np.conj(x) if down else x def base_chirp_chips(M): """Base up-chirp at one sample per chip (used by the receiver).""" n = np.arange(M) return np.exp(1j * np.pi * (n * n / M - n)) def preamble(p): M = p.M parts = [_chirp(p) for _ in range(p.n_preamble)] parts += [_chirp(p, shift=s) for s in p.sync_shifts] parts += [_chirp(p, down=True), _chirp(p, down=True), _chirp(p, down=True, n_chips=M // 4)] return np.concatenate(parts) def bits_per_symbol(p, coherent=True): return p.sf + 2 if coherent else p.sf def bits_to_symbols(bits, p, coherent=True): """Bits -> (index, QPSK value) per symbol. Non-coherent: SF bits per symbol, QPSK value fixed to qpsk_map(0, 0).""" bits = np.asarray(bits, dtype=np.uint8) if not coherent: pad = (-len(bits)) % p.sf b = np.concatenate([bits, np.zeros(pad, np.uint8)]).reshape(-1, p.sf) b = np.concatenate([b, np.zeros((len(b), 2), np.uint8)], axis=1) return bits_to_symbols(b.reshape(-1), p) bps = p.bits_per_symbol pad = (-len(bits)) % bps if pad: bits = np.concatenate([bits, np.zeros(pad, np.uint8)]) b = bits.reshape(-1, bps).astype(np.int64) val = np.zeros(len(b), dtype=np.int64) for j in range(p.sf): val = (val << 1) | b[:, j] idx = gray(val) a = qpsk_map(b[:, p.sf], b[:, p.sf + 1]) return idx, a def modulate(bits, p): """Bits -> complex baseband frame at osr samples/chip (coherent symbols).""" return modulate_symbols(*bits_to_symbols(bits, p), p) def modulate_symbols(idx, a, p): """(index, QPSK value) per data symbol -> frame with preamble and pilots.""" is_p, di = payload_layout(len(idx), p.pilot_every) parts = [preamble(p)] for pil, d in zip(is_p, di): if pil: parts.append(_chirp(p, shift=0)) else: parts.append(a[d] * _chirp(p, shift=int(idx[d]))) return np.concatenate(parts) def n_symbols_for_bits(n_bits, p): return -(-n_bits // p.bits_per_symbol)