hackrfpy 1.0.0__py3-none-any.whl

hackrfpy/cli.py

@@ -0,0 +1,292 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/cli.py'
+#
+#   The CLI shell. One class owns the parser; main(args) dispatches on the
+#   subcommand. __init__(a=None) takes argv from sys.argv OR a passed list, so
+#   the same class drives from the shell or from a script:
+#       app = HackRFCLI(['rx', '-f', '433.92M', '-s', '8M', '-n', '1000000'])
+#       app.main(app.getArgs())
+#
+#   The CLI layer is thin: it parses, resolves the persisted operating mode,
+#   instantiates HackRF once, calls the method, and maps typed exceptions to
+#   clean stderr + exit codes. All real work lives in core + mixins.
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+import argparse
+import os
+import sys
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    _VERSION = _pkg_version("hackrfpy")
+except PackageNotFoundError:  # running from a source tree, not installed
+    _VERSION = "0+unknown"
+
+from .core import HackRF, parse_freq
+from .exceptions import HackRFError, HackRFValueError
+from . import constants as C
+from . import presets as P
+
+
+# frequency parsing now lives in core.parse_freq (single source of truth, and
+# the typed-exception version) so library callers share it. Imported above.
+
+
+# ---- mode state file (mode persists across CLI invocations) ------------------
+def _print_detect(det):
+    print("hackrfpy detect")
+    print("-" * 40)
+    if det["problem"] and not det["found"]:
+        print(f"  {det['problem']}")
+        return
+    print(f"  boards found    : {det['count']}")
+    if det["tools_version"]:
+        print(f"  hackrf-tools    : {det['tools_version']}")
+    if det["libhackrf_version"]:
+        print(f"  libhackrf       : {det['libhackrf_version']}")
+    for b in det["boards"]:
+        tag = "HackRF" if b["is_hackrf"] else "UNCONFIRMED"
+        print(f"  [{b['index']}] {tag}")
+        print(f"      serial   : {b['serial']}")
+        print(f"      name     : {b['name']}")
+        print(f"      firmware : {b['firmware']}"
+              + ("  (stale: <2021, streaming/-N may be unsupported)"
+                 if b["firmware_stale"] else ""))
+    if det["multiple"]:
+        print("  ! multiple boards: select one with --serial <serial>")
+    for w in det.get("warnings", []):
+        print(f"  ! {w}")
+    print(f"  ready           : {'yes' if det['ready'] else 'no'}")
+    if det["problem"] and det["found"]:
+        print(f"  note            : {det['problem']}")
+
+
+def _state_path():
+    base = os.environ.get("XDG_CONFIG_HOME",
+                          os.path.join(os.path.expanduser("~"), ".config"))
+    return os.path.join(base, C.STATE_DIR_NAME, C.STATE_FILE_NAME)
+
+
+def read_mode():
+    path = _state_path()
+    try:
+        with open(path) as f:
+            for line in f:
+                if line.strip().startswith("mode"):
+                    return line.split("=", 1)[1].strip().strip('"').strip("'")
+    except OSError:
+        pass
+    return C.DEFAULT_MODE
+
+
+def write_mode(mode):
+    path = _state_path()
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as f:
+        f.write(f'mode = "{mode}"\n')
+
+
+# Subcommands whose only job is to relay to a device method with **flags.
+def _add_common_rf(p, freq_required=True):
+    p.add_argument("-f", "--frequency", type=parse_freq, required=freq_required,
+                   help="center frequency (e.g. 433.92M, 1.09G, or Hz)")
+    p.add_argument("-s", "--sample-rate", dest="sample_rate", type=parse_freq,
+                   default=8e6, help="sample rate (default 8M)")
+    p.add_argument("--force", action="store_true",
+                   help="downgrade out-of-range rejects to warnings")
+    p.add_argument("--print-cmd", dest="print_cmd", action="store_true",
+                   help="print the hackrf_* command without running it")
+    p.add_argument("-v", "--verbose", action="store_true")
+    p.add_argument("--serial", help="select a board by serial number "
+                   "(multi-board setups)")
+
+
+class HackRFCLI:
+    def __init__(self, a=None):
+        main_parser = argparse.ArgumentParser(prog="hrf", description="hackrfpy")
+        main_parser.add_argument("--version", action="version",
+                                 version=f"%(prog)s {_VERSION}")
+        sub = main_parser.add_subparsers(dest="subparser_name")
+
+        # info
+        sp = sub.add_parser("info", help="device + firmware info")
+        sp.add_argument("--raw", action="store_true")
+        sp.add_argument("-v", "--verbose", action="store_true")
+        sp.add_argument("--print-cmd", dest="print_cmd", action="store_true")
+
+        # detect
+        sp = sub.add_parser("detect",
+                            help="autodetect + identify connected HackRF(s)")
+        sp.add_argument("-v", "--verbose", action="store_true")
+
+        # doctor
+        sp = sub.add_parser("doctor", help="environment / preflight check")
+        sp.add_argument("--path", default=".", help="disk to check for capture")
+
+        # mode
+        sp = sub.add_parser("mode", help="get/set operating mode (rx|tx)")
+        sp.add_argument("value", nargs="?", choices=C.MODES,
+                        help="omit to print current mode")
+
+        # rx / capture (-f optional HERE because --preset can supply it;
+        # main() enforces that one of the two resolves a frequency)
+        sp = sub.add_parser("rx", help="receive IQ to a file")
+        _add_common_rf(sp, freq_required=False)
+        sp.add_argument("-o", "--out", default="capture.iq")
+        sp.add_argument("-n", "--num-samples", dest="num_samples", type=int)
+        sp.add_argument("-d", "--duration", type=float, help="seconds")
+        sp.add_argument("-l", "--lna", type=int, default=16)
+        sp.add_argument("-g", "--vga", type=int, default=20)
+        sp.add_argument("-a", "--amp", action="store_true")
+        sp.add_argument("--bias-tee", dest="bias_tee", action="store_true")
+        sp.add_argument("--bw", dest="baseband_bw", type=parse_freq)
+        sp.add_argument("--segment", dest="segment_secs", type=float,
+                        help="rolling files of N seconds each")
+        sp.add_argument("--no-sigmf", dest="sigmf", action="store_false")
+        sp.add_argument("--preset", help="apply a band preset for freq/rate")
+
+        # tx
+        sp = sub.add_parser("tx", help="transmit IQ from a file (TX mode only)")
+        _add_common_rf(sp)
+        sp.add_argument("source", help="int8 I/Q file to transmit")
+        sp.add_argument("-x", "--txvga", type=int, default=20)
+        sp.add_argument("-a", "--amp", action="store_true")
+        sp.add_argument("--bias-tee", dest="bias_tee", action="store_true")
+        sp.add_argument("--bw", dest="baseband_bw", type=parse_freq)
+        sp.add_argument("-R", "--repeat", action="store_true")
+        sp.add_argument("-n", "--num-samples", dest="num_samples", type=int)
+        sp.add_argument("-d", "--duration", type=float)
+        sp.add_argument("--max-duration", dest="max_duration", type=float,
+                        help="hard time cap (s), enforced even for --repeat")
+
+        # sweep
+        sp = sub.add_parser("sweep", help="spectrum sweep (CSV to stdout)")
+        sp.add_argument("--f-min", dest="f_min", type=parse_freq, required=True)
+        sp.add_argument("--f-max", dest="f_max", type=parse_freq, required=True)
+        sp.add_argument("-w", "--bin-width", dest="bin_width", type=parse_freq)
+        sp.add_argument("-l", "--lna", type=int, default=16)
+        sp.add_argument("-g", "--vga", type=int, default=20)
+        sp.add_argument("-a", "--amp", action="store_true")
+        sp.add_argument("-1", "--one-shot", dest="one_shot", action="store_true")
+        sp.add_argument("-N", "--num-sweeps", dest="num_sweeps", type=int)
+        sp.add_argument("--force", action="store_true")
+        sp.add_argument("--print-cmd", dest="print_cmd", action="store_true")
+        sp.add_argument("-v", "--verbose", action="store_true")
+        sp.add_argument("--serial", help="select a board by serial number")
+
+        # presets
+        sp = sub.add_parser("presets", help="list band presets")
+
+        self.args = main_parser.parse_args(a)
+        self._parser = main_parser
+
+    def getArgs(self):
+        return self.args
+
+    def _make_device(self, args):
+        h = HackRF(verbose=getattr(args, "verbose", False),
+                   serial=getattr(args, "serial", None))
+        h.allow_out_of_spec = getattr(args, "force", False)
+        # restore persisted mode so rx/tx/sweep honor it across invocations
+        h.restore_mode(read_mode())
+        return h
+
+    def main(self, args):
+        name = args.subparser_name
+        if name is None:
+            self._parser.print_help()
+            return
+
+        if name == "presets":
+            for k, v in sorted(P.load_presets().items()):
+                print(f"  {k:10} {v.get('desc','')}")
+            return
+
+        if name == "mode":
+            if args.value is None:
+                print(read_mode())
+            else:
+                h = HackRF()
+                h.restore_mode(read_mode())  # so the banner fires only on a
+                h.set_mode(args.value)       # real rx -> tx switch
+                write_mode(args.value)
+            return
+
+        h = self._make_device(args)
+
+        if name == "info":
+            res = h.info(raw=args.raw, print_cmd=args.print_cmd)
+            if not args.print_cmd:
+                print(res)
+
+        elif name == "detect":
+            det = h.detect()
+            _print_detect(det)
+            # exit non-zero when not ready, so `hrf detect && hrf rx ...` works
+            if not det["ready"]:
+                sys.exit(1)
+
+        elif name == "doctor":
+            report = h.doctor(capture_path=args.path)
+            if report["problems"]:
+                sys.exit(1)   # make preflight usable in `doctor && capture`
+
+        elif name == "rx":
+            if getattr(args, "preset", None):
+                pre = P.get_preset(args.preset)
+                if args.frequency is None:
+                    args.frequency = pre.get("center") or pre.get("f_min")
+                args.sample_rate = pre.get("sample_rate", args.sample_rate)
+            if args.frequency is None:
+                raise HackRFValueError(
+                    "rx needs a frequency: pass -f/--frequency or --preset")
+            h.capture(args.frequency, args.sample_rate, out=args.out,
+                      num_samples=args.num_samples, duration=args.duration,
+                      lna=args.lna, vga=args.vga, amp=args.amp,
+                      bias_tee=args.bias_tee, baseband_bw=args.baseband_bw,
+                      sigmf=args.sigmf, segment_secs=args.segment_secs,
+                      print_cmd=args.print_cmd)
+
+        elif name == "tx":
+            h.transmit(args.frequency, args.sample_rate, args.source,
+                       txvga=args.txvga, amp=args.amp, bias_tee=args.bias_tee,
+                       baseband_bw=args.baseband_bw, repeat=args.repeat,
+                       num_samples=args.num_samples, duration=args.duration,
+                       max_duration=args.max_duration,
+                       print_cmd=args.print_cmd)
+
+        elif name == "sweep":
+            gen = h.sweep(args.f_min, args.f_max, bin_width=args.bin_width,
+                          lna=args.lna, vga=args.vga, amp=args.amp,
+                          one_shot=args.one_shot, num_sweeps=args.num_sweeps,
+                          print_cmd=args.print_cmd)
+            if gen is not None:
+                # CSV to stdout, as documented -- same shape hackrf_sweep
+                # emits, so it round-trips through parse_sweep_line and pipes
+                # cleanly into other tools.
+                for row in gen:
+                    print(", ".join(
+                        [row["date"], row["time"],
+                         str(row["hz_low"]), str(row["hz_high"]),
+                         f"{row['bin_width']:.2f}", str(row["num_samples"])]
+                        + [f"{d:.2f}" for d in row["db"]]))
+
+
+def main():
+    app = HackRFCLI()
+    try:
+        app.main(app.getArgs())
+    except HackRFError as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(e.exit_code)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

hackrfpy/comparison.md

@@ -0,0 +1,175 @@
+# comparison.md — hackrfpy vs other Python HackRF libraries
+
+An honest look at where this library sits among the Python options for the
+HackRF One. The goal is **not** to claim it's the best at everything — each of
+these makes a different, defensible tradeoff. The goal is to identify the niche
+hackrfpy fills and be clear about what it gives up to fill it.
+
+## The one decision that separates them
+
+Every Python HackRF library makes a single architectural choice that determines
+almost everything else: **bind `libhackrf` (the C library) or wrap the
+`hackrf-tools` binaries (the command-line programs).**
+
+* **libhackrf binders** (`python_hackrf`, `pyhackrf2`, `pyhackrf`, the various
+  `py-hackrf-ctypes` / `pylibhackrf` projects) call the C library's functions
+  directly — through ctypes, Cython, or a C extension. They get low-level
+  control and real-time sample callbacks, at the cost of a compiler/headers
+  dependency and a callback-based programming model.
+* **hackrfpy wraps the binaries.** It runs `hackrf_info`, `hackrf_transfer`,
+  `hackrf_sweep`, etc. as subprocesses and manages their I/O and lifecycle. It
+  gives up real-time callback control and adds subprocess overhead, and in
+  exchange gets a dependency-free install, full tool coverage, and a place to
+  put a validation/safety layer.
+
+Almost every difference below traces back to this one fork.
+
+## The landscape
+
+| Library | Approach | Install | TX | Sweep | Device mgmt (clock/spiflash/etc.) | Maintained |
+|---|---|---|---|---|---|---|
+| **hackrfpy** (this) | wraps **binaries** | `pip` + binaries on system; no compiler | yes (gated) | yes | **all 8 tools** | active |
+| **python_hackrf** | Cython → libhackrf | `pip` + compiler + libhackrf headers/libusb | yes | yes | info, sweep, operacake, transfer only | active, most complete binder |
+| **pyhackrf2** | Python → libhackrf (ctypes) | `pip` + libusb/libhackrf | yes | yes | minimal | moderate |
+| **pyhackrf** (dressel/4thel00z) | ctypes → libhackrf | `pip` + libusb/fftw | partial | via callback | minimal | stale |
+| **py-hackrf-ctypes / pylibhackrf** | ctypes / C ext → libhackrf | manual build | varies | via callback | minimal | stale/experimental |
+
+(Approaches verified against each project's own PyPI/GitHub description; feature
+columns reflect what each documents, not exhaustive testing.)
+
+## What the libhackrf binders do well (and where hackrfpy now stands)
+
+Being honest about the architectural tradeoff, and what has and hasn't been narrowed:
+
+* **Real-time sample callbacks.** *Gap narrowed.* The binders expose libhackrf's
+  callback model — register a function that fires as buffers arrive. hackrfpy
+  now offers the same *ergonomics* via `capture_callback(freq, rate, on_block)`:
+  your function is called with each decoded `complex64` block as it streams, and
+  returns `False` to stop. The mechanism differs (it rides the subprocess stream
+  rather than a libhackrf USB-thread callback), so it is not zero-copy — but the
+  measured block-delivery latency is low: on a laptop at 20 Msps, median ~0.04 ms
+  between blocks with ~0.5 ms jitter (`examples/benchmark.py`). So *when data is
+  flowing*, the "latency floor is the pipe" concern is sub-millisecond; the real
+  constraint at top rates is throughput (above), not per-block latency.
+* **Lower overhead at high rates.** *Gap narrowed; measured, with an honest
+  ceiling.* The decode path was optimized to construct `complex64` directly
+  (≈3× faster; benchmarked at ~190–390 MB/s depending on machine, i.e. 5–10× the
+  40 MB/s the device produces at 20 Msps — so **decode is not the bottleneck**).
+  The remaining cost is the subprocess + kernel pipe. Measured on a laptop with a
+  shared USB bus (`examples/benchmark.py`): a 20 Msps capture received **100% of
+  samples with no bulk loss** and only a single startup-transient shortfall over
+  120M samples, but the consumer drained the pipe at a **steady-state ~14 Msps**,
+  so the capture ran slower than real-time (the pipe back-pressures and
+  `hackrf_transfer` blocks rather than dropping). The practical reading: for
+  *capture-to-file or batch* work you lose nothing; for a *live real-time*
+  consumer at the very top of the rate range, the pipe drain is a real ceiling a
+  binder avoids. There is also a fixed ~1–2 s per-capture **startup cost**
+  (process launch + USB setup + device settle) the in-process binders don't pay.
+  These numbers are machine-specific — run the benchmark on your own setup.
+* **Fine-grained mid-stream control.** *Genuine remaining gap.* `hackrf_transfer`
+  takes one frequency and runs until stopped; it cannot retune mid-stream, so
+  hackrfpy cannot either — that is the binary's limit, not a missing feature.
+  What hackrfpy adds is `scan_frequencies([...], rate, n)` to make sequential
+  multi-frequency capture a single clean call, but each retune is still a fresh
+  process with a short re-open gap. **True gapless retuning needs the C library**
+  — if that's your requirement, use a binder.
+* **Android.** `python_hackrf` documents an Android build path. hackrfpy targets
+  desktop OSes. Unchanged.
+
+If your work is "process every sample in real time with the lowest possible
+latency, retuning on the fly," a libhackrf binder — `python_hackrf` is the most
+complete and actively maintained — is still the better fit. The gap is now
+narrower (callback ergonomics and fast decode), but the architectural ceiling is
+real and this document won't pretend otherwise.
+
+## What hackrfpy does that the others don't
+
+The niche, stated plainly:
+
+* **Dependency-free install, especially on Windows.** Because it wraps the
+  binaries, there is no C compiler, no `libhackrf.h`, no `libusb` headers, no
+  `PYTHON_HACKRF_CFLAGS`/`LDFLAGS` to set. The binders all require a build
+  toolchain and the native headers present at install time — the exact friction
+  that makes HackRF-in-Python painful on Windows. hackrfpy needs only the
+  `hackrf-tools` binaries (which ship prebuilt) and pip. This is the single
+  biggest practical differentiator.
+* **Complete tool coverage.** hackrfpy wraps **all eight** `hackrf-tools`
+  binaries, including the ones the binders explicitly skip. `python_hackrf`'s
+  own docs list `hackrf_clock`, `hackrf_cpldjtag`, `hackrf_debug`, and
+  `hackrf_spiflash` as "Will not be implemented." hackrfpy wraps clock, debug,
+  and operacake as full argument passthroughs and provides brick-guarded
+  spiflash/cpldjtag. If you need clock configuration or firmware operations from
+  Python, this is currently the option.
+* **A validation / safety layer.** None of the binders police your inputs — they
+  pass values straight to libhackrf. hackrfpy adds a reject-by-default operating
+  envelope (catch a 60 GHz typo for 6 GHz), gain snapping with honest
+  notification, a sub-recommended-sample-rate warning, an explicit RX/TX mode
+  gate so you can't transmit by accident, a TX gain ceiling against
+  order-of-magnitude fat-fingers, and a `max_duration` dead-man for open-ended
+  transmits. This is a deliberate "help you not break your hardware or the law"
+  layer that a thin binding has no place to put.
+* **Lifecycle safety for scripts.** Clean child reaping on `KeyboardInterrupt`,
+  context managers (`capture_stream`, `sweep_stream`) that guarantee the radio
+  is stopped on exit, and an `atexit` backstop so a dying script doesn't leave a
+  transmitter running. These matter precisely because subprocess management is
+  the risk hackrfpy takes on — so it's where the engineering went.
+* **A real CLI.** `hrf` is a first-class command-line tool (`hrf detect`,
+  `hrf rx`, `hrf sweep`, `hrf doctor`), not just a library. The binders are
+  libraries first; `python_hackrf` has a CLI but centered on info/sweep.
+* **Self-describing captures.** SigMF sidecar metadata written automatically, so
+  a recording carries its frequency/rate/gains instead of being a headerless
+  int8 blob.
+* **Hardware-validated parsing.** The parsers are tested against frozen verbatim
+  output from a real HackRF One (info, sweep, IQ), including real quirks like
+  out-of-order sweep segments and continuation-line fields.
+
+## Honest weaknesses
+
+Where hackrfpy is genuinely behind, beyond the architectural give-ups above:
+
+* **Younger and fewer users** than the established binders. It is validated
+  against a real HackRF One (hardware-marked tests pass; parsers are pinned to
+  verbatim device output), but it has far less field exposure across diverse
+  setups, firmware versions, and edge cases than libraries that have been in
+  wide use for years. Maturity is about breadth of real-world exposure, and
+  that takes time and users.
+* **Subprocess dependence on tool behavior.** It relies on the `hackrf-tools`
+  stdout format and exit codes, which it parses and version-checks — but a
+  future tools change could require parser updates. A binder against the stable
+  C ABI is insulated from that.
+* **No real-time callback path.** Restated because it's the real ceiling: if you
+  outgrow "stream blocks from a subprocess," the architecture won't follow you
+  into zero-latency callback territory without becoming a different library.
+* **Not a DSP library.** By design — it yields `complex64` and stops. The binders
+  don't do DSP either, but their callback model sits closer to where you'd build
+  it.
+
+## Who should use which
+
+* **Use a libhackrf binder (`python_hackrf` first) if:** you need real-time
+  per-buffer callbacks, minimum latency at high sample rates, mid-stream
+  retuning, Android support, or you're already in a compiled-toolchain
+  environment where the build dependency is free.
+* **Use hackrfpy if:** you want a clean `pip` install with no compiler
+  (especially on Windows), a scriptable + CLI workflow, full access to *all* the
+  hackrf tools including clock/debug/firmware, a safety/validation layer that
+  guards against expensive mistakes, robust script lifecycle (clean stop, no
+  orphaned transmitters), and self-describing recordings — and your data path is
+  "capture/sweep to file or to `complex64`," not real-time callback DSP.
+
+## The one-line version
+
+The other libraries are **C bindings** that give you low-level, real-time
+control at the cost of a build toolchain. hackrfpy is a **binary wrapper** that
+gives you a dependency-free install, complete tool coverage, and a safety layer.
+It now matches the binders' callback *ergonomics* (`capture_callback`) and has a
+fast decode path, so the usability gap is small; the remaining hard difference
+is true gapless mid-stream retuning, which needs the C library. Different tools
+for different jobs; the niche is "scriptable HackRF control that installs cleanly
+on Windows and tries to keep you from breaking things."
+
+---
+
+*Landscape current as of mid-2026; library capabilities and maintenance status
+change. Verify against each project's current PyPI/GitHub before relying on a
+specific claim. Feature columns reflect each project's own documentation.*

hackrfpy/constants.py

@@ -0,0 +1,104 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/constants.py'
+#
+#   Single source of truth for the HackRF One operating envelope: hard
+#   frequency / sample-rate ranges, the stepped gain tables, the discrete
+#   baseband-filter bandwidths, and library defaults. EVERYTHING that is a
+#   "limit" lives here so that:
+#       1. there is exactly one place to edit as hardware/firmware evolves,
+#       2. the validation code and the test suite import the SAME numbers and
+#          therefore can never silently drift apart.
+#
+#   WARNING: these describe the LIBRARY's checking envelope, not live device
+#   state. Editing them changes what the library will accept/reject; it does
+#   not change anything on the board.
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+# ---- hard ranges (reject-by-default; --force / allow_out_of_spec downgrades
+#      a reject to a warning) -------------------------------------------------
+# HackRF One tunes 1 MHz - 6 GHz. Values outside this are almost always a
+# fat-finger (typing 60e9 for 6e9), which is exactly what reject-by-default
+# is meant to catch.
+FREQ_MIN_HZ = 1_000_000          # 1 MHz
+FREQ_MAX_HZ = 6_000_000_000      # 6 GHz
+
+# Usable sample rates. The device technically accepts 2-20 Msps; 8-20 is the
+# commonly recommended band. We reject outside 2-20 and warn below 8.
+SR_MIN = 2_000_000               # 2 Msps
+SR_MAX = 20_000_000              # 20 Msps
+SR_WARN_BELOW = 8_000_000        # warn (don't reject) under 8 Msps
+
+# ---- stepped gains (snap-and-notify, round DOWN to the honest device value) -
+# Each entry: (min_db, max_db, step_db). The silicon rounds to a step anyway,
+# so snapping is just telling the truth about what you'll actually get.
+LNA_GAIN = (0, 40, 8)            # IF gain  (MAX2837)
+VGA_GAIN = (0, 62, 2)            # baseband RX gain
+TXVGA_GAIN = (0, 47, 1)          # TX IF gain
+
+# Front-end amplifier is a fixed ~14 dB block, on/off only.
+AMP_DB = 14
+
+# ---- TX safety ceilings (default at true device max so an order-of-magnitude
+#      typo rejects; tighten these for a specific bench) ----------------------
+TX_VGA_CEILING_DB = TXVGA_GAIN[1]    # 47; lower this to cap output on a bench
+TX_AMP_ALLOWED = True                # set False to forbid the 14 dB amp on TX
+
+# ---- discrete baseband filter bandwidths (Hz), MAX2837 supported set --------
+# hackrf_transfer auto-selects one if unset; we replicate a sensible default
+# (~0.75 x sample_rate, snapped to nearest supported) and snap explicit values.
+BASEBAND_FILTER_BW_HZ = (
+    1_750_000, 2_500_000, 3_500_000, 5_000_000, 5_500_000, 6_000_000,
+    7_000_000, 8_000_000, 9_000_000, 10_000_000, 12_000_000, 14_000_000,
+    15_000_000, 20_000_000, 24_000_000, 28_000_000,
+)
+BASEBAND_AUTO_FRACTION = 0.75    # default BW as a fraction of sample rate
+
+# ---- sample format ----------------------------------------------------------
+# HackRF native capture format: interleaved signed 8-bit I, Q, I, Q ...
+BYTES_PER_SAMPLE = 2             # one int8 I + one int8 Q
+IQ_DTYPE = "int8"
+
+# ---- disk / capture lifecycle ----------------------------------------------
+# Used by the capture estimator + guard. Bytes/sec = sample_rate * 2.
+DEFAULT_DISK_HEADROOM = 0.95     # refuse if capture would exceed 95% of free
+DEFAULT_SEGMENT_SECONDS = None   # None = single file; set for rolling segments
+
+# ---- external binaries ------------------------------------------------------
+# Resolved via shutil.which by default; override the directory in config for
+# Windows installs where hackrf-tools aren't on PATH.
+TOOLS = {
+    "info": "hackrf_info",
+    "transfer": "hackrf_transfer",
+    "sweep": "hackrf_sweep",
+    "clock": "hackrf_clock",
+    "spiflash": "hackrf_spiflash",
+    "operacake": "hackrf_operacake",
+    "cpldjtag": "hackrf_cpldjtag",
+    "debug": "hackrf_debug",
+}
+
+# Tools that accept `-d <serial>` for multi-board selection. hackrf_info
+# always lists every board and hackrf_cpldjtag predates the convention, so
+# both are excluded; HackRF(serial=...) injects -d for the rest.
+TOOLS_WITH_SERIAL = ("transfer", "sweep", "clock", "spiflash",
+                     "operacake", "debug")
+
+# The minimum set required for the common capture/sweep workflow. doctor()
+# treats only these as hard problems when missing; the rest are optional
+# device-management extras that not every install ships.
+CORE_TOOLS = ("info", "transfer", "sweep")
+
+# ---- operating modes --------------------------------------------------------
+MODE_RX = "rx"
+MODE_TX = "tx"
+MODES = (MODE_RX, MODE_TX)
+DEFAULT_MODE = MODE_RX
+
+# CLI state-file location (mode persists across invocations here).
+STATE_DIR_NAME = "hackrfpy"
+STATE_FILE_NAME = "state.toml"