#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Send a file from one radio to another over a tunable RF link.

The waveform is Gaussian 2-FSK at modulation index 1, carried in short frames
that each begin with their own preamble and a 63-chip maximal-length sync
word.  Every frame re-acquires symbol timing and carrier offset on its own, so
the two radios need no shared clock and no reverse channel: the transmitter
talks, the receiver keeps whatever passes CRC, and a second pass fills in the
gaps.

Either end can be a HackRF or a CaribouLite; an RTL-SDR can receive.  The two
ends need not be the same radio, and nothing in the waveform depends on which
one you have -- `--radio` only decides how the samples reach the air.

    $ ./rflink.py devices
    $ ./rflink.py selftest                                 # no hardware
    $ ./rflink.py loopback notes.pdf -o /tmp/in            # both radios here
    $ ./rflink.py recv /tmp/in --freq 915M                 # one host
    $ ./rflink.py send notes.pdf --freq 915M               # the other
    $ ./rflink.py send notes.pdf --radio caribou           # from a CaribouLite

Transmitting is licensed activity.  902-928 MHz is the US ISM band and FCC
Part 15 permits unlicensed operation inside its power limits; other bands and
other countries are your problem.  Keep the gain low and the antennas close.
"""

import argparse
import bisect
import contextlib
import hashlib
import math
import os
import queue
import re
import signal
import shutil
import struct
import subprocess
import sys
import tempfile
import threading
import time
import zlib
from fractions import Fraction

import numpy as np

try:
    from scipy.signal import oaconvolve as _fastconv
except ImportError:                                        # numpy-only fallback
    _fastconv = None
try:
    from scipy.signal import resample_poly as _resample
except ImportError:
    _resample = None

# ---------------------------------------------------------------- waveform ---

# 63-chip m-sequence (x^6+x^5+x^2+x+1, phase 37).  Chosen by search for low
# aperiodic autocorrelation sidelobes (0.11) and low correlation against the
# alternating preamble that precedes it.  See README.
SYNC_BITS = np.array(
    [int(c) for c in
     "010100100111100000110111001100011101011111101101000100001011001"],
    dtype=np.int8)

PREAMBLE_BITS = np.tile([1, 0], 32).astype(np.int8)        # 64 symbols
# Trailing guard.  The burst ramps its amplitude down over the last few dozen
# samples; without this the ramp would land on real data and corrupt the CRC.
TAIL_BITS = np.tile([1, 0], 8).astype(np.int8)             # 16 symbols

# Symbol-clock drift hypotheses, in fractional error.  A frame carries no
# timing reference past its sync word, so a few thousand symbols of drift are
# recovered by simply retrying the slice at a different rate.  Two HackRFs are
# normally within 20 ppm of each other and never leave the first entry.
DRIFTS = (0.0, 1e-4, -1e-4, 2e-4, -2e-4, 3e-4, -3e-4,
          4e-4, -4e-4, 5e-4, -5e-4)

CONTAINER_MAGIC = b"RFL1"
CONTAINER_FMT = "<BHQ32s"                                  # flags, namelen, size, sha256
CONTAINER_HDR = 4 + struct.calcsize(CONTAINER_FMT)
FRAME_FMT = "<IIHIBB"      # seq, total, valid length, data frames, k, m
IDENT_SEQ = 0xFFFFFFFF                                     # station-ID frame
FRAME_HDR = struct.calcsize(FRAME_FMT)

# Transmitting into one of these is not a paperwork problem.  Receiving is
# unaffected; this only ever gates the transmitter.
PROTECTED_BANDS = (
    (108e6, 137e6, "aeronautical navigation and ATC voice (VOR, ILS, tower)"),
    (242.5e6, 243.5e6, "military distress and search-and-rescue beacons"),
    (406.0e6, 406.1e6, "COSPAS-SARSAT emergency locator beacons"),
    (960e6, 1215e6, "aeronautical radionavigation: DME/TACAN, and ADS-B "
                    "on 978 MHz (UAT) and 1090 MHz"),
    (1559e6, 1610e6, "satellite navigation: GPS L1, Galileo E1, GLONASS L1"),
)

DEFAULT_FREQ = 915_000_000
DEFAULT_RATE = 2_000_000
DEFAULT_SPS = 20
DEFAULT_IF = 300_000
DEFAULT_PAYLOAD = 512
LEAD_S = 0.02              # dead air before and after a transmission

# Transmit sample formats, as {name: (numpy dtype, full-scale value)}.
# hackrf_transfer reads signed 8-bit; the CaribouLite's tx_test reads signed
# 16-bit, and the plugin's own generators treat 32767 as full scale.
IQ_FORMATS = {"s8": (np.int8, 127), "s16": (np.int16, 32767)}


class Config:
    """Everything both ends must agree on."""

    def __init__(self, sample_rate=DEFAULT_RATE, sps=DEFAULT_SPS,
                 if_offset=DEFAULT_IF, payload=DEFAULT_PAYLOAD, bt=1.0,
                 deviation=None):
        self.sample_rate = int(sample_rate)
        self.sps = int(sps)
        self.if_offset = int(if_offset)
        self.payload = int(payload)
        self.bt = float(bt)
        self.symbol_rate = self.sample_rate / self.sps
        # Modulation index 1: tone spacing equals the symbol rate, which is the
        # minimum spacing for orthogonal non-coherent detection.
        self.deviation = float(deviation) if deviation else self.symbol_rate / 2

    @property
    def body_bytes(self):
        return FRAME_HDR + self.payload + 4                # + CRC32

    @property
    def body_symbols(self):
        return self.body_bytes * 8

    @property
    def frame_symbols(self):
        return (len(PREAMBLE_BITS) + len(SYNC_BITS) + self.body_symbols
                + len(TAIL_BITS))

    @property
    def frame_samples(self):
        return self.frame_symbols * self.sps

    def describe(self):
        return (f"{self.sample_rate/1e6:g} Msps, {self.symbol_rate/1e3:g} kbaud, "
                f"+/-{self.deviation/1e3:g} kHz dev, IF +{self.if_offset/1e3:g} kHz, "
                f"{self.payload} B/frame")


def pn9(nbytes):
    """CC1101-style PN9 whitening sequence (x^9 + x^5 + 1, seeded all ones)."""
    reg = 0x1FF
    out = bytearray()
    for _ in range(nbytes):
        out.append(reg & 0xFF)
        for _ in range(8):
            fb = (reg ^ (reg >> 5)) & 1
            reg = (reg >> 1) | (fb << 8)
    return bytes(out)


_PN9_CACHE = {}


def whiten(data):
    """Self-inverse: whiten(whiten(x)) == x."""
    n = len(data)
    mask = _PN9_CACHE.get(n)
    if mask is None:
        mask = np.frombuffer(pn9(n), dtype=np.uint8)
        _PN9_CACHE[n] = mask
    return (np.frombuffer(data, dtype=np.uint8) ^ mask).tobytes()


# ------------------------------------------------------ erasure coding ------
#
# A frame either passes CRC or is gone, so the channel the receiver sees is an
# erasure channel with known positions -- much friendlier than an error
# channel, and worth twice the correction power for the same parity.  The code
# is Cauchy-form Reed-Solomon over GF(256): the generator is [I ; C] with C a
# Cauchy matrix, every square submatrix of which is invertible, so *any* k of
# the k+m frames in a generation reconstruct it.


def _gf_tables():
    exp = np.zeros(255, dtype=np.uint8)
    log = np.zeros(256, dtype=np.uint8)
    x = 1
    for i in range(255):
        exp[i] = x
        log[x] = i
        x <<= 1
        if x & 0x100:                       # x^8 + x^4 + x^3 + x^2 + 1
            x ^= 0x11D
    return exp, log


GF_EXP, GF_LOG = _gf_tables()
# Full 64 KiB product table: one numpy fancy-index does a vector of products.
_la = GF_LOG[np.arange(256, dtype=np.uint8)].astype(np.int16)
GF_MUL = GF_EXP[(_la[:, None] + _la[None, :]) % 255].astype(np.uint8)
GF_MUL[0, :] = 0
GF_MUL[:, 0] = 0
GF_INV = np.zeros(256, dtype=np.uint8)
GF_INV[1:] = GF_EXP[(255 - GF_LOG[1:].astype(np.int16)) % 255]
del _la


def cauchy(m, k):
    """m x k Cauchy matrix over GF(256); every square submatrix is invertible."""
    if m == 0 or k == 0:
        return np.zeros((m, k), dtype=np.uint8)
    if m + k > 256:
        raise ValueError(f"generation too large for GF(256): {k} + {m}")
    x = np.arange(m, dtype=np.uint8)[:, None]
    y = (np.arange(k) + m).astype(np.uint8)[None, :]
    return GF_INV[x ^ y]


def gf_solve(matrix, rhs):
    """Gauss-Jordan over GF(256): returns x with matrix @ x == rhs."""
    n = matrix.shape[0]
    aug = np.concatenate([matrix.astype(np.uint8), rhs.astype(np.uint8)], axis=1)
    for i in range(n):
        pivot = i + int(np.argmax(aug[i:, i] != 0))
        if aug[pivot, i] == 0:
            raise ValueError("singular matrix")
        if pivot != i:
            aug[[i, pivot]] = aug[[pivot, i]]
        aug[i] = GF_MUL[GF_INV[aug[i, i]], aug[i]]
        col = aug[:, i].copy()
        col[i] = 0
        nz = np.flatnonzero(col)
        if nz.size:
            aug[nz] ^= GF_MUL[col[nz][:, None], aug[i][None, :]]
    return aug[:, n:]


def rs_parity(data, m):
    """data: (k, L) uint8 -> (m, L) uint8 of parity rows."""
    k = data.shape[0]
    if m == 0 or k == 0:
        return np.zeros((m, data.shape[1]), dtype=np.uint8)
    coef = cauchy(m, k)
    out = np.empty((m, data.shape[1]), dtype=np.uint8)
    for j in range(m):
        out[j] = np.bitwise_xor.reduce(GF_MUL[coef[j][:, None], data], axis=0)
    return out


def rs_recover(k, m, length, have_data, have_parity):
    """Rebuild a generation.  have_*: {index: (L,) uint8}.  None if short."""
    missing = [i for i in range(k) if i not in have_data]
    out = np.zeros((k, length), dtype=np.uint8)
    for i, row in have_data.items():
        out[i] = row
    if not missing:
        return out
    use = sorted(have_parity)[:len(missing)]
    if len(use) < len(missing):
        return None
    coef = cauchy(m, k)
    known = sorted(have_data)
    rhs = np.empty((len(use), length), dtype=np.uint8)
    block = np.stack([have_data[i] for i in known]) if known else None
    for a, j in enumerate(use):
        acc = have_parity[j].copy()
        if block is not None:
            # Move everything already known to the right-hand side.
            acc ^= np.bitwise_xor.reduce(
                GF_MUL[coef[j][known][:, None], block], axis=0)
        rhs[a] = acc
    sub = coef[np.array(use)[:, None], np.array(missing)[None, :]]
    for b, i in enumerate(gf_solve(sub, rhs)):
        out[missing[b]] = i
    return out


def generation_plan(ndata, fec_pct):
    """Data frames per generation and parity frames per generation."""
    if fec_pct <= 0 or ndata == 0:
        return 0, 0
    kgen = max(1, min(ndata, int(255 / (1 + fec_pct / 100.0))))
    mgen = max(1, min(255 - kgen, int(round(kgen * fec_pct / 100.0))))
    return kgen, mgen


def gen_span(ndata, kgen, g):
    """Number of real data frames in generation g."""
    return max(0, min(kgen, ndata - g * kgen))


def gaussian_pulse(sps, bt, span=4):
    n = span * sps
    if n % 2 == 0:
        n += 1
    t = (np.arange(n) - (n - 1) / 2) / sps
    sigma = math.sqrt(math.log(2)) / (2 * math.pi * bt)
    g = np.exp(-t ** 2 / (2 * sigma ** 2))
    return g / g.sum()


def lowpass_taps(cutoff, fs, ntaps=81):
    if ntaps % 2 == 0:
        ntaps += 1
    n = np.arange(ntaps) - (ntaps - 1) / 2
    h = (2 * cutoff / fs) * np.sinc(2 * cutoff * n / fs) * np.hamming(ntaps)
    return (h / h.sum()).astype(np.complex64)


def convolve(sig, taps, mode):
    if _fastconv is not None and len(sig) > 4096:
        return _fastconv(sig, taps, mode=mode)
    return np.convolve(sig, taps, mode=mode)


def modulate(bits, cfg, ramp=64):
    """Gaussian-FSK a bit array into a unit-amplitude complex baseband burst."""
    sym = np.where(np.asarray(bits, dtype=np.int8) == 1, 1.0, -1.0)
    freq = np.repeat(sym, cfg.sps) * cfg.deviation
    freq = np.convolve(freq, gaussian_pulse(cfg.sps, cfg.bt), mode="same")
    phase = 2 * np.pi * np.cumsum(freq) / cfg.sample_rate
    wave = np.exp(1j * phase).astype(np.complex64)
    if ramp > 0 and len(wave) > 2 * ramp:
        edge = (1 - np.cos(np.pi * np.arange(ramp) / ramp)) / 2
        wave[:ramp] *= edge
        wave[-ramp:] *= edge[::-1]
    return wave


# ------------------------------------------------------------- framing ------

def build_container(path):
    with open(path, "rb") as fh:
        data = fh.read()
    name = os.path.basename(path).encode("utf-8")[:4096]
    digest = hashlib.sha256(data).digest()
    head = CONTAINER_MAGIC + struct.pack(CONTAINER_FMT, 0, len(name), len(data), digest)
    return head + name + data


def parse_container(blob):
    if len(blob) < CONTAINER_HDR or blob[:4] != CONTAINER_MAGIC:
        raise ValueError("not an rflink container")
    flags, namelen, size, digest = struct.unpack(CONTAINER_FMT, blob[4:CONTAINER_HDR])
    name = blob[CONTAINER_HDR:CONTAINER_HDR + namelen].decode("utf-8", "replace")
    start = CONTAINER_HDR + namelen
    data = blob[start:start + size]
    if len(data) != size:
        raise ValueError(f"container truncated: {len(data)} of {size} bytes")
    return name, data, digest, flags


def frame_bits(seq, total, chunk, cfg, ndata=0, kgen=0, mgen=0):
    pad = chunk + b"\x00" * (cfg.payload - len(chunk))
    core = struct.pack(FRAME_FMT, seq, total, len(chunk),
                       ndata, kgen, mgen) + pad
    body = core + struct.pack("<I", zlib.crc32(core) & 0xFFFFFFFF)
    bits = np.unpackbits(np.frombuffer(whiten(body), dtype=np.uint8))
    return np.concatenate([PREAMBLE_BITS, SYNC_BITS, bits.astype(np.int8),
                           TAIL_BITS])


def ident_frame(callsign, cfg):
    """A station-ID frame, carried in the same modulation as the data.

    47 CFR 97.119 wants the call sign at the end of a communication and at
    least every ten minutes during one.  It is not a data frame: the receiver
    prints it and moves on.
    """
    return frame_bits(IDENT_SEQ, IDENT_SEQ,
                      b"DE " + callsign.upper().encode("ascii")[:60], cfg)


def container_frames(blob, cfg, fec=0):
    """Data frames, then a block of parity frames per generation."""
    size = cfg.payload
    chunks = [blob[i:i + size] for i in range(0, max(len(blob), 1), size)]
    ndata = len(chunks)
    kgen, mgen = generation_plan(ndata, fec)
    ngen = (ndata + kgen - 1) // kgen if kgen else 0
    total = ndata + ngen * mgen

    frames = [frame_bits(i, total, c, cfg, ndata, kgen, mgen)
              for i, c in enumerate(chunks)]
    if kgen:
        padded = np.zeros((ndata, size), dtype=np.uint8)
        for i, c in enumerate(chunks):
            padded[i, :len(c)] = np.frombuffer(c, dtype=np.uint8)
        for g in range(ngen):
            lo = g * kgen
            rows = rs_parity(padded[lo:lo + gen_span(ndata, kgen, g)], mgen)
            for j in range(mgen):
                frames.append(frame_bits(ndata + g * mgen + j, total,
                                         rows[j].tobytes(), cfg,
                                         ndata, kgen, mgen))
    return frames, ndata, kgen, mgen


# ------------------------------------------------------------ transmit ------

def write_iq(path, frames, cfg, passes=1, gap_s=0.0005, lead_s=LEAD_S,
             amplitude=110, ident=None, fmt="s8", invert=False):
    """Stream the whole transmission to an interleaved IQ file.

    fmt is "s8" for hackrf_transfer or "s16" for the CaribouLite's tx_test.
    amplitude stays on the int8 1-127 scale either way and is rescaled, so a
    given --amplitude is the same fraction of full scale on both radios.

    invert conjugates the emitted block.  That is for a transmitter whose own
    path is spectrally inverted, so that conjugating here puts the signal on
    the air the right way round -- see caribou_inverts().
    """
    dtype, full = IQ_FORMATS[fmt]
    scale = full * amplitude / 127.0
    gap = np.zeros(int(cfg.sample_rate * gap_s), dtype=np.complex64)
    lead = np.zeros(int(cfg.sample_rate * lead_s), dtype=np.complex64)
    rot = 2 * np.pi * cfg.if_offset / cfg.sample_rate
    idx = 0
    written = 0
    with open(path, "wb") as fh:
        def emit(block):
            nonlocal idx, written
            n = len(block)
            # Exact modular phase so long transmissions do not drift.
            ph0 = 2 * np.pi * ((cfg.if_offset * idx) % cfg.sample_rate) / cfg.sample_rate
            block = block * np.exp(1j * (ph0 + rot * np.arange(n))).astype(np.complex64)
            iq = np.empty(2 * n, dtype=np.float32)
            iq[0::2] = block.real
            iq[1::2] = -block.imag if invert else block.imag
            fh.write(np.clip(np.rint(iq * scale), -full, full).astype(dtype).tobytes())
            idx += n
            written += n

        # Identify at the start, every ten minutes of air time, and at the end.
        frame_s = (cfg.frame_samples + len(gap)) / cfg.sample_rate
        every = max(1, int(600 / frame_s)) if ident is not None else 0
        since = 0

        emit(lead)
        if ident is not None:
            emit(modulate(ident, cfg))
            emit(gap)
        for _ in range(passes):
            for bits in frames:
                emit(modulate(bits, cfg))
                emit(gap)
                since += 1
                if every and since >= every:
                    emit(modulate(ident, cfg))
                    emit(gap)
                    since = 0
        if ident is not None:
            emit(modulate(ident, cfg))
            emit(gap)
        emit(lead)
    return written


# ------------------------------------------------------------- receive ------

class Demodulator:
    """Streaming GFSK frame recovery.  Feed it raw int8 IQ; it keeps frames."""

    def __init__(self, cfg, threshold=0.60, verbose=True, fmt="s8"):
        self.cfg = cfg
        self.threshold = threshold
        self.verbose = verbose
        self.fmt = fmt            # "s8": HackRF.  "u8": RTL-SDR offset binary
        # Transition width scales with 1/ntaps, so the tap count has to follow
        # the oversampling factor or the filter stops doing anything useful at
        # the higher sample rates.
        self.lp = lowpass_taps(cfg.deviation + cfg.symbol_rate, cfg.sample_rate,
                               ntaps=max(81, 4 * cfg.sps + 1))
        tpl = np.where(SYNC_BITS == 1, 1.0, -1.0)
        self.template = tpl - tpl.mean()
        self.tnorm = float(np.linalg.norm(self.template))
        # Oversampling beyond ~16 samples per symbol buys nothing and costs
        # linearly, so decimate after the anti-alias filter and do the rest of
        # the work at the lower rate.
        self.dec = max([d for d in range(1, cfg.sps + 1)
                        if cfg.sps % d == 0 and cfg.sps // d >= 16] or [1])
        self.sps_eff = cfg.sps // self.dec
        # Full-scale swing of the discriminator at the decimated rate.  Dead
        # air has none, and without a floor its normalised correlation against
        # the sync word is pure division by zero.
        nominal = 2 * math.pi * cfg.deviation * self.dec / cfg.sample_rate
        self.var_floor = (0.1 * nominal) ** 2
        self.carry = np.zeros(0, dtype=np.complex64)
        self.carry_index = 0            # absolute sample index of carry[0]
        # A frame straddling a chunk edge is found again on the next pass, so
        # each block is reprocessed with a whole frame of overlap.  Blocks are
        # kept several times that length, or the overlap dominates the work.
        self.keep = (cfg.frame_samples + len(SYNC_BITS) * cfg.sps
                     + 4 * max(81, 4 * cfg.sps + 1))
        self.min_block = max(4 * self.keep, 1 << 20)
        self.pending = []
        self.pending_n = 0
        self.odd_byte = b""
        self.frames = {}          # data frame index -> full padded payload
        self.parity = {}          # global seq -> full payload
        self.gen_have = {}        # generation -> frames received for it
        self.idents = set()
        self.total = None
        self.ndata = None
        self.kgen = 0
        self.mgen = 0
        self.ngen = 0
        self.recovered = 0
        self.stats = {"samples": 0, "clipped": 0, "power": 0.0, "peak": 0,
                      "candidates": 0, "bad_crc": 0}

    # -- quality ----------------------------------------------------------
    @property
    def complete(self):
        if self.ndata is None:
            return False
        if not self.kgen:
            return len(self.frames) == self.ndata
        # Any k of the k+m frames in a generation rebuild it.
        return all(self.gen_have.get(g, 0) >= gen_span(self.ndata, self.kgen, g)
                   for g in range(self.ngen))

    def quality(self):
        s = self.stats
        n = max(s["samples"], 1)
        rms = math.sqrt(s["power"] / n)
        return {"rms": rms, "peak": s["peak"],
                "dbfs": 20 * math.log10(max(rms, 1e-9) / 127.0),
                "peak_dbfs": 20 * math.log10(max(s["peak"], 1e-9) / 127.0),
                "clip_pct": 100.0 * s["clipped"] / n,
                "frames": len(self.frames), "total": self.total,
                "bad_crc": s["bad_crc"], "candidates": s["candidates"]}

    # -- main path --------------------------------------------------------
    def feed(self, raw):
        """raw: bytes of interleaved int8 IQ.  Returns number of new frames."""
        raw = self.odd_byte + raw
        if len(raw) % 2:
            raw, self.odd_byte = raw[:-1], raw[-1:]
        else:
            self.odd_byte = b""
        if not raw:
            return 0
        if self.fmt == "u8":
            # RTL2832U hands back unsigned bytes centred on 127.5.
            f = np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 127.5
        else:
            f = np.frombuffer(raw, dtype=np.int8).astype(np.float32)
        self.stats["samples"] += len(f) // 2
        a = np.abs(f)
        self.stats["clipped"] += int(np.count_nonzero(a >= 126.5)) // 2
        self.stats["peak"] = max(self.stats["peak"],
                                 int(a.max()) if a.size else 0)
        self.stats["power"] += float(np.dot(f, f)) / 2
        iq = (f[0::2] + 1j * f[1::2]).astype(np.complex64)
        self.pending.append(iq)
        self.pending_n += len(iq)
        if self.pending_n < self.min_block:
            return 0
        return self._process(self._take())

    def _take(self):
        buf = np.concatenate([self.carry] + self.pending)
        self.pending, self.pending_n = [], 0
        return buf

    def flush(self):
        """Process the held-back tail.  Call once the stream has ended."""
        buf = self._take()
        self.carry = np.zeros(0, dtype=np.complex64)
        if len(buf) < self.cfg.frame_samples:
            return 0
        return self._process(buf, final=True)

    def _process(self, buf, final=False):
        cfg = self.cfg
        # Overlap generously: a frame straddling the chunk edge is simply found
        # again next time, and duplicates are harmless.
        keep = self.keep
        base = self.carry_index
        if not final and len(buf) < keep + cfg.sps * 64:
            self.carry, self.carry_index = buf, base
            return 0

        # Mix the IF offset down to DC.  Only the frequency matters to an FM
        # discriminator, but the phase is exact anyway.
        n = np.arange(len(buf), dtype=np.float64)
        ph0 = 2 * np.pi * ((cfg.if_offset * base) % cfg.sample_rate) / cfg.sample_rate
        rot = 2 * np.pi * cfg.if_offset / cfg.sample_rate
        y = buf * np.exp(-1j * (ph0 + rot * n)).astype(np.complex64)
        y = convolve(y, self.lp, "same")
        if self.dec > 1:
            y = y[::self.dec]

        sps = self.sps_eff
        d = np.angle(y[1:] * np.conj(y[:-1])).astype(np.float32)
        m = convolve(d, np.ones(sps, dtype=np.float32) / sps, "valid")

        found = self._scan(m)

        if final:
            self.carry = np.zeros(0, dtype=np.complex64)
            self.carry_index = base + len(buf)
        else:
            self.carry = buf[-keep:].copy()
            self.carry_index = base + len(buf) - keep
        return found

    def _scan(self, m):
        cfg = self.cfg
        sps = self.sps_eff
        L = len(self.template)
        need = int((L + cfg.body_symbols) * sps * (1 + max(DRIFTS))) + 2
        score = np.full(len(m), -2.0, dtype=np.float32)

        for p in range(sps):
            s = m[p::sps].astype(np.float64)
            if len(s) < L + 1:
                continue
            num = np.correlate(s, self.template, "valid")
            c1 = np.concatenate([[0.0], np.cumsum(s)])
            c2 = np.concatenate([[0.0], np.cumsum(s * s)])
            s1 = c1[L:] - c1[:-L]
            s2 = c2[L:] - c2[:-L]
            var = np.maximum(s2 / L - (s1 / L) ** 2, self.var_floor)
            ncc = num / (np.sqrt(var * L) * self.tnorm)
            score[p + np.arange(len(ncc)) * sps] = ncc

        cand = np.flatnonzero(score >= self.threshold)
        if len(cand) == 0:
            return 0
        cand = cand[np.argsort(-score[cand])][:20000]

        taken = []
        minsep = sps * 4
        found = 0
        for pos in cand:
            if pos + need > len(m):
                continue
            i = bisect.bisect_left(taken, pos)
            if ((i and pos - taken[i - 1] < minsep)
                    or (i < len(taken) and taken[i] - pos < minsep)):
                continue
            taken.insert(i, pos)
            self.stats["candidates"] += 1
            if self._decode(m, int(pos)):
                found += 1
        return found

    def _decode(self, m, pos):
        """Try the nominal symbol clock first, then a few drifted ones."""
        for drift in DRIFTS:
            got = self._attempt(m, pos, drift)
            if got is not None:
                return self._keep(*got)
        self.stats["bad_crc"] += 1
        return False

    def _attempt(self, m, pos, drift):
        cfg = self.cfg
        sps = self.sps_eff
        L = len(self.template)
        step = sps * (1.0 + drift)
        sync = m[pos:pos + L * sps:sps]
        t = pos + L * step + np.arange(cfg.body_symbols) * step
        idx = t.astype(np.int64)
        if len(sync) < L or idx[-1] + 1 >= len(m):
            return None
        frac = (t - idx).astype(np.float32)
        vals = m[idx] * (1 - frac) + m[idx + 1] * frac
        # Carrier offset shows up as a DC term on the discriminator.  The sync
        # word is balanced and the body is whitened, so the mean is the offset.
        dc = float(np.mean(np.concatenate([sync, vals])))
        body = whiten(np.packbits((vals > dc).astype(np.uint8)).tobytes())
        core, crc = body[:-4], struct.unpack("<I", body[-4:])[0]
        if (zlib.crc32(core) & 0xFFFFFFFF) != crc:
            return None
        head = struct.unpack(FRAME_FMT, core[:FRAME_HDR])
        seq, total, length, ndata, kgen, mgen = head
        if length > cfg.payload:
            return None
        if seq == IDENT_SEQ and total == IDENT_SEQ:
            return head, core[FRAME_HDR:FRAME_HDR + length]
        if total == 0 or seq >= total or not 0 < ndata <= total:
            return None
        if kgen and (mgen == 0 or kgen + mgen > 256):
            return None
        # Keep the padded payload whole: erasure coding works on fixed-size
        # rows, and the container header says where the file really ends.
        return head, core[FRAME_HDR:FRAME_HDR + cfg.payload]

    def _keep(self, head, payload):
        seq, total, _length, ndata, kgen, mgen = head
        if seq == IDENT_SEQ:
            who = payload.decode("ascii", "replace")
            if who not in self.idents:
                self.idents.add(who)
                if self.verbose:
                    print(f"\n[rx] station ID: {who}", flush=True)
            return True

        if self.ndata is None:
            self.total, self.ndata = total, ndata
            self.kgen, self.mgen = kgen, mgen
            self.ngen = (ndata + kgen - 1) // kgen if kgen else 0
            if self.verbose:
                fec = (f", +{total - ndata} parity"
                       if total > ndata else ", no FEC")
                print(f"[rx] locked: {ndata} data frames "
                       f"({ndata * self.cfg.payload / 1024:.1f} KiB){fec}",
                      flush=True)

        if seq >= self.ndata:
            if not self.mgen or seq in self.parity:
                return False
            gen = (seq - self.ndata) // self.mgen
            if gen >= self.ngen:
                return False
            self.parity[seq] = payload
        else:
            if seq in self.frames:
                return False
            gen = seq // self.kgen if self.kgen else 0
            self.frames[seq] = payload
        self.gen_have[gen] = self.gen_have.get(gen, 0) + 1
        if self.verbose:
            self._progress()
        return True

    def _progress(self):
        got = len(self.frames) + len(self.parity)
        total = self.total
        if sys.stdout.isatty():
            print(f"\r[rx] {got}/{total} frames", end="", flush=True)
        elif got == total or got % max(1, total // 10) == 0:
            print(f"[rx] {got}/{total} frames", flush=True)

    def missing(self):
        if self.ndata is None:
            return None
        return [i for i in range(self.ndata) if i not in self.frames]

    def assemble(self):
        if not self.complete:
            raise ValueError("incomplete")
        size = self.cfg.payload
        if not self.kgen:
            return b"".join(self.frames[i] for i in range(self.ndata))
        out = []
        self.recovered = 0
        for g in range(self.ngen):
            lo = g * self.kgen
            span = gen_span(self.ndata, self.kgen, g)
            have = {i - lo: np.frombuffer(self.frames[i], dtype=np.uint8)
                    for i in range(lo, lo + span) if i in self.frames}
            spare = {}
            for j in range(self.mgen):
                seq = self.ndata + g * self.mgen + j
                if seq in self.parity:
                    spare[j] = np.frombuffer(self.parity[seq], dtype=np.uint8)
            block = rs_recover(span, self.mgen, size, have, spare)
            if block is None:
                raise ValueError(f"generation {g} is short of parity")
            self.recovered += span - len(have)
            out.append(block.tobytes())
        return b"".join(out)


# ------------------------------------------------------------- hardware -----

def list_devices(required=True):
    try:
        out = subprocess.run(["hackrf_info"], capture_output=True, text=True,
                             timeout=20).stdout
    except FileNotFoundError:
        if not required:
            return []          # a CaribouLite host need not have the tools
        sys.exit("hackrf_info not found -- install the hackrf tools")
    devs, cur = [], None
    for line in out.splitlines():
        line = line.strip()
        if line.startswith("Serial number:"):
            cur = {"serial": line.split(":", 1)[1].strip(), "board": None}
            devs.append(cur)
        elif line.startswith("Board ID Number:") and cur:
            cur["board"] = line.split("(", 1)[-1].rstrip(")") if "(" in line else None
    # hackrf_info reads the board ID out of the device, so it can only report
    # a model for one it can open.  A radio already in use by another process
    # arrives here with nothing but its serial -- which matters, because
    # resolve() matches 'one' and 'pro' against exactly that model name.
    for d in devs:
        d["busy"] = d["board"] is None
        if d["busy"]:
            d["board"] = "in use elsewhere"
    return devs


def resolve(spec, devs, exclude=None):
    """Match a serial, a serial suffix, or part of a board name ('pro', 'one')."""
    pool = [d for d in devs if not exclude or d["serial"] != exclude]
    if not pool:
        return None
    if not spec:
        return pool[0]
    s = spec.lower()
    for d in pool:
        if d["serial"].lower() == s or d["serial"].lower().endswith(s):
            return d
    hits = [d for d in pool if not d.get("busy") and s in d["board"].lower()]
    if len(hits) == 1:
        return hits[0]
    if len(hits) > 1:
        sys.exit(f"device spec {spec!r} is ambiguous: "
                 + ", ".join(d["serial"][-8:] for d in hits))
    listing = "\n  ".join(f"{d['serial'][-8:]}  {d['board']}" for d in pool)
    hint = ""
    if any(d.get("busy") for d in pool):
        hint = ("\nA radio that is already open elsewhere cannot be probed, "
                "so its model is unknown and a name like 'one' or 'pro' "
                "cannot match it.  Select it by the last 8 characters of its "
                "serial, which always work.")
    sys.exit(f"no HackRF matches {spec!r}.  Attached:\n  {listing}{hint}")


# Which dongle you have decides the tuning range, and you do not find out
# until you plug it in: an R820T2 covers 24-1766 MHz, an E4000 reaches higher
# but starts at 53 MHz and has a hole in L band.  The sample-rate windows are
# the RTL2832U's and are the same either way.
RTL_TUNE_MIN, RTL_TUNE_MAX = 24e6, 2184e6     # union of the two
R820T_MAX = 1766e6
E4K_MIN = 53e6
E4K_GAP = (1095e6, 1258e6)
RTL_RATE_WINDOWS = ((225001, 300000), (900001, 3200000))
RTL_RATE_SAFE = 2_400_000


def rtl_devices():
    """Enumerate dongles.  Slow -- rtl_test -t opens each one and probes it."""
    try:
        out = subprocess.run(["rtl_test", "-t"], capture_output=True, text=True,
                             timeout=30)
    except (FileNotFoundError, subprocess.TimeoutExpired):
        return None
    text = (out.stdout or "") + (out.stderr or "")
    devs = []
    for line in text.splitlines():
        hit = re.match(r"\s*(\d+):\s*(.+?)\s*$", line)
        if hit and "device" not in hit.group(2).lower():
            devs.append({"index": hit.group(1), "name": hit.group(2)})
    tuner = re.search(r"Found (.+?) tuner", text)
    gains = re.search(r"Supported gain values \(\d+\):\s*(.+)", text)
    for d in devs:
        d["tuner"] = tuner.group(1) if tuner else "?"
        d["gains"] = gains.group(1).split() if gains else []
    return devs


def rtl_check(freq, rate):
    if not any(lo <= rate <= hi for lo, hi in RTL_RATE_WINDOWS):
        windows = ", ".join(f"{lo/1e6:g}-{hi/1e6:g} MHz"
                            for lo, hi in RTL_RATE_WINDOWS)
        sys.exit(f"[rtl] {rate/1e6:g} Msps is outside what an RTL2832U will "
                 f"lock to ({windows})")
    if rate > 2_560_000:
        print(f"[rtl] warning: {rate/1e6:g} Msps drops samples on most "
              f"dongles and most USB controllers; 2.4 Msps is the safe "
              f"ceiling", file=sys.stderr)
    mhz = freq / 1e6
    if not RTL_TUNE_MIN <= freq <= RTL_TUNE_MAX:
        extra = (" -- below that only direct sampling reaches, and this tool "
                 "does not enable it" if freq < RTL_TUNE_MIN else "")
        print(f"[rtl] warning: {mhz:.3f} MHz is outside every common RTL2832U "
              f"tuner ({RTL_TUNE_MIN/1e6:g}-{RTL_TUNE_MAX/1e6:g} MHz)"
              f"{extra}", file=sys.stderr)
    elif freq > R820T_MAX:
        print(f"[rtl] note: {mhz:.3f} MHz needs an E4000; an R820T2 stops at "
              f"{R820T_MAX/1e6:g} MHz", file=sys.stderr)
    elif E4K_GAP[0] <= freq <= E4K_GAP[1]:
        print(f"[rtl] note: {mhz:.3f} MHz falls in the E4000's L-band gap "
              f"({E4K_GAP[0]/1e6:g}-{E4K_GAP[1]/1e6:g} MHz); an R820T2 covers "
              f"it", file=sys.stderr)
    elif freq < E4K_MIN:
        print(f"[rtl] note: {mhz:.3f} MHz is below the E4000's "
              f"{E4K_MIN/1e6:g} MHz floor; an R820T2 covers it",
              file=sys.stderr)


def rtl_cmd(args, cfg):
    cmd = ["rtl_sdr", "-f", str(int(args.freq)), "-s", str(cfg.sample_rate)]
    if args.rtl_device is not None:
        cmd += ["-d", str(args.rtl_device)]
    cmd += ["-g", str(args.gain), "-p", str(args.ppm), "-"]
    return cmd


# ------------------------------------------------------------ CaribouLite --

# The CaribouLite is a Raspberry Pi HAT carrying one AT86RF215, whose two
# radios SoapySDR presents as two separate one-channel devices:
#
#   S1G  the sub-GHz radio, direct conversion, tx_test channel 0
#   HiF  the 2.4 GHz radio, tx_test channel 1, reaching everything else
#        through an RFFC5072 mixer (FULL board only; the ISM variant has no
#        mixer and so only its native 2385-2495 MHz)
#
# Transmitting needs the unmerged transmission_fix work -- see
# ../cariboulite/txfix/README.md.  A stock board receives here but emits
# nothing at all, which is why caribou_tx() insists on seeing the modem
# report that it locked to the I/Q stream.
CARIBOU_CHANNELS = ("s1g", "hif")
CARIBOU_TX_CHANNEL = {"s1g": 0, "hif": 1}
# Measured on this board with SoapySDR's listSampleRates().  The plugin
# accepts nothing else and rounds, loudly, if you ask near a supported rate.
CARIBOU_RATES = (400_000, 500_000, 666_667, 800_000, 1_000_000,
                 1_333_333, 2_000_000, 4_000_000)
CARIBOU_RANGES = {
    "s1g": ((389.5e6, 510e6), (779e6, 1020e6)),
    "hif": ((1e6, 6e9),),
}
CARIBOU_HIF_NATIVE = (2385e6, 2495e6)
CARIBOU_GAIN_MAX = 69

# Spectral sense of each path, measured 2026-11-16 against a HackRF Pro at
# 915 MHz -- see README.  True means that path mirrors the spectrum, so
# rflink has to conjugate to undo it.
#
# Only S1G transmit does.  It is not a quirk of the fix: the HiF path runs the
# modem at 2495 MHz and mixes with a 3410 MHz LO, so the emission comes out of
# the difference and is mirrored a second time, which cancels the first.  Both
# receive paths are the right way round, each confirmed by decoding a file off
# the air with its hash intact -- a mirrored receiver decodes nothing, so that
# is a sharper test than looking at a tone.  Do not infer any of these from
# another; each was measured, and two came out against intuition.
CARIBOU_TX_INVERTS = {"s1g": True, "hif": False}
CARIBOU_RX_INVERTS = {"s1g": False, "hif": False}


@contextlib.contextmanager
def quiet_stdout():
    """Mute writes to fd 1 from C code we do not control.

    SoapyCariboulite printf()s its find and probe chatter straight onto
    stdout.  In `devices` that merely corrupts the listing; in the receive
    streamer, where stdout *is* the IQ pipe, it corrupts the samples.
    """
    sys.stdout.flush()
    saved = os.dup(1)
    null = os.open(os.devnull, os.O_WRONLY)
    try:
        os.dup2(null, 1)
        yield
    finally:
        os.dup2(saved, 1)
        os.close(saved)
        os.close(null)


def caribou_devices():
    """Enumerate CaribouLite radios, or [] if there is no SoapySDR at all."""
    try:
        with quiet_stdout():
            import SoapySDR
            found = list(SoapySDR.Device.enumerate())
    except Exception:                                   # no module, no board
        return []
    devs = []
    for d in found:
        info = dict(d)
        if "cariboulite" not in info.get("driver", "").lower():
            continue
        devs.append({"channel": info.get("channel", "?"),
                     "label": info.get("label", "?"),
                     "serial": info.get("serial", "?")})
    return devs


def caribou_channel(freq, want="auto"):
    """Pick the radio that can reach freq, or explain why none can."""
    mhz = freq / 1e6
    if want != "auto":
        for lo, hi in CARIBOU_RANGES[want]:
            if lo <= freq <= hi:
                return want
        spans = " or ".join(f"{lo/1e6:g}-{hi/1e6:g} MHz"
                            for lo, hi in CARIBOU_RANGES[want])
        sys.exit(f"[cb] the {want.upper()} radio does not reach "
                 f"{mhz:.3f} MHz ({spans})")
    # Prefer S1G where it reaches: it is direct conversion, so no mixer LO and
    # no mixer spurs.  HiF is the fallback and covers everything else.
    for chan in CARIBOU_CHANNELS:
        for lo, hi in CARIBOU_RANGES[chan]:
            if lo <= freq <= hi:
                return chan
    sys.exit(f"[cb] no CaribouLite radio reaches {mhz:.3f} MHz")


def caribou_check(freq, rate, chan):
    """Warn about the traps that are specific to this board."""
    if rate not in CARIBOU_RATES:
        near = min(CARIBOU_RATES, key=lambda r: abs(r - rate))
        # Each rate is 4 MHz over a small integer, so several are recurring
        # decimals and %g renders them as 0.666667.
        def msps(r):
            return f"{r/1e6:.3f}".rstrip("0").rstrip(".")

        pretty = ", ".join(msps(r) for r in CARIBOU_RATES)
        sys.exit(f"[cb] the CaribouLite clocks only {pretty} Msps; "
                 f"{msps(rate)}M is not one of them "
                 f"(nearest {msps(near)}M)")
    if chan == "hif" and not (CARIBOU_HIF_NATIVE[0] <= freq
                              <= CARIBOU_HIF_NATIVE[1]):
        print(f"[cb] note: {freq/1e6:.3f} MHz is outside the HiF radio's "
              f"native {CARIBOU_HIF_NATIVE[0]/1e6:g}-"
              f"{CARIBOU_HIF_NATIVE[1]/1e6:g} MHz window, so it goes through "
              f"the RFFC5072 mixer -- the FULL board has one, the ISM variant "
              f"does not", file=sys.stderr)


def caribou_inverts(chan, rx):
    table = CARIBOU_RX_INVERTS if rx else CARIBOU_TX_INVERTS
    return table[chan]


def caribou_rx_cmd(args, cfg, chan):
    """The receive streamer, as a subprocess of this same script.

    A subprocess rather than a thread on purpose: at 2 Msps the demodulator
    is most of a core, and SoapySDR's reader has to be on another one or the
    stream overflows.
    """
    cmd = [sys.executable, os.path.abspath(__file__), "cbstream",
           "--freq", repr(float(args.freq)),
           "--sample-rate", repr(float(cfg.sample_rate)),
           "--cb-channel", chan,
           "--cb-gain", str(args.cb_gain)]
    if caribou_inverts(chan, rx=True):
        cmd.append("--cb-conjugate")
    return cmd


def find_tx_test(explicit=None):
    """Locate tx_test, which is built, not packaged."""
    tried = []
    for cand in (explicit, os.environ.get("RFLINK_TX_TEST"),
                 shutil.which("tx_test"),
                 "~/cariboulite-txfix/release/tx_test",
                 "/usr/local/lib/cariboulite/tx_test",
                 "/usr/local/bin/tx_test"):
        if not cand:
            continue
        path = os.path.expanduser(cand)
        if os.path.isfile(path) and os.access(path, os.X_OK):
            return path
        tried.append(path)
    sys.exit("[cb] tx_test not found -- it is built from the "
             "transmission_fix branch, not packaged.  Looked in:\n  "
             + "\n  ".join(tried)
             + "\nSee iotsec/cariboulite/txfix/README.md, then pass "
               "--cb-tx-test PATH or set $RFLINK_TX_TEST.")


TX_SYNC_LINE = "Is synchronized to incoming I/Q"


def caribou_tx_cmd(path, args, cfg, chan):
    exe = find_tx_test(args.cb_tx_test)
    print(f"[tx] {os.path.basename(exe)} -c {CARIBOU_TX_CHANNEL[chan]} "
          f"({chan.upper()}), gain {args.cb_tx_gain}/{CARIBOU_GAIN_MAX}")
    return [exe, "-c", str(CARIBOU_TX_CHANNEL[chan]),
            "-f", str(int(args.freq)), "-r", str(int(cfg.sample_rate)),
            "-g", str(args.cb_tx_gain), path]


def caribou_tx_report(log, air_s, elapsed_s):
    """Say whether the waveform was radiated, and how we know.

    The wall clock is the measurement that matters, not tx_test's exit status
    and not its sync line.  A transmitter that is working clocks samples out
    at the sample rate, so a 10 s waveform takes 10 s.  A broken one accepts
    the whole stream into a buffer that is never drained to the radio and
    returns success in about half the time, having radiated nothing -- which
    is what a spectrum capture of that case shows: no burst at all.

    The sync line is a weaker signal than it looks.  tx_test only reprints it
    every few seconds, and its first report is issued before the stream starts
    and always reads 0, so a transmission of a few seconds shows one 0 and
    proves nothing either way.
    """
    try:
        with open(log, errors="replace") as fh:
            text = fh.read()
    except OSError:
        return
    states = [ln.rsplit(":", 1)[-1].strip()
              for ln in text.splitlines() if TX_SYNC_LINE in ln]
    locked = "1" in states
    blocks = re.search(r"samples written:\s*(\d+)\s*blocks", text)
    wrote = f", {blocks.group(1)} blocks" if blocks else ""

    # Allow for start-up: the modem calibrates before the first sample moves.
    if air_s > 1.0 and elapsed_s < 0.8 * air_s:
        print(f"[tx] WARNING: {air_s:.1f} s of waveform was accepted in "
              f"{elapsed_s:.1f} s ({air_s/max(elapsed_s, 1e-9):.1f}x real "
              f"time){wrote}.  The radio cannot have clocked it out that "
              f"fast, so it was buffered and discarded: nothing, or almost "
              f"nothing, reached the air.\n"
              f"[tx] Recover with:  sudo systemctl restart "
              f"cariboulite-fpga.service\n"
              f"[tx] then transmit again.  See "
              f"iotsec/cariboulite/txfix/README.md.", file=sys.stderr)
    elif locked:
        print(f"[tx] radiated in real time ({elapsed_s:.1f} s for "
              f"{air_s:.1f} s of waveform){wrote}, modem locked to the I/Q "
              f"stream")
    else:
        print(f"[tx] radiated in real time ({elapsed_s:.1f} s for "
              f"{air_s:.1f} s of waveform){wrote}; too short for tx_test to "
              f"report the modem's I/Q lock, which it prints only every few "
              f"seconds")


def caribou_tx(path, args, cfg, chan, seconds):
    """Hand a waveform file to tx_test and report whether the modem locked."""
    cmd = caribou_tx_cmd(path, args, cfg, chan)
    # tx_test is extremely chatty on both streams and would fill a pipe long
    # before the waveform ends, so let it write to a file and read it after.
    log = tempfile.mkstemp(suffix=".log", prefix="rflink-tx_test-")[1]
    try:
        t0 = time.time()
        with open(log, "wb") as fh:
            rc = subprocess.run(cmd, stdout=fh, stderr=subprocess.STDOUT,
                                timeout=seconds + 120).returncode
        caribou_tx_report(log, seconds, time.time() - t0)
    finally:
        if os.path.exists(log):
            os.unlink(log)
    return rc


def hackrf_cmd(serial, cfg, freq, rx, args):
    cmd = ["hackrf_transfer", "-d", serial,
           "-f", str(int(freq)), "-s", str(cfg.sample_rate), "-b", "1750000"]
    if rx:
        cmd += ["-r", "-", "-a", str(int(args.rx_amp)),
                "-l", str(args.rx_lna), "-g", str(args.rx_vga)]
    else:
        cmd += ["-a", str(int(args.tx_amp)), "-x", str(args.tx_gain)]
    return cmd


class Receiver:
    """Runs a receiver process and pumps its stdout into a Demodulator."""

    def __init__(self, cmd, demod, capture=None, stderr=subprocess.DEVNULL,
                 label=None, backlog_mb=256):
        self.cmd = cmd
        self.demod = demod
        self.stderr = stderr
        self.label = label or os.path.basename(cmd[0])
        self.capture = open(capture, "wb") if capture else None
        # Bounded on purpose.  The radio delivers at a fixed rate whatever the
        # demodulator manages, and on a Raspberry Pi the demodulator is the
        # slower of the two at 2 Msps.  An unbounded queue turns that deficit
        # into a slow memory leak -- about 1 MB/s of it -- and an hour-long
        # listen then ends in the OOM killer rather than a result.  Dropping
        # the backlog instead costs frames, which is a loss this link already
        # knows how to report and repair; dropping it in the reader thread
        # keeps the pipe drained so the radio itself never stalls.
        self.q = queue.Queue(maxsize=max(8, int(backlog_mb)))
        self.dropped = 0
        self.proc = None
        self.reader = None

    def start(self):
        self.proc = subprocess.Popen(self.cmd, stdout=subprocess.PIPE,
                                     stderr=self.stderr, bufsize=0)
        time.sleep(0.3)
        if self.proc.poll() is not None:
            sys.exit(f"{self.label} exited immediately (rc="
                     f"{self.proc.returncode}) -- is the device free?")
        self.reader = threading.Thread(target=self._pump, daemon=True)
        self.reader.start()

    def wait_ready(self, timeout):
        """Block until the first samples arrive.  Returns False on timeout.

        hackrf_transfer streams within a few hundred milliseconds, but
        opening a CaribouLite runs a whole modem calibration first and takes
        seconds.  Waiting for real samples beats guessing at a settle time,
        and distinguishes a slow radio from one that is never going to
        deliver anything at all.
        """
        end = time.time() + timeout
        while time.time() < end:
            try:
                chunk = self.q.get(timeout=0.2)
            except queue.Empty:
                if self.proc.poll() is not None:
                    return False
                continue
            if chunk is None:
                return False
            if self.capture:
                self.capture.write(chunk)
            self.demod.feed(chunk)
            return True
        return False

    def _pump(self):
        # Hand on whole IQ pairs only.  A short read can end mid-pair, and if
        # the chunk that gets dropped below is an odd number of bytes long,
        # every sample after it has I and Q transposed -- which conjugates the
        # signal, mirrors the spectrum, and silently kills the rest of the
        # receive.  Keeping the odd byte here makes a dropped chunk cost
        # exactly the signal it contained.
        odd = b""
        try:
            while True:
                chunk = self.proc.stdout.read(1 << 20)
                if not chunk:
                    break
                chunk = odd + chunk
                if len(chunk) % 2:
                    chunk, odd = chunk[:-1], chunk[-1:]
                else:
                    odd = b""
                try:
                    self.q.put_nowait(chunk)
                except queue.Full:
                    self.dropped += 1
                    if self.dropped in (1, 100, 1000, 10000):
                        print(f"\n[rx] warning: the demodulator is behind the "
                              f"radio and {self.dropped} MB of signal has "
                              f"been dropped -- lower --sample-rate (a Pi "
                              f"manages about 1.4 Msps), or capture with "
                              f"--capture and run `demod` afterwards",
                              file=sys.stderr)
        finally:
            # Blocking, not put_nowait: the end-of-stream marker must not be
            # the one thing the bound throws away.
            self.q.put(None)

    def drain(self, deadline, stop_when_complete=True):
        """Demodulate until complete, the deadline passes, or the pipe closes."""
        while time.time() < deadline:
            try:
                chunk = self.q.get(timeout=0.2)
            except queue.Empty:
                continue
            if chunk is None:
                return False
            if self.capture:
                self.capture.write(chunk)
            self.demod.feed(chunk)
            if stop_when_complete and self.demod.complete:
                return True
        return self.demod.complete

    def stop(self):
        if self.proc and self.proc.poll() is None:
            self.proc.send_signal(signal.SIGINT)
            try:
                self.proc.wait(timeout=5)
            except subprocess.TimeoutExpired:
                self.proc.kill()
        # Whatever is still buffered is still signal.
        while True:
            try:
                chunk = self.q.get_nowait()
            except queue.Empty:
                break
            if chunk is None:
                break
            if self.capture:
                self.capture.write(chunk)
            self.demod.feed(chunk)
        self.demod.flush()
        if self.capture:
            self.capture.close()


# -------------------------------------------------------------- output ------

def safe_name(name, fallback="received.bin"):
    name = os.path.basename(name.replace("\\", "/")).strip()
    if not name or name in (".", "..") or name.startswith("."):
        return fallback
    return re.sub(r"[^\w.\- ]", "_", name)


def deliver(demod, outdir, force=False):
    blob = demod.assemble()
    name, data, digest, _ = parse_container(blob)
    ok = hashlib.sha256(data).digest() == digest
    os.makedirs(outdir, exist_ok=True)
    path = os.path.join(outdir, safe_name(name))
    if os.path.exists(path) and not force:
        stem, ext = os.path.splitext(path)
        i = 1
        while os.path.exists(f"{stem}.{i}{ext}"):
            i += 1
        path = f"{stem}.{i}{ext}"
    with open(path, "wb") as fh:
        fh.write(data)
    print(f"\n[rx] {'OK  ' if ok else 'BAD '} sha256 {'verified' if ok else 'MISMATCH'}"
          f" -- {len(data)} bytes -> {path}")
    return path, ok


def report(demod, gain_flags="--rx-vga (or --rx-lna)"):
    q = demod.quality()
    print(f"[rx] peak {q['peak']}/127 ({q['peak_dbfs']:+.1f} dBFS), "
          f"{q['clip_pct']:.2f}% clipped, {q['candidates']} sync hits, "
          f"{q['bad_crc']} failed CRC")
    # A GFSK burst has a constant envelope, so the peak is the burst level.
    # Measured on this bench, anything that is not hard against the rails
    # decodes: a HackRF was clean at peak 4/127, and an RTL on AGC was clean
    # at 127/127 with 31% of samples clipped. Failure came only when the
    # HackRF front end railed outright.
    if q["clip_pct"] > 0.05 or q["peak"] >= 127:
        print("[rx] hint: the front end may be clipping, which destroys an "
              "FM signal even at high SNR -- if nothing decodes, drop "
              f"{gain_flags} by 6-12 dB")
    elif q["peak"] < 4:
        print(f"[rx] hint: barely above the quantiser -- raise {gain_flags} "
              "or --tx-gain, or move the antennas closer")


# ------------------------------------------------------------ subcommands ---

def default_if_offset(sample_rate):
    """Where to park the signal, as a function of how much room there is.

    A fixed 300 kHz is right at 2 Msps and above, but the CaribouLite will
    clock as low as 400 ksps, and at 1 Msps a 300 kHz offset pushes the upper
    FSK sideband into the band edge: the selftest drops 12 frames in 40 that
    it keeps at 150 kHz.  Scaling below 2 Msps fixes that and leaves every
    rate a HackRF can reach exactly as it was.
    """
    return min(DEFAULT_IF, 0.15 * sample_rate)


def cfg_from(args):
    if_offset = (args.if_offset if args.if_offset is not None
                 else default_if_offset(args.sample_rate))
    return Config(sample_rate=args.sample_rate, sps=args.sps,
                  if_offset=if_offset, payload=args.frame_bytes,
                  bt=args.bt, deviation=args.deviation)


def pick_radio(args, what):
    """Resolve --radio, enumerating only when it says auto.

    The answer is written back onto args so that later reporting names the
    right flags.
    """
    want = getattr(args, "radio", "hackrf")
    if want == "auto":
        if list_devices(required=False):
            want = "hackrf"
        elif caribou_devices():
            print("[  ] no HackRF; using the CaribouLite", file=sys.stderr)
            want = "caribou"
        else:
            sys.exit(f"no radio found for {what} -- attach a HackRF or a "
                     f"CaribouLite, or say --radio explicitly")
    args.radio = want
    return want


def check_rate(radio, rate, freq, chan=None):
    """Apply whichever radio's sample-rate limits actually apply."""
    if radio == "caribou":
        caribou_check(freq, rate, chan)
    elif rate < 2_000_000:
        sys.exit(f"hackrf_transfer supports 2-20 Msps; --sample-rate "
                 f"{rate/1e6:g}M is too low")


def check_band(freq, force=False):
    for lo, hi, what in PROTECTED_BANDS:
        if lo <= freq <= hi:
            where = (f"{freq/1e6:.3f} MHz falls in {lo/1e6:g}-{hi/1e6:g} MHz, "
                     f"which carries {what}")
            if not force:
                sys.exit(f"[tx] refusing to transmit: {where}.\n"
                         f"[tx] That is a safety-of-life allocation, not a "
                         f"licensing technicality.  Receiving there is fine; "
                         f"pass --force-band if you are transmitting into a "
                         f"cable or a screen room.")
            print(f"[tx] WARNING: {where}.", file=sys.stderr)
            return


def fec_note(frames, ndata, kgen, mgen):
    if not kgen:
        return ""
    spare = len(frames) - ndata
    return (f" ({ndata} data + {spare} parity, generations of "
            f"{kgen}+{mgen}, survives {100.0 * spare / len(frames):.0f}% loss)")


def station_id(args, cfg):
    call = getattr(args, "callsign", None)
    if not call:
        return None
    if not re.fullmatch(r"[A-Za-z0-9/]{3,16}", call):
        sys.exit(f"--callsign {call!r}: expected something like AD7KM or AD7KM/P")
    return ident_frame(call, cfg)


def notice(freq):
    print(f"[tx] transmitting on {freq/1e6:.3f} MHz -- your licence, your "
          f"responsibility", file=sys.stderr)


def cmd_devices(args):
    devs = list_devices(required=False)
    for i, d in enumerate(devs):
        note = "  (select it by serial: its model cannot be read while it is "
        print(f"hackrf  {i}: {d['serial']}  {d['board']}"
              + (note + "open)" if d.get("busy") else ""))
    cb = caribou_devices()
    for d in cb:
        chan = d["channel"].lower()
        spans = " and ".join(f"{lo/1e6:g}-{hi/1e6:g} MHz"
                             for lo, hi in CARIBOU_RANGES.get(chan, ()))
        print(f"caribou {d['channel']}: {d['label']}  [{spans}]")
    rtl = rtl_devices()
    for d in (rtl or []):
        span = (f", gain {d['gains'][0]}-{d['gains'][-1]} dB"
                if d.get("gains") else "")
        print(f"rtl     {d['index']}: {d['name']}  [{d.get('tuner', '?')}"
              f"{span}]  (receive only)")
    if not devs and not cb and not rtl:
        sys.exit("no HackRF, CaribouLite or RTL-SDR found")


def cmd_send(args):
    check_band(args.freq, args.force_band)
    cfg = cfg_from(args)
    radio = pick_radio(args, "transmitting")
    chan = dev = None
    if radio == "caribou":
        chan = caribou_channel(args.freq, args.cb_channel)
        check_rate(radio, cfg.sample_rate, args.freq, chan)
        if not caribou_devices():
            sys.exit("[cb] no CaribouLite found")
    else:
        check_rate(radio, cfg.sample_rate, args.freq)
        dev = resolve(args.tx_serial, list_devices())
        if dev is None:
            sys.exit("no HackRF found")
    fmt = "s16" if radio == "caribou" else "s8"
    invert = radio == "caribou" and caribou_inverts(chan, rx=False)

    blob = build_container(args.file)
    frames, ndata, kgen, mgen = container_frames(blob, cfg, args.fec)
    print(f"[tx] {args.file}: {len(blob)} bytes -> {len(frames)} frames "
          f"x {args.passes} pass(es){fec_note(frames, ndata, kgen, mgen)}")
    print(f"[tx] {cfg.describe()}")
    if invert:
        print(f"[tx] conjugating the waveform: the CaribouLite "
              f"{chan.upper()} transmit path mirrors the spectrum")
    tmp = args.save_iq or tempfile.mkstemp(suffix=".iq", prefix="rflink-")[1]
    try:
        n = write_iq(tmp, frames, cfg, passes=args.passes, gap_s=args.gap,
                     amplitude=args.amplitude, ident=station_id(args, cfg),
                     fmt=fmt, invert=invert)
        air = n / cfg.sample_rate
        print(f"[tx] waveform {air:.2f} s "
              f"({n * 2 * IQ_FORMATS[fmt][0]().itemsize / 1e6:.1f} MB)")
        notice(args.freq)
        t0 = time.time()
        if radio == "caribou":
            rc = caribou_tx(tmp, args, cfg, chan, air)
        else:
            cmd = (hackrf_cmd(dev["serial"], cfg, args.freq, False, args)
                   + ["-t", tmp])
            rc = subprocess.run(cmd, stderr=subprocess.DEVNULL).returncode
        print(f"[tx] done in {time.time()-t0:.1f} s (rc={rc})")
        return rc
    finally:
        if not args.save_iq and os.path.exists(tmp):
            os.unlink(tmp)


def cmd_recv(args):
    cfg = cfg_from(args)
    radio = pick_radio(args, "receiving")
    if radio == "caribou":
        chan = caribou_channel(args.freq, args.cb_channel)
        check_rate(radio, cfg.sample_rate, args.freq, chan)
        if not caribou_devices():
            sys.exit("[cb] no CaribouLite found")
        cmd, label = caribou_rx_cmd(args, cfg, chan), f"CaribouLite {chan.upper()}"
    else:
        check_rate(radio, cfg.sample_rate, args.freq)
        dev = resolve(args.rx_serial, list_devices())
        if dev is None:
            sys.exit("no HackRF found")
        cmd = hackrf_cmd(dev["serial"], cfg, args.freq, True, args)
        label = f"HackRF {dev['serial'][-8:]}"
    demod = Demodulator(cfg, threshold=args.threshold)
    # The CaribouLite streamer reports what it tuned, and why it failed, on
    # stderr; that is worth seeing rather than discarding.
    rx = Receiver(cmd, demod, capture=args.capture, label=label,
                  stderr=None if radio == "caribou" else subprocess.DEVNULL)
    print(f"[rx] listening on {args.freq/1e6:.3f} MHz with the {label} "
          f"-- {cfg.describe()}")
    rx.start()
    try:
        rx.drain(time.time() + args.timeout)
    except KeyboardInterrupt:
        print("\n[rx] interrupted")
    finally:
        rx.stop()
    return finish(demod, args)


def loopback_radios(args):
    """Decide which radio transmits and which receives."""
    tx_radio = args.tx_radio or args.radio
    rx_radio = args.rx_radio or args.radio
    if "auto" in (tx_radio, rx_radio):
        devs = list_devices(required=False)
        cb = caribou_devices()
        if len(devs) >= 2:
            guess = ("hackrf", "hackrf")
        elif devs and cb:
            # One of each.  The CaribouLite transmits, because it is the end
            # that needs the patched datapath proved.
            guess = ("caribou", "hackrf")
            print("[  ] one HackRF and one CaribouLite: transmitting on the "
                  "CaribouLite, listening on the HackRF", file=sys.stderr)
        else:
            sys.exit(f"loopback needs two radios on this host; found "
                     f"{len(devs)} HackRF(s) and {len(cb)} CaribouLite "
                     f"radio(s) -- use send/recv on separate hosts")
        tx_radio = guess[0] if tx_radio == "auto" else tx_radio
        rx_radio = guess[1] if rx_radio == "auto" else rx_radio
    if tx_radio == "caribou" and rx_radio == "caribou":
        sys.exit("[cb] one CaribouLite cannot be both ends of a loopback: "
                 "its two radios share a single SMI bus, which carries one "
                 "direction at a time.  Measured -- transmitting on S1G while "
                 "receiving on HiF delivers zero samples, it does not merely "
                 "run slowly.  Use send and recv on two hosts.")
    return tx_radio, rx_radio


def cmd_loopback(args):
    check_band(args.freq, args.force_band)
    cfg = cfg_from(args)
    tx_radio, rx_radio = loopback_radios(args)
    args.radio = rx_radio              # whose gain flag finish() should name

    tx = rx = tx_chan = rx_chan = None
    if tx_radio == "caribou":
        tx_chan = caribou_channel(args.freq, args.cb_channel)
        check_rate(tx_radio, cfg.sample_rate, args.freq, tx_chan)
        tx_name = f"CaribouLite {tx_chan.upper()}"
    if rx_radio == "caribou":
        rx_chan = caribou_channel(args.freq, args.cb_channel)
        check_rate(rx_radio, cfg.sample_rate, args.freq, rx_chan)
        rx_name = f"CaribouLite {rx_chan.upper()}"
    if "hackrf" in (tx_radio, rx_radio):
        check_rate("hackrf", cfg.sample_rate, args.freq)
        devs = list_devices()
        if tx_radio == "hackrf":
            tx = resolve(args.tx_serial, devs)
            if tx is None:
                sys.exit("no HackRF found to transmit with")
            tx_name = f"HackRF {tx['serial'][-8:]} ({tx['board']})"
        if rx_radio == "hackrf":
            rx = resolve(args.rx_serial, devs,
                         exclude=tx["serial"] if tx else None)
            if rx is None:
                sys.exit("no second HackRF found to receive with")
            rx_name = f"HackRF {rx['serial'][-8:]} ({rx['board']})"
    print(f"[  ] tx {tx_name}  ->  rx {rx_name}")

    fmt = "s16" if tx_radio == "caribou" else "s8"
    invert = tx_radio == "caribou" and caribou_inverts(tx_chan, rx=False)
    blob = build_container(args.file)
    frames, ndata, kgen, mgen = container_frames(blob, cfg, args.fec)
    tmp = tempfile.mkstemp(suffix=".iq", prefix="rflink-")[1]
    txlog = tempfile.mkstemp(suffix=".log", prefix="rflink-tx_test-")[1]
    demod = Demodulator(cfg, threshold=args.threshold)
    if rx_radio == "caribou":
        rxcmd = caribou_rx_cmd(args, cfg, rx_chan)
        rxerr = None
    else:
        rxcmd = hackrf_cmd(rx["serial"], cfg, args.freq, True, args)
        rxerr = subprocess.DEVNULL
    receiver = Receiver(rxcmd, demod, capture=args.capture, label=rx_name,
                        stderr=rxerr)
    txproc = None
    try:
        n = write_iq(tmp, frames, cfg, passes=args.passes, gap_s=args.gap,
                     amplitude=args.amplitude, ident=station_id(args, cfg),
                     fmt=fmt, invert=invert)
        air = n / cfg.sample_rate
        print(f"[tx] {args.file}: {len(blob)} bytes -> {len(frames)} frames "
              f"x {args.passes}{fec_note(frames, ndata, kgen, mgen)}, "
              f"{air:.2f} s on the air")
        print(f"[  ] {cfg.describe()}")

        receiver.start()
        if not receiver.wait_ready(args.open_timeout):
            print(f"[rx] warning: no samples from the {rx_name} after "
                  f"{args.open_timeout:g} s", file=sys.stderr)
        time.sleep(args.settle)
        notice(args.freq)
        if tx_radio == "caribou":
            txcmd = caribou_tx_cmd(tmp, args, cfg, tx_chan)
            txerr = open(txlog, "wb")
            tx_t0 = time.time()
            txproc = subprocess.Popen(txcmd, stdout=txerr,
                                      stderr=subprocess.STDOUT)
        else:
            txerr = None
            txcmd = (hackrf_cmd(tx["serial"], cfg, args.freq, False, args)
                     + ["-t", tmp])
            txproc = subprocess.Popen(txcmd, stderr=subprocess.DEVNULL)

        # The CaribouLite spends seconds calibrating its modem before a single
        # sample reaches the air, so the budget cannot be just the air time.
        slack = 15 + (30 if tx_radio == "caribou" else 0)
        deadline = time.time() + air + args.settle + args.linger + slack
        while txproc.poll() is None and time.time() < deadline:
            if receiver.drain(time.time() + 0.5):
                break
        txproc.wait(timeout=30)
        if txerr:
            txerr.close()
            caribou_tx_report(txlog, air, time.time() - tx_t0)
        receiver.drain(time.time() + args.linger)
    except KeyboardInterrupt:
        print("\n[  ] interrupted")
    finally:
        if txproc and txproc.poll() is None:
            txproc.kill()
        receiver.stop()
        for path in (tmp, txlog):
            if os.path.exists(path):
                os.unlink(path)
    return finish(demod, args)


def cmd_rtl(args):
    """Receive with an RTL-SDR.  Receive only -- the dongle cannot transmit."""
    cfg = cfg_from(args)
    rtl_check(args.freq, cfg.sample_rate)
    # Deliberately not rtl_devices() here: rtl_test -t probes the tuner, which
    # takes seconds and opens the device we are about to want.
    if shutil.which("rtl_sdr") is None:
        sys.exit("rtl_sdr not found -- install the rtl-sdr tools")

    demod = Demodulator(cfg, threshold=args.threshold, fmt="u8")
    # rtl_sdr's own stderr names the tuner and the gain it settled on, and is
    # the only place a failure to open the dongle shows up.
    rx = Receiver(rtl_cmd(args, cfg), demod, capture=args.capture, stderr=None)
    print(f"[rx] listening on {args.freq/1e6:.3f} MHz -- {cfg.describe()}")
    rx.start()
    try:
        rx.drain(time.time() + args.timeout)
    except KeyboardInterrupt:
        print("\n[rx] interrupted")
    finally:
        rx.stop()
    return finish(demod, args)


def cmd_cbstream(args):
    """Stream CS8 IQ from a CaribouLite radio to stdout.  Internal.

    This is the other half of `recv --radio caribou`: the parent runs it as a
    subprocess and demodulates what comes out of the pipe, the same way it
    consumes hackrf_transfer or rtl_sdr.
    """
    # Claim the IQ pipe before SoapySDR is anywhere near fd 1, then point fd 1
    # at stderr so the plugin's printf() chatter cannot land in the samples.
    iq_fd = os.dup(1)
    os.dup2(2, 1)
    out = os.fdopen(iq_fd, "wb", buffering=0)

    try:
        import SoapySDR
        from SoapySDR import (SOAPY_SDR_RX, SOAPY_SDR_CS8,
                              SOAPY_SDR_OVERFLOW, SOAPY_SDR_TIMEOUT)
    except ImportError:
        sys.exit("[cb] the SoapySDR python bindings are missing -- "
                 "apt install python3-soapysdr")

    want = args.cb_channel
    devs = [d for d in SoapySDR.Device.enumerate()
            if dict(d).get("channel", "").lower() == want]
    if not devs:
        sys.exit(f"[cb] no CaribouLite {want.upper()} radio found")
    # Pass the Kwargs object through untouched: SWIG drops a plain dict's
    # values on this path and the plugin then throws IndexError: map::at.
    sdr = SoapySDR.Device(devs[0])
    sdr.setSampleRate(SOAPY_SDR_RX, 0, args.sample_rate)
    sdr.setFrequency(SOAPY_SDR_RX, 0, args.freq)
    if str(args.cb_gain).lower() == "agc":
        sdr.setGainMode(SOAPY_SDR_RX, 0, True)
    else:
        sdr.setGainMode(SOAPY_SDR_RX, 0, False)
        sdr.setGain(SOAPY_SDR_RX, 0, float(args.cb_gain))
    tuned = sdr.getFrequency(SOAPY_SDR_RX, 0)
    print(f"[cb] {want.upper()} tuned {tuned/1e6:.4f} MHz, "
          f"{sdr.getSampleRate(SOAPY_SDR_RX, 0)/1e6:g} Msps, gain "
          f"{sdr.getGain(SOAPY_SDR_RX, 0):g} dB"
          f"{' (AGC)' if sdr.getGainMode(SOAPY_SDR_RX, 0) else ''}",
          file=sys.stderr)

    # CS8 rather than the native CS16: the plugin's converter scales by the
    # 4096-count full scale it reports, so a byte here means the same thing a
    # HackRF byte does and the demodulator's s8 path and its dBFS numbers
    # carry over unchanged.  It also halves what has to cross the pipe.
    stream = sdr.setupStream(SOAPY_SDR_RX, SOAPY_SDR_CS8)
    mtu = sdr.getStreamMTU(stream)
    buf = np.empty(2 * mtu, dtype=np.int8)
    sdr.activateStream(stream)
    overflows = 0
    try:
        while True:
            sr = sdr.readStream(stream, [buf], mtu, timeoutUs=1_000_000)
            if sr.ret > 0:
                n = 2 * sr.ret
                if args.cb_conjugate:
                    q = buf[1:n:2]
                    np.negative(q, out=q)
                    np.maximum(q, -127, out=q)         # -(-128) wraps in int8
                out.write(buf[:n].tobytes())
            elif sr.ret == SOAPY_SDR_OVERFLOW:
                overflows += 1
                if overflows in (1, 10, 100, 1000):
                    print(f"[cb] stream overflow x{overflows} -- samples are "
                          f"being dropped", file=sys.stderr)
            elif sr.ret < 0 and sr.ret != SOAPY_SDR_TIMEOUT:
                print(f"[cb] readStream returned {sr.ret}", file=sys.stderr)
                break
    except (KeyboardInterrupt, BrokenPipeError):
        pass
    finally:
        sdr.deactivateStream(stream)
        sdr.closeStream(stream)
        if overflows:
            print(f"[cb] {overflows} overflow(s) in total", file=sys.stderr)
    return 0


def cmd_demod(args):
    cfg = cfg_from(args)
    demod = Demodulator(cfg, threshold=args.threshold, fmt=args.format)
    with open(args.iqfile, "rb") as fh:
        while True:
            chunk = fh.read(1 << 22)
            if not chunk:
                break
            demod.feed(chunk)
    demod.flush()
    return finish(demod, args)


def cmd_modulate(args):
    cfg = cfg_from(args)
    # No radio is opened here, so --radio only decides the file's format:
    # int8 for hackrf_transfer, int16 for the CaribouLite's tx_test.
    radio = args.radio
    chan = caribou_channel(args.freq, args.cb_channel) if radio == "caribou" else None
    check_rate(radio, cfg.sample_rate, args.freq, chan)
    fmt = "s16" if radio == "caribou" else "s8"
    invert = radio == "caribou" and caribou_inverts(chan, rx=False)
    blob = build_container(args.file)
    frames, ndata, kgen, mgen = container_frames(blob, cfg, args.fec)
    n = write_iq(args.out, frames, cfg, passes=args.passes, gap_s=args.gap,
                 amplitude=args.amplitude, ident=station_id(args, cfg),
                 fmt=fmt, invert=invert)
    bits = 8 * IQ_FORMATS[fmt][0]().itemsize
    print(f"[tx] {len(frames)} frames"
          f"{fec_note(frames, ndata, kgen, mgen)} x {args.passes} -> {args.out} "
          f"({n} samples, {n/cfg.sample_rate:.2f} s, int{bits} IQ @ "
          f"{cfg.sample_rate} Hz"
          f"{', conjugated for the CaribouLite S1G path' if invert else ''})")
    return 0


def finish(demod, args):
    # Name the gain knob the operator can actually turn: the rtl subcommand
    # exposes --gain, a CaribouLite --cb-gain, the HackRF paths --rx-lna /
    # --rx-vga.
    if hasattr(args, "gain"):
        flags = "--gain"
    elif getattr(args, "radio", None) == "caribou":
        flags = "--cb-gain"
    else:
        flags = "--rx-vga (or --rx-lna)"
    if demod.total is None:
        print("\n[rx] no frames recovered")
        report(demod, flags)
        # A handful of sync hits in noise is normal; a steady stream of them
        # on a signal that is plainly there means the two ends disagree.
        if demod.stats["candidates"] >= 4 and demod.quality()["peak"] >= 12:
            print("[rx] hint: the sync word was found but nothing decoded -- "
                  "both ends must agree on --sample-rate, --sps, --deviation, "
                  "--if-offset, --bt and --frame-bytes")
        return 1
    if demod.complete:
        _, ok = deliver(demod, args.outdir, force=args.force)
        if demod.recovered:
            print(f"[rx] Reed-Solomon rebuilt {demod.recovered} lost frame(s)")
        report(demod, flags)
        return 0 if ok else 1
    miss = demod.missing()
    print(f"\n[rx] incomplete: {len(demod.frames)}/{demod.ndata} data frames"
          f"{f' + {len(demod.parity)} parity' if demod.parity else ''}, "
          f"missing {len(miss)}")
    print(f"[rx] missing seq: {miss[:24]}{' ...' if len(miss) > 24 else ''}")
    report(demod, flags)
    if demod.kgen:
        print("[rx] not enough parity to rebuild -- raise --fec on the sender")
    else:
        print("[rx] retry with --fec 20 on the sender, or adjust gains")
    return 1


def cmd_selftest(args):
    """Modulate, impair, demodulate -- no radio involved."""
    cfg = cfg_from(args)
    rng = np.random.default_rng(args.seed)
    payload = rng.bytes(args.bytes)
    tmp = tempfile.mkstemp(suffix=".bin", prefix="rflink-st-")[1]
    with open(tmp, "wb") as fh:
        fh.write(payload)
    try:
        blob = build_container(tmp)
        frames, ndata, kgen, mgen = container_frames(blob, cfg, args.fec)
        iqpath = tmp + ".iq"
        ident = station_id(args, cfg)
        write_iq(iqpath, frames, cfg, passes=args.passes, gap_s=args.gap,
                 amplitude=args.amplitude, ident=ident)
        x = np.frombuffer(open(iqpath, "rb").read(), dtype=np.int8).astype(np.float32)
        os.unlink(iqpath)
        sig = (x[0::2] + 1j * x[1::2]).astype(np.complex64)

        sent = len(frames) * args.passes
        killed = 0
        if args.drop:
            # Blank whole frames where they sit in the waveform, which is what
            # a burst of interference does to them.
            stride = cfg.frame_samples + int(cfg.sample_rate * args.gap)
            base = int(cfg.sample_rate * LEAD_S) + (stride if ident else 0)
            killed = int(round(sent * args.drop / 100.0))
            for v in rng.choice(sent, size=min(killed, sent), replace=False):
                lo = base + int(v) * stride
                sig[lo:lo + stride] = 0

        # sample-clock error
        if args.ppm:
            n = len(sig)
            t = np.arange(n) * (1 + args.ppm * 1e-6)
            t = t[t < n - 1]
            idx = t.astype(np.int64)
            frac = (t - idx).astype(np.float32)
            sig = (sig[idx] * (1 - frac) + sig[idx + 1] * frac).astype(np.complex64)
        # A receiver may run at its own sample rate; only the symbol rate has
        # to match.  This is what lets an RTL-SDR at 2.4 Msps read a HackRF
        # transmitting at 2 Msps.
        # The IF offset is a property of the signal in the air, so the
        # receiver keeps the transmitter's whatever rate it samples at.
        rxcfg = Config(sample_rate=args.rx_rate or cfg.sample_rate,
                       sps=args.rx_sps or cfg.sps, if_offset=cfg.if_offset,
                       payload=args.frame_bytes, bt=args.bt,
                       deviation=args.deviation)
        if abs(rxcfg.symbol_rate - cfg.symbol_rate) > 1e-6:
            sys.exit(f"receiver symbol rate {rxcfg.symbol_rate/1e3:g} kbaud "
                     f"does not match the transmitter's "
                     f"{cfg.symbol_rate/1e3:g} kbaud")
        if rxcfg.sample_rate != cfg.sample_rate:
            ratio = Fraction(int(rxcfg.sample_rate),
                             int(cfg.sample_rate)).limit_denominator(5000)
            if _resample is None:
                sys.exit("--rx-rate needs scipy for resampling")
            sig = _resample(sig, ratio.numerator, ratio.denominator)

        # carrier offset and random phase
        k = 2 * np.pi * args.cfo / rxcfg.sample_rate
        sig = sig * np.exp(1j * (k * np.arange(len(sig)) + rng.uniform(0, 2 * np.pi)))
        # noise at the requested SNR, measured over the occupied bandwidth
        p_sig = float(np.mean(np.abs(sig) ** 2))
        bw_ratio = rxcfg.sample_rate / (2 * (rxcfg.deviation + rxcfg.symbol_rate))
        p_n = p_sig / (10 ** (args.snr / 10)) * bw_ratio
        sig = sig + math.sqrt(p_n / 2) * (rng.standard_normal(len(sig))
                                          + 1j * rng.standard_normal(len(sig)))
        raw = np.empty(2 * len(sig), dtype=np.float32)
        raw[0::2], raw[1::2] = sig.real, sig.imag
        if args.rx_format == "u8":
            raw = np.clip(np.rint(raw + 127.5), 0, 255).astype(np.uint8)
        else:
            raw = np.clip(np.rint(raw), -127, 127).astype(np.int8)

        print(f"[st] {args.bytes} B, {len(frames)} frames x {args.passes}"
              f"{fec_note(frames, ndata, kgen, mgen)}")
        print(f"[st] SNR {args.snr} dB, CFO {args.cfo} Hz, clock {args.ppm} ppm"
              + (f", blanking {killed}/{sent} frames ({args.drop}%)"
                 if killed else ""))
        print(f"[st] tx {cfg.describe()}")
        if (rxcfg.sample_rate != cfg.sample_rate
                or args.rx_format != "s8"):
            print(f"[st] rx {rxcfg.describe()} as {args.rx_format}")
        demod = Demodulator(rxcfg, threshold=args.threshold, verbose=False,
                            fmt=args.rx_format)
        t0 = time.time()
        buf = raw.tobytes()
        for i in range(0, len(buf), 1 << 22):
            demod.feed(buf[i:i + (1 << 22)])
        demod.flush()
        secs = len(sig) / rxcfg.sample_rate
        dt = time.time() - t0
        print(f"[st] demodulated {secs:.2f} s of signal in {dt:.2f} s "
              f"({secs/max(dt,1e-9):.1f}x realtime)")
        if not demod.complete:
            print(f"[st] FAIL {len(demod.frames)}/{demod.ndata} data frames "
                  f"+ {len(demod.parity)} parity, "
                  f"{demod.stats['bad_crc']} bad CRC")
            return 1
        name, data, digest, _ = parse_container(demod.assemble())
        ok = data == payload and hashlib.sha256(data).digest() == digest
        if demod.recovered:
            print(f"[st] Reed-Solomon rebuilt {demod.recovered} lost frame(s)")
        print(f"[st] {'PASS' if ok else 'FAIL'}: {len(data)} bytes, "
              f"name={name!r}, sha256 {'matches' if ok else 'differs'}")
        return 0 if ok else 1
    finally:
        os.unlink(tmp)


# ----------------------------------------------------------------- CLI ------

def freq_arg(s):
    s = s.strip().lower().replace("hz", "")
    mult = {"k": 1e3, "m": 1e6, "g": 1e9}
    if s and s[-1] in mult:
        return float(s[:-1]) * mult[s[-1]]
    return float(s)


def add_radio_opts(p, default="auto", tx=False, rx=False):
    """Flags for choosing a radio and driving a CaribouLite."""
    p.add_argument("--radio", choices=("auto", "hackrf", "caribou"),
                   default=default,
                   help=f"which radio to use (default {default}"
                        + ("; auto prefers a HackRF and falls back to a "
                           "CaribouLite)" if default == "auto" else ")"))
    p.add_argument("--cb-channel", choices=("auto",) + CARIBOU_CHANNELS,
                   default="auto",
                   help="CaribouLite radio: s1g (389.5-510 and 779-1020 MHz, "
                        "direct conversion) or hif (everything else, through "
                        "the mixer).  Default auto picks s1g where it reaches")
    if tx:
        p.add_argument("--cb-tx-gain", type=int, default=50,
                       metavar="DB",
                       help=f"CaribouLite transmit gain 0-{CARIBOU_GAIN_MAX} "
                            f"(default 50)")
        p.add_argument("--cb-tx-test", default=None, metavar="PATH",
                       help="path to tx_test, which is built rather than "
                            "packaged; defaults to $RFLINK_TX_TEST, then the "
                            "usual build locations")
    if rx:
        p.add_argument("--cb-gain", default="agc", metavar="DB",
                       help=f"CaribouLite receive gain 0-{CARIBOU_GAIN_MAX} "
                            f"dB, or 'agc' for the modem's own (default agc)")
        p.add_argument("--open-timeout", type=float, default=20.0,
                       help="seconds to wait for the first samples; a "
                            "CaribouLite calibrates its modem before it "
                            "streams (default 20)")


def add_link_opts(p, tx=False, rx=False, hackrf_rx=False,
                  rate=DEFAULT_RATE, sps=DEFAULT_SPS):
    p.add_argument("--freq", type=freq_arg, default=DEFAULT_FREQ,
                   help="centre frequency, e.g. 915M or 433.92M (default 915M)")
    p.add_argument("--sample-rate", type=freq_arg, default=rate,
                   help=f"sample rate (default {rate/1e6:g}M)")
    p.add_argument("--sps", type=int, default=sps,
                   help=f"samples per symbol; the symbol rate is rate/sps and "
                        f"is what the two ends must agree on (default {sps}, "
                        f"so {rate/sps/1e3:g} kbaud)")
    p.add_argument("--deviation", type=freq_arg, default=None,
                   help="FSK deviation in Hz (default: half the symbol rate)")
    p.add_argument("--if-offset", type=freq_arg, default=None,
                   help="baseband offset keeping the signal off the LO spur "
                        "(default 300k, or 15%% of the sample rate below "
                        "2 Msps so the sidebands stay inside the band)")
    p.add_argument("--bt", type=float, default=1.0, help="Gaussian BT (default 1.0)")
    p.add_argument("--frame-bytes", type=int, default=DEFAULT_PAYLOAD,
                   help="payload bytes per frame (default 512)")
    if tx:
        p.add_argument("--passes", type=int, default=1,
                       help="send the whole file this many times (default 1)")
        p.add_argument("--gap", type=float, default=0.0005,
                       help="inter-frame gap in seconds (default 0.0005)")
        p.add_argument("--amplitude", type=int, default=110,
                       help="int8 DAC amplitude, 1-127 (default 110)")
        p.add_argument("--tx-gain", type=int, default=30,
                       help="TX VGA gain 0-47 dB (default 30)")
        p.add_argument("--tx-amp", type=int, default=0, choices=(0, 1),
                       help="TX RF amplifier (default 0)")
        p.add_argument("--tx-serial", default=None,
                       help="serial, serial suffix, or board name ('pro', 'one')")
        p.add_argument("--save-iq", default=None,
                       help="keep the generated int8 IQ waveform at this path")
        p.add_argument("--fec", type=int, default=0, metavar="PCT",
                       help="add this percent of Reed-Solomon parity frames, "
                            "counted against the data; any k of the k+m "
                            "frames in a generation rebuild it, so the "
                            "tolerable loss is PCT/(100+PCT) of the "
                            "transmission -- --fec 20 survives 17%% (default "
                            "0, off).  The receiver reads the layout out of "
                            "the frames and needs no matching flag.")
        p.add_argument("--callsign", default=os.environ.get("RFLINK_CALLSIGN"),
                       help="send this station ID at the start, at the end, "
                            "and every 10 minutes, as 47 CFR 97.119 requires "
                            "on amateur allocations; defaults to "
                            "$RFLINK_CALLSIGN")
        p.add_argument("--force-band", action="store_true",
                       help="transmit even in a protected band (cable or "
                            "screen room only)")
    if rx:
        p.add_argument("--threshold", type=float, default=0.60,
                       help="sync correlation threshold 0-1 (default 0.60)")
        p.add_argument("--capture", default=None,
                       help="also write the raw IQ here")
    if hackrf_rx:
        p.add_argument("--rx-lna", type=int, default=32,
                       help="RX LNA gain 0-40 dB in 8 dB steps (default 32)")
        p.add_argument("--rx-vga", type=int, default=24,
                       help="RX VGA gain 0-62 dB in 2 dB steps (default 24)")
        p.add_argument("--rx-amp", type=int, default=0, choices=(0, 1),
                       help="RX RF amplifier (default 0)")
        p.add_argument("--rx-serial", default=None,
                       help="serial, serial suffix, or board name ('pro', 'one')")


def add_out_opts(p):
    p.add_argument("-o", "--outdir", default=".", help="where to write the file")
    p.add_argument("--force", action="store_true", help="overwrite an existing file")


def main(argv=None):
    ap = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = ap.add_subparsers(dest="cmd", required=True)

    p = sub.add_parser("devices",
                       help="list attached HackRF, CaribouLite and RTL-SDR radios")
    p.set_defaults(func=cmd_devices)

    p = sub.add_parser("send", help="transmit a file")
    p.add_argument("file")
    add_link_opts(p, tx=True)
    add_radio_opts(p, tx=True)
    p.set_defaults(func=cmd_send)

    p = sub.add_parser("recv", help="listen and reassemble a file")
    add_out_opts(p)
    add_link_opts(p, rx=True, hackrf_rx=True)
    add_radio_opts(p, rx=True)
    p.add_argument("--timeout", type=float, default=600,
                   help="give up after this many seconds (default 600)")
    p.set_defaults(func=cmd_recv)

    p = sub.add_parser("loopback", help="transmit on one radio, receive on the other")
    p.add_argument("file")
    add_out_opts(p)
    add_link_opts(p, tx=True, rx=True, hackrf_rx=True)
    add_radio_opts(p, tx=True, rx=True)
    p.add_argument("--tx-radio", choices=("auto", "hackrf", "caribou"),
                   default=None,
                   help="override --radio for the transmitting end")
    p.add_argument("--rx-radio", choices=("auto", "hackrf", "caribou"),
                   default=None,
                   help="override --radio for the receiving end")
    p.add_argument("--settle", type=float, default=0.6,
                   help="seconds to let the receiver settle first (default 0.6)")
    p.add_argument("--linger", type=float, default=2.0,
                   help="seconds to keep receiving after TX ends (default 2.0)")
    p.set_defaults(func=cmd_loopback)

    p = sub.add_parser("modulate", help="write the waveform to an IQ file")
    p.add_argument("file")
    p.add_argument("-o", "--out", required=True)
    add_link_opts(p, tx=True)
    # No hardware is touched, so this one defaults to a concrete radio rather
    # than enumerating: it only decides int8 vs int16 and whether to conjugate.
    add_radio_opts(p, default="hackrf", tx=True)
    p.set_defaults(func=cmd_modulate)

    p = sub.add_parser("cbstream",
                       help="(internal) stream CaribouLite IQ to stdout")
    p.add_argument("--freq", type=freq_arg, default=DEFAULT_FREQ)
    p.add_argument("--sample-rate", type=freq_arg, default=DEFAULT_RATE)
    p.add_argument("--cb-channel", choices=CARIBOU_CHANNELS, default="s1g")
    p.add_argument("--cb-gain", default="agc")
    p.add_argument("--cb-conjugate", action="store_true")
    p.set_defaults(func=cmd_cbstream, rate_floor=1)

    p = sub.add_parser("demod", help="recover a file from a captured IQ file")
    p.add_argument("iqfile")
    add_out_opts(p)
    add_link_opts(p, rx=True)
    p.add_argument("--format", choices=("s8", "u8"), default="s8",
                   help="s8 for a HackRF capture, u8 for an rtl_sdr one "
                        "(default s8)")
    p.set_defaults(func=cmd_demod, rate_floor=1)

    p = sub.add_parser("rtl", help="receive with an RTL-SDR (receive only)")
    add_out_opts(p)
    add_link_opts(p, rx=True, rate=RTL_RATE_SAFE, sps=24)
    p.add_argument("--gain", default="0",
                   help="tuner gain in dB, or 0 for the dongle's AGC "
                        "(default 0)")
    p.add_argument("--ppm", type=int, default=0,
                   help="crystal error correction in ppm (default 0; the link "
                        "tolerates a long way past this on its own)")
    p.add_argument("--rtl-device", default=None,
                   help="device index or serial (default: the first one)")
    p.add_argument("--timeout", type=float, default=600,
                   help="give up after this many seconds (default 600)")
    p.set_defaults(func=cmd_rtl, rate_floor=1)

    p = sub.add_parser("selftest", help="modulate, impair and demodulate in software")
    add_link_opts(p, tx=True)
    p.add_argument("--bytes", type=int, default=20000, help="test payload size")
    p.add_argument("--rx-rate", type=freq_arg, default=None,
                   help="demodulate at this sample rate instead of the "
                        "transmitter's, e.g. 2.4M for an RTL-SDR")
    p.add_argument("--rx-sps", type=int, default=None,
                   help="samples per symbol at --rx-rate; the symbol rate "
                        "must come out the same as the transmitter's")
    p.add_argument("--rx-format", choices=("s8", "u8"), default="s8",
                   help="u8 models an RTL-SDR's offset-binary output")
    p.add_argument("--drop", type=float, default=0.0, metavar="PCT",
                   help="blank this percent of transmitted frames, as burst "
                        "interference would")
    p.add_argument("--snr", type=float, default=12.0, help="in-band SNR in dB")
    p.add_argument("--cfo", type=freq_arg, default=18_000,
                   help="carrier offset in Hz (default 18k ~ 20 ppm at 915 MHz)")
    p.add_argument("--ppm", type=float, default=20.0, help="sample-clock error")
    p.add_argument("--seed", type=int, default=1)
    p.add_argument("--threshold", type=float, default=0.60)
    # Nothing here touches a radio, so no radio's sample-rate floor applies.
    p.set_defaults(func=cmd_selftest, rate_floor=1)

    try:
        sys.stdout.reconfigure(line_buffering=True)
    except (AttributeError, ValueError):
        pass
    args = ap.parse_args(argv)
    # Only the commands that actually drive a HackRF are bound by its floor,
    # and only while they might still be driving one: once --radio names a
    # CaribouLite the limits are that board's, and check_rate() applies them.
    floor = getattr(args, "rate_floor", 2_000_000)
    if getattr(args, "radio", None) in ("caribou", "auto"):
        floor = 1
    if getattr(args, "sample_rate", DEFAULT_RATE) < floor:
        sys.exit(f"hackrf_transfer supports 2-20 Msps; --sample-rate "
                 f"{args.sample_rate/1e6:g}M is too low")
    if not 0 <= getattr(args, "fec", 0) <= 100:
        sys.exit("--fec takes a percentage from 0 to 100")
    return args.func(args) or 0


if __name__ == "__main__":
    sys.exit(main())
