"""Frame layer: PHY header, minimal MAC, operating profiles, full TX/RX. Over the air (one continuous symbol stream, pilots every ``pilot_every``): preamble | sync | SFD | HEADER (n_hdr symbols) | PAYLOAD (n_pay symbols) PHY header (32 bits + CRC-16, LDPC Z=8 shortened -> 144 coded bits) -------------------------------------------------------------------- bits field 2 version (0) 1 profile 0 = licensed (amateur), 1 = unlicensed (ISM) 3 mode 0 = K=1 coherent (index + QPSK, SF+2 bits/symbol) 1 = K=1 non-coherent (index only, SF bits/symbol) 2 code rate 0 = 1/2 (others reserved) 11 length MAC frame bytes, 1..2047 1 encrypted MAC body is ciphertext (unlicensed only) 12 reserved must be 0 The header is sent at the frame's own SF/BW, which the receiver already knows from the channel it is listening on, and always non-coherently (index bits only), so it can be read before the mode is known, and by a moving station whose phase won't hold still. Its symbol count is a whole number of pilot groups, so the pilot pattern up to the end of the header does not depend on the payload length and the receiver can decode the header first. MAC header ---------- 1 byte flags: bit7 = source callsign present, bit6 = destination present 6 bytes source callsign (base-40, as in M17: up to 9 chars of A-Z 0-9 - / .) 6 bytes destination callsign (optional) ... body Profiles are policy, enforced on transmit (and reported on receive), never baked into the PHY: the licensed profile requires a source callsign and forbids encryption. ``PROFILES`` is the place to add per-band limits. """ from dataclasses import dataclass, field import numpy as np from phy import PhyParams, payload_layout, bits_to_symbols, modulate_symbols, bits_per_symbol from fec import PayloadCodec, SegmentedCodec import rx VERSION = 0 LICENSED, UNLICENSED = 0, 1 HDR_BYTES = 4 MODE_COHERENT, MODE_NONCOHERENT = 0, 1 # Per-profile transmit policy. Rate/bandwidth caps are placeholders to be # filled per band from the applicable rules; None = no cap enforced here. PROFILES = { LICENSED: dict(name="licensed", require_callsign=True, allow_encryption=False, max_raw_bitrate=None, max_bw=None), UNLICENSED: dict(name="unlicensed", require_callsign=False, allow_encryption=True, max_raw_bitrate=None, max_bw=None), } class PolicyError(ValueError): pass # ------------------------------------------------------------------ callsigns _B40 = " ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-/." def callsign_encode(call: str) -> bytes: call = call.upper() if not 1 <= len(call) <= 9 or any(ch not in _B40[1:] for ch in call): raise ValueError(f"bad callsign {call!r}") v = 0 for ch in reversed(call): v = v * 40 + _B40.index(ch) return v.to_bytes(6, "big") def callsign_decode(b: bytes) -> str: v = int.from_bytes(b, "big") out = [] while v: v, r = divmod(v, 40) out.append(_B40[r]) return "".join(out) # ------------------------------------------------------------------ header @dataclass class Header: length: int profile: int = LICENSED mode: int = 0 code_rate: int = 0 encrypted: bool = False version: int = VERSION def pack(self) -> bytes: if not 1 <= self.length <= 2047: raise ValueError("length out of range") w = (self.version & 3) << 30 w |= (self.profile & 1) << 29 w |= (self.mode & 7) << 26 w |= (self.code_rate & 3) << 24 w |= (self.length & 0x7FF) << 13 w |= (int(self.encrypted) & 1) << 12 return w.to_bytes(HDR_BYTES, "big") @classmethod def unpack(cls, b: bytes): w = int.from_bytes(b, "big") if w & 0xFFF: raise ValueError("reserved header bits set") return cls(version=w >> 30, profile=(w >> 29) & 1, mode=(w >> 26) & 7, code_rate=(w >> 24) & 3, length=(w >> 13) & 0x7FF, encrypted=bool((w >> 12) & 1)) def header_codec(p: PhyParams) -> PayloadCodec: return PayloadCodec(HDR_BYTES, p.sf, crc_bits=16, sym_multiple=p.pilot_every, rate=None, whiten_seed=0x0A5) # ------------------------------------------------------------------ MAC @dataclass class MacFrame: body: bytes src: str = None dst: str = None def pack(self) -> bytes: flags = (0x80 if self.src else 0) | (0x40 if self.dst else 0) out = bytes([flags]) if self.src: out += callsign_encode(self.src) if self.dst: out += callsign_encode(self.dst) return out + self.body @classmethod def unpack(cls, b: bytes): flags, i = b[0], 1 src = dst = None if flags & 0x80: src, i = callsign_decode(b[i:i + 6]), i + 6 if flags & 0x40: dst, i = callsign_decode(b[i:i + 6]), i + 6 return cls(body=b[i:], src=src, dst=dst) def check_policy(p: PhyParams, hdr: Header, mac: MacFrame): pol = PROFILES[hdr.profile] if pol["require_callsign"] and not mac.src: raise PolicyError(f"{pol['name']} profile requires a source callsign") if hdr.encrypted and not pol["allow_encryption"]: raise PolicyError(f"{pol['name']} profile forbids encryption") if pol["max_raw_bitrate"] and p.raw_bitrate > pol["max_raw_bitrate"]: raise PolicyError(f"{pol['name']} profile caps raw bitrate at " f"{pol['max_raw_bitrate']:.0f} bps") if pol["max_bw"] and p.bw > pol["max_bw"]: raise PolicyError(f"{pol['name']} profile caps bandwidth at {pol['max_bw']:.0f} Hz") # ------------------------------------------------------------------ TX def default_coherent(p: PhyParams) -> bool: """Payload mode the transmit tools pick when not told: non-coherent at SF >= 10 and on links of 62.5 kHz or narrower (where it measured better, on hardware and in simulation, or is the only mode that survives motion), coherent for SF 7-9 on wider links (its 2 extra bits per symbol come almost free there). A tool default, not part of the format: the header carries the mode either way.""" return p.sf < 10 and p.bw > 62.5e3 def resolve_mode(p: PhyParams, coherent_flag: bool, noncoherent_flag: bool) -> bool: """--coherent / --noncoherent override default_coherent().""" if coherent_flag and noncoherent_flag: raise ValueError("--coherent and --noncoherent are mutually exclusive") if coherent_flag: return True if noncoherent_flag: return False return default_coherent(p) def frame_chips(p: PhyParams, mac_bytes: int, coherent=True) -> int: """Length of a frame (preamble to last pilot) in chips.""" n_tot = header_codec(p).n_sym + SegmentedCodec(mac_bytes, bits_per_symbol(p, coherent)).n_sym return p.payload_start + len(payload_layout(n_tot, p.pilot_every)[0]) * p.M def build_frame(p: PhyParams, body: bytes, profile=LICENSED, src=None, dst=None, encrypted=False, coherent=True): """MAC + header + payload -> complex baseband at osr samples/chip. ``coherent=False`` sends the payload index-only (mode 1).""" mac = MacFrame(body=body, src=src, dst=dst) mb = mac.pack() hdr = Header(length=len(mb), profile=profile, encrypted=encrypted, mode=MODE_COHERENT if coherent else MODE_NONCOHERENT) check_policy(p, hdr, mac) hc = header_codec(p) pc = SegmentedCodec(len(mb), bits_per_symbol(p, coherent)) hi, ha = bits_to_symbols(hc.encode(hdr.pack()), p, coherent=False) pi, pa = bits_to_symbols(pc.encode(mb), p, coherent=coherent) iq = modulate_symbols(np.concatenate([hi, pi]), np.concatenate([ha, pa]), p) return iq, dict(n_hdr=hc.n_sym, n_pay=pc.n_sym, mac_bytes=len(mb), coherent=coherent) # ------------------------------------------------------------------ RX @dataclass class RxResult: stage: str # no_sync | header_fail | payload_fail | ok sync: object = None header: Header = None mac: MacFrame = None info: dict = field(default_factory=dict) def _decode(codec, llr, info, k, p, iterative, coherent=True): """Decode data symbols k.. of a stage; iterative = BICM-ID with the matching demapper.""" if not iterative: return codec.decode(llr) if coherent: yr, yi = info["yr"][k:], info["yi"][k:] demap = lambda La, a, b: rx.demap_extrinsic( yr[a:b], yi[a:b], p.sf, La.reshape(b - a, p.sf + 2)).reshape(-1) else: mu = info["mu"][k:] demap = lambda La, a, b: rx.demap_extrinsic_nc( mu[a:b], p.sf, La.reshape(b - a, p.sf)).reshape(-1) if isinstance(codec, SegmentedCodec): return codec.decode_iterative(demap) S = info["yr"].shape[0] - k if coherent else len(info["mu"]) - k return codec.decode_iterative(lambda La: demap(La, 0, S)) DD_PASSES = 2 # decision-directed channel re-estimation passes DD_CONF = 3.0 # min |posterior LLR| over a symbol's bits to trust it RAMP_RETRY = True # retry a failed stage with a linear carrier drift removed # Effort levels (compute budget per stage, in decodes of that stage): # 0 one decode, no retries (1x) # 1 plus one retry: carrier-drift removal (coherent) or clock # correction (non-coherent) (<= 2x) # 2 everything: carrier drift, clock, decision-directed passes (<= ~7x) EFFORT_MAX = 2 def _drift_correct(x, sync, p, n_sym, n_chips, iters=2): """Measure residual clock drift from this stage's pilots and re-extract with the corrected clock. Returns (sync, z), or (None, None) if there was nothing worth correcting.""" z = rx.extract_frame(x, sync, p, n_chips) changed = False for _ in range(iters): _, info = rx.demodulate_soft(z, p, n_sym) d, sg, span = rx.estimate_drift(info, p) d *= d * d / (d * d + sg * sg) if np.isfinite(sg) else 0.0 # shrink noisy estimates if abs(d) * span < rx.DRIFT_MIN_CHIPS: break sync = rx.apply_drift(sync, d, p) z = rx.extract_frame(x, sync, p, n_chips) changed = True return (sync, z) if changed else (None, None) def _run_stage(codec, x, sync, p, n_sym, k, known_bits, iterative, tracker, coherent=True, effort=EFFORT_MAX): """Extract, demodulate and decode one stage. If it fails, retry with a linear carrier drift across the frame removed, then with the clock corrected from this stage's pilots (a frame that decodes is never touched, so neither correction can cost anything on a good oscillator). Returns (decoded bytes or None, info, sync to carry forward).""" n_chips = p.payload_start + len(payload_layout(n_sym, p.pilot_every)[0]) * p.M z = rx.extract_frame(x, sync, p, n_chips) out, info = _decode_stage(codec, z, p, n_sym, k, known_bits, iterative, tracker, coherent=coherent, effort=effort) info["drift_retry"] = False info["ramp_retry"] = False if effort == 0 or tracker == "legacy": return out, info, sync # (non-coherent symbols don't care about carrier phase, so no ramp retry) if out is None and RAMP_RETRY and coherent: # carrier drifting during the frame (e.g. an oscillator warming up) out2, info2 = _decode_stage(codec, z, p, n_sym, k, known_bits, iterative, tracker, freq_ramp=True, effort=effort) if out2 is not None: info2["drift_retry"], info2["ramp_retry"] = False, True return out2, info2, sync if effort < 2: return out, info, sync if out is None: sync2, z2 = _drift_correct(x, sync, p, n_sym, n_chips) if sync2 is not None: out2, info2 = _decode_stage(codec, z2, p, n_sym, k, known_bits, iterative, tracker, coherent=coherent, effort=effort) info2["drift_retry"] = True if out2 is not None: return out2, info2, sync2 return out, info, sync def _decode_stage(codec, z, p, n_sym, k, known_bits, iterative, tracker, freq_ramp=False, coherent=True, effort=EFFORT_MAX): """Demodulate n_sym symbols, decode the ones from index k on with ``codec``. Symbols before k carry ``known_bits`` (the already-decoded header). If the decode fails, the decoder's confident decisions plus the known symbols are used as extra channel references, and the stage is demodulated and decoded again (up to DD_PASSES times). Frames that decode first time are untouched. Non-coherent stages have no channel phase to refine, so no DD passes. ``known_bits`` are the header's (non-coherent, SF bits per symbol). """ if not coherent: llr, info = rx.demodulate_nc(z, p, n_sym) out, dinfo = _decode(codec, llr[k * p.sf:], info, k, p, iterative, coherent=False) dinfo["dd_passes"] = 0 dinfo["snr_db"] = info["peak_snr_db"] - 10 * np.log10(p.M) dinfo["freq_ramp_hz_per_s"] = 0.0 return out, dinfo bps = p.sf + 2 if k: # header symbols carry QPSK bits 00 known_bits = np.concatenate([known_bits.reshape(k, p.sf), np.zeros((k, 2), np.uint8)], axis=1) llr, info = rx.demodulate_soft(z, p, n_sym, tracker=tracker, freq_ramp=freq_ramp) out, dinfo = _decode(codec, llr[k * bps:], info, k, p, iterative) dinfo["dd_passes"] = 0 dinfo["snr_db"] = info["peak_snr_db"] - 10 * np.log10(p.M) # in the signal bandwidth dinfo["freq_ramp_hz_per_s"] = info["freq_ramp_hz_per_s"] if tracker == "legacy" or effort < 2: return out, dinfo for n in range(DD_PASSES): if out is not None: break post = dinfo["post"].reshape(-1, bps) bits = np.concatenate([known_bits.reshape(-1, bps), (post < 0).astype(np.uint8)]) conf = np.concatenate([np.ones(k, bool), np.abs(post).min(axis=1) > DD_CONF]) h = rx.channel_from_decisions(info["Y"], info["is_pilot"], bits, conf, p) llr, info = rx.demodulate_soft(z, p, n_sym, h=h, freq_ramp=freq_ramp) out, dinfo = _decode(codec, llr[k * bps:], info, k, p, iterative) dinfo["dd_passes"] = n + 1 dinfo["snr_db"] = info["peak_snr_db"] - 10 * np.log10(p.M) dinfo["freq_ramp_hz_per_s"] = info["freq_ramp_hz_per_s"] return out, dinfo def receive_frame(x, p: PhyParams, iterative=True, det_thresh=4.0, excise=True, tracker="adaptive", search_chips=None, effort=EFFORT_MAX) -> RxResult: """Find and decode one frame in ``x`` (samples at p.fs). ``search_chips`` limits where the preamble may start (first N chips of the buffer), so a scanner can walk a long capture frame by frame in order; the rest of the buffer is only used to hold the frame body. ``effort`` (0-2) caps the retries per stage; see EFFORT_MAX. """ q = 0.0 if excise: x, q = rx.excise(x, p) r = rx.decimate(x, p) r_det = r if search_chips is None else r[:int(search_chips) + (p.n_preamble + 6) * p.M] sync = rx.acquire(r_det, p, det_thresh) if sync is None: return RxResult("no_sync") sync = rx.refine(x, sync, p) # stage 1: header only hc = header_codec(p) n_chips = p.payload_start + len(payload_layout(hc.n_sym, p.pilot_every)[0]) * p.M if int(sync.tau0) + n_chips + 8 > len(r): return RxResult("no_sync", sync, info=dict(reason="truncated")) hb, hinfo, sync = _run_stage(hc, x, sync, p, hc.n_sym, 0, np.zeros(0, np.uint8), iterative, tracker, coherent=False, effort=effort) if hb is None: return RxResult("header_fail", sync) try: hdr = Header.unpack(hb) except ValueError: return RxResult("header_fail", sync) if hdr.version != VERSION or hdr.mode not in (MODE_COHERENT, MODE_NONCOHERENT) \ or hdr.code_rate != 0 or hdr.length < 1: return RxResult("header_fail", sync, hdr, info=dict(reason="unsupported mode")) # stage 2: whole frame, payload part coherent = hdr.mode == MODE_COHERENT pc = SegmentedCodec(hdr.length, bits_per_symbol(p, coherent)) n_tot = hc.n_sym + pc.n_sym n_chips = p.payload_start + len(payload_layout(n_tot, p.pilot_every)[0]) * p.M if int(sync.tau0) + n_chips + 8 > len(r): return RxResult("payload_fail", sync, hdr, info=dict(reason="truncated")) k = hc.n_sym known = hc.encode(hb) # header symbols are now known pb, pinfo, sync = _run_stage(pc, x, sync, p, n_tot, k, known, iterative, tracker, coherent=coherent, effort=effort) if pb is None: return RxResult("payload_fail", sync, hdr, info=pinfo) mac = MacFrame.unpack(pb) pinfo["frame_chips"] = n_chips pinfo["coherent"] = coherent pol = PROFILES[hdr.profile] pinfo["policy_ok"] = (bool(mac.src) or not pol["require_callsign"]) and \ (not hdr.encrypted or pol["allow_encryption"]) return RxResult("ok", sync, hdr, mac, info=pinfo)