python-aaronia 0.6.1__tar.gz → 0.6.2__tar.gz

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.6.2] - 2026-08-12
+
 ## [v0.6.1] - 2026-08-12
 
 ### Fixed
@@ -30,8 +32,40 @@ All notable changes to this project will be documented in this file.
   guesses, so the relationships now live in one tested place. Wanting
   8 MHz of spectrum needs 10 MHz of sampling, and
   `iq_sample_rate_for_bandwidth` returns the 15.36 MHz that provides it.
+  `iq_sample_rates_for_clock` covers devices whose receiver clock is not
+  the default: a V6 ECO has a fixed clock and gives the measured ladder,
+  while a full V6 can select a faster one and reach further. Aaronia's
+  samples set `device/receiverclock` to "92MHz" or "245MHz"; only the
+  default has been checked against hardware.
+
+### Added (native SDK)
+- **Device-family auto-detection.** `detect_device_family` and
+  `open_detected_device` try each known family in turn, so an ECO owner
+  no longer has to know that the default `spectranv6` will not find
+  their device and that `spectranv6eco` is the string they needed.
+- **`read_spectra`**, with the stream index taken from the open mode
+  rather than assumed. `spectranv6/raw` carries spectra on stream 2 and
+  IQ on stream 0; every other mode uses stream 0. Hardware-unverified.
+- **`receiver_clock_hz`** on the native source, and
+  `spectranv6eco/rtsa` added to the known open modes. The clock sets the
+  rate ladder's ceiling, so callers that need to know which rates exist
+  can now ask instead of assuming.
 
 ### Fixed (native SDK)
+- **The V6 ECO's fixed receiver clock was recorded as 61.44 MHz.** It is
+  92.16 MHz: an ECO streams at 61.44 MHz sampling, measured against real
+  hardware, and the constraint checked at configuration time is
+  `span * 1.5 <= clock`. The old value rejected every span above
+  40.96 MHz, including the device's own maximum.
+- **Dual-channel capture selected the wrong mode and would have
+  returned corrupted samples.** `RxChannel::Rx1And2` wrote
+  `device/receiverchannel = "Rx1+Rx2"`, which delivers the two inputs as
+  two independent streams at indices 0 and 1. This crate reads a single
+  stream and deinterleaves it, which is the contract of the other mode,
+  `"Rx12"`. On a two-input V6 the result would have been Rx1's samples
+  split into two bogus channels, with no error anywhere. It now writes
+  `"Rx12"`. Aaronia's `RawIQ2RX` and `RawIQ2RXInterleave` samples
+  demonstrate one mode each. Still hardware-unverified.
 - **Sweep mode set the wrong resolution-bandwidth key.** It sent
   `main/rbw`, which no Aaronia sample uses; the key is `main/rbwfreq`.
   Checked against Aaronia's published `SweepSpectrumEco` sample, which

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/Cargo.lock

@@ -3027,7 +3027,7 @@ dependencies = [
 
 [[package]]
 name = "python-aaronia"
-version = "0.6.1"
+version = "0.6.2"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3556,7 +3556,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.6.1"
+version = "0.6.2"
 dependencies = [
  "anyhow",
  "bitflags 2.13.1",

{python_aaronia-0.6.1 → python_aaronia-0.6.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.6.1"
+version = "0.6.2"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.6.1
+Version: 0.6.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.6.1 → python_aaronia-0.6.2}/docs/HTTPSPEC.md

@@ -590,6 +590,44 @@ Data captured using antennas with location or directional information.
 | `azimuth` | Azimuth of directional antenna |
 | `declination` | Declination of directional antenna |
 
+## What the native SDK samples tell us about this API
+
+Aaronia's [C++ SDK samples](https://github.com/Aaronia-Open-source/RTSA-API-Samples)
+drive the same hardware through a different transport, so some of what
+they establish applies here and some does not.
+
+### GPS needs enabling, over HTTP too
+
+The `device/gpsmode` and `device/sclksource` keys the `GPSTime` sample
+writes are the same keys this config tree exposes, so the prerequisite
+is identical. A device ships with `gpsmode` set to `Disabled` and takes
+its stream clock from whatever `sclksource` names, which on the system
+tested here was `10MHz` rather than GPS. Timestamps are not
+GPS-disciplined until both change, and nothing reports an error
+meanwhile.
+
+Observed on a V6 ECO: `gpsmode` offers `Disabled`, `Location`, `Time`
+and `Location and Time`; `sclksource` offers `Consumer`, `Oscillator`,
+`GPS`, `PPS`, `10MHz` and three `... Provider` variants.
+
+### The rate ladder carries over
+
+`decimation0` takes the same labels as the SDK's `main/decimation`,
+`"Full"` through `"1 / 512"`, verified by writing one over HTTP. Both
+transports drive the same divider.
+
+### Two things that do not carry over
+
+- **Receiver-channel selection.** There is no `device/receiverchannel`
+  here. The tree exposes per-channel settings instead — `centerfreq0`
+  and `centerfreq1`, `decimation0` and `decimation1`, `rfchsource0` and
+  `rfchsource1` — and which channels reach the stream is a property of
+  the RTSA mission graph. The SDK's `Rx12` versus `Rx1+Rx2` distinction
+  has no equivalent.
+- **Stream indices.** The SDK separates IQ from spectra by packet stream
+  index. HTTP selects data with the `input=` parameter and reports the
+  kind in each packet's `payload` field.
+
 ## Authorization & Licensing
 
 ### HTTP Streaming vs Remote Configuration

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/docs/SDKSPEC.md

@@ -876,3 +876,61 @@ the Aaronia Software License Agreement governs use of the SDK itself (see
 [Licensing Considerations](#licensing-considerations)); this community document
 describes only the public interface. "Aaronia", "RTSA", and "Spectran" are the
 property of Aaronia AG.
+
+## Facts taken from Aaronia's published samples
+
+The following come from
+[Aaronia-Open-source/RTSA-API-Samples](https://github.com/Aaronia-Open-source/RTSA-API-Samples),
+read in full. They are vendor code rather than vendor documentation, but
+they are the closest thing to an authoritative statement of how the API
+is meant to be driven, and this crate's native-SDK paths cannot be
+tested here.
+
+### Both receivers, two different modes
+
+`device/receiverchannel` takes four values, and the last two are not
+interchangeable:
+
+| Value | Delivery |
+| --- | --- |
+| `Rx1`, `Rx2` | One input, one stream |
+| `Rx12` | Both inputs interleaved into **one** stream: four floats per sample, `[I0, Q0, I1, Q1]`, read from stream 0 |
+| `Rx1+Rx2` | Both inputs as **two independent streams**, fetched and consumed separately at indices 0 and 1 |
+
+`RawIQ2RXInterleave` uses the first, `RawIQ2RX` the second. This crate
+reads a single stream and deinterleaves it, so it writes `Rx12`.
+
+### V6 against V6 ECO
+
+| | Full V6 | V6 ECO |
+| --- | --- | --- |
+| Family string | `spectranv6` | `spectranv6eco` |
+| `device/receiverchannel` | Set explicitly | Never set: one receiver |
+| `device/receiverclock` | Set, `"92MHz"` or `"245MHz"` | Never set: fixed |
+| Spectrum packets | Stream index 2 | Stream index 0 |
+| Raw-mode open string | `spectranv6/raw` | `spectranv6eco/rtsa` |
+
+The clock matters beyond configuration: with `span * 1.5 <=
+receiverclock`, a V6 on the fast clock reaches roughly 163 MHz of span
+where the ECO's fixed clock allows 61.44 MHz.
+
+### Sample rates
+
+`main/decimation` accepts either the label (`"1 / 64"`) or the index
+(`6`). Combined with the clock, that gives the rate ladder: the top rate
+is `receiverclock / 1.5` and each step halves it.
+
+### Transmitting
+
+The samples flag the first packet `SEGMENT_START | STREAM_START`, the
+last `SEGMENT_END | STREAM_END`, and everything between `0`. The
+transceiver samples additionally send a zero-length packet carrying only
+`STREAM_START`, timestamped at the master stream clock, before real
+data, to improve startup synchronisation.
+
+### Keys this crate does not use
+
+`device/outputformat` (`"iq"` or `"spectra"`), `main/demodcenterfreq`
+and `main/demodspanfreq`, `main/centerfreqtx` and `main/centerfreqrx`
+for independent transceiver tuning, `calibration/preamp`, and the
+read-only `boostusbbytessecond` throughput reading.

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/docs/VERIFICATION.md

@@ -21,7 +21,10 @@ SDK are marked unverified.
 | SoapySDR plugin RX | HTTP | Verified manually (~9.7 Msps via `SoapySDRUtil`); no automated live test, as a `soapysdr` dev-dependency would make `cargo test` unbuildable without system SoapySDR |
 | Python bindings RX | HTTP | Verified manually (NumPy and Arrow); no automated live test |
 | TX (`UnifiedSink`, `aaronia_sink_*`, SoapySDR TX) | Native SDK | **Hardware-unverified**. No TX-licensed device available |
-| Dual-channel RX (`Rx1And2`, `read_samples_dual`) | Native SDK | **Hardware-unverified**. Requires a full V6 |
+| Dual-channel RX (`Rx1And2`, `read_samples_dual`) | Native SDK | **Hardware-unverified**. Requires a full V6. Selects `Rx12`, the interleaved single-stream mode, matching how this crate reads |
+| Spectra reads (`read_spectra`) | Native SDK | **Hardware-unverified**. Packet layout and stream index follow Aaronia's `RawSpectrum` sample |
+| Device-family detection (`open_detected_device`) | Native SDK | **Hardware-unverified**. Enumerates each known family in turn |
+| Sample-rate ladder and usable bandwidth | Both | **Live-verified at the default clock** on a V6 ECO, rung by rung. Faster receiver clocks are inferred from the documented constraint, not measured |
 | GPS hardware time | Native SDK | **Hardware-unverified** |
 | Native SDK capture generally | Native SDK | **Hardware-unverified**; compiled and unit-tested in a Linux VM each release |
 | HTTP TX push (`/sample`) | HTTP | Endpoint exercised live; RF output not measured |
@@ -40,6 +43,15 @@ cargo test --all-features --test live_smoke -- --ignored --nocapture
 Contributions that convert an unverified row, particularly from users
 with a full V6 or a TX licence, are welcome.
 
+Native-SDK entries carry a second qualifier worth stating plainly: they
+are not merely untested, they run on a platform this project cannot
+build on locally. They are compile-checked for Linux and Windows and
+their logic is drawn from Aaronia's published samples, which caught
+three real defects, but nothing has executed them against a device.
+
+If you have a full V6 or a TX licence, closing one of these rows is the
+single most valuable contribution you can make to this crate.
+
 ## Related
 
 - [QUICKSTART.md](QUICKSTART.md) — setting up an RTSA-Suite mission.

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/python-aaronia/Cargo.toml

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

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/src/lib.rs

@@ -134,6 +134,6 @@ pub use unified_source::{
 /// Utilities for DB/linear conversions and string parsing
 pub use utils::{
     IQ_CLOCK_HZ, USABLE_BANDWIDTH_RATIO, db_to_linear, format_frequency, format_sample_rate,
-    iq_sample_rate_for_bandwidth, iq_sample_rates, linear_to_db, nearest_iq_sample_rate,
-    parse_frequency, parse_sample_rate, usable_bandwidth_hz,
+    iq_sample_rate_for_bandwidth, iq_sample_rates, iq_sample_rates_for_clock, linear_to_db,
+    nearest_iq_sample_rate, parse_frequency, parse_sample_rate, usable_bandwidth_hz,
 };

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/src/native_sdk.rs

@@ -725,6 +725,43 @@ impl NativeSdkClient {
         }
     }
 
+    /// The device families this SDK knows about, in the order worth
+    /// trying.
+    pub const DEVICE_FAMILIES: [&'static str; 2] = ["spectranv6", "spectranv6eco"];
+
+    /// Find which family actually has a device attached.
+    ///
+    /// `AARTSAAPI_EnumDevice` matches one family at a time, so a caller
+    /// configured for `spectranv6` finds nothing on a machine holding
+    /// only a V6 ECO, and the failure reads as "no device" rather than
+    /// "wrong family". This tries each family in turn and returns the
+    /// first that enumerates a device, so the common case needs no
+    /// configuration at all.
+    ///
+    /// # Safety
+    /// `handle` must be an open library handle.
+    pub unsafe fn detect_device_family(
+        &self,
+        handle: &mut AARTSAAPI_Handle,
+    ) -> Result<Option<&'static str>> {
+        for family in Self::DEVICE_FAMILIES {
+            match unsafe { self.enum_device(handle, family, 0) } {
+                Ok(Some(_)) => {
+                    info!("Detected device family {family}");
+                    return Ok(Some(family));
+                }
+                // An empty family is the normal answer for the one that
+                // is not attached; keep looking.
+                Ok(None) => continue,
+                Err(e) => {
+                    debug!("Enumerating {family} failed, trying the next: {e}");
+                    continue;
+                }
+            }
+        }
+        Ok(None)
+    }
+
     pub unsafe fn enum_device(
         &self,
         handle: &mut AARTSAAPI_Handle,
@@ -1240,6 +1277,27 @@ pub(crate) fn split_packet(packet_samples: usize, remaining: usize) -> (usize, u
     (to_caller, packet_samples - to_caller)
 }
 
+/// What one spectra packet described, alongside the values appended to
+/// the caller's buffer.
+///
+/// A packet holds `frames` consecutive spectra of `bins_per_frame`
+/// values each, laid out one after another, so frame `i` occupies
+/// `[i * bins_per_frame ..][.. bins_per_frame]` of what was appended.
+/// Values are dBm.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SpectraRead {
+    /// Number of spectra in the packet.
+    pub frames: usize,
+    /// Bins in each spectrum.
+    pub bins_per_frame: usize,
+    /// Frequency of the first bin, in Hz.
+    pub start_frequency_hz: f64,
+    /// Spacing between bins, in Hz.
+    pub step_frequency_hz: f64,
+    /// Packet start time, on the device's clock.
+    pub start_time: f64,
+}
+
 // === High-Level Stream Manager ===
 
 /// The open-mode supplied to `AARTSAAPI_OpenDevice`. Tracking which family /
@@ -1251,6 +1309,9 @@ pub enum DeviceOpenMode {
     Raw,
     /// `spectranv6eco/iqreceiver` — IQ receiver on the ECO platform.
     EcoIqReceiver,
+    /// `spectranv6eco/rtsa` — the ECO's raw pipeline, which is what its
+    /// spectrum sample opens. There is no `spectranv6eco/raw`.
+    EcoRtsa,
     /// `spectranv6/sweepsa` — sweep spectrum analyzer on the V6 platform.
     Sweepsa,
     /// `spectranv6eco/sweepsa` — sweep spectrum analyzer on the ECO platform.
@@ -1267,6 +1328,9 @@ impl DeviceOpenMode {
     pub fn from_open_string(s: &str) -> Self {
         match s {
             "spectranv6/raw" => Self::Raw,
+            // The ECO's equivalent of raw mode is called rtsa; it has no
+            // "spectranv6eco/raw".
+            "spectranv6eco/rtsa" => Self::EcoRtsa,
             "spectranv6eco/iqreceiver" => Self::EcoIqReceiver,
             "spectranv6/sweepsa" => Self::Sweepsa,
             "spectranv6eco/sweepsa" => Self::EcoSweepsa,
@@ -1281,6 +1345,22 @@ impl DeviceOpenMode {
     pub fn supports_raw_only_keys(&self) -> bool {
         matches!(self, Self::Raw)
     }
+
+    /// Which stream index carries spectra in this mode.
+    ///
+    /// Not a property of the device family, which is how this reads at
+    /// first glance. In `spectranv6/raw` the same device delivers IQ on
+    /// stream 0 and spectra on stream 2, selected by
+    /// `device/outputformat`; Aaronia's `RawIQ` and `RawSpectrum`
+    /// samples differ in exactly that. Every other mode, including the
+    /// ECO's `rtsa` and both `sweepsa` variants, carries spectra on
+    /// stream 0.
+    pub fn spectra_stream_index(&self) -> i32 {
+        match self {
+            Self::Raw => 2,
+            _ => 0,
+        }
+    }
 }
 
 pub struct NativeSdkSource {
@@ -1305,6 +1385,11 @@ pub struct NativeSdkSource {
     /// time-gaps into both outputs (each call consumes whole packets
     /// the other path never sees), so the second path errors instead.
     read_mode: Option<ReadMode>,
+    /// Receiver clock in Hz, learned when the IQ receiver is configured.
+    /// The sample-rate ladder is derived from it, so callers that need
+    /// to know which rates exist should read it rather than assume the
+    /// default. `None` until the device has been configured.
+    receiver_clock_hz: Option<f64>,
 }
 
 /// Which of the two packet-consuming read paths a streaming session
@@ -1399,6 +1484,7 @@ impl NativeSdkSource {
                 sample_buffer: VecDeque::new(),
                 dual_sample_buffer: VecDeque::new(),
                 read_mode: None,
+                receiver_clock_hz: None,
             })
         }
     }
@@ -1595,6 +1681,40 @@ impl NativeSdkSource {
         }
     }
 
+    /// Open whichever device is present, without the caller naming the
+    /// family.
+    ///
+    /// `mode` is the suffix, for example `"raw"` or `"iqreceiver"`. The
+    /// family is detected first, then joined to it. Note the two
+    /// families do not offer identical modes: the V6 has `raw`, while
+    /// the ECO's equivalent is `rtsa`, so pass a mode the detected
+    /// family supports or use [`Self::open_device`] directly.
+    ///
+    /// # Safety
+    /// Same contract as [`Self::open_device`].
+    pub unsafe fn open_detected_device(
+        &mut self,
+        mode: &str,
+        serial_number: &[WideChar],
+    ) -> Result<()> {
+        unsafe {
+            let family = {
+                let handle = self
+                    .handle
+                    .as_mut()
+                    .ok_or_else(|| Error::Sdk("SDK not initialized".to_string()))?;
+                self.client.detect_device_family(handle)?.ok_or_else(|| {
+                    Error::Sdk(format!(
+                        "no Aaronia device found in any known family ({})",
+                        NativeSdkClient::DEVICE_FAMILIES.join(", ")
+                    ))
+                })?
+            };
+            let open_string = format!("{family}/{mode}");
+            self.open_device(&open_string, serial_number)
+        }
+    }
+
     /// Returns the currently configured open mode, if a device is open.
     pub fn open_mode(&self) -> Option<DeviceOpenMode> {
         self.open_mode.clone()
@@ -1887,13 +2007,18 @@ impl NativeSdkSource {
                     crate::utils::DEFAULT_RECEIVER_CLOCK_HZ
                 }
             } else {
-                // Eco devices report no receiverclock key; the family is fixed
-                // at 61.44 MHz per the README. Use that here so the IQ Mode
-                // constraint is checked against the right clock.
-                const ECO_FIXED_CLOCK_HZ: f64 = 61_440_000.0;
-                ECO_FIXED_CLOCK_HZ
+                // Eco devices report no receiverclock key: the clock is
+                // fixed. It is 92.16 MHz, not the 61.44 MHz this used to
+                // assume. A V6 ECO streams at 61.44 MHz sampling, measured
+                // over HTTP against real hardware, and the constraint
+                // checked below is `span * 1.5 <= clock`, so the clock
+                // cannot be lower than 92.16 MHz. With the old value this
+                // rejected every span above 40.96 MHz, including the
+                // device's own maximum.
+                crate::utils::DEFAULT_RECEIVER_CLOCK_HZ
             };
 
+            self.receiver_clock_hz = Some(actual_clock_hz);
             crate::utils::validate_iq_mode(span_freq, actual_clock_hz)?;
 
             info!("IQ Receiver configuration completed");
@@ -1979,6 +2104,101 @@ impl NativeSdkSource {
     pub const READ_POLL_INTERVAL: std::time::Duration = std::time::Duration::from_millis(5);
     pub const READ_POLL_DEADLINE: std::time::Duration = std::time::Duration::from_millis(500);
 
+    /// The receiver clock in Hz, once the device has been configured.
+    ///
+    /// Worth reading rather than assuming: the sample-rate ladder runs
+    /// from `clock / 1.5` downward in halves, so a V6 on the 245 MHz
+    /// clock reaches rates a V6 ECO cannot. Pass this to
+    /// [`crate::utils::iq_sample_rates_for_clock`] to get the rates this
+    /// device actually supports.
+    pub fn receiver_clock_hz(&self) -> Option<f64> {
+        self.receiver_clock_hz
+    }
+
+    /// Read one packet of spectra, appending its values to `out`.
+    ///
+    /// Returns `None` when no packet arrived within
+    /// [`Self::READ_POLL_DEADLINE`], matching the IQ read.
+    ///
+    /// The stream index comes from the open mode rather than a constant:
+    /// `spectranv6/raw` carries spectra on stream 2 while its IQ is on
+    /// stream 0, and every other mode uses stream 0. See
+    /// [`DeviceOpenMode::spectra_stream_index`]. The device must also be
+    /// producing spectra in the first place, which in raw mode means
+    /// `device/outputformat` set to `"spectra"`.
+    ///
+    /// > Hardware-unverified. The packet layout, `num` frames of `size`
+    /// > bins, follows Aaronia's `RawSpectrum` sample; no spectra-capable
+    /// > device has been available to run it against.
+    ///
+    /// # Safety
+    /// The device must be open and streaming.
+    pub unsafe fn read_spectra(&mut self, out: &mut Vec<f32>) -> Result<Option<SpectraRead>> {
+        unsafe {
+            if !self.stream_active {
+                return Err(Error::Sdk("Streaming not active".to_string()));
+            }
+            let stream = self
+                .open_mode
+                .as_ref()
+                .map(DeviceOpenMode::spectra_stream_index)
+                .unwrap_or(0);
+            let device = self
+                .device
+                .as_mut()
+                .ok_or_else(|| Error::Sdk("No device opened".to_string()))?;
+
+            let started = std::time::Instant::now();
+            let packet_opt = loop {
+                match self.client.get_packet(device, stream, 0)? {
+                    Some(p) => break Some(p),
+                    None => {
+                        if started.elapsed() >= Self::READ_POLL_DEADLINE {
+                            break None;
+                        }
+                        std::thread::sleep(Self::READ_POLL_INTERVAL);
+                    }
+                }
+            };
+
+            let Some(packet) = packet_opt else {
+                return Ok(None);
+            };
+
+            // Consume on every path out from here: `get_packet` always
+            // returns the head of the queue, so leaving one behind makes
+            // every later read return the same packet forever.
+            let result = (|| {
+                if packet.fp32.is_null() || packet.num <= 0 || packet.size == 0 {
+                    return Ok(None);
+                }
+                let frames = packet.num as usize;
+                let bins = packet.size as usize;
+                // Bound the product before allocating: a corrupt header
+                // must not size a multi-gigabyte copy.
+                const MAX_VALUES: usize = 1 << 26;
+                let total = frames.checked_mul(bins).filter(|n| *n <= MAX_VALUES);
+                let Some(total) = total else {
+                    return Err(Error::Sdk(format!(
+                        "spectra packet claims {frames} frames of {bins} bins,                          which exceeds the {MAX_VALUES}-value limit"
+                    )));
+                };
+                out.reserve(total);
+                out.extend_from_slice(std::slice::from_raw_parts(packet.fp32, total));
+                Ok(Some(SpectraRead {
+                    frames,
+                    bins_per_frame: bins,
+                    start_frequency_hz: packet.start_frequency,
+                    step_frequency_hz: packet.step_frequency,
+                    start_time: packet.start_time,
+                }))
+            })();
+
+            self.client.consume_packets(device, stream, 1)?;
+            result
+        }
+    }
+
     /// Read up to `max_samples` complex IQ pairs from the device.
     ///
     /// **Magnitude scaling differs by open mode.** Comparing the official
@@ -2494,11 +2714,16 @@ impl Drop for NativeSdkSource {
 /// `device/receiverchannel` config item.
 ///
 /// The full SPECTRAN V6 has two RF inputs; the V6 ECO has one. The config
-/// strings (`"Rx1"`, `"Rx2"`, `"Rx1+Rx2"`) come from the official
-/// RTSA-API-Samples; `"Rx1"` is what [`NativeSdkSource::
-/// configure_iq_receiver`] has always written and is the only variant
-/// verified against real hardware (see
-/// [`NativeSdkSource::set_receiver_channel`]).
+/// strings come from the official RTSA-API-Samples, which use four:
+/// `"Rx1"`, `"Rx2"`, `"Rx12"` and `"Rx1+Rx2"`. The last two both enable
+/// both inputs but differ in delivery — `"Rx12"` interleaves them into
+/// one stream, `"Rx1+Rx2"` produces two independent streams — so they
+/// are not interchangeable. This crate reads one stream and
+/// deinterleaves it, so [`RxChannel::Rx1And2`] writes `"Rx12"`.
+///
+/// `"Rx1"` is what [`NativeSdkSource::configure_iq_receiver`] has
+/// always written and is the only variant verified against real
+/// hardware (see [`NativeSdkSource::set_receiver_channel`]).
 ///
 /// The enum itself lives in [`crate::utils`] so cross-platform
 /// configuration code can name a channel without the `native-sdk`
@@ -3132,6 +3357,7 @@ mod tests {
             sample_buffer: VecDeque::new(),
             dual_sample_buffer: VecDeque::new(),
             read_mode: None,
+            receiver_clock_hz: None,
         };
 
         assert!(!source.is_streaming());

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/src/unified_sink.rs

@@ -189,6 +189,11 @@ impl UnifiedSink {
         )),
         allow(unused_variables)
     )]
+    /// Aaronia's `IQTransceiverSweep` sample precedes real data with a
+    /// zero-length packet carrying only `STREAM_START`, timestamped at
+    /// the master stream clock, "to improve startup synch". Passing an
+    /// empty slice here does the same thing. Untested against hardware,
+    /// like the rest of this path, but it is what the vendor does.
     pub fn write_samples(
         &mut self,
         channel: i32,

{python_aaronia-0.6.1 → python_aaronia-0.6.2}/src/utils.rs

@@ -39,9 +39,18 @@ pub enum RxChannel {
     Rx1,
     /// Second RF input (full V6 only; hardware-unverified).
     Rx2,
-    /// Both inputs, interleaved into one packet (full V6 only;
-    /// hardware-unverified). Read both streams with
-    /// `read_samples_dual` on the native SDK source.
+    /// Both inputs interleaved into a single stream (full V6 only;
+    /// hardware-unverified). Read with `read_samples_dual` on the
+    /// native SDK source.
+    ///
+    /// The device offers two ways to run both inputs and they are not
+    /// interchangeable. `"Rx12"`, used here, interleaves the pair into
+    /// one stream: four floats per sample, `[I0, Q0, I1, Q1]`, read
+    /// from stream 0. `"Rx1+Rx2"` instead delivers two independent
+    /// streams that must be fetched and consumed separately, at indices
+    /// 0 and 1. Aaronia's `RawIQ2RXInterleave` and `RawIQ2RX` samples
+    /// show one each. This crate reads a single stream and
+    /// deinterleaves it, so it requires the former.
     Rx1And2,
 }
 
@@ -51,7 +60,10 @@ impl RxChannel {
         match self {
             Self::Rx1 => "Rx1",
             Self::Rx2 => "Rx2",
-            Self::Rx1And2 => "Rx1+Rx2",
+            // Not "Rx1+Rx2": that selects two separate streams, while
+            // this crate reads one interleaved stream. See the variant
+            // documentation above.
+            Self::Rx1And2 => "Rx12",
         }
     }
 }
@@ -80,7 +92,7 @@ pub fn deinterleave_dual_iq<'a>(
     if stride < 4 {
         return Err(Error::Sdk(format!(
             "packet stride {} cannot carry two interleaved IQ channels (need >= 4); \
-             is device/receiverchannel set to Rx1+Rx2?",
+             is device/receiverchannel set to Rx12?",
             stride
         )));
     }
@@ -283,7 +295,13 @@ pub fn receiver_clock_for_label(label: &str) -> f64 {
     }
 }
 
-/// Master clock the IQ sample-rate ladder divides down from.
+/// Highest IQ sample rate available with the default receiver clock.
+///
+/// This is the [`DEFAULT_RECEIVER_CLOCK_HZ`] divided by the 1.5 factor
+/// that [`validate_iq_mode`] enforces, and it matches the maximum
+/// measured on a SPECTRAN V6 ECO. A full V6 can select a faster
+/// receiver clock, so use [`iq_sample_rates_for_clock`] when the clock
+/// is known rather than assuming this ceiling.
 pub const IQ_CLOCK_HZ: f64 = 61_440_000.0;
 
 /// Fraction of the sample rate that survives the anti-alias filter.
@@ -301,9 +319,27 @@ pub const USABLE_BANDWIDTH_RATIO: f64 = 0.8;
 /// it got what it asked for will compute every derived frequency
 /// wrongly.
 pub fn iq_sample_rates() -> [f64; 10] {
+    iq_sample_rates_for_clock(DEFAULT_RECEIVER_CLOCK_HZ)
+}
+
+/// The IQ sample rates available at a given receiver clock, highest
+/// first.
+///
+/// The top rate is `receiver_clock_hz / 1.5`, the most that
+/// [`validate_iq_mode`] permits, and each step halves it.
+///
+/// **Measured only at the default clock.** A V6 ECO has a fixed
+/// receiver clock and produced exactly the ladder this returns for
+/// [`DEFAULT_RECEIVER_CLOCK_HZ`], verified rung by rung. A full V6 can
+/// select other clocks — Aaronia's own samples use `"92MHz"` and
+/// `"245MHz"` — and the rates there follow the same constraint but have
+/// not been confirmed against hardware. Read `device/receiverclock`
+/// from the device and pass it here rather than assuming.
+pub fn iq_sample_rates_for_clock(receiver_clock_hz: f64) -> [f64; 10] {
+    let top = receiver_clock_hz / 1.5;
     let mut rates = [0.0; 10];
     for (n, rate) in rates.iter_mut().enumerate() {
-        *rate = IQ_CLOCK_HZ / (1u32 << n) as f64;
+        *rate = top / f64::from(1u32 << n);
     }
     rates
 }
@@ -396,6 +432,22 @@ mod ladder_tests {
     use super::*;
 
     /// The ten rates the device reports in its own decimation enum.
+    /// A V6 with a faster receiver clock reaches higher rates. Aaronia's
+    /// samples select "245MHz", which the constraint puts at 163.84 MHz
+    /// of span. Inferred from the constraint, not measured.
+    #[test]
+    fn faster_clock_raises_the_ceiling() {
+        let fast = iq_sample_rates_for_clock(245_760_000.0);
+        assert!((fast[0] - 163_840_000.0).abs() < 1.0);
+        assert!(
+            fast[0] > iq_sample_rates()[0],
+            "a faster clock must reach further"
+        );
+        for pair in fast.windows(2) {
+            assert!((pair[0] / pair[1] - 2.0).abs() < 1e-9);
+        }
+    }
+
     #[test]
     fn ladder_matches_the_device() {
         let rates = iq_sample_rates();
@@ -457,7 +509,10 @@ mod tests {
         // per the official RTSA-API-Samples.
         assert_eq!(RxChannel::Rx1.as_config_str(), "Rx1");
         assert_eq!(RxChannel::Rx2.as_config_str(), "Rx2");
-        assert_eq!(RxChannel::Rx1And2.as_config_str(), "Rx1+Rx2");
+        // "Rx12" interleaves both inputs into one stream, which is
+        // what this crate reads. "Rx1+Rx2" would deliver two separate
+        // streams and silently break the deinterleave.
+        assert_eq!(RxChannel::Rx1And2.as_config_str(), "Rx12");
     }
 
     #[test]
@@ -499,7 +554,7 @@ mod tests {
             Err(e) => e,
             Ok(_) => panic!("stride 2 must be rejected"),
         };
-        assert!(err.to_string().contains("Rx1+Rx2"), "got: {err}");
+        assert!(err.to_string().contains("Rx12"), "got: {err}");
     }
 
     #[test]