hackrfpy 1.0.0__py3-none-any.whl

hackrfpy/_commands/sweep.py

@@ -0,0 +1,219 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/_commands/sweep.py'
+#
+#   SweepMixin: spectrum sweep via hackrf_sweep. hackrf_sweep emits CSV to
+#   stdout continuously until stopped, so this is the streaming/generator case
+#   -- the analog of a continuous-acquisition loop. Each CSV row is:
+#     date, time, hz_low, hz_high, hz_bin_width, num_samples, dB, dB, ...
+#   We yield parsed rows so the caller can plot/store/decode as they arrive.
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+from .. import constants as C
+
+
+class SweepMixin:
+    def sweep(self, f_min_hz, f_max_hz, *, bin_width=None, lna=16, vga=20,
+              amp=False, one_shot=False, num_sweeps=None, print_cmd=False):
+        # GENERATOR yielding parsed rows (dicts). Validate the band edges with
+        # the same hard-range logic, snap gains. hackrf_sweep takes the range
+        # in MHz as f_min:f_max.
+        f_min_hz = self._check_hard_range("f_min", f_min_hz,
+                                          C.FREQ_MIN_HZ, C.FREQ_MAX_HZ)
+        f_max_hz = self._check_hard_range("f_max", f_max_hz,
+                                          C.FREQ_MIN_HZ, C.FREQ_MAX_HZ)
+        if f_min_hz >= f_max_hz:
+            from ..exceptions import HackRFValueError
+            raise HackRFValueError("f_min must be < f_max")
+        lna = self._snap_gain("lna_gain", lna, C.LNA_GAIN)
+        vga = self._snap_gain("vga_gain", vga, C.VGA_GAIN)
+        self._record_params(f_min=f_min_hz, f_max=f_max_hz, lna=lna, vga=vga,
+                            amp=amp, bin_width=bin_width, mode="rx")
+        self.print_message(f"[*] mode: {self.mode}")
+
+        lo = int(f_min_hz // 1_000_000)
+        hi = int(f_max_hz // 1_000_000)
+        # hackrf_sweep takes integer MHz edges, so sub-MHz precision is lost.
+        # Warn rather than silently shift the band the user asked for.
+        if f_min_hz % 1_000_000 or f_max_hz % 1_000_000:
+            self.warn(
+                f"sweep edges snapped to MHz: "
+                f"{f_min_hz/1e6:g}:{f_max_hz/1e6:g} -> {lo}:{hi} MHz "
+                f"(hackrf_sweep takes integer MHz)")
+        argv = ["sweep", "-f", f"{lo}:{hi}", "-l", lna, "-g", vga,
+                "-a", 1 if amp else 0]
+        if bin_width is not None:
+            argv += ["-w", int(bin_width)]
+        if one_shot:
+            argv += ["-1"]
+        if num_sweeps is not None:
+            argv += ["-N", int(num_sweeps)]
+
+        if print_cmd:
+            self._run(argv, mode="blocking", print_cmd=True)
+            return
+
+        def _gen():
+            # Explicitly close the inner stream generator on the way out.
+            # Relying on GC to do it is not deterministic, and an unclosed
+            # inner generator leaves hackrf_sweep running ORPHANED after the
+            # caller breaks out of the loop.
+            #
+            # NOTE on ordering: real hackrf_sweep does NOT emit frequency
+            # segments low-to-high -- it interleaves them (observed: 88, 98,
+            # 93, 103 MHz for an 88:108 sweep). All rows of ONE sweep share a
+            # timestamp. Consumers that need a contiguous spectrum must group
+            # by timestamp and sort segments by hz_low; do NOT assume the rows
+            # arrive in frequency order.
+            inner = self._run(argv, mode="stream", text=True)
+            try:
+                for line in inner:
+                    row = self.parse_sweep_line(line)
+                    if row is not None:
+                        yield row
+            finally:
+                inner.close()
+        return _gen()
+
+    def sweep_collect(self, f_min_hz, f_max_hz, num_sweeps=1, **k):
+        # Convenience: collect a bounded number of sweeps into a list.
+        k.pop("num_sweeps", None)
+        return list(self.sweep(f_min_hz, f_max_hz, num_sweeps=num_sweeps, **k))
+
+    def monitor_frequencies(self, freqs_hz, *, span_hz=2_000_000, duration=None,
+                            on_update=None, lna=16, vga=20, amp=False):
+        # Watch POWER over time at several frequencies, backed by hackrf_sweep's
+        # fast internal hardware retuning. This is DELIBERATELY a different
+        # method from scan_frequencies():
+        #   - scan_frequencies() returns IQ SAMPLES (complex64) per frequency,
+        #     via separate hackrf_transfer captures (re-open gap between each).
+        #   - monitor_frequencies() returns POWER (dB) per frequency over time,
+        #     via one continuous hackrf_sweep. No IQ -- spectrum bins only.
+        # Use this for "is there activity on these channels?" monitoring; use
+        # scan_frequencies for "give me the samples at each frequency."
+        #
+        # Yields dicts: {freq_hz: power_db, ...} once per sweep pass, mapping
+        # each requested frequency to the dB of the sweep bin covering it.
+        # Runs until `duration` seconds elapse, on_update returns False, or the
+        # caller stops iterating (the underlying sweep is reaped on exit).
+        import time as _time
+        lo = min(freqs_hz) - span_hz
+        hi = max(freqs_hz) + span_hz
+        t0 = _time.time()
+
+        def _nearest_power(rows_by_low, f):
+            # find the sweep segment whose [hz_low, hz_high) covers f, return
+            # the mean dB of that segment's bins (a simple power proxy)
+            for low in sorted(rows_by_low):
+                r = rows_by_low[low]
+                if r["hz_low"] <= f < r["hz_high"]:
+                    db = r["db"]
+                    return sum(db) / len(db) if db else float("-inf")
+            return None
+
+        from .._stream_ctx import StreamCtx
+        results = []
+        stopped = False
+        with StreamCtx(self.sweep(lo, hi, lna=lna, vga=vga, amp=amp)) as gen:
+            rows_by_low = {}
+            last_time = None
+            for row in gen:
+                if last_time is not None and row["time"] != last_time and rows_by_low:
+                    update = {f: _nearest_power(rows_by_low, f) for f in freqs_hz}
+                    if on_update is not None:
+                        if on_update(update) is False:
+                            stopped = True
+                            break
+                    else:
+                        results.append(update)
+                    rows_by_low = {}
+                    if duration is not None and _time.time() - t0 >= duration:
+                        break
+                rows_by_low[row["hz_low"]] = row
+                last_time = row["time"]
+            # flush the final buffered pass (stream ended before its timestamp
+            # rolled over) -- unless we were explicitly stopped by on_update
+            if rows_by_low and not stopped:
+                update = {f: _nearest_power(rows_by_low, f) for f in freqs_hz}
+                if on_update is not None:
+                    on_update(update)
+                else:
+                    results.append(update)
+        return None if on_update is not None else results
+
+    def sweep_to_file(self, f_min_hz, f_max_hz, out, *, binary=False,
+                      inverse_fft=False, bin_width=None, lna=16, vga=20,
+                      amp=False, one_shot=False, num_sweeps=None,
+                      print_cmd=False):
+        # Write sweep output straight to a file instead of yielding parsed
+        # rows. This is the home for hackrf_sweep's binary-output flags, which
+        # don't fit the text-CSV generator:
+        #   binary=True       -> -B  raw binary FFT-bin output
+        #   inverse_fft=True  -> -I  binary inverse-FFT output (implies binary)
+        # With neither, this writes the normal CSV text to the file via -r.
+        # Returns the output path. The binary formats are NOT parsed by this
+        # library (parse_sweep_line is text-only); you own the format on read.
+        f_min_hz = self._check_hard_range("f_min", f_min_hz,
+                                          C.FREQ_MIN_HZ, C.FREQ_MAX_HZ)
+        f_max_hz = self._check_hard_range("f_max", f_max_hz,
+                                          C.FREQ_MIN_HZ, C.FREQ_MAX_HZ)
+        if f_min_hz >= f_max_hz:
+            from ..exceptions import HackRFValueError
+            raise HackRFValueError("f_min must be < f_max")
+        lna = self._snap_gain("lna_gain", lna, C.LNA_GAIN)
+        vga = self._snap_gain("vga_gain", vga, C.VGA_GAIN)
+        lo = int(f_min_hz // 1_000_000)
+        hi = int(f_max_hz // 1_000_000)
+        argv = ["sweep", "-f", f"{lo}:{hi}", "-l", lna, "-g", vga,
+                "-a", 1 if amp else 0, "-r", out]
+        if bin_width is not None:
+            argv += ["-w", int(bin_width)]
+        if one_shot:
+            argv += ["-1"]
+        if num_sweeps is not None:
+            argv += ["-N", int(num_sweeps)]
+        if inverse_fft:
+            argv += ["-I"]          # binary inverse FFT (binary output mode)
+        elif binary:
+            argv += ["-B"]          # raw binary output
+        res = self._run(argv, mode="blocking", print_cmd=print_cmd)
+        return None if print_cmd else out
+
+    def sweep_stream(self, f_min_hz, f_max_hz, **k):
+        # Context manager around the sweep generator so the underlying
+        # hackrf_sweep is ALWAYS reaped on exit -- including KeyboardInterrupt
+        # out of a live consumer loop (e.g. a waterfall). Without this, a
+        # caller that breaks out or Ctrl-C's relies on GC to close the
+        # generator, which can orphan the child:
+        #     with h.sweep_stream(88e6, 108e6) as rows:
+        #         for row in rows: ...
+        from .._stream_ctx import StreamCtx
+        gen = self.sweep(f_min_hz, f_max_hz, **k)
+        return StreamCtx(gen)
+
+    @staticmethod
+    def parse_sweep_line(line):
+        # Returns {date,time,hz_low,hz_high,bin_width,num_samples,db:[...]} or
+        # None for blank/garbled lines.
+        line = line.strip()
+        if not line:
+            return None
+        parts = [p.strip() for p in line.split(",")]
+        if len(parts) < 7:
+            return None
+        try:
+            return {
+                "date": parts[0],
+                "time": parts[1],
+                "hz_low": int(parts[2]),
+                "hz_high": int(parts[3]),
+                "bin_width": float(parts[4]),
+                "num_samples": int(parts[5]),
+                "db": [float(x) for x in parts[6:]],
+            }
+        except ValueError:
+            return None

hackrfpy/_commands/transmit.py

@@ -0,0 +1,104 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy
+#   'src/hackrfpy/_commands/transmit.py'
+#
+#   TransmitMixin: transmit via hackrf_transfer -t. Gated entirely by operating
+#   mode -- transmit() raises HackRFModeError unless the device is in TX mode.
+#   Switching to TX mode (set_mode/`hrf mode tx`) is the deliberate, one-time
+#   confirmation and prints the safety banner. Frequency uses the full device
+#   range and is never policed; the gain ceiling in constants.py guards against
+#   an order-of-magnitude fat-finger only.
+#
+#   Author(s): <you>
+##--------------------------------------------------------------------\
+
+from .. import constants as C
+
+
+class TransmitMixin:
+    def transmit(self, freq, sample_rate, source, *, txvga=20, amp=False,
+                 bias_tee=False, baseband_bw=None, repeat=False,
+                 num_samples=None, duration=None, max_duration=None,
+                 print_cmd=False):
+        # source: path to an int8 I/Q file to transmit.
+        # max_duration: hard ceiling (seconds) enforced even for open-ended
+        #   repeat transmits. A transmitter that runs until .stop() is a
+        #   regulatory + hardware risk if the controlling script dies; this
+        #   gives every transmit an optional dead-man bound.
+        self.require_mode(C.MODE_TX)          # the gate
+        freq, sample_rate, txvga, amp = self.validate_tx(
+            freq, sample_rate, txvga, amp)
+        bw = self._auto_baseband(sample_rate, baseband_bw)
+        self._record_params(freq=freq, sample_rate=sample_rate, txvga=txvga,
+                            amp=amp, baseband_bw=bw, mode="tx")
+        self.print_message(f"[*] mode: {self.mode}  (TX)")
+
+        argv = ["transfer", "-t", source,
+                "-f", int(freq), "-s", int(sample_rate),
+                "-x", txvga, "-a", 1 if amp else 0, "-b", int(bw)]
+        if bias_tee:
+            argv += ["-p", 1]
+        if repeat:
+            argv += ["-R"]
+        if num_samples is not None:
+            argv += ["-n", int(num_samples)]
+
+        # An explicit duration, or a max_duration ceiling on an otherwise
+        # open-ended repeat, both run as TIMED so the child is reaped on time.
+        effective_timed = duration if duration is not None else (
+            max_duration if repeat and num_samples is None else None)
+        if effective_timed is not None:
+            return self._run(argv, mode="timed", duration=effective_timed,
+                             print_cmd=print_cmd)
+        if num_samples is not None or not repeat:
+            # bounded by file length or -n; runs to completion
+            return self._run(argv, mode="blocking", print_cmd=print_cmd)
+        # repeat with no bound and no max_duration -> open-ended handle
+        if print_cmd:
+            self._run(argv, mode="blocking", print_cmd=True)
+            return None
+        self.warn("open-ended repeat transmit with no max_duration; "
+                  "caller must .stop() the returned handle.")
+        return self._run(argv, mode="handle", kind="tx")
+
+    # ---- aliases ----
+    def tx(self, *a, **k):
+        return self.transmit(*a, **k)
+
+    def transmit_file(self, freq, sample_rate, source, **k):
+        return self.transmit(freq, sample_rate, source, **k)
+
+    def transmit_cw(self, freq, sample_rate, *, amplitude=127, txvga=20,
+                    amp=False, bias_tee=False, baseband_bw=None,
+                    duration=None, max_duration=None, print_cmd=False):
+        # Constant-wave / signal-source test mode: hackrf_transfer -c <amp>.
+        # Transmits a fixed signal at `amplitude` (0-127) instead of a file.
+        # TX-gated like any transmit. Useful for antenna/range testing. Open-
+        # ended unless duration/max_duration bounds it (the dead-man applies).
+        self.require_mode(C.MODE_TX)
+        freq, sample_rate, txvga, amp = self.validate_tx(
+            freq, sample_rate, txvga, amp)
+        bw = self._auto_baseband(sample_rate, baseband_bw)
+        amplitude = max(0, min(int(amplitude), 127))
+        self._record_params(freq=freq, sample_rate=sample_rate, txvga=txvga,
+                            amp=amp, baseband_bw=bw, mode="tx", cw=amplitude)
+        self.print_message(f"[*] mode: {self.mode}  (TX, CW source)")
+
+        argv = ["transfer", "-c", amplitude,
+                "-f", int(freq), "-s", int(sample_rate),
+                "-x", txvga, "-a", 1 if amp else 0, "-b", int(bw)]
+        if bias_tee:
+            argv += ["-p", 1]
+
+        timed = duration if duration is not None else max_duration
+        if timed is not None:
+            return self._run(argv, mode="timed", duration=timed,
+                             print_cmd=print_cmd)
+        if print_cmd:
+            self._run(argv, mode="blocking", print_cmd=True)
+            return None
+        self.warn("open-ended CW transmit with no duration/max_duration; "
+                  "caller must .stop() the returned handle.")
+        return self._run(argv, mode="handle", kind="tx")

hackrfpy/_receiver.py

@@ -0,0 +1,151 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy  'src/hackrfpy/_receiver.py'
+#   Persistent fixed-frequency receiver. Opens ONE long-lived
+#   hackrf_transfer stream and serves decoded complex64 segments on demand,
+#   so you don't pay the ~1-2 s process spin-up for every capture. This is
+#   the data-collection answer to the per-capture startup cost measured by
+#   examples/benchmark.py.
+#
+#   ARCHITECTURAL HONESTY: hackrf_transfer cannot retune mid-stream, so this
+#   is FIXED-FREQUENCY by design. It is "start once, drain over time at one
+#   frequency", NOT "one process I can retune". For multiple frequencies use
+#   scan_frequencies (separate captures) or monitor_frequencies (sweep). True
+#   gapless retuning needs the C library.
+##--------------------------------------------------------------------\
+
+import numpy as np
+
+
+class PersistentReceiver:
+    # A long-lived RX stream at one frequency. Created via
+    # HackRF.open_receiver(...); use as a context manager so the child is
+    # always reaped:
+    #
+    #   with h.open_receiver(100e6, 8e6) as rx:
+    #       a = rx.read(1_000_000)        # exactly 1e6 complex64 samples
+    #       b = rx.read(1_000_000)        # again, NO new process spin-up
+    #       for block in rx.blocks():     # or iterate raw decoded blocks
+    #           ...
+    #
+    # The underlying hackrf_transfer is launched once on __enter__ (or first
+    # use) and runs continuously until close()/__exit__.
+    def __init__(self, hackrf, freq, sample_rate, *, lna=16, vga=20, amp=False,
+                 baseband_bw=None, read_samples=131072):
+        self._h = hackrf
+        self.freq = freq
+        self.sample_rate = sample_rate
+        self.lna = lna
+        self.vga = vga
+        self.amp = amp
+        self.baseband_bw = baseband_bw
+        self.read_samples = read_samples
+        self._gen = None            # the raw-bytes stream generator
+        self._carry = b""           # leftover bytes between reads (odd splits)
+        self._closed = False
+        self.total_samples = 0      # cumulative samples served
+
+    # ---- lifecycle ---------------------------------------------------------
+    def _ensure_open(self):
+        if self._gen is not None or self._closed:
+            return
+        h = self._h
+        # validate + snap exactly like capture() does, and record params so
+        # relative_power_db() etc. can read the gains back. validate_rx returns
+        # (freq, sample_rate, lna, vga); amp passes through untouched on RX.
+        freq, sample_rate, lna, vga = h.validate_rx(
+            self.freq, self.sample_rate, self.lna, self.vga)
+        amp = bool(self.amp)
+        bw = h._auto_baseband(sample_rate, self.baseband_bw)
+        self.freq, self.sample_rate = freq, sample_rate
+        self.lna, self.vga, self.amp = lna, vga, amp
+        h._record_params(freq=freq, sample_rate=sample_rate, lna=lna, vga=vga,
+                         amp=amp, baseband_bw=bw, mode="rx")
+        argv = ["transfer", "-r", "-", "-f", int(freq), "-s", int(sample_rate),
+                "-l", lna, "-g", vga, "-a", 1 if amp else 0, "-b", int(bw)]
+        # one long-lived stream; large read granularity for sustained rate
+        self._gen = h._run(argv, mode="stream", read_samples=self.read_samples)
+        # register on the live backstop so a dying script reaps it
+        from .core import _LIVE
+        try:
+            _LIVE.add(self)
+        except Exception:
+            pass
+
+    def __enter__(self):
+        self._ensure_open()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+        return False
+
+    def close(self):
+        if self._closed:
+            return
+        self._closed = True
+        if self._gen is not None:
+            try:
+                self._gen.close()       # interrupts + reaps the child
+            except Exception:
+                pass
+            self._gen = None
+        try:
+            from .core import _LIVE
+            _LIVE.discard(self)
+        except Exception:
+            pass
+
+    def stop(self):
+        # alias so PersistentReceiver works with the _LIVE backstop, which
+        # calls .stop() on whatever it holds
+        self.close()
+
+    # ---- data access -------------------------------------------------------
+    def read(self, n_samples):
+        # Return EXACTLY n_samples complex64 (or fewer if the stream ends).
+        # Pulls and decodes raw bytes from the persistent stream until it has
+        # enough; carries any partial trailing pair between calls. No new
+        # process is launched -- this is the whole point.
+        self._ensure_open()
+        need_bytes = int(n_samples) * 2          # 2 int8 per complex sample
+        buf = self._carry
+        for chunk in self._gen:
+            buf += chunk
+            if len(buf) >= need_bytes:
+                break
+        take = buf[:need_bytes]
+        self._carry = buf[need_bytes:]
+        # decode, dropping any odd trailing byte (shouldn't happen since we
+        # cut on an even boundary, but be safe)
+        iq = self._h.decode_iq(take)
+        self.total_samples += len(iq)
+        return iq
+
+    def blocks(self):
+        # Yield decoded complex64 blocks as they arrive (raw cadence), until
+        # the stream ends or the caller stops iterating. Good for a continuous
+        # consumer that doesn't need a fixed sample count per read.
+        self._ensure_open()
+        if self._carry:
+            lead = self._h.decode_iq(self._carry)
+            self._carry = b""
+            if len(lead):
+                self.total_samples += len(lead)
+                yield lead
+        for chunk in self._gen:
+            iq = self._h.decode_iq(chunk)
+            self.total_samples += len(iq)
+            yield iq
+
+    def callback(self, on_block, *, max_samples=None):
+        # Inverted loop over blocks(): call on_block(iq, total) per block;
+        # stop on False, on max_samples, or stream end.
+        for iq in self.blocks():
+            cont = on_block(iq, self.total_samples)
+            if cont is False:
+                break
+            if max_samples is not None and self.total_samples >= max_samples:
+                break
+        return self.total_samples

hackrfpy/_stream_ctx.py

@@ -0,0 +1,24 @@
+#! /usr/bin/python3
+
+##--------------------------------------------------------------------\
+#   hackrfpy  'src/hackrfpy/_stream_ctx.py'
+#   Shared context manager that guarantees a live capture/sweep generator
+#   is closed (and its child process reaped) on block exit, including on
+#   exception or KeyboardInterrupt. Used by capture_stream and sweep_stream.
+##--------------------------------------------------------------------\
+
+
+class StreamCtx:
+    # Wrap a live generator so its finally-block (which interrupts + reaps the
+    # hackrf_* child) runs on __exit__, even if the body raised. Iterable, so
+    # `for x in rows:` works directly on the bound name.
+    def __init__(self, gen):
+        self._gen = gen
+
+    def __enter__(self):
+        return self._gen
+
+    def __exit__(self, exc_type, exc, tb):
+        if self._gen is not None:
+            self._gen.close()
+        return False  # never suppress the caller's exception