hackrfpy 1.0.0__py3-none-any.whl

hackrfpy/__init__.py

@@ -0,0 +1,19 @@
+#! /usr/bin/python3
+##--------------------------------------------------------------------\
+#   hackrfpy  'src/hackrfpy/__init__.py'
+#   Public API surface.
+##--------------------------------------------------------------------\
+from .core import HackRF, load_iq, parse_freq
+from .sigmf import write_sigmf_meta, read_sigmf_meta
+from .exceptions import (
+    HackRFError, HackRFValueError, HackRFModeError,
+    HackRFDeviceError, HackRFEnvironmentError,
+)
+from . import constants
+
+__all__ = [
+    "HackRF", "load_iq", "parse_freq", "constants",
+    "write_sigmf_meta", "read_sigmf_meta",
+    "HackRFError", "HackRFValueError", "HackRFModeError",
+    "HackRFDeviceError", "HackRFEnvironmentError",
+]

hackrfpy/_commands/capture.py

@@ -0,0 +1,282 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/_commands/capture.py'
+#
+#   CaptureMixin: receive via hackrf_transfer -r. Exercises all consumption
+#   modes and the IQ-path choice:
+#       - num_samples  -> bounded (default), mode="blocking"
+#       - duration     -> timed, mode="timed"
+#       - neither      -> open-ended handle, mode="handle" (.stop() to end)
+#       - to_stdout    -> '-r -' streamed + decoded in-Python (live path)
+#       - segment_secs -> rolling files (capture lifecycle the CLI binary lacks)
+#
+#   Mixin only; assumes _run, validate_rx, estimate_capture, decode_iq,
+#   _auto_baseband, require_mode, print_message on the host class.
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+import os
+
+from .. import constants as C
+from ..sigmf import write_sigmf_meta
+
+
+class CaptureMixin:
+    def capture(self, freq, sample_rate, *, out="capture.iq",
+                num_samples=None, duration=None,
+                lna=16, vga=20, amp=False, bias_tee=False,
+                baseband_bw=None, to_stdout=False, sigmf=True,
+                segment_secs=None, print_cmd=False):
+        self.require_mode(C.MODE_RX)
+        freq, sample_rate, lna, vga = self.validate_rx(freq, sample_rate, lna, vga)
+        bw = self._auto_baseband(sample_rate, baseband_bw)
+        self._record_params(freq=freq, sample_rate=sample_rate, lna=lna,
+                            vga=vga, amp=amp, baseband_bw=bw, mode="rx")
+        self.print_message(f"[*] mode: {self.mode}")
+
+        # segmented capture is its own lifecycle path
+        if segment_secs:
+            return self._capture_segmented(
+                freq, sample_rate, out, segment_secs, lna, vga, amp,
+                bias_tee, bw, sigmf, print_cmd)
+
+        target = "-" if to_stdout else out
+        argv = self._rx_argv(freq, sample_rate, target, lna, vga, amp,
+                             bias_tee, bw, num_samples)
+
+        if to_stdout:
+            if print_cmd:
+                self._run(argv, mode="blocking", print_cmd=True)
+                return None
+            # live path: stream raw IQ chunks, decode to complex64 as we go.
+            # An odd-length chunk would split an I/Q pair; dropping the byte
+            # would swap I/Q for everything after, so carry it forward.
+            # The inner stream generator is closed EXPLICITLY on the way out;
+            # leaving it to GC can orphan a receiving hackrf_transfer after
+            # the caller breaks out of the loop.
+            def _gen():
+                tail = b""
+                inner = self._run(argv, mode="stream")
+                try:
+                    for chunk in inner:
+                        buf = tail + chunk
+                        cut = len(buf) - (len(buf) % 2)
+                        buf, tail = buf[:cut], buf[cut:]
+                        if buf:
+                            yield self.decode_iq(buf)
+                finally:
+                    inner.close()
+            return _gen()
+
+        # file path: estimate + guard disk before committing
+        if not print_cmd:
+            est = self.estimate_capture(sample_rate, num_samples, duration,
+                                        os.path.dirname(out) or ".")
+            self.print_message(
+                f"[*] ~{(est['total_bytes'] or 0)/1e6:.1f} MB, "
+                f"{est['bytes_per_sec']/1e6:.1f} MB/s")
+
+        if duration is not None:
+            res = self._run(argv, mode="timed", duration=duration,
+                            print_cmd=print_cmd)
+        elif num_samples is not None:
+            res = self._run(argv, mode="blocking", print_cmd=print_cmd)
+        else:
+            # open-ended: hand back a controller; caller .stop()s it
+            if print_cmd:
+                self._run(argv, mode="blocking", print_cmd=True)
+                return None
+            return self._run(argv, mode="handle")
+
+        if sigmf and not print_cmd:
+            write_sigmf_meta(out, freq, sample_rate, lna=lna, vga=vga,
+                             amp=amp, datatype="ci8")
+        return res
+
+    # ---- aliases ----
+    def rx(self, *a, **k):
+        return self.capture(*a, **k)
+
+    def capture_samples(self, freq, sample_rate, num_samples, **k):
+        return self.capture(freq, sample_rate, num_samples=num_samples, **k)
+
+    def capture_seconds(self, freq, sample_rate, duration, **k):
+        return self.capture(freq, sample_rate, duration=duration, **k)
+
+    def scan_frequencies(self, freqs, sample_rate, num_samples, *,
+                         on_capture=None, **k):
+        # Sequentially capture a fixed sample count at each frequency in
+        # `freqs`, retuning between them. This does NOT close the gapless-
+        # retune gap (each retune is a fresh hackrf_transfer with a short
+        # re-open, since the binary can't retune mid-stream) -- but it makes
+        # the common "look at several frequencies in one pass" workflow a
+        # single call instead of hand-rolled orchestration.
+        #
+        #   results = h.scan_frequencies([433.92e6, 868e6, 915e6], 8e6, 1e6)
+        #   # -> {freq: complex64 array}
+        #
+        # on_capture(freq, iq) is called per frequency if given (e.g. to
+        # process-and-discard instead of holding every array in memory).
+        results = {}
+        for f in freqs:
+            iq = self.capture_array(f, sample_rate, int(num_samples), **k)
+            if on_capture is not None:
+                on_capture(f, iq)
+            else:
+                results[f] = iq
+        return results if on_capture is None else None
+
+    # ---- in-memory + context-managed entry points ----
+    def capture_array(self, freq, sample_rate, num_samples, *,
+                      return_params=False, **k):
+        # Scripting entry point: return EXACTLY num_samples complex64 samples
+        # in RAM, no file. Built on the stdout-stream path so it shares the
+        # odd-byte carry + clean-reap logic. The stream is closed as soon as
+        # we have enough, which interrupts hackrf_transfer promptly.
+        #
+        # return_params=True -> (iq, params) where params is the snapped
+        # last_params dict; default False keeps the bare-ndarray return so the
+        # common case is unchanged.
+        import numpy as np
+        if num_samples is None or num_samples <= 0:
+            from ..exceptions import HackRFValueError
+            raise HackRFValueError("capture_array needs a positive num_samples")
+        k.pop("to_stdout", None)
+        k.pop("out", None)
+        gen = self.capture(freq, sample_rate, to_stdout=True, **k)
+        if gen is None:                       # print_cmd dry run
+            return None
+        blocks, have = [], 0
+        try:
+            for block in gen:
+                blocks.append(block)
+                have += len(block)
+                if have >= num_samples:
+                    break
+        finally:
+            gen.close()                       # reap the child deterministically
+        iq = (np.empty(0, dtype=np.complex64) if not blocks
+              else np.concatenate(blocks)[:num_samples])
+        if return_params:
+            return iq, self.last_params
+        return iq
+
+    def open_receiver(self, freq, sample_rate, *, lna=16, vga=20, amp=False,
+                      baseband_bw=None, read_samples=131072):
+        # Open a PERSISTENT fixed-frequency receiver: one long-lived
+        # hackrf_transfer you drain in segments over time, so you don't pay the
+        # ~1-2 s process spin-up per capture. Use as a context manager:
+        #
+        #   with h.open_receiver(100e6, 8e6) as rx:
+        #       a = rx.read(1_000_000)     # exact sample count
+        #       b = rx.read(1_000_000)     # again, no new process
+        #       for blk in rx.blocks(): ...      # or raw decoded blocks
+        #
+        # FIXED-FREQUENCY by design -- hackrf_transfer can't retune mid-stream.
+        # For multiple frequencies use scan_frequencies (IQ per freq) or
+        # monitor_frequencies (sweep-backed power). The child is reaped on exit
+        # and registered on the atexit backstop.
+        from .._receiver import PersistentReceiver
+        return PersistentReceiver(self, freq, sample_rate, lna=lna, vga=vga,
+                                  amp=amp, baseband_bw=baseband_bw,
+                                  read_samples=read_samples)
+
+    def capture_stream(self, freq, sample_rate, **k):
+        # Context manager wrapping the live stdout stream so the receiving
+        # hackrf_transfer is ALWAYS reaped on exit, even on exception:
+        #     with h.capture_stream(433.92e6, 8e6) as blocks:
+        #         for iq in blocks: ...
+        from .._stream_ctx import StreamCtx
+        k.pop("to_stdout", None)
+        gen = self.capture(freq, sample_rate, to_stdout=True, **k)
+        return StreamCtx(gen)
+
+    def capture_callback(self, freq, sample_rate, on_block, *,
+                         max_samples=None, max_blocks=None, **k):
+        # Binder-style ergonomics over the subprocess stream: instead of the
+        # caller writing the receive loop, register a callback that fires with
+        # each decoded complex64 block as it arrives. This is the usability
+        # analog of libhackrf's rx callback -- same data, same latency as
+        # capture_stream, but the loop is inverted so calling code looks like
+        # the C-binding libraries.
+        #
+        #   def on_block(iq, n_so_far):
+        #       ...                      # return False to stop early
+        #
+        # The child is always reaped on exit (normal, early-stop, or
+        # exception). Stops when on_block returns False, when max_samples /
+        # max_blocks is reached, or when the source ends.
+        from .._stream_ctx import StreamCtx
+        k.pop("to_stdout", None)
+        total = 0
+        blocks = 0
+        with StreamCtx(self.capture(freq, sample_rate, to_stdout=True, **k)) \
+                as gen:
+            for iq in gen:
+                cont = on_block(iq, total)
+                total += len(iq)
+                blocks += 1
+                if cont is False:
+                    break
+                if max_samples is not None and total >= max_samples:
+                    break
+                if max_blocks is not None and blocks >= max_blocks:
+                    break
+        return total
+
+    # ---- internals ----
+    def _rx_argv(self, freq, sample_rate, target, lna, vga, amp, bias_tee,
+                 bw, num_samples):
+        argv = ["transfer", "-r", target,
+                "-f", int(freq), "-s", int(sample_rate),
+                "-l", lna, "-g", vga,
+                "-a", 1 if amp else 0,
+                "-b", int(bw)]
+        if bias_tee:
+            argv += ["-p", 1]
+        if num_samples is not None:
+            argv += ["-n", int(num_samples)]
+        return argv
+
+    def _capture_segmented(self, freq, sample_rate, out, segment_secs, lna,
+                           vga, amp, bias_tee, bw, sigmf, print_cmd):
+        # Rolling files out_000.iq, out_001.iq, ... each `segment_secs` long.
+        # Each segment is a bounded blocking capture, so files are whole.
+        base, ext = os.path.splitext(out)
+        ext = ext or ".iq"
+        n_per = int(sample_rate * segment_secs)
+        idx = 0
+        results = []
+        self.print_message(f"[*] segmented capture: {segment_secs}s per file")
+        # Honest note: each segment is a fresh hackrf_transfer spawn (device
+        # open + retune), so there is a short GAP (~hundreds of ms) of missing
+        # samples between files. Segments are whole, not gapless.
+        self.print_message("[!] note: segments are not gapless "
+                           "(short re-open gap between files)")
+        try:
+            while True:
+                # Disk guard PER SEGMENT: this is the run-indefinitely mode,
+                # so check before each file rather than once up front. Raises
+                # HackRFEnvironmentError when the next segment wouldn't fit
+                # within the headroom, instead of filling the disk.
+                if not print_cmd:
+                    self.estimate_capture(sample_rate, num_samples=n_per,
+                                          path=os.path.dirname(out) or ".")
+                seg = f"{base}_{idx:03d}{ext}"
+                argv = self._rx_argv(freq, sample_rate, seg, lna, vga, amp,
+                                     bias_tee, bw, n_per)
+                res = self._run(argv, mode="blocking", print_cmd=print_cmd)
+                if sigmf and not print_cmd:
+                    write_sigmf_meta(seg, freq, sample_rate, lna=lna, vga=vga,
+                                     amp=amp, datatype="ci8")
+                results.append(seg)
+                idx += 1
+                if print_cmd:
+                    break  # one example command is enough for dry-run
+        except KeyboardInterrupt:
+            # reachable now that _run re-raises after stopping the child
+            self.print_message("[*] segmented capture stopped by user")
+        return results

hackrfpy/_commands/device.py

@@ -0,0 +1,204 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/_commands/device.py'
+#
+#   DeviceMixin: the device-management commands other wrappers tend to drop
+#   (clock, spiflash, operacake, cpldjtag, debug), plus the `doctor` preflight.
+#   spiflash writes firmware and can BRICK the board, so it is heavily guarded:
+#   it refuses unless confirm=True is passed explicitly.
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+import re
+import shutil
+
+from .. import constants as C
+from ..exceptions import HackRFDeviceError, HackRFEnvironmentError, HackRFValueError
+
+
+class DeviceMixin:
+    # ---- clock ----
+    def clock(self, *args, print_cmd=False):
+        argv = ["clock"] + list(args)
+        return self._run(argv, mode="blocking", text=True, print_cmd=print_cmd)
+
+    # ---- operacake antenna switch ----
+    def operacake(self, *args, print_cmd=False):
+        argv = ["operacake"] + list(args)
+        return self._run(argv, mode="blocking", text=True, print_cmd=print_cmd)
+
+    def operacake_list(self):
+        return self.operacake("-l")
+
+    # ---- cpld jtag (CPLD firmware) ----
+    def cpldjtag(self, firmware, *, confirm=False, print_cmd=False):
+        if not confirm and not print_cmd:
+            raise HackRFValueError(
+                "cpldjtag flashes the CPLD and can brick the board. "
+                "Pass confirm=True if you are certain.")
+        return self._run(["cpldjtag", "-x", firmware], mode="blocking",
+                         text=True, print_cmd=print_cmd)
+
+    # ---- spiflash (firmware) ----
+    def spiflash_write(self, firmware, *, confirm=False, print_cmd=False):
+        # Writing firmware. The single most dangerous operation in the library.
+        if not confirm and not print_cmd:
+            raise HackRFValueError(
+                "spiflash_write flashes device firmware and can BRICK the "
+                "board if interrupted or given a bad image. Pass confirm=True "
+                "only with a verified firmware .bin and stable power.")
+        return self._run(["spiflash", "-w", firmware], mode="blocking",
+                         text=True, print_cmd=print_cmd)
+
+    def spiflash_read(self, out, length=None, print_cmd=False):
+        argv = ["spiflash", "-r", out]
+        if length is not None:
+            argv += ["-l", int(length)]
+        return self._run(argv, mode="blocking", text=True, print_cmd=print_cmd)
+
+    def spiflash_reset(self, print_cmd=False):
+        return self._run(["spiflash", "-R"], mode="blocking", text=True,
+                         print_cmd=print_cmd)
+
+    # ---- debug register access ----
+    def debug(self, *args, print_cmd=False):
+        argv = ["debug"] + list(args)
+        return self._run(argv, mode="blocking", text=True, print_cmd=print_cmd)
+
+    # =================================================================
+    # preflight: environment / readiness check
+    # (was 'doctor' -- kept as an alias below for the familiar CLI verb)
+    # =================================================================
+    def preflight(self, capture_path="."):
+        # Checks tooling, board presence, free disk, and reports the active
+        # mode. Returns a structured report; raises only on hard environment
+        # failures the user must fix.
+        report = {"tools": {}, "boards": [], "mode": self.mode,
+                  "tool_version": None, "disk_free_bytes": None,
+                  "features": {}, "problems": []}
+
+        # 1. tools on PATH (or tools_dir). Only the CORE tools (info,
+        #    transfer, sweep) count as problems -- a box without operacake or
+        #    spiflash is perfectly capture-ready, and flagging them broke the
+        #    documented `doctor && capture` exit-code pattern on minimal
+        #    Windows installs that ship only the core binaries.
+        for key, name in C.TOOLS.items():
+            try:
+                report["tools"][name] = self.resolve(key)
+            except HackRFDeviceError:
+                report["tools"][name] = None
+                if key in C.CORE_TOOLS:
+                    report["problems"].append(f"missing core binary: {name}")
+
+        # 2. board enumeration via hackrf_info (only if present)
+        if report["tools"].get(C.TOOLS["info"]):
+            try:
+                out, _, _ = self._run(["info"], mode="blocking", text=True)
+                parsed = self.parse_info(out)
+                report["boards"] = parsed.get("boards", [])
+                # version skew is the main fragility of the subprocess
+                # approach: '-r -' stdout and 'sweep -N' need modern tools.
+                lib = parsed.get("library", {})
+                report["tool_version"] = lib.get("hackrf_info_version")
+                m = re.match(r"(\d{4})", report["tool_version"] or "")
+                if m and int(m.group(1)) < 2021:
+                    report["problems"].append(
+                        f"hackrf-tools {report['tool_version']} predates "
+                        f"2021; '-r -' streaming and 'sweep -N' may be "
+                        f"unsupported -- please upgrade")
+                if not report["boards"]:
+                    report["problems"].append(
+                        "no HackRF board detected (check USB / permissions)")
+            except HackRFDeviceError as e:
+                report["problems"].append(str(e))
+
+        # 2b. feature probe: derive capability flags from the firmware version
+        #     (reliable year) and tools version. See features().
+        fw = None
+        if report["boards"]:
+            fw = report["boards"][0].get("firmware_version")
+        report["features"] = self.features(report.get("tool_version"), fw)
+
+        # 3. disk
+        try:
+            report["disk_free_bytes"] = shutil.disk_usage(capture_path).free
+        except OSError as e:
+            report["problems"].append(f"cannot stat disk at {capture_path}: {e}")
+
+        self._print_preflight(report)
+        return report
+
+    # doctor: familiar alias for preflight (brew/flutter-style verb). The CLI
+    # still exposes `hrf doctor`; the honest method name is preflight().
+    def doctor(self, capture_path="."):
+        return self.preflight(capture_path=capture_path)
+
+    def features(self, tool_version=None, firmware_version=None):
+        # Map version strings -> capability flags. The reliable year signal is
+        # the FIRMWARE version (e.g. "2024.02.1"); the tools version is often a
+        # git tag (e.g. "git-b1dbb47") with no parseable year. If nothing is
+        # passed, probe the device once and use both. Table-driven + pure, so
+        # unit-testable without hardware.
+        if tool_version is None and firmware_version is None:
+            try:
+                parsed = self.parse_info(
+                    self._run(["info"], mode="blocking", text=True)[0])
+                tool_version = (parsed.get("library", {})
+                                .get("hackrf_info_version"))
+                boards = parsed.get("boards", [])
+                if boards:
+                    firmware_version = boards[0].get("firmware_version")
+            except HackRFDeviceError:
+                pass
+
+        # Prefer the firmware version's year; fall back to the tools version.
+        # A "git-" build is a from-source build, which is current by
+        # definition -- treat it as modern rather than merely "unknown".
+        def _year(v):
+            m = re.match(r"(\d{4})", v or "")
+            return int(m.group(1)) if m else None
+
+        year = _year(firmware_version) or _year(tool_version)
+        is_git = ((tool_version or "").startswith("git-")
+                  or (firmware_version or "").startswith("git-"))
+        # known if we have a real year OR it's an identifiable git build
+        known = year is not None or is_git
+        modern = is_git or year is None or year >= 2021
+        return {
+            "tool_version": tool_version,
+            "firmware_version": firmware_version,
+            "version_known": known,
+            "is_git_build": is_git,
+            "stdout_streaming": modern,                    # rx -r - / sweep
+            "sweep_num_sweeps": modern,                    # sweep -N
+            "bias_tee": is_git or year is None or year >= 2018,  # -p
+        }
+
+    def _print_preflight(self, r):
+        print("hackrfpy preflight")
+        print("-" * 40)
+        for name, path in r["tools"].items():
+            print(f"  {'OK ' if path else 'XX '} {name:18} "
+                  f"{path or 'NOT FOUND'}")
+        if r.get("tool_version"):
+            print(f"  tools version   : {r['tool_version']}")
+        feats = r.get("features", {})
+        if feats and not feats.get("stdout_streaming", True):
+            print("  ! stdout streaming (rx -r - / capture_array) unsupported "
+                  "by this tools version")
+        print(f"  boards detected : {len(r['boards'])}")
+        for b in r["boards"]:
+            sn = b.get("serial_number", b.get("serial", "?"))
+            print(f"      - {sn}")
+        if r["disk_free_bytes"] is not None:
+            print(f"  free disk       : {r['disk_free_bytes']/1e9:.1f} GB")
+        print(f"  active mode     : {r['mode']}")
+        if r["problems"]:
+            print("  problems:")
+            for p in r["problems"]:
+                print(f"      ! {p}")
+        else:
+            print("  no problems found")

hackrfpy/_commands/info.py

@@ -0,0 +1,172 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/_commands/info.py'
+#
+#   InfoMixin: hackrf_info wrapper. The clean request/response case -- run the
+#   binary, capture stdout text, parse to a dict. Mixin only; assumes the host
+#   HackRF class provides _run, print_message, and mode state.
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+import re
+
+
+class InfoMixin:
+    def info(self, raw=False, print_cmd=False):
+        # Returns a parsed dict by default, or the raw text if raw=True.
+        if print_cmd:
+            self._run(["info"], mode="blocking", print_cmd=True)
+            return None
+        out, err, rc = self._run(["info"], mode="blocking", text=True)
+        self.print_message(f"[*] mode: {self.mode}")
+        if raw:
+            return out
+        return self.parse_info(out)
+
+    def get_info(self):
+        # alias
+        return self.info()
+
+    def detect(self):
+        # Hardware autodetection + identification, the HackRF analog of a
+        # serial-port scan. The HackRF is NOT a serial device -- there are no
+        # COM ports to walk -- so "detection" means: run hackrf_info, confirm
+        # each enumerated board is actually a HackRF, and report identity +
+        # firmware. Never raises for "no board"; that is a normal result the
+        # caller inspects. Raises HackRFDeviceError only if hackrf_info itself
+        # cannot run (missing binary).
+        #
+        # Returns a dict:
+        #   {
+        #     "found": bool,         # at least one board enumerated
+        #     "ready": bool,         # >=1 CONFIRMED HackRF + usable tooling
+        #     "count": int,
+        #     "boards": [ {index, serial, name, firmware, is_hackrf,
+        #                  firmware_stale}, ... ],
+        #     "tools_version": str|None,
+        #     "libhackrf_version": str|None,
+        #     "multiple": bool,      # >1 board -> disambiguate with serial=
+        #     "problem": str|None,
+        #   }
+        from ..exceptions import HackRFDeviceError
+        result = {"found": False, "ready": False, "count": 0, "boards": [],
+                  "tools_version": None, "libhackrf_version": None,
+                  "multiple": False, "warnings": [], "problem": None}
+        try:
+            out, _, _ = self._run(["info"], mode="blocking", text=True)
+        except HackRFDeviceError as e:
+            # hackrf_info couldn't run at all (binary missing). Surface it as a
+            # problem rather than raising, so detect() is always safe to call.
+            result["problem"] = str(e)
+            return result
+
+        parsed = self.parse_info(out)
+        lib = parsed.get("library", {})
+        result["tools_version"] = lib.get("hackrf_info_version")
+        result["libhackrf_version"] = lib.get("libhackrf_version")
+        # device-emitted free-text warnings, e.g. "There are N other devices
+        # on the same USB bus. You may have problems at high sample rates."
+        result["warnings"] = parsed.get("warnings", [])
+
+        boards = parsed.get("boards", [])
+        result["count"] = len(boards)
+        result["found"] = len(boards) > 0
+        result["multiple"] = len(boards) > 1
+
+        for b in boards:
+            board_id = b.get("board_id_number", "")
+            # "Board ID Number: 2 (HackRF One)" -> confirm it's a HackRF
+            is_hackrf = "hackrf" in board_id.lower()
+            fw = b.get("firmware_version", "")
+            m = re.match(r"(\d{4})", fw or "")
+            stale = bool(m and int(m.group(1)) < 2021)
+            result["boards"].append({
+                "index": b.get("index"),
+                "serial": b.get("serial_number"),
+                "name": board_id or None,
+                "firmware": fw or None,
+                "is_hackrf": is_hackrf,
+                "firmware_stale": stale,
+            })
+
+        # ready = at least one confirmed HackRF present
+        result["ready"] = any(bd["is_hackrf"] for bd in result["boards"])
+        if result["found"] and not result["ready"]:
+            result["problem"] = ("a USB device was enumerated but did not "
+                                 "identify as a HackRF")
+        elif not result["found"]:
+            result["problem"] = "no HackRF board detected (check USB / drivers)"
+        return result
+
+    def identify(self, serial=None):
+        # Return the identity of a single board: the one matching `serial`, or
+        # the first detected board if serial is None. Returns the board dict
+        # from detect()["boards"], or None if not found. Convenience for "what
+        # am I about to talk to?" before a capture/transmit.
+        det = self.detect()
+        if not det["boards"]:
+            return None
+        if serial is None:
+            return det["boards"][0]
+        for b in det["boards"]:
+            if b["serial"] and serial in b["serial"]:
+                return b
+        return None
+
+    @staticmethod
+    def parse_info(text):
+        # hackrf_info prints "Key: value" lines: a version preamble, then one
+        # block per board. We keep the preamble under "library" and each board
+        # under "boards". A board starts at "Found HackRF" or, for outputs that
+        # omit it, at an "Index:" line.
+        #
+        # Real-hardware quirks this handles:
+        #   - "Hardware supported by installed firmware:" puts its value on the
+        #     NEXT, indented line (e.g. "    HackRF One") rather than after the
+        #     colon -- so an empty value followed by an indented line is a
+        #     continuation, not a blank.
+        #   - Trailing free-text warnings with no colon (e.g. "There are 2
+        #     other devices on the same USB bus. You may have problems at high
+        #     sample rates.") are collected under result["warnings"] instead of
+        #     being silently dropped.
+        result = {"library": {}, "boards": [], "warnings": []}
+        current = None
+        last_target = None      # dict the last key was written to
+        last_key = None         # the last key, for continuation lines
+        for raw in text.splitlines():
+            line = raw.strip()
+            if not line:
+                continue
+            if line.lower().startswith("found hackrf"):
+                current = {}
+                result["boards"].append(current)
+                last_target = last_key = None
+                continue
+            if ":" not in line:
+                # No colon. Either a continuation of the previous key whose
+                # value was on this indented line, or a free-text warning.
+                if (last_target is not None and last_key is not None
+                        and raw[:1].isspace() and not last_target.get(last_key)):
+                    last_target[last_key] = line   # fill the empty continuation
+                else:
+                    result["warnings"].append(line)
+                continue
+            key, _, val = line.partition(":")
+            key = re.sub(r"[^a-z0-9]+", "_", key.strip().lower()).strip("_")
+            val = val.strip()
+            if key == "index":
+                if current is None or "index" in current:
+                    current = {}
+                    result["boards"].append(current)
+                current[key] = val
+                last_target, last_key = current, key
+            elif current is None:
+                result["library"][key] = val   # version preamble
+                last_target, last_key = result["library"], key
+            else:
+                current[key] = val
+                last_target, last_key = current, key
+        return result