python-aaronia 0.8.1__tar.gz → 0.9.0__tar.gz

{python_aaronia-0.8.1 → python_aaronia-0.9.0}/CHANGELOG.md

@@ -2,6 +2,230 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Added
+- **SoapySDR: device sensors.** The plugin exposed one sensor
+  (`cumulative_drops`); it now surfaces the device's live telemetry from
+  `/healthstatus` — FPGA and frontend temperature, ADC headroom (dB below
+  full scale, so a client can raise the reference level before it clips),
+  USB and DSP buffer fill, error and overflow rates, GPS satellites and
+  position. `listSensors` / `readSensor` / `getSensorInfo`, read through a
+  dedicated connection and briefly cached, so polling them during a
+  capture neither stalls the sample stream nor costs a fetch per key.
+  HTTP backend only: the native SDK's own `AARTSAAPI_ConfigHealth` tree
+  reads all zeros in raw-SDK mode — the live telemetry is computed and
+  populated by RTSA-Suite, the managing application, not by the raw SDK,
+  confirmed by dumping the tree live from a V6 ECO — so over `sdk=true`
+  the plugin reports only `cumulative_drops`, which is real and
+  client-side. Verified live over HTTP on a V6 ECO.
+- **SoapySDR: bandwidth API.** `setBandwidth` / `getBandwidth` /
+  `listBandwidths` / `getBandwidthRange`. The device's alias-free
+  bandwidth is 0.8x its sample rate; these expose that as SoapySDR's
+  separate knob, mapping a requested bandwidth to a sample rate and
+  driving the already-verified `setSampleRate` — no new device-write path.
+  Verified on a V6 ECO: 15.36 MS/s reports 12.288 MHz, `setBandwidth`
+  snaps to a rung.
+- **SoapySDR: the native SDK is discoverable.** `find` advertises a
+  second `sdk=true` device beside the HTTP one whenever the SDK is
+  installed, and `sdk=true` / `serial=` force the native backend instead
+  of silently falling back to localhost HTTP. Verified streaming 15.357
+  MS/s over the SDK through the plugin from Python.
+- **C ABI.** `aaronia_source_read_sensors` (fills a value struct, `NaN`
+  for absent — no ownership, nothing to free);
+  `aaronia_source_builder_force_source_type` and `aaronia_sdk_installed`,
+  the C equivalent of `force_native_sdk`, which C had no way to request;
+  and the stateless bandwidth helpers `aaronia_usable_bandwidth_hz` /
+  `aaronia_iq_sample_rate_for_bandwidth`. `DeviceSensors` is the Rust type
+  behind the first.
+
+### Fixed
+- **File playback reported the decompression time as the capture time.**
+  A DSPT_IQ-compressed `.rtsa` is decompressed through RTSAFileTool, which
+  writes a fresh header stamped with the moment of conversion, so the
+  re-opened file reported *now* — a 2020 capture read as 2026. The
+  original header's `creation_time`, parsed before compression was
+  detected, is now carried across the decompression, and the derived
+  start/end fall-backs follow it. Surfaced the first time the fixture test
+  ran on a machine with RTSA-Suite installed.
+- **The SoapySDR plugin could not load the SDK inside a host that carries
+  its own Qt6.** The loader was given `LOAD_LIBRARY_SEARCH_DEFAULT_DIRS`,
+  which searches the host application's directory first; a GNU Radio
+  (radioconda) install holds a different Qt6 build there under the same
+  names, and the load failed. It now searches only the DLL's own
+  directory, the SDK install root, and System32.
+- **The Seify native-SDK test panicked on teardown.** `AaroniaSeifyDevice`
+  owns a tokio runtime, and dropping one inside an async context is a
+  tokio panic; the test is synchronous now.
+
+## [v0.8.2] - 2026-09-08
+
+The native-SDK backend, validated on a Spectran V6 ECO on Windows 11 for
+the first time. Every item below was found by running against the device;
+the suite that found them ships as `tests/native_sdk_live.rs`.
+
+### Fixed
+
+- **The SDK library could not load on a stock Windows install.** RTSA-Suite
+  PRO puts `AaroniaRTSAAPI.dll` in `sdk\` and its ~23 dependencies (Qt6,
+  avcodec, libcrypto, …) in the install root; `LoadLibraryExW` searches
+  neither, so detection found the file and the load failed with a bare
+  `LoadLibraryExW failed`. The install root is added to the DLL search list
+  (`AddDllDirectory`) and the library loaded with the
+  `LOAD_LIBRARY_SEARCH_*` flags that consult it — not `SetDllDirectory`,
+  which would switch safe search mode off for the whole host process.
+- **A V6 ECO was never found.** `init_native_sdk` enumerated the family
+  `spectranv6` only; the ECO answers to `spectranv6eco`, so a machine
+  holding one reported "No Spectran V6 devices found" with the device on
+  the bus. Each known family is now tried, as `detect_device_family`
+  already documented.
+- **ECO IQ came from the spectrum pipeline at 0.4 MS/s.** The ECO's raw-IQ
+  mode was mapped to `spectranv6eco/rtsa`, which is its spectrum pipeline
+  (`RawSpectrumEco.cpp`); IQ read from it arrived at ~0.4 MS/s whatever
+  rate was asked for. `spectranv6eco/iqreceiver` — the mode Aaronia's own
+  `IQReceiverEco.cpp` opens — is used instead. `/raw` also opens on an ECO
+  but has no `main/spanfreq`, so it cannot honour a requested rate.
+- **The ECO delivered 1.5× the requested rate.** In `iqreceiver` mode
+  `main/spanfreq` is a bandwidth and the pipeline streams at 1.5× it —
+  every rung exactly, 10 MHz → 15.0 MS/s, 15.36 → 23.04 — up to a
+  59.2 MS/s USB ceiling. The request is now translated so the caller gets
+  the rate it named on every backend: a 15.36 MS/s request measures
+  15.360 MS/s over 153 M samples.
+- **Native-SDK loss was invisible.** Packet flags `WARN_DROPPED` and
+  `TIME_DISCONTINUITY` were logged at debug level and nothing else, so
+  `cumulative_drops()` read 0 through any amount of loss and
+  `last_timestamp_ns()` read 0 always. Both, and `take_overrun()`, now
+  report the native source's packets. `WARN_INACCURATE` is deliberately
+  not an overrun: the ECO's fractional resampler sets it routinely.
+- **`sample_rate_hz()` echoed the request on native sources.** It now
+  reports the rate the device's packets carry once one has been read, as
+  the HTTP backend already did.
+- **`read_samples` and `read_samples_dual` returned one packet per call**
+  however large `max_samples` was. Both now drain already-queued packets
+  until the caller is satisfied, waiting only for the first — and not
+  even that when carry-over samples were already handed out, where the
+  old code could sleep out the whole poll deadline on a backlog.
+- **A `device_serial` in the second family was never found.** Family
+  enumeration stopped at the first family holding any device, so a
+  machine with both a V6 and an ECO could not select the ECO by serial.
+  Every family is enumerated and the serial resolved across them.
+- **Python could not ask for the SDK.** `python-aaronia` depended on the
+  crate's default features, which exclude the backend, and `aaronia.open()`
+  with neither `url` nor `file` pinned to localhost HTTP rather than
+  auto-detecting. A `native-sdk` feature and `open(sdk=True, serial=…)` /
+  `AaroniaConfig.native_sdk` select it explicitly; a missing SDK is then
+  an error, never a silent fallback.
+- **A unit test assumed no SDK on the machine.**
+  `test_detect_best_source_type_localhost_fallback` asserted the
+  localhost-HTTP fallback unconditionally, so `cargo test` failed on any
+  machine with RTSA-Suite installed — the one place the backend gets
+  tested. It now asserts the actual rule: the SDK when installed, HTTP
+  otherwise.
+- **The Soapy plugin's Windows build assumed MSVC.** The Rust static-lib
+  name is keyed on the compiler now, not the OS; the windows-gnu toolchain
+  emits `libsdr_aaronia_rs.a`.
+
+### Added
+
+- `tests/native_sdk_live.rs`: thirteen hardware tests — detection,
+  identity, ten open/close cycles, a centre-frequency sweep, mid-stream
+  retune, a span-ladder characterisation that records the device-reported
+  rate per rung, a steady-state rate check, a soak with drop accounting,
+  error-message quality, and the Seify and C-ABI paths.
+- `scripts/native-sdk-validate.ps1`: runs the whole matrix on a Windows
+  machine with a device.
+- `NativeSdkSource::{observed_sample_rate_hz, cumulative_drops,
+  take_overrun, last_timestamp_ns}`.
+
+### Measured on a V6 ECO (Windows 11, RTSA-Suite PRO 3.0.3)
+
+Every ladder rung from 3.84 to 49.152 MHz delivers exactly the requested
+rate, 3/3 trials each; 61.44 MHz caps at 59.214 MS/s. Steady-state
+delivery is 100.0% of the reported rate. The `iqreceiver` pipeline
+delivers ~40% of rate for the first ~5 s after start, then settles; the
+rate and soak tests warm up past it. The SoapySDR plugin, built with
+MSVC against radioconda's SoapySDR, streams 15.357 MS/s over the SDK
+into Python; see [docs/VERIFICATION.md](docs/VERIFICATION.md) for the
+two limits found on the way.
+
+
+_Also in 0.8.2 (recorded here on the 0.9.0 pass; these landed across the 0.8.x docs/perf commits and were never restamped):_
+
+### Performance
+- **The int16 and float16 IQ decoders are ~23% faster end to end.** Both
+  built their output with `Vec::with_capacity` then `push` per sample,
+  which carries a capacity check the compiler cannot elide and which was
+  blocking vectorisation. Collecting from the slice iterator instead —
+  `TrustedLen`, so the vector is sized once — measured 495 to 2433 MS/s
+  on the decode loop alone, and 123.5 to 152 MS/s over the whole HTTP
+  path including framing and transport. float32 was already a single
+  `copy_nonoverlapping` and is unchanged.
+
+  Worth stating what this does not buy: at 605 MB/s the crate is about
+  2.5x the fastest a V6 can produce and 6x a WiFi 6E link, so it was not
+  the bottleneck before and is not now. What it buys is CPU left over
+  for whatever consumes the samples.
+
+### Added
+- **`scripts/fake-rtsa-server.py`** serves `/stream` in the real wire
+  format at loopback speed, so a decode path can be measured without a
+  device or a network. It is how the figures above were taken: over any
+  real link the transport dominates and a CPU change is invisible. Its
+  docstring carries the caveat that goes with it — over loopback hyper's
+  adaptive read buffer never leaves its 8 KiB floor, so kernel time there
+  is a property of the harness, not of the crate.
+
+### Documentation
+- **`rate_reduction` is time compression, not a sample-rate divider.**
+  Five places described it as reducing the rate or optimising bandwidth.
+  It thins frames over time — the operation the `waterfall` payload is
+  described by — so a continuous IQ stream, having no frames, is
+  unaffected: measured at factors of 2, 10 and 64, `sampleFrequency`
+  holds at 15,359,988 Hz and the byte rate does not move. That is the
+  parameter behaving as specified on a payload it was not meant for.
+  `live_stream_rate_reduction_and_scale` had asserted only that packets
+  arrived, which is true either way, so nothing caught the wrong
+  description; it now pins the IQ behaviour.
+- **The stream can be compressed, up to 6.55x, via `format=rtsa`.**
+  Captured from RTSA-Suite's own HTTP Client block:
+  `GET /stream?format=rtsa&rate_reduction=8&input=main&compression=5&rate_adaption=0`.
+  `format=rtsa` streams the file container and is the only format that
+  accepts `compression=N`, which applies the file format's own lossy
+  codec. The container carries `float32` (`mSampleType` 11, `DSST_F32N`),
+  so level 0 is plain float32 with under 1% of chunk overhead — 123.0
+  MB/s against 122.9 theoretical at 15.36 MS/s. Against that baseline the
+  codec buys 2.74x at level 1, 4.43x at level 5 and 13.10x at level 9;
+  even level 1 undercuts plain `int16` while carrying float precision.
+  Ratios hold at 3.84 MS/s too.
+
+  HTTPSPEC had documented `format=rtsa` only as the thing a typo falls
+  back to — "a completely different wire format rather than an error" —
+  and this release had gone on to claim compression was neither offered
+  nor useful. Both are corrected. Generic HTTP compression is still not
+  available on `/stream` and still would not help (zlib manages 1.07x on
+  `float32`); Aaronia's codec wins by being lossy and signal-aware.
+
+  This crate cannot use it for IQ, tested rather than assumed: a real
+  compressed payload handed to `Decompressor::decompress` comes back
+  rejected as proprietary `DSPT_IQ`, the same wall that stops compressed
+  IQ *files*. `format=rtsa` also defaults to `mCompression=1`, so only
+  `compression=0` is decodable and that is 20% larger than plain `int16`.
+  Spectra should decode, `DSPT_SPECTRA` being documented, but this
+  mission has no spectra input to try.
+
+### Performance
+- **The control plane is now requested compressed.** `reqwest` gains the
+  `deflate` and `gzip` features, so the client sends
+  `Accept-Encoding: gzip,deflate` where it previously sent none. Measured
+  against the device: `/remoteconfig` 17,432 bytes to 3,299 deflated,
+  `/healthstatus` 6,100 to 1,436. Both are read at every device open, and
+  `/healthstatus` again on each stream-gap report. No effect on `/stream`,
+  which the server does not compress at any level.
+- The reader channel's size comment claimed ~157 KiB chunks and ~10 MB of
+  queue. Measured against a live server it is 64 KiB for 71% of chunks,
+  so the queue is ~4 MB, about 45 ms at the 88 MB/s a WiFi 6E path
+  delivers.
+
 ## [v0.8.1] - 2026-09-07
 
 ### Fixed

{python_aaronia-0.8.1 → python_aaronia-0.9.0}/CONTRIBUTING.md

@@ -127,6 +127,20 @@ cargo bench                                       # Run all benchmarks
 cargo bench --bench parse_int16_packet            # Run a specific harness
 ```
 
+Those measure decode paths in isolation. To measure the whole HTTP path
+end to end without hardware, `scripts/fake-rtsa-server.py` serves
+`/stream` in the real wire format as fast as a client will take it:
+
+```bash
+scripts/fake-rtsa-server.py 54999 int16 &
+# then point HttpEndpointsClient::start_stream at http://127.0.0.1:54999
+```
+
+It saturates loopback at several GB/s, so the client is always the
+bottleneck. Worth reaching for when a change looks like it should be
+faster but a real link hides the difference — over WiFi or even 2.5GbE
+the network dominates and CPU work does not show up at all.
+
 ### 8. Mutation Testing
 
 `cargo mutants` runs in CI on a weekly cron (Mondays) and on manual dispatch, advisory-only. To run it locally:

{python_aaronia-0.8.1 → python_aaronia-0.9.0}/Cargo.lock

@@ -2,6 +2,12 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
 [[package]]
 name = "ahash"
 version = "0.8.12"
@@ -356,6 +362,18 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "async-compression"
+version = "0.4.43"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3976abdc8fe7d1133d43d304afd42abdf5bc3e1319d263d223bde07b5efc4be8"
+dependencies = [
+ "compression-codecs",
+ "compression-core",
+ "pin-project-lite",
+ "tokio",
+]
+
 [[package]]
 name = "async-executor"
 version = "1.14.0"
@@ -777,6 +795,23 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "compression-codecs"
+version = "0.4.38"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf"
+dependencies = [
+ "compression-core",
+ "flate2",
+ "memchr",
+]
+
+[[package]]
+name = "compression-core"
+version = "0.4.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789"
+
 [[package]]
 name = "concurrent-queue"
 version = "2.5.0"
@@ -930,6 +965,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "crc32fast"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8498c871161e1742aaa9d52551b2d6ebdd4c3d45a3be423e3728f33b955be550"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "criterion"
 version = "0.5.1"
@@ -1326,6 +1370,17 @@ dependencies = [
  "rustc_version",
 ]
 
+[[package]]
+name = "flate2"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+ "zlib-rs",
+]
+
 [[package]]
 name = "fnv"
 version = "1.0.7"
@@ -2401,6 +2456,16 @@ dependencies = [
  "unicase",
 ]
 
+[[package]]
+name = "miniz_oxide"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
 [[package]]
 name = "mio"
 version = "1.2.2"
@@ -3027,7 +3092,7 @@ dependencies = [
 
 [[package]]
 name = "python-aaronia"
-version = "0.8.1"
+version = "0.9.0"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3556,7 +3621,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.8.1"
+version = "0.9.0"
 dependencies = [
  "anyhow",
  "bitflags 2.13.1",
@@ -3790,6 +3855,12 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
 [[package]]
 name = "simd_cesu8"
 version = "1.2.0"
@@ -4376,6 +4447,7 @@ version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
+ "async-compression",
  "bitflags 2.13.1",
  "bytes",
  "futures-core",
@@ -5206,6 +5278,12 @@ dependencies = [
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "zlib-rs"
+version = "0.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34b31d188d9d685a4f9c7b46d6e36631b07058d2cfe190267adce54dc230bf12"
+
 [[package]]
 name = "zmij"
 version = "1.0.23"

{python_aaronia-0.8.1 → python_aaronia-0.9.0}/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.8.1"
+version = "0.9.0"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"
@@ -18,7 +18,13 @@ rustdoc-args = ["--cfg", "docsrs"]
 crate-type = ["cdylib", "staticlib", "rlib"]
 
 [dependencies]
-reqwest = { version = "0.13", features = ["blocking", "json", "stream"], optional = true }
+# `deflate`/`gzip`: the RTSA control plane compresses when asked and we
+# were not asking — /remoteconfig is 17,432 bytes plain against 3,299
+# deflated, /healthstatus 6,100 against 1,436, and both are fetched on
+# every device open. RTSA-Suite's own HTTP Client sends
+# `Accept-Encoding: deflate`. Costs nothing on /stream, which the server
+# does not compress at any level.
+reqwest = { version = "0.13", features = ["blocking", "json", "stream", "deflate", "gzip"], optional = true }
 serde = { version = "1.0", features = ["derive"], optional = true }
 serde_json = { version = "1.0", optional = true }
 thiserror = "2.0"
@@ -57,6 +63,11 @@ proptest = "1.5"
 criterion = { version = "0.5", features = ["html_reports"] }
 wiremock = "0.6" # For HTTP endpoint resiliency testing
 
+# The native-SDK live suite uses `#[tokio::test]`, and must build in a
+# `--no-default-features --features native-sdk` configuration where the
+# `http` feature is not pulling `dep:tokio` in.
+tokio = { version = "1.43", features = ["rt-multi-thread", "macros", "time", "sync"] }
+
 # Each `[[bench]]` declares one criterion harness binary. Run with
 # `cargo bench --bench <name>`. Coverage:
 #   parse_int16_packet    — HTTP int16 packet parse throughput

{python_aaronia-0.8.1 → python_aaronia-0.9.0}/DESIGN.md

@@ -81,7 +81,7 @@ Hop dwell deadlines come from `sdr_source::DwellController`; per-hop pacing addi
 
 The HTTP reader task (spawned by `init_http_source` in `unified_source.rs`) runs a `DropDetector` over each packet's `start_time`/`end_time` metadata. A timestamp gap larger than the tolerance latches `AaroniaSource::pending_overrun`, which `take_overrun()` reads and clears. `single_channel_pump` and `hop_pump` (`sdr_source_impl.rs`) call `take_overrun()` once per emitted `IqPacket`, so a drop detected anywhere since the last read surfaces as `IqPacket::overrun = true` on the next packet. This is a per-call signal, not a precise per-sample one, since drop timing is lost once chunks merge into the flat `sample_buffer`.
 
-The native-SDK and file backends do not populate this yet (`overrun` is always `false` for them). Native-SDK overrun detection would need to read the overflow/dropped warning bits from the packet `flags` field, which the RX path currently ignores.
+The native-SDK and file backends do not populate this yet (`overrun` is always `false` for them). Native-SDK overrun detection would need the overflow/dropped warning bits from the packet `flags` field. The RX path reads and logs those at debug level, but does not yet latch them into `pending_overrun`.
 
 The Aaronia capture thread (`AaroniaSdrSource::start`) is wrapped in `catch_unwind`: a panic inside the pump loop is logged rather than silently unwinding the thread.
 

{python_aaronia-0.8.1 → python_aaronia-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.8.1
+Version: 0.9.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -40,6 +40,14 @@ cd python-aaronia
 maturin develop --release
 ```
 
+To reach the Aaronia native SDK as well — a Spectran on this machine's
+USB, with RTSA-Suite PRO installed, on Windows or Linux — build with the
+feature; the default wheel speaks only HTTP and files:
+
+```bash
+maturin develop --release --features native-sdk
+```
+
 Check your setup before writing any code:
 
 ```bash
@@ -70,6 +78,15 @@ own schedule, or for Apache Arrow:
 
 ```python
 src = aaronia.open(freq=2.44e9, rate=15.36e6, format="I16")
+```
+
+`sdk=True` opens the device through the native SDK instead of a server
+(`serial=` picks one of several). It is an error, not a fallback, when
+the SDK is missing — a capture never quietly comes from another backend:
+
+```python
+src = aaronia.open(sdk=True, freq=2.44e9, rate=15.36e6)
+src = aaronia.open(sdk=True, serial="C2-P-03000105", freq=2.44e9)
 samples = src.read_samples_numpy(65536)       # numpy complex64 array
 batch = src.read_samples_arrow(65536)         # pyarrow FixedSizeListArray of [re, im]
 src.set_center_frequency(2.41e9)              # live retune, no teardown
@@ -157,6 +174,7 @@ Every field is readable and writable.
 | `http_base_url` | RTSA-Suite HTTP server URL; pins the HTTP backend |
 | `file_path` | Path to a recorded `.rtsa` file; pins the file backend |
 | `device_serial` | Device selection for the native-SDK backend |
+| `native_sdk` | `True` pins the source to the native SDK; missing SDK is an error |
 | `center_freq` | Center frequency, Hz |
 | `sample_rate` | IQ sample rate, Hz (the Aaronia "span") |
 | `reference_level` | Reference level, dBm |

{python_aaronia-0.8.1 → python_aaronia-0.9.0}/PLUGINS.md

@@ -17,6 +17,17 @@ sdr-aaronia-rs = { version = "0.8", features = ["seify"] }
 
 Instantiate the device with `AaroniaSeifyDevice::from_args` and use it directly (or via `seify::dev::DynDeviceBackend`). The backend is **not** part of seify's built-in enumeration registry — `seify::enumerate()` will not discover it.
 
+`url=` selects the HTTP backend and `file=` playback. `sdk=true` (or
+`serial=<device serial>`) selects the Aaronia native SDK; that needs the
+crate built with both features — `features = ["seify", "native-sdk"]` —
+on Windows or Linux with RTSA-Suite PRO installed. Without the feature
+the request is a clean error, never a fallback to HTTP.
+
+`AaroniaSeifyDevice` owns a tokio runtime. Drop it from synchronous
+code: dropping it inside an `async` context (a `#[tokio::test]`, a task)
+is a tokio panic, "Cannot drop a runtime in a context where blocking is
+not allowed".
+
 ```rust
 use sdr_aaronia_rs::seify_impl::AaroniaSeifyDevice;
 use seify::{Args, RxDevice, RxStreamer, DeviceInfo};
@@ -64,6 +75,15 @@ The plugin requires `cmake`, `SoapySDR`, and the compiled `sdr-aaronia-rs` stati
    make
    ```
 
+   On Windows, point CMake at the SoapySDR you will load the module into
+   — `-DSoapySDR_DIR="C:\Program Files\PothosSDR\cmake"` for PothosSDR,
+   or `<radioconda>\Library\cmake` for a GNU Radio (radioconda) install —
+   and build with **MSVC**. Both of those runtimes are MSVC-built, and a
+   SoapySDR module is C++ (virtual classes, `std::string` across the
+   boundary), so a MinGW-built module cannot load into them; the Rust
+   side must then be the `x86_64-pc-windows-msvc` toolchain too. Add
+   `-DAARONIA_NATIVE_SDK=ON` for the native-SDK backend.
+
 3. Ensure SoapySDR can find the plugin. You can install it to your system's Soapy modules directory (e.g. `/usr/local/lib/SoapySDR/modules0.8/`) or set the `SOAPY_SDR_PLUGIN_PATH` environment variable:
    ```bash
    export SOAPY_SDR_PLUGIN_PATH=$(pwd)/soapy-aaronia/build
@@ -80,13 +100,29 @@ SoapySDRUtil --info
 
 ### Usage
 
-The driver expects the `url` argument to connect to the Spectran V6 RTSA HTTP server.
+`url=` connects to an RTSA-Suite HTTP server block, `file=` plays back a
+recording, and `sdk=true` (or `serial=<device serial>`) opens the device
+through the Aaronia native SDK — a build with `-DAARONIA_NATIVE_SDK=ON`
+on a machine with RTSA-Suite PRO installed. A bare `driver=aaronia` keeps
+its old meaning, the HTTP server on localhost; when the SDK is installed,
+`SoapySDRUtil --find` lists a second, `sdk=true` entry beside it.
 
 ```bash
 # Example testing with SoapySDRUtil
 SoapySDRUtil --probe="driver=aaronia,url=http://localhost:54664"
+SoapySDRUtil --probe="driver=aaronia,sdk=true"
 ```
 
+Two things learned running the plugin on Windows inside a GNU Radio
+(radioconda) install: that build's Python binding rejects the `dict`
+form for every driver — `SoapySDR.Device("driver=aaronia,sdk=true")`
+works where `SoapySDR.Device(dict(driver="aaronia", sdk="true"))` raises
+"no match" — and a host process that has already loaded its own Qt6
+(GNU Radio Companion itself) cannot also load the Aaronia SDK, which
+brings a different Qt6; use `url=` from inside GRC. Loading the SDK from
+a host whose *directory* merely contains Qt6 copies, such as
+`SoapySDRUtil` in radioconda's `Library\bin`, works since 0.8.3.
+
 In Python (using `SoapySDR` python bindings):
 ```python
 import SoapySDR
@@ -146,3 +182,48 @@ In SoapySDR, you can access these metrics via the `readSensor()` API:
 drops = sdr.readSensor("cumulative_drops")
 print(f"Gaps seen: {drops}")
 ```
+
+### Sensors
+
+Over the **HTTP backend** the plugin also surfaces the device's live
+telemetry from `/healthstatus` as SoapySDR sensors. `listSensors()`
+returns only those the device is currently reporting:
+
+```python
+for name in sdr.listSensors():
+    info = sdr.getSensorInfo(name)
+    print(f"{name} = {sdr.readSensor(name)} {info.units}")
+# fpga_temp = 54.3 C
+# frontend_temp = 65.1 C
+# adc_range = 29.4 dB        # headroom below full scale; near 0 is close to clipping
+# usb_buffer = 0.0625        # transfer-buffer fill, fraction 0-1
+# dsp_buffer = 0
+# gps_satellites = 0
+# ...plus cumulative_drops
+```
+
+`adc_range` is the one to watch when setting the reference level, and a
+climbing `usb_buffer` is the first sign the host is not draining the
+stream fast enough. The reads are briefly cached, so a probe's burst of
+`readSensor` calls costs one HTTP fetch, and they go through a separate
+connection from the sample stream — polling sensors during a capture does
+not stall sample delivery. Over the **native SDK** backend only
+`cumulative_drops` is reported: the raw SDK's own `AARTSAAPI_ConfigHealth`
+tree reads all zeros (the live telemetry is populated by RTSA-Suite, the
+managing application, not by the raw SDK), so exposing it there would
+report a device permanently at 0 °C.
+
+### Bandwidth
+
+SoapySDR keeps sample rate and analog/usable bandwidth as separate knobs.
+The RTSA's alias-free bandwidth is ~0.8x its sample rate, exposed here:
+
+```python
+sdr.setBandwidth(SoapySDR.SOAPY_SDR_RX, 0, 10e6)   # asks for ~10 MHz usable
+print(sdr.getBandwidth(SoapySDR.SOAPY_SDR_RX, 0))  # the bandwidth actually delivered
+print(sdr.listBandwidths(SoapySDR.SOAPY_SDR_RX, 0))
+```
+
+`setBandwidth` maps the request to the nearest sample-rate rung and
+drives `setSampleRate`; the two stay consistent, so setting either
+updates the other.

{python_aaronia-0.8.1 → python_aaronia-0.9.0}/docs/APPS.md

@@ -54,8 +54,9 @@ device's real ladder rather than round numbers it cannot produce: on a
 V6 ECO that is 61.44 MHz halved down to 120 kHz, which the RTSA GUI
 labels Full through 1/512. Nothing in between exists, so a request
 between rungs snaps to the nearest and logs a warning. A full V6 has a
-selectable receiver clock and reaches higher; the plugin advertises the
-ECO ladder, so check the rate the device reports if you are on one.
+selectable receiver clock and reaches higher. The plugin advertises
+whatever ladder the device declares, falling back to the ECO's only
+when the device cannot be asked.
 
 The single gain element is `REF`, the Aaronia reference level in dBm. It
 is not an amplifier gain: raising it reduces sensitivity. Start near