lrfhss 1.0.0__tar.gz

lrfhss-1.0.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-09
+
+First public release.
+
+- Blind LR-FHSS receiver: decodes all six EU868 and US915 LR-FHSS data rates
+  (DR8 to DR11, DR5 and DR6) without knowing a packet's timing, carrier
+  frequency or hopping sequence.
+- Standard-compliant encoder that reuses the receiver's trellis, CRC,
+  whitening and interleaver.
+- Live reception from an SDR through SoapySDR (`lrfhss.sdr`).
+- Optional C++ core (`lrfhss._viterbi_ext`), bit-exact with the numpy
+  implementation, shipped in the binary wheels.
+
+[Unreleased]: https://github.com/ShayanMajumder/LR-FHSS/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/ShayanMajumder/LR-FHSS/releases/tag/v1.0.0

lrfhss-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shayan Majumder <shayan.majumder2@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lrfhss-1.0.0/MANIFEST.in

@@ -0,0 +1,11 @@
+# The sdist must carry everything needed to compile lrfhss._viterbi_ext:
+# setuptools picks up the .cpp sources listed in setup.py, but not the
+# headers and lookup tables they include.
+graft src
+include CHANGELOG.md
+
+# Tests and the one recording they read, so the sdist can be verified.
+include tests/*.py
+include examples/data/capture_39kHz_hdr3.wav
+
+global-exclude *.so *.pyd *.o *.obj *.py[cod] __pycache__

lrfhss-1.0.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: lrfhss
+Version: 1.0.0
+Summary: Blind LR-FHSS receiver and encoder: detects, synchronises and decodes LR-FHSS packets from raw IQ
+Author-email: Shayan Majumder <shayan.majumder2@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ShayanMajumder/LR-FHSS
+Project-URL: Source, https://github.com/ShayanMajumder/LR-FHSS
+Project-URL: Issues, https://github.com/ShayanMajumder/LR-FHSS/issues
+Project-URL: Changelog, https://github.com/ShayanMajumder/LR-FHSS/blob/main/CHANGELOG.md
+Keywords: LR-FHSS,LoRa,LoRaWAN,SDR,satellite IoT,physical layer,receiver
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.9
+Provides-Extra: plots
+Requires-Dist: matplotlib>=3.5; extra == "plots"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# PyLR-FHSS
+
+[![CI](https://github.com/ShayanMajumder/LR-FHSS/actions/workflows/ci.yml/badge.svg)](https://github.com/ShayanMajumder/LR-FHSS/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/lrfhss)](https://pypi.org/project/lrfhss/)
+[![Python](https://img.shields.io/pypi/pyversions/lrfhss)](https://pypi.org/project/lrfhss/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/ShayanMajumder/LR-FHSS/blob/main/LICENSE)
+
+A blind LR-FHSS receiver. Given raw IQ, it finds packets without being told
+where they are: matched-filter sync search, header decode, then the
+LFSR-predicted hop schedule to gather and decode the payload.
+
+![The bundled recording, decoded](examples/plots/packet_spectrogram.png)
+
+![The same recording at -22 dB SNR, still decoded](examples/plots/packet_SNR_-22.png)
+
+Both are the bundled recording, a real over-the-air packet carrying
+"hello world", decoded and drawn by `examples/decode_recording.py`. Each box
+marks where the receiver found a header replica (red) or a payload fragment
+(cyan).
+
+- **Top: as captured.** Three header replicas, then three payload fragments,
+  each a narrow line on its own hop frequency.
+- **Bottom: buried in noise.** The same capture with white noise added down
+  to -22 dB SNR, so the signal is about 160 times weaker than the noise in a
+  125 kHz reference bandwidth. The packet is invisible, yet the receiver
+  still finds it without being told where to look, locks onto it and decodes
+  the payload with a passing CRC. The boxes land where they did in the clean
+  capture.
+
+Why it survives: each hop is only about 488 Hz wide. Filtering down to one
+hop throws away 99.6% of the noise in 125 kHz, which leaves an SNR of about
++2 dB inside the hop. The header is sent three times and the copies are
+combined, and the payload is protected by convolutional coding and a CRC.
+For comparison, LoRa's most robust setting, SF12, is specified down to
+-20 dB SNR.
+
+-22 dB is near this packet's limit, so whether it decodes depends on the
+noise draw. To try it, set `SNR_DB` and `NOISE_SEED` at the top of the
+script.
+
+## Install
+
+Python 3.10+:
+
+```bash
+pip install lrfhss            # or "lrfhss[plots]" for the spectrogram plots
+```
+
+Wheels for Linux, macOS and Windows include the compiled core
+(`lrfhss._viterbi_ext`), which the hot paths use automatically. To work on
+the code instead, install from a clone, which needs a C++ compiler:
+
+```bash
+git clone https://github.com/ShayanMajumder/LR-FHSS.git
+cd LR-FHSS
+python3 -m venv venv
+source venv/bin/activate
+pip install -e ".[test]"      # add ",plots" for matplotlib
+```
+
+The compiled core is an accelerator, not a requirement: if it cannot be
+built, the install still succeeds and everything runs on numpy, bit-for-bit
+identical, just several times slower (`LRFHSS_NO_EXT=1` skips the build on
+purpose). The fallback is silent, so to check:
+
+```bash
+python3 -c "import lrfhss; print(lrfhss.config._HAVE_VEXT_LOCAL)"
+```
+
+Live SDR reception additionally needs SoapySDR, which is a system package
+rather than a pip one -- see [`examples/arduino/`](https://github.com/ShayanMajumder/LR-FHSS/tree/main/examples/arduino) and
+`examples/live_receive.py`.
+
+## Decode a capture
+
+```python
+import lrfhss
+
+lrfhss.config.retune(722_660, sync_word='12AD101B', hdr_count=4)
+
+for packet in lrfhss.decode('capture.wav'):
+    if packet['crc']:
+        print(bytes(packet['bytes']))
+```
+
+Two things the receiver cannot work out for itself:
+
+- **bandwidth**, which sets the sample rate, symbol length and dwell times.
+- **`hdr_count`**, the number of header replicas (1-4). It is not carried in
+  the header, and a wrong value puts the payload window a whole dwell out.
+
+Grid and coding rate *are* in the header, so they are not settings. For
+standards-compliant traffic, `retune_dr(8)` or `retune_dr(5, region='US915')`
+sets everything at once, replica count included.
+
+`decode()` returns every candidate it considered; `packet['crc']` is the
+accept gate. The rejects come back too, because they are what you need when
+a capture will not decode.
+
+## Generate a packet
+
+```python
+iq, meta = lrfhss.encode(b'hello world', dr=8)
+iq, meta = lrfhss.encode(b'hello world', bw_khz=722.66, CR=0)
+```
+
+The encoder reuses the decoder's own trellis, CRC, whitening and interleaver,
+so the two are compatible by construction.
+
+## Examples
+
+```bash
+python3 examples/decode_recording.py   # the bundled recording, no setup
+python3 examples/encode.py             # generate a packet and decode it back
+python3 examples/live_receive.py       # decode off an SDR, live
+```
+
+Each is a flat script: edit the settings block at the top and run it.
+[`examples/arduino/`](https://github.com/ShayanMajumder/LR-FHSS/tree/main/examples/arduino) has two transmitter sketches, for an
+STM32 with an SX1262 or an LR1120, to give `live_receive.py` something to
+hear.
+
+## Tests
+
+```bash
+pytest              # 99 tests, ~45 s
+```
+
+Self-contained: nothing is skipped and nothing needs external data. CI runs
+them on Linux, macOS and Windows for every push and pull request.
+
+## Layout
+
+```
+lrfhss/
+  config       every retunable parameter, retune(), DR tables
+  frontend     decimating channeliser        dsp        filters, notching
+  detect       matched filter, CFAR, sync    header     header decode, CFO
+  payload      payload window and decode     quality    energy/length checks
+  acquire      IQ + candidates               arbitrate  which are real packets
+  pipeline     decode() -- orders the above  encoder    encode()
+  sdr          LiveReceiver (optional)       plotting   spectrograms
+  phy/         hopping, fec, gmsk, framing -- protocol primitives
+src/           C++ core, one file per role
+examples/      runnable scripts
+```
+
+`arbitrate` is the one to read first if you are changing behaviour: one
+physical packet appears as several candidates, and deciding which are real is
+where this receiver has historically gone wrong.
+
+## Collaboration and support
+
+Open to collaborations :) If you would like some personal support replicating
+these results, let me know: [shayan.majumder2@gmail.com](mailto:shayan.majumder2@gmail.com).
+
+## Acknowledgements
+
+Thanks to the [Microwaves and Engineering group](https://microwaves.site.hw.ac.uk/)
+at Heriot-Watt University for supporting this work, and to
+[jumanamirza/LR-FHSS-receiver](https://github.com/jumanamirza/LR-FHSS-receiver) for making her work open source.
+
+## License
+
+MIT, see [LICENSE](https://github.com/ShayanMajumder/LR-FHSS/blob/main/LICENSE).
+
+Shayan Majumder <shayan.majumder2@gmail.com>

lrfhss-1.0.0/README.md

@@ -0,0 +1,167 @@
+# PyLR-FHSS
+
+[![CI](https://github.com/ShayanMajumder/LR-FHSS/actions/workflows/ci.yml/badge.svg)](https://github.com/ShayanMajumder/LR-FHSS/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/lrfhss)](https://pypi.org/project/lrfhss/)
+[![Python](https://img.shields.io/pypi/pyversions/lrfhss)](https://pypi.org/project/lrfhss/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/ShayanMajumder/LR-FHSS/blob/main/LICENSE)
+
+A blind LR-FHSS receiver. Given raw IQ, it finds packets without being told
+where they are: matched-filter sync search, header decode, then the
+LFSR-predicted hop schedule to gather and decode the payload.
+
+![The bundled recording, decoded](examples/plots/packet_spectrogram.png)
+
+![The same recording at -22 dB SNR, still decoded](examples/plots/packet_SNR_-22.png)
+
+Both are the bundled recording, a real over-the-air packet carrying
+"hello world", decoded and drawn by `examples/decode_recording.py`. Each box
+marks where the receiver found a header replica (red) or a payload fragment
+(cyan).
+
+- **Top: as captured.** Three header replicas, then three payload fragments,
+  each a narrow line on its own hop frequency.
+- **Bottom: buried in noise.** The same capture with white noise added down
+  to -22 dB SNR, so the signal is about 160 times weaker than the noise in a
+  125 kHz reference bandwidth. The packet is invisible, yet the receiver
+  still finds it without being told where to look, locks onto it and decodes
+  the payload with a passing CRC. The boxes land where they did in the clean
+  capture.
+
+Why it survives: each hop is only about 488 Hz wide. Filtering down to one
+hop throws away 99.6% of the noise in 125 kHz, which leaves an SNR of about
++2 dB inside the hop. The header is sent three times and the copies are
+combined, and the payload is protected by convolutional coding and a CRC.
+For comparison, LoRa's most robust setting, SF12, is specified down to
+-20 dB SNR.
+
+-22 dB is near this packet's limit, so whether it decodes depends on the
+noise draw. To try it, set `SNR_DB` and `NOISE_SEED` at the top of the
+script.
+
+## Install
+
+Python 3.10+:
+
+```bash
+pip install lrfhss            # or "lrfhss[plots]" for the spectrogram plots
+```
+
+Wheels for Linux, macOS and Windows include the compiled core
+(`lrfhss._viterbi_ext`), which the hot paths use automatically. To work on
+the code instead, install from a clone, which needs a C++ compiler:
+
+```bash
+git clone https://github.com/ShayanMajumder/LR-FHSS.git
+cd LR-FHSS
+python3 -m venv venv
+source venv/bin/activate
+pip install -e ".[test]"      # add ",plots" for matplotlib
+```
+
+The compiled core is an accelerator, not a requirement: if it cannot be
+built, the install still succeeds and everything runs on numpy, bit-for-bit
+identical, just several times slower (`LRFHSS_NO_EXT=1` skips the build on
+purpose). The fallback is silent, so to check:
+
+```bash
+python3 -c "import lrfhss; print(lrfhss.config._HAVE_VEXT_LOCAL)"
+```
+
+Live SDR reception additionally needs SoapySDR, which is a system package
+rather than a pip one -- see [`examples/arduino/`](https://github.com/ShayanMajumder/LR-FHSS/tree/main/examples/arduino) and
+`examples/live_receive.py`.
+
+## Decode a capture
+
+```python
+import lrfhss
+
+lrfhss.config.retune(722_660, sync_word='12AD101B', hdr_count=4)
+
+for packet in lrfhss.decode('capture.wav'):
+    if packet['crc']:
+        print(bytes(packet['bytes']))
+```
+
+Two things the receiver cannot work out for itself:
+
+- **bandwidth**, which sets the sample rate, symbol length and dwell times.
+- **`hdr_count`**, the number of header replicas (1-4). It is not carried in
+  the header, and a wrong value puts the payload window a whole dwell out.
+
+Grid and coding rate *are* in the header, so they are not settings. For
+standards-compliant traffic, `retune_dr(8)` or `retune_dr(5, region='US915')`
+sets everything at once, replica count included.
+
+`decode()` returns every candidate it considered; `packet['crc']` is the
+accept gate. The rejects come back too, because they are what you need when
+a capture will not decode.
+
+## Generate a packet
+
+```python
+iq, meta = lrfhss.encode(b'hello world', dr=8)
+iq, meta = lrfhss.encode(b'hello world', bw_khz=722.66, CR=0)
+```
+
+The encoder reuses the decoder's own trellis, CRC, whitening and interleaver,
+so the two are compatible by construction.
+
+## Examples
+
+```bash
+python3 examples/decode_recording.py   # the bundled recording, no setup
+python3 examples/encode.py             # generate a packet and decode it back
+python3 examples/live_receive.py       # decode off an SDR, live
+```
+
+Each is a flat script: edit the settings block at the top and run it.
+[`examples/arduino/`](https://github.com/ShayanMajumder/LR-FHSS/tree/main/examples/arduino) has two transmitter sketches, for an
+STM32 with an SX1262 or an LR1120, to give `live_receive.py` something to
+hear.
+
+## Tests
+
+```bash
+pytest              # 99 tests, ~45 s
+```
+
+Self-contained: nothing is skipped and nothing needs external data. CI runs
+them on Linux, macOS and Windows for every push and pull request.
+
+## Layout
+
+```
+lrfhss/
+  config       every retunable parameter, retune(), DR tables
+  frontend     decimating channeliser        dsp        filters, notching
+  detect       matched filter, CFAR, sync    header     header decode, CFO
+  payload      payload window and decode     quality    energy/length checks
+  acquire      IQ + candidates               arbitrate  which are real packets
+  pipeline     decode() -- orders the above  encoder    encode()
+  sdr          LiveReceiver (optional)       plotting   spectrograms
+  phy/         hopping, fec, gmsk, framing -- protocol primitives
+src/           C++ core, one file per role
+examples/      runnable scripts
+```
+
+`arbitrate` is the one to read first if you are changing behaviour: one
+physical packet appears as several candidates, and deciding which are real is
+where this receiver has historically gone wrong.
+
+## Collaboration and support
+
+Open to collaborations :) If you would like some personal support replicating
+these results, let me know: [shayan.majumder2@gmail.com](mailto:shayan.majumder2@gmail.com).
+
+## Acknowledgements
+
+Thanks to the [Microwaves and Engineering group](https://microwaves.site.hw.ac.uk/)
+at Heriot-Watt University for supporting this work, and to
+[jumanamirza/LR-FHSS-receiver](https://github.com/jumanamirza/LR-FHSS-receiver) for making her work open source.
+
+## License
+
+MIT, see [LICENSE](https://github.com/ShayanMajumder/LR-FHSS/blob/main/LICENSE).
+
+Shayan Majumder <shayan.majumder2@gmail.com>

lrfhss-1.0.0/lrfhss/__init__.py

@@ -0,0 +1,31 @@
+# Copyright (c) 2026 Shayan Majumder <shayan.majumder2@gmail.com>
+# SPDX-License-Identifier: MIT
+"""LR-FHSS blind receiver."""
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version('lrfhss')
+except PackageNotFoundError:     # a source tree that was never pip-installed
+    __version__ = '0.0.0+unknown'
+
+from . import config
+from .config import datarate, retune_dr
+from .detect import find_packets, find_packets_windowed
+from .encoder import encode, encode_packet, payload_fragments
+from .frontend import load_frontend, load_frontend_windowed
+from .header import decode_header_at
+from .payload import decode_payload_at
+from .pipeline import DecodeOptions, decode
+from .plotting import plot_packet_spectrogram
+from .quality import check_energy_length
+
+__all__ = [
+    'config', 'datarate', 'retune_dr',
+    'decode', 'DecodeOptions',
+    'encode', 'encode_packet', 'payload_fragments',
+    'load_frontend', 'load_frontend_windowed',
+    'find_packets', 'find_packets_windowed',
+    'decode_header_at', 'decode_payload_at',
+    'check_energy_length',
+    'plot_packet_spectrogram',
+]

lrfhss-1.0.0/lrfhss/acquire.py

@@ -0,0 +1,84 @@
+# Copyright (c) 2026 Shayan Majumder <shayan.majumder2@gmail.com>
+# SPDX-License-Identifier: MIT
+"""Getting IQ and sync-word candidates out of a capture."""
+import numpy as np
+
+from . import config as cfg
+from . import report
+from .detect import (_fine_sync, find_packets, find_packets_windowed,
+                     find_packets_streaming_interleaved)
+from .dsp import notch_spurs
+from .frontend import load_frontend
+from .header import _sync_carrier, decode_header_at, header_fft_peak
+
+
+def detect(iq, windowed_scan=False, window_sec=0.1, hop_sec=0.05):
+    """Sync-word candidates from IQ already in memory."""
+    report.scanning(windowed_scan, window_sec, hop_sec)
+    if windowed_scan:
+        return find_packets_windowed(iq, window_sec=window_sec, hop_sec=hop_sec)
+    return find_packets(iq)
+
+
+def load_and_detect(fn, windowed_scan=False, window_sec=0.1, hop_sec=0.05):
+    """Read the capture through the front end, then scan it."""
+    report.loading()
+    iq = load_frontend(fn)
+    report.loaded(len(iq))
+    iq = notch_spurs(iq, cfg.SPUR_FREQS)
+    return iq, detect(iq, windowed_scan, window_sec, hop_sec)
+
+
+def can_stream(fn, windowed_scan):
+    """Whether the interleaved path applies."""
+    return windowed_scan and str(fn).lower().endswith('.wav')
+
+
+def stream_interleaved(fn, acquire, decide, max_packets=20,
+                       window_sec=0.1, hop_sec=0.05):
+    """Detect and decode window by window, overlapping the two."""
+    report.streaming(window_sec, hop_sec)
+    results = []
+    confirmed_footprints = []
+    n_sync = 0
+    grown = [None]
+    chunks = []
+
+    def on_chunk(chunk):
+        chunks.append(chunk)
+        grown[0] = np.concatenate(chunks)
+
+    def on_window(w_start, w_buf, w_hits, iq_prefix_len):
+        nonlocal n_sync
+        for _score, t_local, hf in sorted(w_hits, reverse=True):
+            if len(results) >= max_packets:
+                return
+            t_global = w_start + t_local
+            if any(lo <= t_global <= hi for lo, hi, _ in confirmed_footprints):
+                continue
+            iq = grown[0]
+            acq = acquire(iq, t_global, hf)
+            n_sync += 1
+            entry = decide(iq, acq, results)
+            if entry is not None and entry['crc'] and entry['footprint'] is not None:
+                confirmed_footprints.append(entry['footprint'])
+
+    find_packets_streaming_interleaved(fn, window_sec=window_sec, hop_sec=hop_sec,
+                                       on_chunk=on_chunk, on_window=on_window)
+    return grown[0], results, n_sync
+
+
+def acquire_one(iq, t0, hf):
+    """Refine one candidate: fine sync, then decode its header."""
+    fcorr, fhf, fstart, fcfo = _fine_sync(iq, int(t0), int(hf))
+    win = fstart - cfg.SYNC_START_BIT*cfg.SMBL
+    ws = win if win >= 0 else fstart
+    f0 = header_fft_peak(iq[ws:ws + cfg.HDR_BIT_NUM*cfg.SMBL + 4*cfg.SMBL], fhf)
+    est = _sync_carrier(iq, win, f0 - 400, f0 + 400)
+    sync_q = est[2] if est is not None else float('inf')   # can't check: don't skip
+    if sync_q < cfg.SYNC_SKIP_Q:
+        return dict(t0=t0, hf=hf, fcorr=fcorr, fhf=fhf, fstart=fstart, fcfo=fcfo,
+                    hdr=None, hwin=win, hf_precise=fhf, sync_q=sync_q)
+    hdr, soft, hwin, hf_precise = decode_header_at(iq, fhf, fstart, fcfo)
+    return dict(t0=t0, hf=hf, fcorr=fcorr, fhf=fhf, fstart=fstart, fcfo=fcfo,
+                hdr=hdr, hwin=hwin, hf_precise=hf_precise, sync_q=sync_q)

lrfhss-1.0.0/lrfhss/arbitrate.py

@@ -0,0 +1,123 @@
+# Copyright (c) 2026 Shayan Majumder <shayan.majumder2@gmail.com>
+# SPDX-License-Identifier: MIT
+"""Deciding which sync candidates are real packets."""
+import os
+
+from . import config as cfg
+from . import report
+from .payload import _packet_footprint, _packet_slots, decode_payload_at
+from .plotting import plot_packet_spectrogram
+from .quality import check_energy_length, packet_snr_db
+
+
+def find_duplicate(results, t0):
+    """The already-confirmed packet this candidate is a replica of, if any."""
+    for prev in results:
+        if not prev['crc']:
+            continue
+        if abs(t0 - prev['t0']) < cfg.STAY_HDR*cfg.HDR_COUNT:
+            return prev
+    return None
+
+
+class ClusterPruner:
+    """Tracks, per cluster, what has been submitted / decoded / retired."""
+
+    def __init__(self, n):
+        self.submitted = [False]*n
+        self.decoded = [False]*n
+        self.retired = [False]*n
+
+    def next_batch(self, order, start, size):
+        """The next `size` not-yet-submitted clusters, in `order`."""
+        batch, j = [], start
+        while j < len(order) and len(batch) < size:
+            ci = order[j]
+            if not self.submitted[ci]:
+                batch.append(ci)
+            j += 1
+        return batch, j
+
+    def mark_submitted(self, batch):
+        for ci in batch:
+            self.submitted[ci] = True
+
+    def retire_predicted(self, clusters, footprint, keep):
+        """Retire clusters the confirmed packet's hop schedule accounts for."""
+        t_lo, t_hi, freqs = footprint
+        gone = []
+        for cj in range(len(clusters)):
+            if cj == keep or self.decoded[cj] or self.retired[cj]:
+                continue
+            _, tj, fj = clusters[cj]
+            if t_lo <= tj <= t_hi and any(abs(fj-p) < 1500 for p in freqs):
+                self.submitted[cj] = True
+                self.retired[cj] = True
+                gone.append(cj)
+        return gone
+
+    def restore(self, clusters_idx):
+        """Undo a retirement: the candidate that caused it failed its
+        payload, so its siblings -- other locks on the same packet, often
+        better aligned in time -- still deserve their turn.
+        """
+        for cj in clusters_idx:
+            self.retired[cj] = False
+            self.submitted[cj] = False
+
+
+def _header_matches_known_config(hdr):
+    return not (hdr['CR'] != cfg.KNOWN_CR or hdr['grid'] != cfg.KNOWN_GRID
+                or hdr['hop'] != cfg.KNOWN_HOP or hdr['BW'] != cfg.KNOWN_BW
+                or int(''.join(map(str, hdr['hopseq'])), 2) != cfg.KNOWN_HOPSEQ)
+
+
+def evaluate(iq, acq, results, clusters=None, pruner=None, ci=None,
+             plot_spectrograms=False, plot_dir='.'):
+    """Decide one acquired candidate, decoding its payload if it survives."""
+    hdr = acq['hdr']
+    if hdr is None:
+        return None
+
+    dup_of = find_duplicate(results, acq['fstart'])
+    if dup_of is not None:
+        report.duplicate(acq['fstart'], acq['fhf'], dup_of['t0'])
+        return None
+
+    length_ok, pwr_snr = check_energy_length(iq, acq['hwin'], hdr)
+    if not length_ok:
+        report.ghost(pwr_snr)
+        return None
+    report.snr(pwr_snr)
+    report.candidate(acq['fstart'], acq['fhf'], acq['fcorr'], hdr)
+
+    footprint = _packet_footprint(hdr, acq['hwin'], acq['hf_precise'])
+    retired_now = []
+    if footprint is not None and pruner is not None and clusters is not None:
+        retired_now = pruner.retire_predicted(clusters, footprint, ci)
+        report.retired(len(retired_now))
+
+    payload_bytes, crc_ok = decode_payload_at(iq, hdr, acq['hwin'], acq['hf_precise'])
+    report.payload(crc_ok, payload_bytes)
+    if not crc_ok and retired_now:
+        pruner.restore(retired_now)
+
+    if crc_ok:
+        if not _header_matches_known_config(hdr):
+            report.config_mismatch()
+        if plot_spectrograms:
+            os.makedirs(plot_dir, exist_ok=True)
+            png = os.path.join(plot_dir, 'packet_t%.3fs.png' % (acq['fstart']/cfg.FS))
+            saved = plot_packet_spectrogram(iq, hdr, acq['hwin'], acq['hf_precise'], png)
+            if saved:
+                report.plot_written(saved)
+
+    snr_db = slots = None
+    if crc_ok:
+        slots = _packet_slots(iq, hdr, acq['hwin'], acq['hf_precise'])
+        snr_db = packet_snr_db(iq, slots) if slots else None
+    entry = dict(idx=len(results), t0=acq['fstart'], corr=acq['fcorr'],
+                 header=hdr, bytes=payload_bytes, crc=crc_ok, footprint=footprint,
+                 snr_db=snr_db, slots=slots)
+    results.append(entry)
+    return entry