python-aaronia 0.11.0__tar.gz → 0.11.2__tar.gz

{python_aaronia-0.11.0 → python_aaronia-0.11.2}/CHANGELOG.md

@@ -4,6 +4,71 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.11.2] - 2026-09-11
+
+### Added
+- **`capture_sample_rate_hz()`** on `SpectranSource`, the rate counterpart of
+  `capture_frequency_hz()`. It describes the samples a read just returned, not
+  the newest rate the background reader has seen, so a consumer that resamples
+  or sizes an FFT from it agrees with the block in its hands.
+
+### Fixed
+- **A read no longer spans a sample-rate change.** The retune boundary rule
+  from 0.11.0 covered frequency only, so a rate change could land mid-block —
+  with the returned samples labelled at whichever rate the reader had reached
+  by then. Reads now stop at a rate change too, holding the rest for the next
+  call, and queued samples keep the rate they were captured at.
+- **The HTTP read timeout is a budget for the whole block, not per receive.**
+  A read asking for a large block against a slow stream could wait the full
+  timeout repeatedly and take far longer than the caller allowed.
+- **File tuning setters no longer rewrite the recording's metadata.**
+  `set_center_frequency_hz`, `set_sample_rate_hz` and `set_reference_level_dbm`
+  overwrote the config on a file source, so the playback then described itself
+  by what was asked for rather than by what was recorded.
+
+### Fixed (futuresdr source)
+- **The buffer pool is bounded by bytes, not by a fixed count.** It held 256
+  buffers of `block_size` regardless of size — 256 MiB at a 1 Mi-sample block.
+  Depth is now derived from `block_size` against a 64 MiB ceiling, and a
+  `block_size` past that ceiling is rejected at `start()` instead of consuming
+  the memory.
+- **A refused channel override is no longer retried forever.** A retune the
+  device rejected slept 100 ms and tried the same frequency again, indefinitely.
+  The rejected frequency is now remembered and skipped until the override
+  changes. A retune failure on the *commanded* frequency, which has no such
+  fallback, propagates rather than spinning.
+- **A parked viewer keeps receiving after its dwell expires.** Reads for an
+  override channel were budgeted from the hop deadline, which is already in the
+  past once parked — so the read budget was zero and the viewer starved.
+- **Packets carry the metadata of the samples in them.** They reported the
+  commanded frequency and the source's current rate; they now carry the
+  captured pair, and samples whose frequency cannot be confirmed are dropped
+  rather than mislabelled.
+- **Returning a buffer to a full pool cannot block the pump.**
+
+## [v0.11.1] - 2026-09-10
+
+### Fixed
+- **A stream gap now ends the block it precedes, instead of hiding inside
+  one.** Read assembly noted a dropped chunk and carried on concatenating,
+  so a returned block held samples from both sides of the hole while
+  `take_overrun` said only "somewhere in there". A consumer resetting its
+  filters once, before the block, still ran the discontinuity through
+  them — and for an FM discriminator that is a phase step, i.e. a
+  frequency spike that reads downstream as a sync edge.
+
+  A gap has a position, and the only position a consumer can act on is a
+  read boundary. The post-gap chunk is now stashed and the block ends,
+  exactly as it already did for a retune, with the flag carried to the
+  read that begins there. A gap on a read's first chunk still reports
+  against that read, since nothing precedes it to split from.
+
+  This also reaches reconnects, which are discontinuities for the same
+  reason: the stream stopped and resumed, so the samples either side are
+  not adjacent. Reads continue across a reconnect as before, they just
+  no longer splice across it.
+
+
 ## [v0.11.0] - 2026-09-09
 
 ### Changed

{python_aaronia-0.11.0 → python_aaronia-0.11.2}/Cargo.lock

@@ -3092,7 +3092,7 @@ dependencies = [
 
 [[package]]
 name = "python-aaronia"
-version = "0.11.0"
+version = "0.11.2"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3621,7 +3621,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.11.0"
+version = "0.11.2"
 dependencies = [
  "anyhow",
  "bitflags 2.13.1",

{python_aaronia-0.11.0 → python_aaronia-0.11.2}/Cargo.toml

@@ -2,7 +2,7 @@
 name = "sdr-aaronia-rs"
 description = "Unified Rust interface for Aaronia Spectran Spectrum Analyzers / SDRs, featuring Python bindings, a SoapySDR plugin, HTTP streaming, and native SDK support."
 license = "GPL-3.0-or-later"
-version = "0.11.0"
+version = "0.11.2"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"

{python_aaronia-0.11.0 → python_aaronia-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.11.0
+Version: 0.11.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)

{python_aaronia-0.11.0 → python_aaronia-0.11.2}/README.md

@@ -93,6 +93,8 @@ tokio = { version = "1.43", features = ["rt-multi-thread", "macros"] }
 # sdr-aaronia-rs = { version = "0.8", features = ["native-sdk", "futuresdr"] }
 ```
 
+HTTP reads use one timeout budget for the entire requested block and return partial data at a timeout, frequency change, sample-rate change, or detected gap. `capture_frequency_hz()` and `capture_sample_rate_hz()` describe the returned samples even when newer packets are queued. File tuning setters preserve the recording's metadata.
+
 ## Quickstart
 
 Set the RF parameters and read:

{python_aaronia-0.11.0 → python_aaronia-0.11.2}/python-aaronia/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "python-aaronia"
-version = "0.11.0"
+version = "0.11.2"
 edition = "2024"
 description = "Python bindings for sdr-aaronia-rs (Aaronia SPECTRAN V6 SDR source)"
 license = "GPL-3.0-or-later"

{python_aaronia-0.11.0 → python_aaronia-0.11.2}/src/sdr_source_impl.rs

@@ -129,13 +129,41 @@ const EMPTY_READ_BAILOUT: u32 = 16;
 /// should see EOF rather than be silently fed an empty channel.
 const READ_ERROR_BAILOUT: u32 = 5;
 
+fn accepted_override(requested: Option<f64>, rejected: Option<u64>) -> Option<f64> {
+    requested.filter(|f| f.is_finite() && *f > 0.0 && rejected != Some(f.to_bits()))
+}
+
+fn read_budget(parked: bool, deadline: Instant) -> Duration {
+    if parked {
+        Duration::from_millis(50)
+    } else {
+        deadline.saturating_duration_since(Instant::now())
+    }
+}
+
+fn packet_frequency(captured_hz: f64, commanded_hz: f64) -> Option<f64> {
+    if captured_hz > 0.0 {
+        ((captured_hz - commanded_hz).abs() <= STALE_TOLERANCE_HZ).then_some(captured_hz)
+    } else {
+        Some(commanded_hz)
+    }
+}
+
 impl SdrSource for SpectranSdrSource {
     fn start(
         self: Box<Self>,
         config: SourceConfig,
         advice: Arc<dyn DwellAdvice>,
     ) -> Result<SdrHandle, SdrError> {
-        let (tx, receiver) = channel::bounded::<IqPacket>(1024);
+        let block_size = self.block_size.max(1024);
+        if block_size > 8 * 1024 * 1024 {
+            return Err(SdrError::BadConfig(
+                "block_size exceeds the 64 MiB sample-buffer limit".into(),
+            ));
+        }
+        let pool_depth =
+            (64 * 1024 * 1024 / (block_size * std::mem::size_of::<Complex32>())).clamp(1, 64);
+        let (tx, receiver) = channel::bounded::<IqPacket>(pool_depth);
         let stop_flag = Arc::new(AtomicBool::new(false));
         let stop_thread = stop_flag.clone();
 
@@ -243,12 +271,9 @@ impl SdrSource for SpectranSdrSource {
                     let hopping =
                         !channels_hz.is_empty() && !matches!(backend, SpectranBackend::File(_));
 
-                    let (pool_tx, pool_rx) = channel::bounded::<Vec<Complex32>>(256);
-                    for _ in 0..256 {
-                        let _ = pool_tx.send(Vec::with_capacity(block_size));
-                    }
+                    let (pool_tx, pool_rx) = channel::bounded::<Vec<Complex32>>(pool_depth);
 
-                    if hopping {
+                    let pump_result = if hopping {
                         info!(
                             "Aaronia hop mode: {} channels, dwell {:?}-{:?} (adaptive={})",
                             channels_hz.len(),
@@ -268,7 +293,6 @@ impl SdrSource for SpectranSdrSource {
                             &pool_tx,
                         )
                         .await
-                        .map_err(|e| Error::Config(e.to_string()))?;
                     } else {
                         single_channel_pump(
                             &mut source,
@@ -281,11 +305,10 @@ impl SdrSource for SpectranSdrSource {
                             &pool_tx,
                         )
                         .await
-                        .map_err(|e| Error::Config(e.to_string()))?;
-                    }
+                    };
 
                     let _ = source.stop_streaming().await;
-                    Ok::<_, Error>(())
+                    pump_result
                 })?;
                             Ok(())
                         })() {
@@ -340,13 +363,23 @@ async fn single_channel_pump(
 ) -> Result<()> {
     let mut empty_reads = 0u32;
     let mut current_freq = center_frequency_hz;
+    let file_playback = source.source_info().source_type == SourceType::File;
+    let mut rejected_override = None;
     while !stop_thread.load(Ordering::SeqCst) {
-        let target = advice.channel_override().unwrap_or(center_frequency_hz);
+        let requested = if file_playback {
+            None
+        } else {
+            accepted_override(advice.channel_override(), rejected_override)
+        };
+        let target = requested.unwrap_or(center_frequency_hz);
         if (target - current_freq).abs() > 1.0 {
             if let Err(e) = source.set_center_frequency_hz(target).await {
                 warn!("Aaronia retune to {:.3} MHz failed: {e}", target / 1e6);
-                tokio::time::sleep(Duration::from_millis(100)).await;
-                continue;
+                if requested.is_some() {
+                    rejected_override = Some(target.to_bits());
+                    continue;
+                }
+                return Err(e);
             }
             current_freq = target;
             drain_during_settle(source, block_size, RETUNE_SETTLE).await;
@@ -357,8 +390,12 @@ async fn single_channel_pump(
             .unwrap_or_else(|_| Vec::with_capacity(block_size));
         raw_buffer.clear();
 
-        let n = match source.read_samples(&mut raw_buffer, block_size).await {
+        let n = match source
+            .read_samples_deadline(&mut raw_buffer, block_size, Duration::from_millis(50))
+            .await
+        {
             Ok(v) => v,
+            Err(Error::Io(ref e)) if e.kind() == std::io::ErrorKind::TimedOut => continue,
             Err(e) => {
                 warn!("Aaronia read_samples error: {e} — stopping");
                 break;
@@ -374,13 +411,19 @@ async fn single_channel_pump(
             continue;
         }
         empty_reads = 0;
+        let Some(packet_center) = packet_frequency(source.capture_frequency_hz(), current_freq)
+        else {
+            raw_buffer.clear();
+            let _ = pool_tx.try_send(raw_buffer);
+            continue;
+        };
         // The rate is read per packet: on HTTP the rate the device actually
         // streams is only known once packets flow, and may not be the one
         // asked for (it snaps to the decimation ladder).
         let pkt = IqPacket {
             samples: crate::sdr_source::PooledIqBuffer::new_pooled(raw_buffer, pool_tx.clone()),
-            center_frequency_hz: current_freq,
-            sample_rate_hz: source.sample_rate_hz() as f32,
+            center_frequency_hz: packet_center,
+            sample_rate_hz: source.capture_sample_rate_hz() as f32,
             overrun: source.take_overrun(),
         };
         if tx.send(pkt).is_err() {
@@ -426,12 +469,13 @@ async fn hop_pump(
     // by contrast is per-hop on purpose: a quiet channel isn't a
     // dead source, and hopping is the cure.
     let mut read_errors = 0u32;
+    let mut rejected_override = None;
     while !stop_thread.load(Ordering::SeqCst) {
         // A live `/video` viewer wants a specific channel: park there,
         // bypassing the hop list, until the override changes or clears.
         // `channel_idx` only advances on a genuine hop below, so hopping
         // resumes exactly where it left off once the viewer disconnects.
-        let override_freq = advice.channel_override();
+        let override_freq = accepted_override(advice.channel_override(), rejected_override);
         let channel = override_freq.unwrap_or_else(|| {
             let c = channels_hz[channel_idx];
             channel_idx = (channel_idx + 1) % channels_hz.len();
@@ -444,6 +488,10 @@ async fn hop_pump(
         if channel != current_channel {
             if let Err(e) = source.set_center_frequency_hz(channel).await {
                 warn!("Aaronia retune to {:.3} MHz failed: {e}", channel / 1e6);
+                if override_freq.is_some() {
+                    rejected_override = Some(channel.to_bits());
+                    continue;
+                }
                 consecutive_retune_failures += 1;
                 if consecutive_retune_failures >= READ_ERROR_BAILOUT {
                     return Err(Error::Config(format!(
@@ -473,22 +521,10 @@ async fn hop_pump(
             if stop_thread.load(Ordering::SeqCst) {
                 break;
             }
-            let still_overridden = advice.channel_override() == Some(channel);
-            if override_freq.is_some() {
-                // Parked here for live view: hold regardless of the dwell
-                // deadline, but break out the moment the viewer's channel
-                // changes or they disconnect so the outer loop can retune
-                // or resume hopping.
-                if !still_overridden {
-                    break;
-                }
-            } else if still_overridden {
-                // A viewer just requested this exact channel while we were
-                // still mid-hop-dwell here — break out now (rather than
-                // waiting for the normal dwell deadline) so the next outer
-                // iteration parks on it promptly.
+            if accepted_override(advice.channel_override(), rejected_override) != override_freq {
                 break;
-            } else if Instant::now() >= deadline {
+            }
+            if override_freq.is_none() && Instant::now() >= deadline {
                 break;
             }
 
@@ -506,7 +542,7 @@ async fn hop_pump(
             // channel stays open instead of closing. Returning whatever
             // arrived by the deadline keeps the hop cadence intact, and
             // the `n == 0` branch below already handles an empty read.
-            let remaining = deadline.saturating_duration_since(Instant::now());
+            let remaining = read_budget(override_freq.is_some(), deadline);
             let n = match source
                 .read_samples_deadline(&mut raw_buffer, block_size, remaining)
                 .await
@@ -553,24 +589,20 @@ async fn hop_pump(
             // that carry no per-packet frequency (file, native SDK), so
             // those fall back to the commanded channel.
             let captured_hz = source.capture_frequency_hz();
-            if captured_hz > 0.0 && (captured_hz - channel).abs() > STALE_TOLERANCE_HZ {
+            let Some(packet_center) = packet_frequency(captured_hz, channel) else {
                 // Pre-retune samples. Discard rather than mislabel them;
                 // the settle is short and the next read is clean. Hand
                 // the buffer back to the pool by the same route a
                 // delivered packet takes — dropping it here would shrink
                 // the pool by one on every hop.
                 raw_buffer.clear();
-                let _ = pool_tx.send(raw_buffer);
+                let _ = pool_tx.try_send(raw_buffer);
                 continue;
-            }
+            };
             let pkt = IqPacket {
                 samples: crate::sdr_source::PooledIqBuffer::new_pooled(raw_buffer, pool_tx.clone()),
-                center_frequency_hz: if captured_hz > 0.0 {
-                    captured_hz
-                } else {
-                    channel
-                },
-                sample_rate_hz: source.sample_rate_hz() as f32,
+                center_frequency_hz: packet_center,
+                sample_rate_hz: source.capture_sample_rate_hz() as f32,
                 overrun: source.take_overrun(),
             };
             if tx.send(pkt).is_err() {
@@ -612,3 +644,31 @@ async fn drain_during_settle(
         }
     }
 }
+
+#[cfg(test)]
+mod review_regressions {
+    use super::*;
+    #[test]
+    fn parked_reads_continue_after_the_original_dwell_expires() {
+        let expired = Instant::now() - Duration::from_secs(1);
+        assert!(!read_budget(true, expired).is_zero());
+        assert!(read_budget(false, expired).is_zero());
+    }
+    #[test]
+    fn single_channel_packets_reject_stale_frequency_metadata() {
+        assert_eq!(packet_frequency(433e6, 915e6), None);
+        assert_eq!(packet_frequency(915e6 - 500.0, 915e6), Some(915e6 - 500.0));
+        assert_eq!(packet_frequency(0.0, 915e6), Some(915e6));
+    }
+    #[test]
+    fn override_can_move_to_another_channel_or_clear() {
+        assert_ne!(None, accepted_override(Some(915e6), None));
+        assert_ne!(Some(915e6), accepted_override(Some(433e6), None));
+        assert_ne!(Some(915e6), accepted_override(None, None));
+        assert_eq!(None, accepted_override(Some(f64::NAN), None));
+        assert_eq!(
+            None,
+            accepted_override(Some(915e6), Some(915e6_f64.to_bits()))
+        );
+    }
+}