@@ -42,6 +42,14 @@ def capture(self, freq: float, sample_rate: float, *,
4242 baseband_bw : float | None = None , to_stdout : bool = False ,
4343 sigmf : bool = True , segment_secs : float | None = None ,
4444 print_cmd : bool = False ) -> Any :
45+ """Receive IQ at freq/sample_rate into a file (with SigMF sidecar).
46+
47+ Bound with num_samples or duration, or neither for an open-ended handle
48+ (call .stop() on the returned process handle). segment_secs rolls output
49+ across numbered files (whole files, short re-open gap between them; use
50+ open_receiver for gapless). to_stdout=True streams decoded blocks
51+ instead of writing a file.
52+ """
4553 self .require_mode (C .MODE_RX )
4654 freq , sample_rate , lna , vga = self .validate_rx (freq , sample_rate , lna , vga )
4755 bw = self ._auto_baseband (sample_rate , baseband_bw )
@@ -110,20 +118,29 @@ def _gen() -> Generator[np.ndarray, None, None]: # decoded, not raw
110118
111119 # ---- aliases ----
112120 def rx (self , * a : Any , ** k : Any ) -> Any :
121+ """Alias of capture()."""
113122 return self .capture (* a , ** k )
114123
115124 def capture_samples (self , freq : float , sample_rate : float ,
116125 num_samples : int , ** k : Any ) -> Any :
126+ """Alias of capture() with a required num_samples bound."""
117127 return self .capture (freq , sample_rate , num_samples = num_samples , ** k )
118128
119129 def capture_seconds (self , freq : float , sample_rate : float ,
120130 duration : float , ** k : Any ) -> Any :
131+ """Alias of capture() with a required duration bound."""
121132 return self .capture (freq , sample_rate , duration = duration , ** k )
122133
123134 def scan_frequencies (self , freqs : list [float ], sample_rate : float ,
124135 num_samples : int , * ,
125136 on_capture : Callable [..., Any ] | None = None ,
126137 ** k : Any ) -> dict [float , np .ndarray ] | None :
138+ """Capture num_samples of IQ at each frequency in turn.
139+
140+ Returns {freq: complex64 ndarray}, or None when on_capture consumes
141+ blocks instead. Each visit re-opens the device (short gap between
142+ frequencies).
143+ """
127144 # Sequentially capture a fixed sample count at each frequency in
128145 # `freqs`, retuning between them. This does NOT close the gapless-
129146 # retune gap (each retune is a fresh hackrf_transfer with a short
@@ -148,6 +165,11 @@ def scan_frequencies(self, freqs: list[float], sample_rate: float,
148165 # ---- in-memory + context-managed entry points ----
149166 def capture_array (self , freq : float , sample_rate : float , num_samples : int ,
150167 * , return_params : bool = False , ** k : Any ) -> Any :
168+ """Return exactly num_samples complex64 samples in RAM, no file.
169+
170+ The scripting entry point. return_params=True also returns the
171+ validated parameters actually used.
172+ """
151173 # Scripting entry point: return EXACTLY num_samples complex64 samples
152174 # in RAM, no file. Built on the stdout-stream path so it shares the
153175 # odd-byte carry + clean-reap logic. The stream is closed as soon as
@@ -184,6 +206,12 @@ def open_receiver(self, freq: float, sample_rate: float, *, lna: int = 16,
184206 vga : int = 20 , amp : bool = False ,
185207 baseband_bw : float | None = None ,
186208 read_samples : int = 131072 ) -> PersistentReceiver :
209+ """Open a long-lived receive stream; returns a PersistentReceiver.
210+
211+ One hackrf_transfer process serves many .read(n) calls: consecutive
212+ reads are gapless (contrast capture(segment_secs=...)). Use as a context
213+ manager to guarantee the child is reaped.
214+ """
187215 # Open a PERSISTENT fixed-frequency receiver: one long-lived
188216 # hackrf_transfer you drain in segments over time, so you don't pay the
189217 # ~1-2 s process spin-up per capture. Use as a context manager:
@@ -204,6 +232,11 @@ def open_receiver(self, freq: float, sample_rate: float, *, lna: int = 16,
204232
205233 def capture_stream (self , freq : float , sample_rate : float ,
206234 ** k : Any ) -> StreamCtx :
235+ """Context manager yielding decoded complex64 blocks from a live stream.
236+
237+ The receiving hackrf_transfer is always reaped on block exit, even on
238+ exception.
239+ """
207240 # Context manager wrapping the live stdout stream so the receiving
208241 # hackrf_transfer is ALWAYS reaped on exit, even on exception:
209242 # with h.capture_stream(433.92e6, 8e6) as blocks:
@@ -217,6 +250,11 @@ def capture_callback(self, freq: float, sample_rate: float,
217250 on_block : Callable [..., Any ], * ,
218251 max_samples : int | None = None ,
219252 max_blocks : int | None = None , ** k : Any ) -> int :
253+ """Invoke on_block(iq) per decoded block until a bound or False return.
254+
255+ Bounds: max_samples, max_blocks, or the callback returning False.
256+ Returns the number of samples delivered.
257+ """
220258 # Binder-style ergonomics over the subprocess stream: instead of the
221259 # caller writing the receive loop, register a callback that fires with
222260 # each decoded complex64 block as it arrives. This is the usability
0 commit comments