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

"""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)