hackrfpy 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hackrfpy
-Version: 1.1.0
+Version: 1.2.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

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

@@ -1,6 +1,6 @@
 [project]
 name = "hackrfpy"
-version = "1.1.0"
+version = "1.2.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"

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

@@ -3,7 +3,7 @@
 #   hackrfpy  'src/hackrfpy/__init__.py'
 #   Public API surface.
 ##--------------------------------------------------------------------\
-from .core import HackRF, load_iq, parse_freq
+from .core import HackRF, load_iq, encode_iq, parse_freq
 from .sigmf import write_sigmf_meta, read_sigmf_meta
 from .exceptions import (
     HackRFError, HackRFValueError, HackRFModeError,
@@ -18,7 +18,7 @@ except PackageNotFoundError:                     # running from a checkout
     __version__ = "0.0.0+unknown"
 
 __all__ = [
-    "HackRF", "load_iq", "parse_freq", "constants", "__version__",
+    "HackRF", "load_iq", "encode_iq", "parse_freq", "constants", "__version__",
     "write_sigmf_meta", "read_sigmf_meta",
     "HackRFError", "HackRFValueError", "HackRFModeError",
     "HackRFDeviceError", "HackRFEnvironmentError",

{hackrfpy-1.1.0 → hackrfpy-1.2.0}/src/hackrfpy/_commands/sweep.py

@@ -15,7 +15,9 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable, Generator
+from typing import Any, Callable, Generator, Iterable
+
+import numpy as np
 
 from .. import constants as C
 from .._host import HostOps
@@ -111,6 +113,90 @@ class SweepMixin(HostOps):
             return []
         return list(rows)
 
+    @staticmethod
+    def iter_sweep_passes(rows: Iterable[dict[str, Any]]
+                          ) -> Generator[dict[str, Any], None, None]:
+        """Group parsed sweep rows into whole passes, one contiguous array each.
+
+        Pure function over rows from sweep() / parse_sweep_line(); no device.
+        Yields, per pass:
+
+            {"start": hz, "stop": hz, "bin_width": hz, "points": n,
+             "level": np.ndarray[float32, n]   # ascending frequency,
+             "date": str, "time": str,         # first row of the pass
+             "segments": k, "contiguous": bool}
+
+        The pass boundary is SEGMENT REVISIT -- the same hz_low arriving
+        again -- never a timestamp change. Real hackrf_sweep stamps each row
+        individually, so a timestamp boundary flushes on nearly every row over
+        a wide span and emits partial spectra (this is what broke
+        monitor_frequencies on hardware before 1.1.0; a consumer that groups
+        by timestamp has the same bug). Segments arrive out of frequency
+        order and are sorted here. Bins a pass never covered (a gap between
+        segments, which hackrf_sweep does not normally produce) are NaN, and
+        "contiguous" is False, so a plot shows a hole rather than a lie.
+
+        A trailing partial pass (stream ended mid-pass) is yielded last with
+        whatever it has; check "segments" if that matters.
+        """
+        seen: set[int] = set()
+        batch: list[dict[str, Any]] = []
+        for row in rows:
+            low = int(row["hz_low"])
+            if low in seen:
+                yield SweepMixin._stitch_pass(batch)
+                seen.clear()
+                batch = []
+            seen.add(low)
+            batch.append(row)
+        if batch:
+            yield SweepMixin._stitch_pass(batch)
+
+    @staticmethod
+    def _stitch_pass(rows: list[dict[str, Any]]) -> dict[str, Any]:
+        rows = sorted(rows, key=lambda r: int(r["hz_low"]))
+        bw = float(rows[0]["bin_width"])
+        start = int(rows[0]["hz_low"])
+        stop = max(int(r["hz_high"]) for r in rows)
+        n = int(round((stop - start) / bw))
+        level = np.full(n, np.nan, dtype=np.float32)
+        covered = 0
+        for r in rows:
+            db = np.asarray(r["db"], dtype=np.float32)
+            i0 = int(round((int(r["hz_low"]) - start) / bw))
+            i1 = min(n, i0 + db.size)
+            level[i0:i1] = db[: i1 - i0]
+            covered += i1 - i0
+        return {"start": start, "stop": stop, "bin_width": bw, "points": n,
+                "level": level, "date": rows[0].get("date"),
+                "time": rows[0].get("time"), "segments": len(rows),
+                "contiguous": covered >= n}
+
+    def sweep_passes(self, f_min_hz: float, f_max_hz: float, *,
+                     bin_width: float | None = None,
+                     lna: int = 16, vga: int = 20, amp: bool = False,
+                     num_sweeps: int | None = None
+                     ) -> Generator[dict[str, Any], None, None]:
+        """Stream a sweep as whole passes: one stitched spectrum per pass.
+
+        sweep() with iter_sweep_passes() applied: the consumer gets a
+        contiguous, frequency-sorted float32 array per complete pass instead
+        of interleaved segments. Same validation, snapping and child
+        lifecycle as sweep(); break out of the loop (or close the generator)
+        to stop hackrf_sweep. Edges snap outward to whole MHz, so "start" and
+        "stop" are the swept edges, not the requested ones.
+        """
+        rows = self.sweep(f_min_hz, f_max_hz, bin_width=bin_width, lna=lna,
+                          vga=vga, amp=amp, num_sweeps=num_sweeps)
+        assert rows is not None               # print_cmd is not offered here
+
+        def _gen() -> Generator[dict[str, Any], None, None]:
+            try:
+                yield from SweepMixin.iter_sweep_passes(rows)
+            finally:
+                rows.close()                  # reaps hackrf_sweep on early exit
+        return _gen()
+
     def monitor_frequencies(self, freqs_hz: list[float], *,
                             span_hz: float = 2_000_000,
                             duration: float | None = None,

{hackrfpy-1.1.0 → hackrfpy-1.2.0}/src/hackrfpy/_receiver.py

@@ -173,17 +173,22 @@ class PersistentReceiver:
         # 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.
+        # An odd-length chunk splits an I/Q pair across two reads. decode_iq
+        # DROPS an odd trailing byte, and dropping one byte here would swap
+        # I and Q for every sample that follows (capture()'s stream path
+        # carries the byte for exactly this reason). The read1() cap in
+        # _run is even, but a pipe is free to return fewer bytes than
+        # asked, so the odd case is real. Carry the byte in self._carry,
+        # the same buffer read() uses, so blocks() and read() can be mixed.
         gen = 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 gen:
-            iq = self._h.decode_iq(chunk)
-            self.total_samples += len(iq)
-            yield iq
+            buf = self._carry + chunk
+            cut = len(buf) - (len(buf) % 2)
+            self._carry = buf[cut:]
+            if cut:
+                iq = self._h.decode_iq(buf[:cut])
+                self.total_samples += len(iq)
+                yield iq
 
     def callback(self, on_block: Callable[[np.ndarray, int], Any], *,
                  max_samples: int | None = None) -> int:

{hackrfpy-1.1.0 → hackrfpy-1.2.0}/src/hackrfpy/constants.py

@@ -45,6 +45,18 @@ TXVGA_GAIN = (0, 47, 1)          # TX IF gain
 # Front-end amplifier is a fixed ~14 dB block, on/off only.
 AMP_DB = 14
 
+# ---- recommended starting gains for a receive capture ----------------------
+# The API defaults (lna=16, vga=20 on capture()/open_receiver()/sweep()) are
+# unchanged for compatibility, but they are LOW: on 2026-09-17 a typical
+# antenna at 16/20 produced captures spanning only +/-4 of the 127 int8 codes
+# (effectively 3-bit recordings) that passed every power check. The collection
+# tools moved to 32/28 and so should any new consumer. Reference these BY NAME
+# rather than copying the numbers, so a future revision reaches everyone.
+# Tune per band from here; a short probe through a capture-health check tells
+# you whether the ADC is under-driven or clipping.
+RECOMMENDED_LNA = 32             # dB, on the LNA_GAIN steps
+RECOMMENDED_VGA = 28             # dB, on the VGA_GAIN steps
+
 # ---- 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

{hackrfpy-1.1.0 → hackrfpy-1.2.0}/src/hackrfpy/core.py

@@ -976,6 +976,15 @@ class HackRF(InfoMixin, CaptureMixin, TransmitMixin, SweepMixin, DeviceMixin):
         iq /= 128.0          # normalize int8 full-scale to ~[-1, 1)
         return iq
 
+    @staticmethod
+    def encode_iq(iq: np.ndarray) -> bytes:
+        """Encode complex samples to HackRF-native interleaved int8 bytes.
+
+        The inverse of decode_iq: see the module-level encode_iq() for the
+        contract. Provided on the class for symmetry with decode_iq.
+        """
+        return encode_iq(iq)
+
     # ---- power / relative calibration (Level 1) ----------------------------
     # These turn the device's arbitrary dBFS amplitude into something that is
     # at least CONSISTENT across gain settings (and, with a user-supplied
@@ -1127,3 +1136,28 @@ def load_iq(path: str, count: int | None = None,
     iq.imag = a[1::2]
     iq /= 128.0
     return iq
+
+
+def encode_iq(iq: np.ndarray) -> bytes:
+    """Encode complex samples to HackRF-native interleaved int8 I/Q bytes.
+
+    The exact inverse of decode_iq() / load_iq() for anything they produced:
+    those divide by 128, this multiplies by 128, rounds to nearest, and clips
+    to the int8 range, so decode -> encode -> decode is lossless and a
+    recording re-encoded from decoded blocks is byte-identical to the stream
+    (the property hackrf-web's recorder relies on). For arbitrary complex
+    input it is the natural quantiser: +1.0 clips to 127, -1.0 maps to -128.
+
+    Returns bytes laid out I0, Q0, I1, Q1, ... -- the format hackrf_transfer
+    reads for -t and writes for -r, and the SigMF "ci8" datatype.
+    """
+    iq = np.asarray(iq)
+    if iq.ndim != 1:
+        raise HackRFValueError(
+            f"encode_iq expects a 1-D complex array, got shape {iq.shape}")
+    out = np.empty(2 * iq.size, dtype=np.int8)
+    # rint, not astype: astype truncates toward zero and would bias every
+    # sample toward 0 by up to one code.
+    out[0::2] = np.clip(np.rint(iq.real * 128.0), -128, 127)
+    out[1::2] = np.clip(np.rint(iq.imag * 128.0), -128, 127)
+    return out.tobytes()