python-aaronia 0.12.0__tar.gz → 0.13.1__tar.gz

{python_aaronia-0.12.0 → python_aaronia-0.13.1}/CHANGELOG.md

@@ -4,6 +4,70 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.13.1] - 2026-10-08
+
+### Added
+- `NativeSdkSource::configure_sweepsa_with_reference_level` applies an optional
+  reference level to native spectrum sweeps, backported from Specola's vendor
+  update. Explicit levels require valid SDK bounds and are checked before any
+  configuration write; unsupported/missing settings fail instead of being ignored.
+  The existing `SweepsaConfig` layout and `configure_sweepsa` API remain compatible.
+
+
+## [v0.13.0] - 2026-10-08
+
+### Added
+- Native IQ packet RF span and centre metadata, independent of the actual IQ
+  sample clock. Mono and dual reads preserve that geometry with carried samples.
+- Direct SDK capability queries: configuration bounds, clock/channel/decimation
+  options with their original enum indices and disabled flags, selected mode,
+  and SDK version. Missing metadata stays unknown; no RTSA app is required.
+- Receive-only `NativeReceiverOptions`: explicit family/mode, IQ receiver RF
+  span, or enabled raw clock/decimation selection. SDK configuration bounds are
+  checked before writes. They are not a hardware qualification certificate.
+- Versioned capability JSON and RF-span controls in C and Python; device-derived
+  ranges and observed RF bandwidth in seify and SoapySDR. Windows/Linux Python
+  release wheels now enable `native-sdk` (the proprietary SDK remains separate).
+- An opt-in, serial-selected `native_sdk_qualification` example for receive-only
+  span changes and repeated device stop/reopen checks.
+
+### Fixed
+- Failed SDK opens close any partially allocated device. Connect/start failures
+  attempt stop, disconnect and close while preserving the original error.
+- Stop attempts all cleanup steps, returns the first failure, clears carried IQ
+  and observed metadata, and retains a failed-close handle for a Drop retry.
+  Repeated start/stop calls are idempotent; unified restart reopens the same
+  selected serial and settings, without silently switching devices or backend.
+- SDK global initialization/shutdown reference counting is serialized across the
+  initialized-state transition.
+- IQ receiver span validation uses the opened mode's `main/spanfreq` bounds,
+  rather than the legacy V6 raw-clock constraint. Runtime native setters use the
+  same configuration path as construction.
+- Reads stop before a queued packet changes centre, IQ rate or RF span, and a
+  carry-only read does not wait for another SDK packet.
+- Native capabilities and sensors no longer come from an unrelated HTTP server.
+- Unknown SDK modes cannot reinterpret spectra as IQ or IQ as spectra.
+- SoapySDR tolerates an unknown discrete sample-rate ladder and reports native
+  bandwidth from packet metadata. An RX open no longer attempts TX setup.
+- Release publication is gated on full CI, with semver checked against the
+  previous reachable release instead of a fixed historical tag.
+
+### Migration and qualification
+- This 0.x minor release adds public config fields and SDK mode enum variants.
+  Build `SpectranConfig` with `..Default::default()` and review exhaustive mode
+  matches. Existing C struct layouts and functions are retained.
+- Explicit `spectranv6eco/raw` is preserved; automatic ECO selection remains
+  `iqreceiver`. Explicit raw clock/decimation controls replace the legacy rate
+  request; the actual delivered rate comes from IQ packets.
+- Soapy TX setup requires explicit `tx=true`, a native backend and compatible
+  licensed hardware. TX and dual-RX remain hardware-unverified here.
+- Windows ECO mono qualification passed five stop/reopen cycles at RF spans
+  44, 20, 10, 5 and 44 MHz. The 44 MHz span carried about 59.214 MS/s; the lower
+  spans carried 30, 15 and 7.5 MS/s. One initial discontinuity was reported, with
+  no additional discontinuities during this short trial. Signals was restored.
+  This is not an endurance, amplitude-calibration or all-model certification.
+  See [native SDK compatibility](docs/NATIVE_SDK_COMPATIBILITY.md).
+
 ## [v0.12.0] - 2026-09-29
 
 ### Removed

{python_aaronia-0.12.0 → python_aaronia-0.13.1}/Cargo.lock

@@ -1288,7 +1288,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -2065,7 +2065,7 @@ checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
 dependencies = [
  "hermit-abi",
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3049,7 +3049,7 @@ dependencies = [
 
 [[package]]
 name = "python-aaronia"
-version = "0.12.0"
+version = "0.13.1"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3120,7 +3120,7 @@ dependencies = [
  "once_cell",
  "socket2",
  "tracing",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3426,14 +3426,14 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "rustls"
-version = "0.23.43"
+version = "0.23.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0283386ce02abc0151e1761d08802dfe86c173b0b494af5cbc086574e453da06"
+checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
 dependencies = [
  "aws-lc-rs",
  "once_cell",
@@ -3483,7 +3483,7 @@ dependencies = [
  "security-framework",
  "security-framework-sys",
  "webpki-root-certs",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3578,7 +3578,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.12.0"
+version = "0.13.1"
 dependencies = [
  "anyhow",
  "bitflags 2.13.1",
@@ -4158,10 +4158,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.4.3",
+ "getrandom 0.3.4",
  "once_cell",
  "rustix",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -4819,7 +4819,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]

{python_aaronia-0.12.0 → python_aaronia-0.13.1}/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.12.0"
+version = "0.13.1"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"
@@ -139,3 +139,7 @@ widestring = { version = "1.1", optional = true }
 
 [workspace]
 members = ["python-aaronia"]
+
+[[example]]
+name = "native_sdk_qualification"
+required-features = ["native-sdk", "http", "file"]

{python_aaronia-0.12.0 → python_aaronia-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.12.0
+Version: 0.13.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -103,41 +103,39 @@ common fields.
 
 The
 [quickstart](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/QUICKSTART.md)
-covers configuring the RTSA-Suite HTTP Server block, which everything
-above depends on.
+covers configuring the RTSA-Suite HTTP Server block for HTTP sources. Native SDK sources do not require that server.
 
-## Sample rates
+## Sample rate and RF span
 
-The device runs a ladder of rates rather than a continuous range: each
-rung is half the one above it. Ask for anything else and it quietly
-uses the nearest rung, leaving your program computing against a rate
-that is not in use.
+The module-level `sample_rates()` and `sample_rate_for_bandwidth()` functions
+remain legacy HTTP/ECO helpers. They are not capabilities of every native device.
+For a native IQ receiver, request RF span separately and inspect packet geometry:
 
 ```python
-aaronia.sample_rates()                  # every rate, highest first
-aaronia.sample_rate_for_bandwidth(8e6)  # 15.36e6: the lowest rate covering 8 MHz
+cfg = aaronia.SpectranConfig()
+cfg.force_native_sdk = True
+cfg.device_serial = "YOUR_DEVICE_SERIAL"
+cfg.native_mode = "iqreceiver"
+cfg.rf_span_hz = 44e6
+cfg.center_frequency_hz = 280e6
+cfg.reference_level_dbm = -50
+src = aaronia.SpectranSource()
+src.start_streaming(cfg)
+print(src.capabilities())                 # schema_version + capabilities
+samples = src.read_samples_numpy(65536)
+print(src.source_info())                  # observed rate and RF span
+src.set_rf_span_hz(20e6)
+src.stop_streaming()
 ```
 
-**Sample rate is not RF bandwidth.** You get every sample, so an FFT of
-them spans the full rate — but only the middle 80% is flat and
-calibrated. That is not an approximation: RTSA reports exactly 0.8 x Fs
-as the packet's frequency range at every rate. Outside it, data still
-arrives, attenuated and uncalibrated.
-
-So **to see N Hz of spectrum, sample at N / 0.8**, which is what
-`sample_rate_for_bandwidth()` computes. Aaronia's data sheet is more
-conservative still — 44 MHz for the ECO against the 49.152 MHz it
-declares at full span — because the analog filter is ~1 dB down by that
-edge. The
-[quickstart](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/QUICKSTART.md#4-troubleshooting)
-has the measurements.
-
-`sample_rates()` returns the V6 ECO's ladder, 61.44 MHz down to 120 kHz.
-A full V6 selects its receiver clock and goes higher, by how much is
-unsettled; see
-[the note in HTTPSPEC](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/HTTPSPEC.md#unresolved-the-full-v6s-top-rate).
-There, trust the rate the device reports in stream metadata, which
-`diagnose()` prints.
+IQ sample clock and valid RF span are distinct. The tested ECO delivered 44 MHz
+RF span at about 59.214 MS/s, and 20 MHz at 30 MS/s. Native configuration bounds
+may exceed the model's rated bandwidth. Neither those bounds nor RF span certifies
+amplitude calibration. Unknown metadata stays unknown. See the
+[qualification matrix](../docs/NATIVE_SDK_COMPATIBILITY.md).
+
+For HTTP only, the legacy helper uses the measured 0.8×Fs filter width and ECO
+rate ladder. Prefer `source_info()` for what the stream actually delivered.
 
 ## Choosing a wire format
 
@@ -178,6 +176,11 @@ Every field is readable and writable.
 | `file_path` | Path to a recorded `.rtsa` file; pins the file backend |
 | `device_serial` | Device selection for the native-SDK backend |
 | `force_native_sdk` | `True` pins the source to the native SDK; missing SDK is an error |
+| `native_family` | Optional bare SDK family, e.g. `"spectranv6eco"` |
+| `native_mode` | Optional receive-only `"iqreceiver"` or `"raw"` |
+| `rf_span_hz` | Optional requested native IQ receiver RF span, Hz |
+| `receiver_clock` | Optional enabled raw-mode SDK clock label |
+| `decimation_factor` | Optional raw-mode power-of-two factor |
 | `center_frequency_hz` | Center frequency, Hz |
 | `sample_rate_hz` | IQ sample rate (Fs), Hz |
 | `reference_level_dbm` | Reference level, dBm |

{python_aaronia-0.12.0 → python_aaronia-0.13.1}/README.md

@@ -240,11 +240,11 @@ Add the following to your `Cargo.toml`:
 ```toml
 [dependencies]
 # By default, includes HTTP, File and C FFI backend support
-sdr-aaronia-rs = "0.12"
+sdr-aaronia-rs = "0.13"
 tokio = { version = "1.43", features = ["rt-multi-thread", "macros"] }
 
 # To enable additional backends, opt into their features (e.g. native-sdk, futuresdr)
-# sdr-aaronia-rs = { version = "0.12", features = ["native-sdk", "futuresdr"] }
+# sdr-aaronia-rs = { version = "0.13", 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.
@@ -330,6 +330,40 @@ building from source and the wire-format trade-offs are in
 [PLUGINS.md](PLUGINS.md); pass `format=I16` to halve network bandwidth,
 which is a real wire-format change rather than a client-side conversion.
 
+### Native SDK geometry and lifecycle
+
+Enable `native-sdk` on Windows or Linux and install Aaronia's SDK separately.
+RTSA-Suite does not need to be running. `NativeReceiverOptions` selects a
+receive-only mode and an RF span independently of `sample_rate_hz`:
+
+```rust,no_run
+# #[cfg(all(feature = "http", feature = "file", feature = "native-sdk", any(target_os = "windows", target_os = "linux")))]
+# async fn example() -> sdr_aaronia_rs::Result<()> {
+use sdr_aaronia_rs::{SpectranSourceBuilder, SourceType};
+use sdr_aaronia_rs::capabilities::NativeReceiverOptions;
+let mut builder = SpectranSourceBuilder::new();
+builder.force_source_type(SourceType::NativeSdk);
+builder.device_serial("YOUR_DEVICE_SERIAL".to_owned());
+builder.native_options(NativeReceiverOptions {
+    mode: Some("iqreceiver".into()),
+    rf_span_hz: Some(44e6),
+    ..Default::default()
+});
+let mut source = builder.build().await?;
+let capabilities = source.device_capabilities().await;
+source.start_streaming().await?;
+// After reading IQ, capture_sample_rate_hz / capture_bandwidth_hz describe
+// the delivered samples. Configuration bounds do not certify RF performance.
+source.stop_streaming().await?;
+# Ok(())
+# }
+```
+
+Stop releases the device. Restart on the same unified source reopens the selected
+serial and reapplies settings. Unknown metadata stays unknown; there is no
+universal ECO/V6 bandwidth ratio. See the
+[mode and qualification matrix](docs/NATIVE_SDK_COMPATIBILITY.md) for tested scope.
+
 ### seify (Rust-native)
 
 Enable the `seify` feature and construct the device with

python_aaronia-0.13.1/docs/NATIVE_SDK_COMPATIBILITY.md

@@ -0,0 +1,99 @@
+# Native SDK configuration and qualification (0.13)
+
+The driver queries the opened device and mode rather than imposing one ECO's
+rate ladder on every SPECTRAN. `DeviceCapabilities` reports SDK configuration
+metadata; it does not certify every model, hardware option or licensed mode.
+Aaronia's [current compact USB range](https://aaronia.com/en/shop/spectrum-analyzer/real-time/compact-usb)
+has different bandwidths and receiver/transmitter options. Consult the specific
+model's rating as well as the SDK's enabled options.
+
+## Supported receive paths
+
+| Family / mode | Configuration path | Validation here |
+| --- | --- | --- |
+| `spectranv6eco/iqreceiver` (automatic ECO default) | RF span via `main/spanfreq`; actual rate/span from IQ packets | Windows ECO mono live trial |
+| `spectranv6/iqreceiver` | RF span via `main/spanfreq`; actual rate/span from IQ packets | Mode/geometry tests; no hardware trial |
+| `spectranv6/raw`, `spectranrsa/raw` | Raw clock, channel and decimation options from ConfigInfo | Configuration/parser tests; no hardware trial |
+| `spectranv6eco/raw` (explicit only) | Enabled raw clock/channel/decimation options when exposed | Mode tests; no dual-ECO hardware trial |
+| ECO `rtsa`, V6/ECO `sweepsa` | Low-level spectra API only; refused by unified IQ configuration | Payload guards |
+| Other family/mode strings | Enumeration may accept an explicit family; unknown IQ payload modes are refused | No hardware claims |
+
+Automatic discovery tries the known family names. `DeviceNotFound` and
+`DeviceNotReady` are typed errors; SDK ownership errors retain `SdkApi` codes.
+The application chooses its retry deadline. No retry silently changes device,
+starts RTSA, or takes over a device owned by another process.
+
+## Three different bandwidth values
+
+1. `NativeReceiverOptions.rf_span_hz` / `set_rf_span_hz`: requested RF span in an
+   IQ receiver mode. The setter returns SDK read-back while open, or the queued
+   request while stopped; restart revalidates deferred settings.
+2. `DeviceCapabilities.rf_span_hz`: SDK ConfigInfo setting bounds. The tested ECO
+   SDK returned 1 Hz–200 MHz, exceeding that model's 44 MHz rated width. These
+   bounds alone must not be presented as a calibrated hardware bandwidth.
+3. `capture_bandwidth_hz()` / `SourceInfo.bandwidth_hz`: valid RF span declared by
+   the IQ packets actually returned. `capture_sample_rate_hz()` is the separate
+   IQ sample clock. Unavailable capture bandwidth is zero (unknown).
+
+RF span does not establish dBm amplitude calibration. The legacy HTTP 0.8×Fs
+helper and the IQ receiver's legacy Fs/1.5 request translation are compatibility
+helpers, not universal hardware laws. Use explicit RF span and observed packet
+geometry when the recording or display depends on exact coverage.
+
+## Explicit raw configuration
+
+Select `mode=raw`, then use an enabled `receiver_clock` label and/or a power-of-two
+`decimation_factor`. The option's original index is retained despite disabled or
+empty entries. An unavailable/disabled request fails before configuration writes.
+Explicit raw clock/decimation selects the pipeline instead of the legacy
+`sample_rate_hz` request. The delivered packet rate remains authoritative.
+Receiver channels are validated against the opened raw mode. A mono ECO trial
+cannot establish dual-RX support, interleaving, or the licensed options of a
+200-series ECO, PLUS or XPR device.
+
+## Opening, stopping and reopening
+
+Partial open/connect/start failures attempt all applicable cleanup. Stop attempts
+stop, disconnect and close, returning the first error after attempting the rest.
+A failed close remains owned for a Drop retry. Repeated start/stop calls are
+idempotent; successful stop clears stale carry/geometry. Unified restart reopens
+the same serial and mode, reapplying settings. Settings queued while stopped are
+checked against fresh metadata before writes on reopen. SDK calls themselves
+remain vendor operations without a driver-imposed cancellation deadline.
+
+## Binding parity
+
+Rust exposes typed capabilities/options. C adds capability JSON (schema version
+1), RF span range/setter and builder options without changing existing C struct
+layouts; free JSON with `spectran_string_free`. Python exposes config fields,
+`capabilities()`, `source_info()` and `set_rf_span_hz()`. Seify and Soapy consume
+reported bounds; an unknown native discrete rate ladder is empty rather than a
+fabricated ECO ladder. Soapy's native bandwidth is observed RF span, not Fs×0.8.
+Soapy TX setup now requires explicit `tx=true` and compatible licensed hardware.
+
+## Windows live result, 2026-10-08
+
+An explicitly selected SPECTRAN V6 ECO on Windows, SDK API 1.0.4, was tested with
+RTSA closed, reference level −50 dBm, 65,536-sample reads and five eight-second
+cycles. Each cycle called start twice, read IQ, then called stop twice. Frequency
+and reference settings were queued while closed; restart reopened the same serial.
+
+| Cycle | Requested / observed RF span | Observed IQ rate | Centre | Returned samples |
+| --- | --- | --- | --- | --- |
+| 1 | 44 MHz | 59.2137035 MS/s | 280 MHz | 268,500,992 |
+| 2 | 20 MHz | 30 MS/s | 281 MHz | 196,476,928 |
+| 3 | 10 MHz | 15 MS/s | 282 MHz | 98,435,072 |
+| 4 | 5 MHz | 7.5 MS/s | 283 MHz | 49,119,232 |
+| 5 | 44 MHz | 59.2137035 MS/s | 284 MHz | 388,038,656 |
+
+The program exited successfully and printed its completion marker. The cumulative
+discontinuity count was one from the first cycle and did not increase. Signals
+was restored afterward with fresh samples and its previous tune/reference level.
+This short mono trial does not establish endurance, hot-unplug recovery, Linux
+hardware operation, wider raw clocks, dual-RX, TX or all-model compatibility.
+
+Reproduce only on a device available for exclusive receive use:
+
+```sh
+cargo run --example native_sdk_qualification --features native-sdk -- YOUR_DEVICE_SERIAL 8
+```

{python_aaronia-0.12.0 → python_aaronia-0.13.1}/docs/SDKSPEC.md

@@ -6,6 +6,24 @@ The Aaronia Real-Time Spectrum Analyzer (RTSA) Vendor Software Development Kit (
 
 > **Status & attribution.** This document is a *community-compiled* reference, **not** an official Aaronia specification. It is assembled from Aaronia's official open-source sample code, public posts on the Aaronia V6 forum, vendor SDK headers, and empirical analysis. Where these disagree, the vendor's own materials are authoritative. See [Sources and Attribution](#sources-and-attribution) for the upstream, vendor-published references.
 
+## Sweep reference level (0.13.1)
+
+Use `configure_sweepsa_with_reference_level(&config, Some(-50.0))` to apply a
+reference level in dBm. `None` preserves the previous setting, as the existing
+`configure_sweepsa` call does. Explicit levels are validated against SDK metadata
+before any sweep geometry is changed. This additive method carries Specola's
+vendor functionality without adding a field to the public `SweepsaConfig` struct.
+
+## Current driver behavior (0.13)
+
+See [Native SDK compatibility and qualification](NATIVE_SDK_COMPATIBILITY.md)
+for the current configuration, lifecycle and binding contract. Older empirical
+measurements below describe their particular mode/device, not every V6 variant.
+IQ `stepFrequency` is the actual sample clock; `spanFrequency` is valid RF span;
+centre is `startFrequency + spanFrequency / 2`. The driver carries these values
+with the returned IQ, never replacing RF span with a universal clock ratio.
+SDK ConfigInfo bounds can exceed a model's rated bandwidth.
+
 ## Table of Contents
 
 - [Features and Purpose](#features-and-purpose)
@@ -53,7 +71,7 @@ The Aaronia RTSA Vendor SDK provides low-level, high-performance access to Aaron
     *   **Clock Rates** (V6): 46MHz (46.08), 61MHz (61.44), 76MHz (76.80), 92MHz (92.16), 122MHz (122.88), 184MHz (184.32), 245MHz (245.76), 492MHz (491.52) — see the full label table under [Rust Binding Notes](#rust-binding-notes)
     *   **Clock Rates** (V6 ECO): fixed at 92.16 MHz. Its top IQ rate is 61.44 MHz, which is that clock over 1.5 — easy to confuse, and confusing them records the rate as the clock
     *   **Decimation**: Full, 1/2, 1/4, 1/8, 1/16, 1/32, 1/64, 1/128, 1/256, 1/512
-    *   **IQ Mode Sample Rate**: equal to `spanfreq` (constraint: `spanfreq ≤ receiverclock / 1.5`). Measured on a V6 ECO, untested on a full V6, and not obviously consistent with Aaronia's own 245 MHz / 250 Msample figures for the V6 — see [HTTPSPEC](HTTPSPEC.md#unresolved-the-full-v6s-top-rate)
+    *   **IQ receiver sample rate**: reported by packet `stepFrequency`, separately from `spanfreq` / RF span. Lower ECO spans measured 1.5× span, with an independent ceiling at wider spans; this is not a raw-mode constraint
 *   **Health Monitoring**: Real-time device status including temperatures, sample rates, power levels, USB statistics, GPS data
 
 ## Verified Architecture
@@ -396,7 +414,7 @@ a `/2ⁿ` ladder: a 10 MHz request streams at 15.0 MS/s, 15.36 at 23.04,
 Every rung of a request→delivered sweep was ×1.5 to the third decimal.
 This crate's `sample_rate_hz` is the sample rate (the HTTP backend
 delivers exactly it), so `configure_iq_receiver` writes `rate / 1.5` on
-this mode and the caller gets the rate it named on every backend; a
+this mode as a compatibility request, subject to the observed ceiling; a
 15.36 MS/s request now measures 15.360 MS/s, and `sample_rate_hz` reports
 what the packets carry. Two more measured facts: the pipeline delivers
 ~40% of rate for ~5 s after start and flags one `TIME_DISCONTINUITY` as
@@ -405,47 +423,23 @@ it settles, then holds 100.0% with no further flags; and it sets
 which is why that flag is not treated as an overrun. `spectranv6/raw` on
 a full V6 has not been measured and is left untranslated.
 
-### IQ-mode receiver clock constraint
-
-`NativeSdkSource::configure_iq_receiver` calls
-`utils::validate_iq_mode(rate, clock)` twice, and the order matters.
-
-The gate runs **before the first config write**, against the clock the
-call *leaves in place* — which is not always the one the device holds on
-entry:
-
-- On `spectranv6/raw`, the function writes `device/receiverclock` itself
-  (`DEFAULT_RECEIVER_CLOCK_LABEL`, `"92MHz"`, = 92.16 MHz), so that write
-  decides the clock and the check uses it. Checking the *current* setting
-  here would pass a rate the incoming clock cannot carry: a V6 left on
-  245.76 MHz would accept 150 MS/s and then have the clock pulled down to
-  92.16 MHz underneath it.
-- On every other open mode the clock write is skipped
-  (`DeviceOpenMode::supports_raw_only_keys` is true only for `Raw`), so
-  the device keeps what it has and the check reads it live. An eco
-  exposes no such key and falls back to the 92.16 MHz default; a full V6
-  in a non-raw IQ mode may sit on a faster clock, and assuming 92.16
-  there would refuse rates it can genuinely reach.
-
-The second call runs after the writes, against the clock read back from
-`device/receiverclock` via `AARTSAAPI_ConfigGetString`. Its real job is
-to make `receiver_clock_hz()` report the device's own number rather than
-the requested one. As a check it is deliberately weak in one direction:
-the rate already fits the intended clock, so a device sitting on a
-*faster* clock than intended still passes — an ignored clock write is
-invisible here, and harmless, because a rate that fits 92.16 MHz also
-fits 245.76. What it catches is a device on a clock too slow for the
-rate, which the pre-write check had no way to know about. That error
-says the device is already configured, since unlike the pre-write refusal
-there is no prior state to restore.
-
-Both enforce `rate * 1.5 <= clock`; the pre-write one returns
-`Error::Config` from `validate_iq_mode`, the post-write one wraps it in
-an `Error::Sdk`. `utils::the_92mhz_label_is_the_default_receiver_clock`
-pins the label↔rate equality the raw-mode arm depends on.
-
-The ConfigItem labels the SDK exposes are *rounded* — `"92MHz"` is
-actually 92.16 MHz, etc. Use `receiver_clock_for_label` to convert.
+### Mode-specific validation (0.13)
+
+IQ receiver requests validate `main/spanfreq` against the opened mode's ConfigInfo
+before writes. They do not use a default 92 MHz raw clock as a ceiling. Explicit
+RF span avoids the legacy Fs/1.5 translation; packet geometry reports what was
+actually delivered, including the independent USB/IQ ceiling.
+
+Raw modes retain the legacy default clock/rate validation for callers that do not
+request explicit raw controls. `NativeReceiverOptions.receiver_clock` and
+`decimation_factor` instead select enabled device-provided enum options; they do
+not apply the legacy 1.5× check to a wider raw pipeline. Actual rate comes from
+packets. A decimation-only request preserves the currently reported clock when
+available. Unknown capabilities remain unknown; the legacy `receiver_clock_hz()`
+fallback is not proof of the installed hardware's clock.
+
+The ConfigItem labels are rounded (`"92MHz"` is 92.16 MHz). The legacy conversion
+table is retained below; explicit labels are validated against the device options.
 
 | Label    | Actual rate    | Source             |
 |----------|----------------|--------------------|

python_aaronia-0.13.1/examples/native_sdk_qualification.rs

@@ -0,0 +1,94 @@
+//! Receive-only ECO qualification: explicit serial, span, carry and stop/reopen.
+//! Run only with the radio released by other apps; no TX is opened.
+#[cfg(all(
+    feature = "native-sdk",
+    any(target_os = "windows", target_os = "linux")
+))]
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> anyhow::Result<()> {
+    use sdr_aaronia_rs::{Error, SourceType, SpectranSourceBuilder};
+    use std::time::{Duration, Instant};
+    let serial = std::env::args()
+        .nth(1)
+        .ok_or_else(|| anyhow::anyhow!("Pass the explicit USB serial"))?;
+    let seconds: u64 = std::env::args()
+        .nth(2)
+        .map(|s| s.parse())
+        .transpose()?
+        .unwrap_or(8);
+    anyhow::ensure!(
+        (2..=30).contains(&seconds),
+        "cycle duration must be 2–30 seconds"
+    );
+    let mut builder = SpectranSourceBuilder::new();
+    builder
+        .force_source_type(SourceType::NativeSdk)
+        .device_serial(serial)
+        .center_frequency_hz(280e6)
+        .reference_level_dbm(-50.0)
+        .rf_span_hz(44e6);
+    let until = Instant::now() + Duration::from_secs(15);
+    let mut source = loop {
+        match builder.build().await {
+            Ok(source) => break source,
+            Err(Error::DeviceNotReady { .. } | Error::DeviceNotFound { .. })
+                if Instant::now() < until =>
+            {
+                tokio::time::sleep(Duration::from_millis(500)).await
+            }
+            Err(error) => return Err(error.into()),
+        }
+    };
+    println!("{}", source.device_capabilities().await.to_json()?);
+    let mut buffer = Vec::new();
+    for (index, span) in [44e6, 20e6, 10e6, 5e6, 44e6].into_iter().enumerate() {
+        if index > 0 {
+            source.set_rf_span_hz(span).await?;
+        }
+        source.start_streaming().await?;
+        source.start_streaming().await?; // Must be idempotent.
+        let until = Instant::now() + Duration::from_secs(seconds);
+        let mut samples = 0usize;
+        let mut reads = 0;
+        while Instant::now() < until {
+            match source.read_samples(&mut buffer, 65536).await {
+                Ok(n) => {
+                    samples += n;
+                    reads += 1;
+                }
+                Err(Error::Io(error)) if error.kind() == std::io::ErrorKind::TimedOut => continue,
+                Err(error) => return Err(error.into()),
+            }
+        }
+        let info = source.source_info();
+        println!(
+            "{{\"cycle\":{index},\"requested_span_hz\":{span},\"sample_rate_hz\":{},\"rf_span_hz\":{},\"center_hz\":{},\"samples\":{samples},\"reads\":{reads},\"drops\":{}}}",
+            info.sample_rate_hz,
+            info.bandwidth_hz,
+            info.center_frequency_hz,
+            source.cumulative_drops()
+        );
+        anyhow::ensure!(samples > 0, "no IQ in cycle {index}");
+        anyhow::ensure!(
+            (info.bandwidth_hz - span).abs() < 1.0,
+            "RF width differs from request"
+        );
+        source.stop_streaming().await?;
+        source.stop_streaming().await?; // Must not close twice.
+        // Configuration while closed is deferred; start reopens the same serial.
+        source
+            .set_center_frequency_hz(280e6 + (index + 1) as f64 * 1e6)
+            .await?;
+        source.set_reference_level_dbm(-50.0 + index as f64).await?;
+    }
+    source.stop_streaming().await?;
+    println!("{{\"qualification_complete\":true}}");
+    Ok(())
+}
+#[cfg(not(all(
+    feature = "native-sdk",
+    any(target_os = "windows", target_os = "linux")
+)))]
+fn main() {
+    eprintln!("Requires native-sdk on Windows or Linux");
+}

{python_aaronia-0.12.0 → python_aaronia-0.13.1}/include/spectran.h

@@ -305,6 +305,13 @@ SpectranFfiError spectran_endpoints_client_control_recording(HttpEndpointsClient
 
 // --- General FFI Utilities --- //
 
+/* Additive native SDK APIs; existing struct layouts remain unchanged. */
+char *spectran_source_capabilities_json(void *source);
+SpectranFfiError spectran_source_rf_span_range(void *source, double *min_hz, double *max_hz);
+SpectranFfiError spectran_source_set_rf_span_hz(void *source, double hz);
+SpectranFfiError spectran_source_builder_native_options(SpectranSourceBuilder *builder,
+    const char *family, const char *mode, double rf_span_hz, const char *clock, uint32_t decimation);
+
 void spectran_string_free(char* s);
 // Takes the code as an int so any value is safe to pass; unknown codes
 // yield "Unknown error code".

{python_aaronia-0.12.0 → python_aaronia-0.13.1}/python-aaronia/Cargo.toml

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