hackrfpy 1.0.0__py3-none-any.whl

hackrfpy/exceptions.py

@@ -0,0 +1,43 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/exceptions.py'
+#
+#   Typed exception hierarchy. The API layer (core + mixins) RAISES these;
+#   the CLI layer catches the base class once in main() and pretty-prints to
+#   stderr with a clean exit code. Importing scripts get real, catchable
+#   exceptions instead of sentinel return values.
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+
+class HackRFError(Exception):
+    """Base for everything this library raises. Catch this to catch all."""
+    exit_code = 1
+
+
+class HackRFValueError(HackRFError):
+    """A parameter is outside the operating envelope (freq, sample rate, gain).
+    Raised by the validation layer when reject-by-default fires and --force
+    was not given."""
+    exit_code = 2
+
+
+class HackRFModeError(HackRFError):
+    """An operation was attempted in the wrong mode -- e.g. transmit() while
+    the device is in RX mode. Switch modes first (the deliberate TX gate)."""
+    exit_code = 3
+
+
+class HackRFDeviceError(HackRFError):
+    """The device or its tooling failed: a hackrf_* binary is missing, no board
+    was found, or a subprocess exited non-zero."""
+    exit_code = 4
+
+
+class HackRFEnvironmentError(HackRFError):
+    """The host environment can't support the request: insufficient disk for a
+    capture, missing permissions, etc. Surfaced mostly by doctor/estimator."""
+    exit_code = 5

hackrfpy/presets.py

@@ -0,0 +1,68 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/presets.py'
+#
+#   Band / frequency presets. These are a USER CONVENIENCE for scanning and
+#   selecting -- named center/edge frequencies and sensible sample rates so you
+#   don't memorize numbers. They are NOT a TX gate; transmit uses the full
+#   device range regardless of presets.
+#
+#   Built-ins can be extended/overridden from a user TOML
+#   (~/.config/hackrfpy/presets.toml) via load_presets().
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+import os
+
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # pragma: no cover
+    tomllib = None
+
+# Each preset: center or (f_min, f_max) for sweeps, plus a default sample rate.
+BUILTIN_PRESETS = {
+    "fm":       {"f_min": 88_000_000,   "f_max": 108_000_000, "sample_rate": 10_000_000,
+                 "desc": "FM broadcast band"},
+    "airband":  {"f_min": 118_000_000,  "f_max": 137_000_000, "sample_rate": 8_000_000,
+                 "desc": "VHF airband (AM voice)"},
+    "ads-b":    {"center": 1_090_000_000, "sample_rate": 8_000_000,
+                 "desc": "ADS-B (1090 MHz)"},
+    "ism-433":  {"center": 433_920_000, "sample_rate": 2_000_000,
+                 "desc": "433 MHz ISM"},
+    "ism-915":  {"center": 915_000_000, "sample_rate": 8_000_000,
+                 "desc": "915 MHz ISM (US)"},
+    "noaa-apt": {"f_min": 137_000_000,  "f_max": 138_000_000, "sample_rate": 2_000_000,
+                 "desc": "NOAA weather satellites"},
+    "gps-l1":   {"center": 1_575_420_000, "sample_rate": 10_000_000,
+                 "desc": "GPS L1"},
+}
+
+
+def _config_path():
+    base = os.environ.get("XDG_CONFIG_HOME",
+                          os.path.join(os.path.expanduser("~"), ".config"))
+    return os.path.join(base, "hackrfpy", "presets.toml")
+
+
+def load_presets():
+    # Built-ins overlaid with the user's TOML (user wins on key collisions).
+    presets = {k: dict(v) for k, v in BUILTIN_PRESETS.items()}
+    path = _config_path()
+    if tomllib and os.path.isfile(path):
+        with open(path, "rb") as f:
+            user = tomllib.load(f)
+        for name, cfg in user.get("presets", {}).items():
+            presets[name] = cfg
+    return presets
+
+
+def get_preset(name):
+    presets = load_presets()
+    if name not in presets:
+        from .exceptions import HackRFValueError
+        raise HackRFValueError(
+            f"unknown preset {name!r}; known: {', '.join(sorted(presets))}")
+    return presets[name]

hackrfpy/sigmf.py

@@ -0,0 +1,72 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/sigmf.py'
+#
+#   Minimal SigMF metadata writer. Writes a '<capture>.sigmf-meta' sidecar so
+#   recordings are self-describing instead of headerless int8 blobs. Follows
+#   the SigMF core namespace; HackRF native format is interleaved signed 8-bit
+#   I/Q -> datatype "ci8".
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+import json
+import os
+from datetime import datetime, timezone
+
+
+def write_sigmf_meta(data_path, freq, sample_rate, *, lna=None, vga=None,
+                     amp=None, datatype="ci8", extra=None):
+    # Sidecar path: foo.iq -> foo.sigmf-meta
+    base, _ = os.path.splitext(data_path)
+    meta_path = base + ".sigmf-meta"
+
+    hw = "HackRF One"
+    annotations_gains = {}
+    if lna is not None:
+        annotations_gains["hackrf:lna_gain_db"] = lna
+    if vga is not None:
+        annotations_gains["hackrf:vga_gain_db"] = vga
+    if amp is not None:
+        annotations_gains["hackrf:amp_enabled"] = bool(amp)
+
+    meta = {
+        "global": {
+            "core:datatype": datatype,
+            "core:sample_rate": float(sample_rate),
+            "core:hw": hw,
+            "core:version": "1.0.0",
+            "core:recorder": "hackrfpy",
+            **annotations_gains,
+        },
+        "captures": [
+            {
+                "core:sample_start": 0,
+                "core:frequency": float(freq),
+                "core:datetime": datetime.now(timezone.utc).isoformat(),
+            }
+        ],
+        "annotations": [],
+    }
+    if extra:
+        meta["global"].update(extra)
+
+    with open(meta_path, "w") as f:
+        json.dump(meta, f, indent=2)
+    return meta_path
+
+
+def read_sigmf_meta(path: str) -> dict:
+    """Read a .sigmf-meta sidecar back into a dict.
+
+    Accepts either the meta path itself or the data path (foo.iq is mapped
+    to foo.sigmf-meta). The reader half of write_sigmf_meta so consuming
+    code can recover frequency / sample rate / gains without re-parsing.
+    """
+    if not path.endswith(".sigmf-meta"):
+        base, _ = os.path.splitext(path)
+        path = base + ".sigmf-meta"
+    with open(path) as f:
+        return json.load(f)

hackrfpy-1.0.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: hackrfpy
+Version: 1.0.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: 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
+Requires-Dist: numpy>=1.26
+Requires-Dist: matplotlib ; extra == 'plotting'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/LC-Linkous/hackRF_python
+Project-URL: Issues, https://github.com/LC-Linkous/hackRF_python/issues
+Project-URL: Repository, https://github.com/LC-Linkous/hackRF_python
+Provides-Extra: plotting
+Description-Content-Type: text/markdown
+
+# hackrfpy
+
+**An Unofficial Python CLI + Scripting Wrapper for the HackRF One that works on Windows**
+
+[![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/)
+[![Downloads](https://static.pepy.tech/badge/hackrfpy)](https://pepy.tech/project/hackrfpy)
+[![License: GPL v2](https://img.shields.io/badge/License-GPL_v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
+
+A non-GUI Python wrapper and command-line tool for the HackRF One software-defined radio. This library provides programmatic control for IQ capture, spectrum sweeps, and transmit, with self-describing SigMF recordings.
+
+Unlike libraries that bind to `libhackrf` through C extensions, hackrfpy runs the standard `hackrf-tools` command-line binaries (`hackrf_info`, `hackrf_transfer`, `hackrf_sweep`, and the device-management tools) as subprocesses. Nothing has to be compiled, which is what makes it practical to install and run on Windows. The cost is that the `hackrf-tools` binaries are a **system** dependency you install separately; see [Installation](#installation).
+
+This repository uses official resources and documentation but is **NOT** endorsed by Great Scott Gadgets or the HackRF project. Refer to official resources and support for product information.
+
+## Features
+
+- **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
+- **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
+- **CLI** — the `hrf` command-line shell over the full API
+
+## Installation
+
+```bash
+pip install hackrfpy
+```
+
+The library itself depends only on `numpy`. The plotting examples need an optional extra:
+
+```bash
+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:
+
+- **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.
+
+Verify the install with `hackrf_info`.
+
+## Quick Start
+
+```python
+from hackrfpy import HackRF
+
+h = HackRF()
+det = h.detect()
+if det["ready"]:
+    print(h.identify())
+```
+
+To collect a bounded IQ capture as a normalized `complex64` array:
+
+```python
+from hackrfpy import HackRF
+
+h = HackRF()
+iq = h.capture_array(433.92e6, 8e6, num_samples=1_000_000)   # 433.92 MHz, 8 Msps
+print(iq.dtype, len(iq))                                      # complex64, 1000000
+```
+
+To run a single spectrum sweep:
+
+```python
+from hackrfpy import HackRF
+
+h = HackRF()
+rows = h.sweep_collect(88e6, 108e6, num_sweeps=1)   # FM broadcast band
+for r in rows:
+    print(r["hz_low"], r["hz_high"], min(r["db"]), max(r["db"]))
+```
+
+## 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:
+
+```python
+from hackrfpy import HackRF
+
+h = HackRF()
+h.set_mode("tx")                # prints the TX-mode safety banner
+h.transmit(433.92e6, 8e6, "signal.iq", txvga=20)
+```
+
+**Transmitting is regulated.** You are responsible for operating within the law and within your equipment's limits.
+
+## Examples
+
+The [main GitHub repository](https://github.com/LC-Linkous/hackRF_python) provides runnable examples, grouped by what they demonstrate.
+
+**Getting started / device control**
+
+- `device_explorer.py` — detect, identify, and report board capabilities (read-only)
+- `capture_to_file.py` — bounded capture to a file with a SigMF sidecar, then read it back
+
+**Acquisition**
+
+- `persistent_capture.py` — collect many segments at one frequency from a single long-lived process
+- `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
+
+**Sweep and plotting**
+
+- `sweep_collect.py` — one sweep across a band, saved to CSV
+- `waterfall_realtime.py` — a live, continuously updating spectrum waterfall
+- `waterfall_persistent.py` — a single-frequency FFT waterfall over time
+
+**Calibration and benchmarking**
+
+- `calibrate.py` — derive an `offset_db` and frequency-response curve for relative-power readings
+- `benchmark.py` — measure decode throughput and callback latency on your hardware
+
+**Sample data**
+
+- `collect_sample_data.py` — collect real IQ + sweep datasets (read-only; never transmits)
+
+> 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:
+
+- **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)
+
+## Contributing
+
+This is an unofficial community project. Contributions welcome!
+
+- Report bugs and request features on [GitHub](https://github.com/LC-Linkous/hackRF_python)
+- 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.
+
+## Citing
+
+If you use this library in your work, citation details are in the repository's `CITATION.cff`.
+
+## License
+
+GPL-2.0 — this package and the repo code is unofficial software with no warranty, offered AS-IS. Use at your own risk.
+
+The licensing of this software does NOT take priority over the official releases and the decisions of Great Scott Gadgets, and does NOT apply to any of their products or firmware.
+
+## Acknowledgments
+
+- Great Scott Gadgets and the HackRF community, who created and maintain the device and its tools
+- Official HackRF documentation and resources, especially [hackrf.readthedocs.io](https://hackrf.readthedocs.io/)
+- All contributors to this library, including those who have contributed code and reached out with questions
+
+---
+
+**Disclaimer**: This software is unofficial and not supported by Great Scott Gadgets or the HackRF project. For official software and support, visit [hackrf.readthedocs.io](https://hackrf.readthedocs.io/). The HackRF makers do not offer tech support for this software, do not maintain it, and have no responsibility for any of the contents.

hackrfpy-1.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+hackrfpy/__init__.py,sha256=RLgE12IvGvDVMQKOh7ZneGDcbokSCoz-3j6MoqaCqv8,698
+hackrfpy/_commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hackrfpy/_commands/capture.py,sha256=zfQJK5zrA_KSjL6DmcdIeohqLJAPayD0EoXamPkvCA8,13123
+hackrfpy/_commands/device.py,sha256=ENeTspf1WdzJJsjvUkcs4kwrmxnzHU865pIHF5jhiaM,9449
+hackrfpy/_commands/info.py,sha256=p9J_QAsF4Zh1piUVUsb8VO2xIaLIujAfH0WWQu0hFpo,7688
+hackrfpy/_commands/sweep.py,sha256=j0xvbttiP2shNZkVWDA5iiYqfM4xs-6Ldyx6X3qVYRo,10450
+hackrfpy/_commands/transmit.py,sha256=cSNlMhJ-Q7YCrsmBeDYePe77wLAC06Yi8hKdOwWNv9w,5037
+hackrfpy/_receiver.py,sha256=iu6Gud9We8eH4ZOR6D0EUQ9eYuzEqJsmscMY7IIHyTE,6257
+hackrfpy/_stream_ctx.py,sha256=woDXoC82OP3D195T89vf6qpaQIzHF6AAl3FBFJWYt9g,940
+hackrfpy/cli.py,sha256=BuTcr47Oz30YM5HrJVGwy6qWjfgRJh57voK31GJQRxA,12379
+hackrfpy/comparison.md,sha256=FXMV3OxRmijJAdjNvJMIk4nbPwiqup_dAQ5oawXatyk,10981
+hackrfpy/constants.py,sha256=r2hFbRqa6a2Z5DCWF5GKdfrS5edkSjP6DzbIa-crLJU,4786
+hackrfpy/core.py,sha256=PMO7ISzrG2DYRsAYFa6RczNl47wULcjanfoG5VAt9Jc,33216
+hackrfpy/exceptions.py,sha256=kXKHe9MPrV3CyT01pG-rkgsY1q24gKvBFV7xZh6Eh-8,1493
+hackrfpy/presets.py,sha256=9F4nWlfZ61_dfwmTx6JaMxIY-L8O32FHngOFAz0zeKw,2573
+hackrfpy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hackrfpy/sigmf.py,sha256=t4sk3CeuzAVog9vYgqyV2FEN7HIc26TRZl7E0lKV7r0,2275
+hackrfpy-1.0.0.dist-info/licenses/LICENSE,sha256=gXf5dRMhNSbfLPYYTY_5hsZ1r7UU1OaKQEAQUhuIBkM,18092
+hackrfpy-1.0.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+hackrfpy-1.0.0.dist-info/entry_points.txt,sha256=Xbr4o5v7gokphyoAOXj3Dmw9DKV668ddp7U5VZ8Nzn8,43
+hackrfpy-1.0.0.dist-info/METADATA,sha256=RMmEjfhJ2vbp9_R8Wqo4yfpAl76544lKCbJDm0VZN5c,8453
+hackrfpy-1.0.0.dist-info/RECORD,,

hackrfpy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

hackrfpy-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+hrf = hackrfpy.cli:main
+