Skip to content

Commit e2c685f

Browse files
LC-LinkousLC-Linkous
committed
pypi page readme
1 parent a1b1740 commit e2c685f

1 file changed

Lines changed: 162 additions & 0 deletions

File tree

‎hackrfpy/README.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# hackrfpy
2+
3+
**An Unofficial Python CLI + Scripting Wrapper for the HackRF One that works on Windows**
4+
5+
[![PyPI version](https://badge.fury.io/py/hackrfpy.svg)](https://badge.fury.io/py/hackrfpy)
6+
[![Python versions](https://img.shields.io/pypi/pyversions/hackrfpy.svg)](https://pypi.org/project/hackrfpy/)
7+
[![PyPI - Wheel](https://img.shields.io/pypi/wheel/hackrfpy.svg)](https://pypi.org/project/hackrfpy/)
8+
[![Downloads](https://static.pepy.tech/badge/hackrfpy)](https://pepy.tech/project/hackrfpy)
9+
[![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)
10+
11+
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.
12+
13+
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).
14+
15+
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.
16+
17+
## Features
18+
19+
- **Device Discovery** — detect and identify connected HackRF boards, report firmware and identity
20+
- **IQ Capture** — bounded, timed, streaming, or callback-style receive; decoded to normalized `complex64`
21+
- **Spectrum Sweep** — collect or stream `hackrf_sweep` output across a frequency range
22+
- **Transmit** — file playback and constant-wave test mode, behind a deliberate TX-mode gate
23+
- **Operating Envelope** — per-parameter range checks and gain snapping against the device's real steps
24+
- **SigMF Recordings** — self-describing `.iq` captures with metadata sidecars
25+
- **Error Handling** — a typed exception hierarchy and verbose output options
26+
- **CLI** — the `hrf` command-line shell over the full API
27+
28+
## Installation
29+
30+
```bash
31+
pip install hackrfpy
32+
```
33+
34+
The library itself depends only on `numpy`. The plotting examples need an optional extra:
35+
36+
```bash
37+
pip install "hackrfpy[plotting]"
38+
```
39+
40+
Python 3.11+ is required.
41+
42+
**You also need the `hackrf-tools` binaries**, which are *not* a pip dependency — they are installed at the OS level:
43+
44+
- **Linux:** `sudo apt install hackrf` (or your distribution's equivalent)
45+
- **macOS:** `brew install hackrf`
46+
- **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.
47+
48+
Verify the install with `hackrf_info`.
49+
50+
## Quick Start
51+
52+
```python
53+
from hackrfpy import HackRF
54+
55+
h = HackRF()
56+
det = h.detect()
57+
if det["ready"]:
58+
print(h.identify())
59+
```
60+
61+
To collect a bounded IQ capture as a normalized `complex64` array:
62+
63+
```python
64+
from hackrfpy import HackRF
65+
66+
h = HackRF()
67+
iq = h.capture_array(433.92e6, 8e6, num_samples=1_000_000) # 433.92 MHz, 8 Msps
68+
print(iq.dtype, len(iq)) # complex64, 1000000
69+
```
70+
71+
To run a single spectrum sweep:
72+
73+
```python
74+
from hackrfpy import HackRF
75+
76+
h = HackRF()
77+
rows = h.sweep_collect(88e6, 108e6, num_sweeps=1) # FM broadcast band
78+
for r in rows:
79+
print(r["hz_low"], r["hz_high"], min(r["db"]), max(r["db"]))
80+
```
81+
82+
## Transmitting
83+
84+
Transmit is gated behind an explicit mode switch, because an accidental transmit is the one operation that can damage equipment or break the law:
85+
86+
```python
87+
from hackrfpy import HackRF
88+
89+
h = HackRF()
90+
h.set_mode("tx") # prints the TX-mode safety banner
91+
h.transmit(433.92e6, 8e6, "signal.iq", txvga=20)
92+
```
93+
94+
**Transmitting is regulated.** You are responsible for operating within the law and within your equipment's limits.
95+
96+
## Examples
97+
98+
The [main GitHub repository](https://github.com/LC-Linkous/hackRF_python) provides runnable examples, grouped by what they demonstrate.
99+
100+
**Getting started / device control**
101+
102+
- `device_explorer.py` — detect, identify, and report board capabilities (read-only)
103+
- `capture_to_file.py` — bounded capture to a file with a SigMF sidecar, then read it back
104+
105+
**Acquisition**
106+
107+
- `persistent_capture.py` — collect many segments at one frequency from a single long-lived process
108+
- `power_meter.py` — live dBFS power meter at one frequency via the callback API
109+
- `scan_then_capture.py` — sweep a band, find the strongest bin, then capture there
110+
111+
**Sweep and plotting**
112+
113+
- `sweep_collect.py` — one sweep across a band, saved to CSV
114+
- `waterfall_realtime.py` — a live, continuously updating spectrum waterfall
115+
- `waterfall_persistent.py` — a single-frequency FFT waterfall over time
116+
117+
**Calibration and benchmarking**
118+
119+
- `calibrate.py` — derive an `offset_db` and frequency-response curve for relative-power readings
120+
- `benchmark.py` — measure decode throughput and callback latency on your hardware
121+
122+
**Sample data**
123+
124+
- `collect_sample_data.py` — collect real IQ + sweep datasets (read-only; never transmits)
125+
126+
> Most plotting examples require the optional plotting dependencies:
127+
> `pip install "hackrfpy[plotting]"`
128+
129+
## Documentation
130+
131+
For comprehensive documentation, the full method reference, the CLI reference, and the operating envelope:
132+
133+
- **Library GitHub repository**: [https://github.com/LC-Linkous/hackRF_python/](https://github.com/LC-Linkous/hackRF_python/)
134+
- **Official HackRF documentation**: [https://hackrf.readthedocs.io/](https://hackrf.readthedocs.io/) (not associated with this library)
135+
136+
## Contributing
137+
138+
This is an unofficial community project. Contributions welcome!
139+
140+
- Report bugs and request features on [GitHub](https://github.com/LC-Linkous/hackRF_python)
141+
- For device information and OFFICIAL resources, see [https://hackrf.readthedocs.io/](https://hackrf.readthedocs.io/)
142+
- 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.
143+
144+
## Citing
145+
146+
If you use this library in your work, citation details are in the repository's `CITATION.cff`.
147+
148+
## License
149+
150+
GPL-2.0 — this package and the repo code is unofficial software with no warranty, offered AS-IS. Use at your own risk.
151+
152+
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.
153+
154+
## Acknowledgments
155+
156+
- Great Scott Gadgets and the HackRF community, who created and maintain the device and its tools
157+
- Official HackRF documentation and resources, especially [hackrf.readthedocs.io](https://hackrf.readthedocs.io/)
158+
- All contributors to this library, including those who have contributed code and reached out with questions
159+
160+
---
161+
162+
**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.

0 commit comments

Comments
 (0)