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.
400 lines
17 KiB
400 lines
17 KiB
"""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)
|
|
|