python-aaronia 0.8.2__tar.gz → 0.10.0__tar.gz

{python_aaronia-0.8.2 → python_aaronia-0.10.0}/CHANGELOG.md

@@ -2,82 +2,247 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
-
-### 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.
+## [v0.10.0] - 2026-09-08
+
+### Breaking changes
+
+**One name per concept, with its unit.** A field, parameter or getter holding a
+bare number now carries its unit (`_hz`, `_dbm`, `_db`, `_s`); a type that
+already carries one, such as `Duration`, does not. `span_frequency` is gone: it
+meant the IQ *sample rate*, while the same word meant alias-free *bandwidth* in
+the link budget. Old names were removed rather than deprecated, since an alias
+that kept working would preserve the ambiguity this release exists to remove.
+The `spanfreq` device key and the `frequencySpan` JSON field are the vendor's
+vocabulary and are unchanged.
+
+| Old | New |
+| --- | --- |
+| `AaroniaConfig::center_frequency` (field + builder) | `center_frequency_hz` |
+| `AaroniaConfig::span_frequency` (field + builder) | `sample_rate_hz` |
+| `AaroniaConfig::reference_level` (field + builder) | `reference_level_dbm` |
+| `AaroniaSourceBuilder::center_frequency` / `span_frequency` / `reference_level` | `center_frequency_hz` / `sample_rate_hz` / `reference_level_dbm` |
+| `AaroniaSource::set_center_frequency` / `set_span_frequency` / `set_reference_level` | `set_center_frequency_hz` / `set_sample_rate_hz` / `set_reference_level_dbm` |
+| `SourceInfo::center_frequency` / `span_frequency` / `reference_level` | `center_frequency_hz` / `sample_rate_hz` / `reference_level_dbm` |
+| `SourceInfo::sample_rate_hz()` (method) | removed — read the field of the same name |
+| `UnifiedSinkConfig::span_frequency`, `trans_gain` | `sample_rate_hz`, `trans_gain_db` |
+| `ThroughputMeasurement::max_sustainable_span_hz` | `max_sustainable_bandwidth` |
+| `ThroughputMeasurement::stream_sample_rate` | `stream_sample_rate_hz` |
+| `LinkBudgetVerdict::sample_rate`, `fit_span_hz` | `sample_rate_hz`, `fit_bandwidth_hz` |
+| `RtsaMetadata` / `StreamingSdrConfig` bare quantities | unit-suffixed (`_hz`, `_s`) |
+| `HttpSourceBuilder::frequency` / `frequency_str` / `sample_rate` / `reference_level` | `center_frequency_hz` / `center_frequency_str` / `sample_rate_hz` / `reference_level_dbm` |
+| `HttpSinkBuilder::frequency`, `sample_rate` | `center_frequency_hz`, `sample_rate_hz` |
+| `HttpSource::new` / `with_advanced_options`, `HttpSink::new` parameters | `center_frequency_hz` / `sample_rate_hz` / `reference_level_dbm` |
+| `DeviceCapabilities::center_frequency`, `reference_level` | `center_frequency_hz`, `reference_level_dbm` |
+| `PacketMetadata::sample_rate()` | `sample_rate_hz()` |
+
+`frequency` became `center_frequency_hz`, not `frequency_hz`: it was always the
+centre frequency. The `_str` variants take a string carrying its own units
+(`"146.52M"`), so they keep no suffix. `DeviceCapabilities` is
+`#[non_exhaustive]`, so callers reach those fields through the API rather than
+by literal.
+
+**Rust types name the device: `Aaronia*` becomes `Spectran*`** —
+`SpectranConfig`, `SpectranSource`, `SpectranSourceBuilder`,
+`SpectranSinkBuilder`, `SpectranSeifyDevice`, `SpectranSeifyRxStreamer`,
+`SpectranBackend`, `SpectranSdrSource`.
+
+The vendor name stays wherever it is a frozen contract rather than a
+description: the `aaronia_*` C symbols and the `AaroniaSource` /
+`AaroniaFfiError` typedefs, the crate, the PyPI package, the Python module,
+`AaroniaSoapyDevice`, and `driver=aaronia`. That last is the load-bearing one —
+it is typed into GQRX and SDR++ configs already in the world, where breaking it
+reads as "device not found" with nothing pointing at the cause.
+
+**Python takes the same vocabulary**, its four exceptions included.
+
+| Old Python | New |
+| --- | --- |
+| `aaronia.AaroniaConfig` | `aaronia.SpectranConfig` |
+| `aaronia.AaroniaSource` | `aaronia.SpectranSource` |
+| `aaronia.Aaronia{Connection,Hardware,Timeout}Error`, `AaroniaStreamClosed` | `Spectran…` |
+| `cfg.center_freq` | `cfg.center_frequency_hz` |
+| `cfg.sample_rate` | `cfg.sample_rate_hz` |
+| `cfg.reference_level` | `cfg.reference_level_dbm` |
+| `cfg.read_timeout` | `cfg.read_timeout_s` |
+| `cfg.native_sdk` | `cfg.force_native_sdk` |
+| `src.set_center_frequency()` / `set_sample_rate()` / `set_reference_level()` | `set_center_frequency_hz()` / `set_sample_rate_hz()` / `set_reference_level_dbm()` |
+| `open(freq=, rate=, bandwidth=, ref_level=, read_timeout=)` | `open(center_frequency_hz=, sample_rate_hz=, bandwidth_hz=, reference_level_dbm=, read_timeout_s=)` |
+
+`open()`'s keywords changed with them. It is the one-line front door and the
+longer names cost the headline example a wrap, but `open(url, bandwidth=10e6)`
+gives no way to tell Hz from MHz. `sdk=`, `url=`, `file=`, `serial=`, `format=`
+and `scale=` carry no unit and are unchanged.
+
+**The whole C ABI moves to `spectran_*`.** Every exported symbol, the header
+(`include/aaronia.h` is now `include/spectran.h`), the opaque typedefs
+(`AaroniaSource` / `AaroniaSourceBuilder` / `AaroniaSink` / `AaroniaSinkBuilder`
+/ `AaroniaFfiError` / `CAaroniaSourceType` become `Spectran*`), and the plugin
+class `AaroniaSoapyDevice` become `SpectranSoapyDevice`. The table below lists
+the symbols that also changed shape; the rest changed prefix only, so
+`aaronia_x` is `spectran_x`.
+
+What keeps the vendor name: `driver=aaronia`, because it is typed into GQRX and
+SDR++ configuration files already in the world and breaking it reads as "device
+not found"; the crate, the PyPI package and the Python module, which are
+published names; and `AARTSAAPI_*` / `AaroniaRTSAAPI.dll`, which are the
+vendor's own.
+
+**The C ABI is renamed with no forwarders**, so a consumer gets an undefined
+symbol at link time and this table is the migration guide. `FfiSourceInfo`'s
+fields moved with the header in the same commit: C reads them positionally, so
+a stale header would go on reading the right bytes under the wrong name.
+
+| Old C symbol | New |
+| --- | --- |
+| `aaronia_source_builder_center_frequency` | `spectran_source_builder_center_frequency_hz` |
+| `aaronia_source_builder_span_frequency` | `spectran_source_builder_sample_rate_hz` |
+| `aaronia_source_builder_reference_level` | `spectran_source_builder_reference_level_dbm` |
+| `aaronia_source_set_center_frequency` | `spectran_source_set_center_frequency_hz` |
+| `aaronia_source_set_span_frequency` | `spectran_source_set_sample_rate_hz` |
+| `aaronia_source_set_reference_level` | `spectran_source_set_reference_level_dbm` |
+| `aaronia_sink_builder_center_frequency` | `spectran_sink_builder_center_frequency_hz` |
+| `aaronia_sink_builder_sample_rate` | `spectran_sink_builder_sample_rate_hz` |
+| `aaronia_sink_builder_trans_gain` | `spectran_sink_builder_trans_gain_db` |
+| `aaronia_source_read_sensors` | `spectran_source_get_sensors` |
+| `aaronia_endpoints_client_read_sensors` | `spectran_endpoints_client_get_sensors` |
+| `FfiSourceInfo::center_frequency` / `span_frequency` / `reference_level` | `center_frequency_hz` / `sample_rate_hz` / `reference_level_dbm` |
+| `aaronia_source_get_gps_time(.., double*)` | `spectran_source_get_gps_time_ns(.., int64_t*)` |
+
+The two `read_sensors` are a verb change, not a unit one. `read_` advances a
+stream here (`spectran_source_read_samples`); sensors are a snapshot, so they
+join `spectran_source_get_capabilities`.
+
+**GPS time changes type as well as name.** `gps_time_ns() -> Option<i64>`, and
+`int64_t*` in C, matching `last_timestamp_ns`. The conversion moved into the
+library because epoch nanoseconds land near `1.7e18`, where an `f64`'s step is
+256 ns — a single `seconds * 1e9` discards tens of nanoseconds the reading
+still had. The SoapySDR plugin's own whole/fractional split is deleted.
+`GpsState::time` is now `time_s`, and the C function accepts a `NULL`
+out-parameter meaning "is there a fix?".
+
+It does **not** improve precision. The device reports `gpstime` as an `f64`,
+whose step at present-day epoch values is about 240 ns, and nothing downstream
+recovers what was never there. `utils::gps_seconds_to_nanos` documents that
+bound and a test pins it against the naive multiply. Across receivers ~240 ns
+is ~70 m of ranging uncertainty, so correlate on the per-packet stream
+timestamps and keep GPS for disciplining and wall-clock labelling.
+
+`CaptureControl`'s fields gained units without moving its JSON keys: each is
+now pinned by an explicit `#[serde(rename)]` rather than derived from the Rust
+field name, so a later rename cannot change the wire format by accident.
+`tests/wire_contract.rs` asserts those keys, and asserts the vendor
+`AARTSAAPI_Packet` mirror still matches its C header field for field.
 
 ### 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.
+- **The stream clock source can be set, not just read.** `device/sclksource`
+  selects what disciplines the receiver's clock; a V6 ECO offers `Consumer`,
+  `Oscillator`, `GPS`, `PPS`, `10MHz` and three `... Provider` variants. It was
+  readable but read-only, and SoapySDR's `setClockSource` merely logged a
+  warning telling the operator to change it in RTSA-Suite.
+  `SpectranSource::set_clock_source`, `spectran_source_set_clock_source` and the
+  plugin's `setClockSource` now write it on both backends — native SDK via
+  `ConfigSetString`, HTTP via a `simpleconfig` PUT that is read back to confirm,
+  because a `/remoteconfig` PUT naming a block outside the running mission
+  answers 200 and changes nothing. A confirmed mismatch is an **error** naming
+  the sources the device does offer: being told you are on a reference you are
+  not is worse than a failed call. A read-back yielding nothing is reported as
+  unconfirmed rather than failed.
+
+  This is what makes cross-receiver correlation possible: lock a fleet to one
+  10 MHz / PPS / GPS reference and their per-packet timestamps share a timebase.
+  What is *not* possible is a commanded synchronous start — the SDK's C API has
+  no set-time and no arm-at-time entry point, so multi-device work is a shared
+  reference plus post-alignment on timestamps.
 
-### 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.
+### Fixed
+- **A trailing slash in `device_type` no longer produces a malformed open
+  string.** The family/mode split asked whether the string contained a slash, so
+  `"spectranv6/"` counted as already mode-qualified and went to
+  `AARTSAAPI_OpenDevice` verbatim. The mode is now the text after the *first*
+  slash, and an empty one means none was given. The ECO was the sharp edge:
+  `"spectranv6eco/"` also slipped past the `spectranv6eco/raw` → `iqreceiver`
+  remap, so the device was asked for a pipeline it does not have and answered
+  with a result code that said nothing about the typo.
+
+  A `device_type` naming no family (`""`, `"/"`, `"/raw"`) is no longer
+  completed into a family-less `"/raw"`; it comes back untouched and is refused
+  at both points where a device type reaches the SDK. Both guards are needed
+  because enumeration runs first, and an empty family simply enumerates to
+  nothing — the old path reported "no devices found" and never mentioned the
+  typo. `device_family` and `device_open_mode` stay infallible: a typo in one
+  field is not a reason to make four accessors return `Result`.
+- **An over-wide sample rate no longer reaches the hardware before it is
+  refused.** `configure_iq_receiver` checked the IQ-mode constraint as its last
+  act, so a rate the receiver clock cannot carry was written to
+  `main/centerfreq` and `main/spanfreq` first and rejected afterwards — leaving
+  the device holding the misconfiguration the check exists to prevent, and per
+  the SDK quietly emitting corrupted samples if anything started the stream.
+  The check now runs before the first write.
+
+  It checks against the clock the call *leaves in place*, which is not always
+  the one the device holds on entry. Raw mode writes the clock itself, so that
+  write is what counts: a V6 left on its 245.76 MHz clock would otherwise pass a
+  150 MS/s request that stops being valid the moment this same call drops the
+  clock to 92.16 MHz. Every other mode skips that write, so there the live
+  setting is the honest number. The read-back after the writes is kept, and is
+  what `receiver_clock_hz()` reports. Native SDK only; the HTTP backend already
+  validated at the API boundary.
+
+## [v0.9.0] - 2026-09-08
 
-  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.
+### 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.
 
-### 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.
+### 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
 
@@ -169,6 +334,84 @@ 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.2 → python_aaronia-0.10.0}/Cargo.lock

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

{python_aaronia-0.8.2 → python_aaronia-0.10.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.2"
+version = "0.10.0"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"

{python_aaronia-0.8.2 → python_aaronia-0.10.0}/DESIGN.md

@@ -4,7 +4,7 @@ This document describes the architecture of the `sdr-aaronia-rs` crate, which pr
 
 ## 1. Overview
 
-The Aaronia ecosystem offers three ways to access Spectran hardware: the native RTSA-Suite PRO SDK, the HTTP streaming API, and recorded RTSA files. This crate wraps all three behind a single deterministic facade, `AaroniaSource`, so callers can work with Aaronia hardware without depending on the underlying transport.
+The Aaronia ecosystem offers three ways to access Spectran hardware: the native RTSA-Suite PRO SDK, the HTTP streaming API, and recorded RTSA files. This crate wraps all three behind a single deterministic facade, `SpectranSource`, so callers can work with Aaronia hardware without depending on the underlying transport.
 
 ## 2. Architecture
 
@@ -13,7 +13,7 @@ The crate is built around an automatic source-detection router that instantiates
 ```mermaid
 graph TB
     subgraph "sdr-aaronia-rs Unified API"
-        API[AaroniaSourceBuilder]
+        API[SpectranSourceBuilder]
         Detection[Deterministic Auto-Detection]
     end
 
@@ -32,13 +32,13 @@ graph TB
 
 ## 3. Source Selection
 
-`AaroniaSource::new(config)` selects a backend using strict, deterministic rules:
+`SpectranSource::new(config)` selects a backend using strict, deterministic rules:
 
 | Configuration | Backend | Fallback | Platforms |
 |---|---|---|---|
-| `AaroniaConfig::from_file("recording.rtsa")` | File | None — fails if the file is missing | All |
-| `AaroniaConfig::from_http("http://192.168.1.100")` | HTTP | None — fails if unreachable | All |
-| `AaroniaConfig::default()` (nothing specified) | Native SDK, when the `native-sdk` feature is enabled and the SDK library is found | Connects to the default HTTP endpoint (`http://localhost:54664`) otherwise. Since `native-sdk` is not a default feature, a stock build always resolves to HTTP. | All (SDK itself is Windows/Linux only) |
+| `SpectranConfig::from_file("recording.rtsa")` | File | None — fails if the file is missing | All |
+| `SpectranConfig::from_http("http://192.168.1.100")` | HTTP | None — fails if unreachable | All |
+| `SpectranConfig::default()` (nothing specified) | Native SDK, when the `native-sdk` feature is enabled and the SDK library is found | Connects to the default HTTP endpoint (`http://localhost:54664`) otherwise. Since `native-sdk` is not a default feature, a stock build always resolves to HTTP. | All (SDK itself is Windows/Linux only) |
 | Force option, e.g. `config.force_native_sdk()` | Forced type | None — fails if unavailable | Depends on forced type |
 
 ## 4. Backend Implementations
@@ -58,7 +58,7 @@ Available on Windows and Linux only, behind the non-default `native-sdk` feature
 
 - Implements the V9 RTSA HTTP specification.
 - Supports Basic Auth and token-based authentication.
-- **Formats**: supports the `Json`, `Int16`, `Float16`, and `Float32` wire formats, maintaining a persistent chunked-transfer buffer across packet boundaries. The default is `Float32` (binary, lossless); `Int16` is opt-in via `AaroniaConfig::stream_format()` / `stream_scale()`.
+- **Formats**: supports the `Json`, `Int16`, `Float16`, and `Float32` wire formats, maintaining a persistent chunked-transfer buffer across packet boundaries. The default is `Float32` (binary, lossless); `Int16` is opt-in via `SpectranConfig::stream_format()` / `stream_scale()`.
 - Beyond streaming, `HttpEndpointsClient` exposes device control and health telemetry (as a generic configuration tree) within a headless Rust process.
 
 ### 4.3 RTSA Files
@@ -69,21 +69,21 @@ Available on Windows and Linux only, behind the non-default `native-sdk` feature
 
 ## 5. Channel Hopping and Dwell Control
 
-Under the `sdr-source` feature, `AaroniaSdrSource` (in `sdr_source_impl.rs`) implements the `SdrSource` trait from the external `orecchiette-sdr-source-rs` crate, which the crate re-exports as `sdr_source`. Automatic mid-stream retuning via `SourceConfig.channels_hz` is supported per backend:
+Under the `sdr-source` feature, `SpectranSdrSource` (in `sdr_source_impl.rs`) implements the `SdrSource` trait from the external `orecchiette-sdr-source-rs` crate, which the crate re-exports as `sdr_source`. Automatic mid-stream retuning via `SourceConfig.channels_hz` is supported per backend:
 
 - **Native SDK**: re-issues `configure_iq_receiver` with the new center frequency, applying the change to the open device handle via the `main/centerfreq` configuration key. No stream restart is required.
-- **HTTP**: `AaroniaSource::set_center_frequency` wraps `HttpEndpointsClient::configure_capture` as a `PUT` to the license-free `/control` endpoint, always sending the complete capture tuple (center, span, reference level) with unchanged values filled from the cached config. The full tuple is required: RTSA servers silently ignore a capture `PUT` carrying only one of the two frequency fields (it returns `{"success":true}` but the device stays put — live-verified). Hopping deliberately avoids `/remoteconfig` and is not gated on the license probe. (Whether that path needs the "Remote Config" license at all is unconfirmed: a system without the license accepted `/remoteconfig` writes in testing. See docs/HTTPSPEC.md.)
+- **HTTP**: `SpectranSource::set_center_frequency_hz` wraps `HttpEndpointsClient::configure_capture` as a `PUT` to the license-free `/control` endpoint, always sending the complete capture tuple (center, span, reference level) with unchanged values filled from the cached config. The full tuple is required: RTSA servers silently ignore a capture `PUT` carrying only one of the two frequency fields (it returns `{"success":true}` but the device stays put — live-verified). Hopping deliberately avoids `/remoteconfig` and is not gated on the license probe. (Whether that path needs the "Remote Config" license at all is unconfirmed: a system without the license accepted `/remoteconfig` writes in testing. See docs/HTTPSPEC.md.)
 - **File**: not supported.
 
 Hop dwell deadlines come from `sdr_source::DwellController`; per-hop pacing additionally inserts a ~75 ms settle after every retune (`RETUNE_SETTLE` in `sdr_source_impl.rs`) to ride out the RTSA's apply-config latency and flush stale samples from the pipeline.
 
 ## 6. Overrun Detection and Fault Handling
 
-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 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 `SpectranSource::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 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.
+The Aaronia capture thread (`SpectranSdrSource::start`) is wrapped in `catch_unwind`: a panic inside the pump loop is logged rather than silently unwinding the thread.
 
 ## 7. FutureSDR Integration