hackrfpy 1.0.0__tar.gz → 1.1.0__tar.gz

{hackrfpy-1.0.0 → hackrfpy-1.1.0}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: hackrfpy
-Version: 1.0.0
+Version: 1.1.0
 Summary: A self-contained CLI + scriptable wrapper for the HackRF One, built on the hackrf-tools binaries (no libhackrf bindings required).
 Keywords: hackrf,sdr,rf,spectrum,sigmf
 Author: LC-Linkous
 License-Expression: GPL-2.0-or-later
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
 Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -27,6 +26,7 @@ Description-Content-Type: text/markdown
 
 **An Unofficial Python CLI + Scripting Wrapper for the HackRF One that works on Windows**
 
+[![Tests](https://github.com/LC-Linkous/hackRF_python/actions/workflows/tests.yml/badge.svg)](https://github.com/LC-Linkous/hackRF_python/actions/workflows/tests.yml)
 [![PyPI version](https://badge.fury.io/py/hackrfpy.svg)](https://badge.fury.io/py/hackrfpy)
 [![Python versions](https://img.shields.io/pypi/pyversions/hackrfpy.svg)](https://pypi.org/project/hackrfpy/)
 [![PyPI - Wheel](https://img.shields.io/pypi/wheel/hackrfpy.svg)](https://pypi.org/project/hackrfpy/)
@@ -43,13 +43,27 @@ This repository uses official resources and documentation but is **NOT** endorse
 
 - **Device Discovery** — detect and identify connected HackRF boards, report firmware and identity
 - **IQ Capture** — bounded, timed, streaming, or callback-style receive; decoded to normalized `complex64`
-- **Spectrum Sweep** — collect or stream `hackrf_sweep` output across a frequency range
+- **Spectrum Sweep** — collect or stream `hackrf_sweep` output across a frequency range, plus multi-frequency power monitoring over time
 - **Transmit** — file playback and constant-wave test mode, behind a deliberate TX-mode gate
 - **Operating Envelope** — per-parameter range checks and gain snapping against the device's real steps
 - **SigMF Recordings** — self-describing `.iq` captures with metadata sidecars
 - **Error Handling** — a typed exception hierarchy and verbose output options
+- **Lifecycle Safety** — clean interrupts on both platforms, an `atexit` backstop, and an OS dead-man (pdeathsig / Job Object) so even a hard-killed script cannot orphan a transmitter
 - **CLI** — the `hrf` command-line shell over the full API
 
+## Platform support
+
+hackrfpy is developed and tested on **Windows**, and has also been verified on Debian Linux with real hardware. Running the `hackrf-tools` binaries as subprocesses — rather than binding to `libhackrf` through a C extension — is what makes that portability cheap: there is no compiler or build step on any platform, and each OS runs its own native tools. Process control is handled per-platform (`SIGINT` on POSIX, `CTRL_BREAK` on Windows), with the interrupt, flush, and dead-man paths covered by tests on every OS, no skips.
+
+A platform is called **tested** here only after the full suite (hardware tests included) passes against a real board:
+
+- **Windows** — the primary development platform, verified continuously against real hardware.
+- **Linux** — verified 2026-09-19 on Debian 12 (`hackrf` 2022.09.1, firmware 2024.02.1): full suite, 227/227. Mechanics additionally exercised against tools 2023.01.1 on Ubuntu, so both packaged tools versions are known-good. Setup notes for Debian-family systems are in the [main repository README](https://github.com/LC-Linkous/hackRF_python#linux-setup-debian-family).
+
+**macOS remains experimental**: the mechanics are CI-tested there, but board-attached operation is unverified. If you run it with a board, please [open an issue](https://github.com/LC-Linkous/hackRF_python/issues) — a passing hardware suite is what promotes a platform, and the bar is not a formality: the Linux verification run surfaced and fixed two real process-lifecycle bugs.
+
+One caveat that applies everywhere: `tools_dir` must point at binaries built for the OS you are on — the Windows `.EXE` bundle will never run on Linux, and vice versa.
+
 ## Installation
 
 ```bash
@@ -64,13 +78,13 @@ pip install "hackrfpy[plotting]"
 
 Python 3.11+ is required.
 
-**You also need the `hackrf-tools` binaries**, which are *not* a pip dependency — they are installed at the OS level:
+**You also need the `hackrf-tools` binaries**, which are *not* a pip dependency — they are installed separately at the OS level. hackrfpy locates them on your `PATH` (or via a configured `tools_dir`).
 
-- **Linux:** `sudo apt install hackrf` (or your distribution's equivalent)
-- **macOS:** `brew install hackrf`
-- **Windows:** the tools are published as CI build artifacts under the [Actions tab](https://github.com/greatscottgadgets/hackrf/actions) of the HackRF repo; see the main repository README for the step-by-step.
+- **Windows** — *tested.* The tools are published as CI build artifacts under the [Actions tab](https://github.com/greatscottgadgets/hackrf/actions) of the HackRF repo; see the main repository README for the step-by-step.
+- **Linux** — *tested.* `sudo apt install hackrf` (or your distribution's equivalent).
+- **macOS** — *experimental, see [Platform support](#platform-support).* `brew install hackrf`.
 
-Verify the install with `hackrf_info`.
+Verify the tools are installed with `hackrf_info`.
 
 ## Quick Start
 
@@ -104,9 +118,20 @@ for r in rows:
     print(r["hz_low"], r["hz_high"], min(r["db"]), max(r["db"]))
 ```
 
+The same operations are available from the shell via the `hrf` entry point:
+
+```bash
+hrf detect                          # is a board attached and ready?
+hrf rx -f 433.92M -s 8M -n 2000000 -o capture.iq
+hrf sweep --f-min 88M --f-max 108M
+hrf monitor 98.1M 103.7M -d 10      # power over time on several frequencies
+```
+
+Frequencies accept unit suffixes (`433.92M`, `1.09G`), and most commands take `--print-cmd` to show the underlying `hackrf_*` invocation without running it. The full CLI reference is in the repository README.
+
 ## Transmitting
 
-Transmit is gated behind an explicit mode switch, because an accidental transmit is the one operation that can damage equipment or break the law:
+Transmit is gated behind an explicit mode switch, because an accidental transmit is the one operation that can damage equipment (or break the law)
 
 ```python
 from hackrfpy import HackRF
@@ -116,8 +141,18 @@ h.set_mode("tx")                # prints the TX-mode safety banner
 h.transmit(433.92e6, 8e6, "signal.iq", txvga=20)
 ```
 
+A bounded constant-wave test tone is available without a source file: `h.transmit_cw(433.92e6, 2e6, duration=2)`, or `hrf tx --cw -f 433.92M -s 2M -d 2` from the CLI (the duration is mandatory there — an unbounded carrier is exactly the risk the gates exist to prevent). Behind the mode gate sit an `atexit` backstop and an OS dead-man, so even a hard-killed script cannot leave a transmitter on the air.
+
 **Transmitting is regulated.** You are responsible for operating within the law and within your equipment's limits.
 
+## Thread safety
+
+A `HackRF` instance is **not** safe to share across threads: methods mutate
+per-instance state (`last_params`, the persisted operating mode, logging
+wiring) without locks. Instances are cheap -- the constructor touches no
+hardware -- so create one per thread, or confine all hackrfpy calls to a
+single worker thread.
+
 ## Examples
 
 The [main GitHub repository](https://github.com/LC-Linkous/hackRF_python) provides runnable examples, grouped by what they demonstrate.
@@ -129,9 +164,10 @@ The [main GitHub repository](https://github.com/LC-Linkous/hackRF_python) provid
 
 **Acquisition**
 
-- `persistent_capture.py` — collect many segments at one frequency from a single long-lived process
+- `persistent_capture.py` — gapless back-to-back segments at one frequency from a single long-lived receive process (contrast with `capture(segment_secs=...)`, whose files have a short re-open gap between them)
 - `power_meter.py` — live dBFS power meter at one frequency via the callback API
 - `scan_then_capture.py` — sweep a band, find the strongest bin, then capture there
+- `channel_monitor.py` — live power meter on several frequencies at once via `monitor_frequencies` (one continuous sweep, no plotting extra needed)
 
 **Sweep and plotting**
 
@@ -146,14 +182,19 @@ The [main GitHub repository](https://github.com/LC-Linkous/hackRF_python) provid
 
 **Sample data**
 
-- `collect_sample_data.py` — collect real IQ + sweep datasets (read-only; never transmits)
+- `collect_sample_data.py` — collect real IQ + sweep datasets with per-capture validation (read-only; never transmits)
+- `fm_demod_to_wav.py` — demodulate a captured FM broadcast IQ file to an audible mono WAV (numpy + stdlib only; file processing, never touches the device)
+
+**Transmit**
+
+- `tx_test_tone.py` — the one transmitting example: a bounded CW test tone behind the TX-mode gate, with `--print-cmd` dry-run
 
 > Most plotting examples require the optional plotting dependencies:
 > `pip install "hackrfpy[plotting]"`
 
 ## Documentation
 
-For comprehensive documentation, the full method reference, the CLI reference, and the operating envelope:
+Every public method carries a docstring: `help(hackrfpy.HackRF)` or `python -m pydoc hackrfpy` is the offline method reference, and a test gates the whole surface so it cannot drift. For the narrative documentation, the CLI reference, and the operating envelope:
 
 - **Library GitHub repository**: [https://github.com/LC-Linkous/hackRF_python/](https://github.com/LC-Linkous/hackRF_python/)
 - **Official HackRF documentation**: [https://hackrf.readthedocs.io/](https://hackrf.readthedocs.io/) (not associated with this library)
@@ -163,6 +204,7 @@ For comprehensive documentation, the full method reference, the CLI reference, a
 This is an unofficial community project. Contributions welcome!
 
 - Report bugs and request features on [GitHub](https://github.com/LC-Linkous/hackRF_python)
+- If you run the library on Linux or macOS, reports from real hardware are especially welcome (see [Platform support](#platform-support))
 - For device information and OFFICIAL resources, see [https://hackrf.readthedocs.io/](https://hackrf.readthedocs.io/)
   - Please do **NOT** request features or report bugs to Great Scott Gadgets or the HackRF project! This is an unofficial project and they do not maintain it.
 

{hackrfpy-1.0.0 → hackrfpy-1.1.0}/README.md

@@ -2,6 +2,7 @@
 
 **An Unofficial Python CLI + Scripting Wrapper for the HackRF One that works on Windows**
 
+[![Tests](https://github.com/LC-Linkous/hackRF_python/actions/workflows/tests.yml/badge.svg)](https://github.com/LC-Linkous/hackRF_python/actions/workflows/tests.yml)
 [![PyPI version](https://badge.fury.io/py/hackrfpy.svg)](https://badge.fury.io/py/hackrfpy)
 [![Python versions](https://img.shields.io/pypi/pyversions/hackrfpy.svg)](https://pypi.org/project/hackrfpy/)
 [![PyPI - Wheel](https://img.shields.io/pypi/wheel/hackrfpy.svg)](https://pypi.org/project/hackrfpy/)
@@ -18,13 +19,27 @@ This repository uses official resources and documentation but is **NOT** endorse
 
 - **Device Discovery** — detect and identify connected HackRF boards, report firmware and identity
 - **IQ Capture** — bounded, timed, streaming, or callback-style receive; decoded to normalized `complex64`
-- **Spectrum Sweep** — collect or stream `hackrf_sweep` output across a frequency range
+- **Spectrum Sweep** — collect or stream `hackrf_sweep` output across a frequency range, plus multi-frequency power monitoring over time
 - **Transmit** — file playback and constant-wave test mode, behind a deliberate TX-mode gate
 - **Operating Envelope** — per-parameter range checks and gain snapping against the device's real steps
 - **SigMF Recordings** — self-describing `.iq` captures with metadata sidecars
 - **Error Handling** — a typed exception hierarchy and verbose output options
+- **Lifecycle Safety** — clean interrupts on both platforms, an `atexit` backstop, and an OS dead-man (pdeathsig / Job Object) so even a hard-killed script cannot orphan a transmitter
 - **CLI** — the `hrf` command-line shell over the full API
 
+## Platform support
+
+hackrfpy is developed and tested on **Windows**, and has also been verified on Debian Linux with real hardware. Running the `hackrf-tools` binaries as subprocesses — rather than binding to `libhackrf` through a C extension — is what makes that portability cheap: there is no compiler or build step on any platform, and each OS runs its own native tools. Process control is handled per-platform (`SIGINT` on POSIX, `CTRL_BREAK` on Windows), with the interrupt, flush, and dead-man paths covered by tests on every OS, no skips.
+
+A platform is called **tested** here only after the full suite (hardware tests included) passes against a real board:
+
+- **Windows** — the primary development platform, verified continuously against real hardware.
+- **Linux** — verified 2026-09-19 on Debian 12 (`hackrf` 2022.09.1, firmware 2024.02.1): full suite, 227/227. Mechanics additionally exercised against tools 2023.01.1 on Ubuntu, so both packaged tools versions are known-good. Setup notes for Debian-family systems are in the [main repository README](https://github.com/LC-Linkous/hackRF_python#linux-setup-debian-family).
+
+**macOS remains experimental**: the mechanics are CI-tested there, but board-attached operation is unverified. If you run it with a board, please [open an issue](https://github.com/LC-Linkous/hackRF_python/issues) — a passing hardware suite is what promotes a platform, and the bar is not a formality: the Linux verification run surfaced and fixed two real process-lifecycle bugs.
+
+One caveat that applies everywhere: `tools_dir` must point at binaries built for the OS you are on — the Windows `.EXE` bundle will never run on Linux, and vice versa.
+
 ## Installation
 
 ```bash
@@ -39,13 +54,13 @@ pip install "hackrfpy[plotting]"
 
 Python 3.11+ is required.
 
-**You also need the `hackrf-tools` binaries**, which are *not* a pip dependency — they are installed at the OS level:
+**You also need the `hackrf-tools` binaries**, which are *not* a pip dependency — they are installed separately at the OS level. hackrfpy locates them on your `PATH` (or via a configured `tools_dir`).
 
-- **Linux:** `sudo apt install hackrf` (or your distribution's equivalent)
-- **macOS:** `brew install hackrf`
-- **Windows:** the tools are published as CI build artifacts under the [Actions tab](https://github.com/greatscottgadgets/hackrf/actions) of the HackRF repo; see the main repository README for the step-by-step.
+- **Windows** — *tested.* The tools are published as CI build artifacts under the [Actions tab](https://github.com/greatscottgadgets/hackrf/actions) of the HackRF repo; see the main repository README for the step-by-step.
+- **Linux** — *tested.* `sudo apt install hackrf` (or your distribution's equivalent).
+- **macOS** — *experimental, see [Platform support](#platform-support).* `brew install hackrf`.
 
-Verify the install with `hackrf_info`.
+Verify the tools are installed with `hackrf_info`.
 
 ## Quick Start
 
@@ -79,9 +94,20 @@ for r in rows:
     print(r["hz_low"], r["hz_high"], min(r["db"]), max(r["db"]))
 ```
 
+The same operations are available from the shell via the `hrf` entry point:
+
+```bash
+hrf detect                          # is a board attached and ready?
+hrf rx -f 433.92M -s 8M -n 2000000 -o capture.iq
+hrf sweep --f-min 88M --f-max 108M
+hrf monitor 98.1M 103.7M -d 10      # power over time on several frequencies
+```
+
+Frequencies accept unit suffixes (`433.92M`, `1.09G`), and most commands take `--print-cmd` to show the underlying `hackrf_*` invocation without running it. The full CLI reference is in the repository README.
+
 ## Transmitting
 
-Transmit is gated behind an explicit mode switch, because an accidental transmit is the one operation that can damage equipment or break the law:
+Transmit is gated behind an explicit mode switch, because an accidental transmit is the one operation that can damage equipment (or break the law)
 
 ```python
 from hackrfpy import HackRF
@@ -91,8 +117,18 @@ h.set_mode("tx")                # prints the TX-mode safety banner
 h.transmit(433.92e6, 8e6, "signal.iq", txvga=20)
 ```
 
+A bounded constant-wave test tone is available without a source file: `h.transmit_cw(433.92e6, 2e6, duration=2)`, or `hrf tx --cw -f 433.92M -s 2M -d 2` from the CLI (the duration is mandatory there — an unbounded carrier is exactly the risk the gates exist to prevent). Behind the mode gate sit an `atexit` backstop and an OS dead-man, so even a hard-killed script cannot leave a transmitter on the air.
+
 **Transmitting is regulated.** You are responsible for operating within the law and within your equipment's limits.
 
+## Thread safety
+
+A `HackRF` instance is **not** safe to share across threads: methods mutate
+per-instance state (`last_params`, the persisted operating mode, logging
+wiring) without locks. Instances are cheap -- the constructor touches no
+hardware -- so create one per thread, or confine all hackrfpy calls to a
+single worker thread.
+
 ## Examples
 
 The [main GitHub repository](https://github.com/LC-Linkous/hackRF_python) provides runnable examples, grouped by what they demonstrate.
@@ -104,9 +140,10 @@ The [main GitHub repository](https://github.com/LC-Linkous/hackRF_python) provid
 
 **Acquisition**
 
-- `persistent_capture.py` — collect many segments at one frequency from a single long-lived process
+- `persistent_capture.py` — gapless back-to-back segments at one frequency from a single long-lived receive process (contrast with `capture(segment_secs=...)`, whose files have a short re-open gap between them)
 - `power_meter.py` — live dBFS power meter at one frequency via the callback API
 - `scan_then_capture.py` — sweep a band, find the strongest bin, then capture there
+- `channel_monitor.py` — live power meter on several frequencies at once via `monitor_frequencies` (one continuous sweep, no plotting extra needed)
 
 **Sweep and plotting**
 
@@ -121,14 +158,19 @@ The [main GitHub repository](https://github.com/LC-Linkous/hackRF_python) provid
 
 **Sample data**
 
-- `collect_sample_data.py` — collect real IQ + sweep datasets (read-only; never transmits)
+- `collect_sample_data.py` — collect real IQ + sweep datasets with per-capture validation (read-only; never transmits)
+- `fm_demod_to_wav.py` — demodulate a captured FM broadcast IQ file to an audible mono WAV (numpy + stdlib only; file processing, never touches the device)
+
+**Transmit**
+
+- `tx_test_tone.py` — the one transmitting example: a bounded CW test tone behind the TX-mode gate, with `--print-cmd` dry-run
 
 > Most plotting examples require the optional plotting dependencies:
 > `pip install "hackrfpy[plotting]"`
 
 ## Documentation
 
-For comprehensive documentation, the full method reference, the CLI reference, and the operating envelope:
+Every public method carries a docstring: `help(hackrfpy.HackRF)` or `python -m pydoc hackrfpy` is the offline method reference, and a test gates the whole surface so it cannot drift. For the narrative documentation, the CLI reference, and the operating envelope:
 
 - **Library GitHub repository**: [https://github.com/LC-Linkous/hackRF_python/](https://github.com/LC-Linkous/hackRF_python/)
 - **Official HackRF documentation**: [https://hackrf.readthedocs.io/](https://hackrf.readthedocs.io/) (not associated with this library)
@@ -138,6 +180,7 @@ For comprehensive documentation, the full method reference, the CLI reference, a
 This is an unofficial community project. Contributions welcome!
 
 - Report bugs and request features on [GitHub](https://github.com/LC-Linkous/hackRF_python)
+- If you run the library on Linux or macOS, reports from real hardware are especially welcome (see [Platform support](#platform-support))
 - For device information and OFFICIAL resources, see [https://hackrf.readthedocs.io/](https://hackrf.readthedocs.io/)
   - Please do **NOT** request features or report bugs to Great Scott Gadgets or the HackRF project! This is an unofficial project and they do not maintain it.
 

{hackrfpy-1.0.0 → hackrfpy-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hackrfpy"
-version = "1.0.0"
+version = "1.1.0"
 description = "A self-contained CLI + scriptable wrapper for the HackRF One, built on the hackrf-tools binaries (no libhackrf bindings required)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -9,11 +9,10 @@ license-files = ["LICENSE*"]
 authors = [{ name = "LC-Linkous" }]
 keywords = ["hackrf", "sdr", "rf", "spectrum", "sigmf"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)",
     "Operating System :: Microsoft :: Windows",
-    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -47,10 +46,43 @@ dev = [
     "pytest-cov",
     "ruff",
     "mypy",
+    "sigmf>=1.2",     # official validator: spec compliance is tested, not trusted
 ]
 
 [tool.pytest.ini_options]
 markers = [
     "hardware: tests that require a connected HackRF (self-skip if absent)",
 ]
-testpaths = ["tests"]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/hackrfpy"]
+# The point of this config: the package ships a py.typed marker, which promises
+# downstream type-checkers that the inline annotations are real. These settings
+# are what make that promise true -- every def in the shipped package must be
+# annotated, or CI fails.
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[tool.ruff]
+# Match the codebase's existing style rather than reformatting it.
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+# Default ruleset (pyflakes + a pycodestyle subset). Kept deliberately small:
+# this gates CI, so every enabled rule should be one we actually want to block
+# a merge on.
+select = ["E", "F", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+# E741 ("ambiguous variable name l"): `l` reads naturally as "line" in the
+# sweep-line parsing comprehensions. Cosmetic only, and renaming would churn
+# working parser tests.
+"tests/test_parsing.py" = ["E741"]
+"tests/test_real_output.py" = ["E741"]

{hackrfpy-1.0.0 → hackrfpy-1.1.0}/src/hackrfpy/__init__.py

@@ -11,8 +11,14 @@ from .exceptions import (
 )
 from . import constants
 
+try:
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+    __version__ = _pkg_version("hackrfpy")
+except PackageNotFoundError:                     # running from a checkout
+    __version__ = "0.0.0+unknown"
+
 __all__ = [
-    "HackRF", "load_iq", "parse_freq", "constants",
+    "HackRF", "load_iq", "parse_freq", "constants", "__version__",
     "write_sigmf_meta", "read_sigmf_meta",
     "HackRFError", "HackRFValueError", "HackRFModeError",
     "HackRFDeviceError", "HackRFEnvironmentError",

{hackrfpy-1.0.0 → hackrfpy-1.1.0}/src/hackrfpy/_commands/capture.py

@@ -18,18 +18,38 @@
 #   Author(s): <you>
 ##--------------------------------------------------------------------\
 
+from __future__ import annotations
+
 import os
+from typing import TYPE_CHECKING, Any, Callable, Generator
+
+import numpy as np
 
 from .. import constants as C
+from .._host import HostOps
 from ..sigmf import write_sigmf_meta
 
+if TYPE_CHECKING:
+    from .._receiver import PersistentReceiver
+    from .._stream_ctx import StreamCtx
+
 
-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):
+class CaptureMixin(HostOps):
+    def capture(self, freq: float, sample_rate: float, *,
+                out: str = "capture.iq", num_samples: int | None = None,
+                duration: float | None = None, lna: int = 16, vga: int = 20,
+                amp: bool = False, bias_tee: bool = False,
+                baseband_bw: float | None = None, to_stdout: bool = False,
+                sigmf: bool = True, segment_secs: float | None = None,
+                print_cmd: bool = False) -> Any:
+        """Receive IQ at freq/sample_rate into a file (with SigMF sidecar).
+
+        Bound with num_samples or duration, or neither for an open-ended handle
+        (call .stop() on the returned process handle). segment_secs rolls output
+        across numbered files (whole files, short re-open gap between them; use
+        open_receiver for gapless). to_stdout=True streams decoded blocks
+        instead of writing a file.
+        """
         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)
@@ -57,7 +77,7 @@ class CaptureMixin:
             # 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():
+            def _gen() -> Generator[np.ndarray, None, None]:   # decoded, not raw
                 tail = b""
                 inner = self._run(argv, mode="stream")
                 try:
@@ -97,17 +117,30 @@ class CaptureMixin:
         return res
 
     # ---- aliases ----
-    def rx(self, *a, **k):
+    def rx(self, *a: Any, **k: Any) -> Any:
+        """Alias of capture()."""
         return self.capture(*a, **k)
 
-    def capture_samples(self, freq, sample_rate, num_samples, **k):
+    def capture_samples(self, freq: float, sample_rate: float,
+                        num_samples: int, **k: Any) -> Any:
+        """Alias of capture() with a required num_samples bound."""
         return self.capture(freq, sample_rate, num_samples=num_samples, **k)
 
-    def capture_seconds(self, freq, sample_rate, duration, **k):
+    def capture_seconds(self, freq: float, sample_rate: float,
+                        duration: float, **k: Any) -> Any:
+        """Alias of capture() with a required duration bound."""
         return self.capture(freq, sample_rate, duration=duration, **k)
 
-    def scan_frequencies(self, freqs, sample_rate, num_samples, *,
-                         on_capture=None, **k):
+    def scan_frequencies(self, freqs: list[float], sample_rate: float,
+                         num_samples: int, *,
+                         on_capture: Callable[..., Any] | None = None,
+                         **k: Any) -> dict[float, np.ndarray] | None:
+        """Capture num_samples of IQ at each frequency in turn.
+
+        Returns {freq: complex64 ndarray}, or None when on_capture consumes
+        blocks instead. Each visit re-opens the device (short gap between
+        frequencies).
+        """
         # 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
@@ -130,8 +163,13 @@ class CaptureMixin:
         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):
+    def capture_array(self, freq: float, sample_rate: float, num_samples: int,
+                      *, return_params: bool = False, **k: Any) -> Any:
+        """Return exactly num_samples complex64 samples in RAM, no file.
+
+        The scripting entry point. return_params=True also returns the
+        validated parameters actually used.
+        """
         # 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
@@ -164,8 +202,16 @@ class CaptureMixin:
             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):
+    def open_receiver(self, freq: float, sample_rate: float, *, lna: int = 16,
+                      vga: int = 20, amp: bool = False,
+                      baseband_bw: float | None = None,
+                      read_samples: int = 131072) -> PersistentReceiver:
+        """Open a long-lived receive stream; returns a PersistentReceiver.
+
+        One hackrf_transfer process serves many .read(n) calls: consecutive
+        reads are gapless (contrast capture(segment_secs=...)). Use as a context
+        manager to guarantee the child is reaped.
+        """
         # 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:
@@ -184,7 +230,13 @@ class CaptureMixin:
                                   amp=amp, baseband_bw=baseband_bw,
                                   read_samples=read_samples)
 
-    def capture_stream(self, freq, sample_rate, **k):
+    def capture_stream(self, freq: float, sample_rate: float,
+                       **k: Any) -> StreamCtx:
+        """Context manager yielding decoded complex64 blocks from a live stream.
+
+        The receiving hackrf_transfer is always reaped on block exit, even on
+        exception.
+        """
         # 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:
@@ -194,8 +246,15 @@ class CaptureMixin:
         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):
+    def capture_callback(self, freq: float, sample_rate: float,
+                         on_block: Callable[..., Any], *,
+                         max_samples: int | None = None,
+                         max_blocks: int | None = None, **k: Any) -> int:
+        """Invoke on_block(iq) per decoded block until a bound or False return.
+
+        Bounds: max_samples, max_blocks, or the callback returning False.
+        Returns the number of samples delivered.
+        """
         # 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
@@ -228,8 +287,9 @@ class CaptureMixin:
         return total
 
     # ---- internals ----
-    def _rx_argv(self, freq, sample_rate, target, lna, vga, amp, bias_tee,
-                 bw, num_samples):
+    def _rx_argv(self, freq: float, sample_rate: float, target: str, lna: int,
+                 vga: int, amp: bool, bias_tee: bool, bw: float,
+                 num_samples: int | None) -> list[Any]:
         argv = ["transfer", "-r", target,
                 "-f", int(freq), "-s", int(sample_rate),
                 "-l", lna, "-g", vga,
@@ -241,8 +301,10 @@ class CaptureMixin:
             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):
+    def _capture_segmented(self, freq: float, sample_rate: float, out: str,
+                           segment_secs: float, lna: int, vga: int, amp: bool,
+                           bias_tee: bool, bw: float, sigmf: bool,
+                           print_cmd: bool) -> list[str]:
         # 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)
@@ -268,7 +330,7 @@ class CaptureMixin:
                 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)
+                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")