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

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

@@ -4,6 +4,302 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.11.0] - 2026-09-09
+
+### Changed
+- **A read never spans a retune, and packets carry the frequency they
+  were captured at.** The centre frequency now travels through the
+  sample channel with the samples it belongs to, so
+  `read_samples`/`read_samples_deadline` stop at a frequency boundary
+  and `SpectranSource::capture_frequency_hz` reports what the stream
+  said, not what was requested.
+
+  Reading the frequency from shared state at consume time cannot work:
+  the reader task runs ahead of the consumer, so a buffer parsed before
+  a retune would be tagged with the frequency after it. Measured on a
+  V6 ECO over RTSA HTTP at 61.44 MSPS, a retune is carried by the signal
+  within 24 ms median and 39 ms worst case, and during that window the
+  device is still delivering the old centre.
+
+  Callers already handle short reads — `read_samples_numpy` slices what
+  it got, and a SoapySDR `readStream` returning fewer than `numElems` is
+  ordinary — so the visible change is that a buffer taken across a
+  retune is no longer a mixture of two frequencies. `RETUNE_SETTLE` in
+  the `SdrSource` facade drops from 75 ms to 20 ms with it: the
+  frequency check rejects stale samples exactly, so the drain is only an
+  efficiency measure. A 48-tune sweep of every FPV band falls from 28.2 s
+  to 5.9 s.
+
+### Added
+- **The GPS mode can be set, not just the clock source.** `device/gpsmode`
+  decides whether GPS supplies location, time, both, or nothing, and the device
+  ships on `Disabled` — in which state no fix is ever reported and
+  `gps_time_ns` returns `None` forever, reading as broken rather than
+  unconfigured. `SpectranSource::set_gps_mode` writes it on both backends,
+  with the same confirm-by-read-back rule as the clock source.
+- **`clock_source()`, `clock_sources()`, `gps_mode()`, `gps_modes()`** on
+  `SpectranSource`, so reading the current reference no longer means fetching
+  the whole capability tree. These read over HTTP; the writes work on both
+  backends.
+- **Dual-channel RX reaches SoapySDR.** A full V6's two inputs were readable
+  from Rust, C and Python but not through the plugin, which reported one
+  channel and refused any other. Open with `rx_channel=Rx1And2` and
+  `getNumChannels(RX)` reports 2; `setupStream(RX, …, {0, 1})` puts
+  `readStream` on the paired read, filling both buffers with the same count.
+  The count follows the request, not the model — dual capture is configured
+  before the device opens, so a V6 opened single-channel has one channel to
+  offer. Still hardware-unverified: the development device is a single-channel
+  ECO.
+- **`read_samples_dual_deadline`** (Rust) and
+  **`spectran_source_read_samples_dual_timeout`** (C), the dual counterparts of
+  the existing deadline-bounded reads. `readStream` must honour the
+  application's `timeoutUs`, which the blocking dual read ignored.
+- **The device's master stream clock is readable from a source.**
+  `SpectranSource::master_stream_time_ns`,
+  `spectran_source_get_master_stream_time_ns`, Python
+  `master_stream_time_ns()`, and SoapySDR `getHardwareTime("master")`. It was
+  reachable only through the TX sink before. Unlike `last_timestamp_ns` it
+  answers before the first packet, so a caller that must not stamp data to
+  1970 has something to read; it is also the clock two receivers are aligned
+  on. Native-SDK backend only.
+- **Python gained `master_stream_time_ns()` and `gps_time_ns()`**, which the
+  Rust and C surfaces already had.
+- **[docs/SYNC.md](docs/SYNC.md)** — what the hardware does and does not offer
+  for multi-device timing. The vendor API has no set-time, no arm-at-time and
+  no trigger in any of its 34 functions, so UHD-style commanded capture is not
+  possible; a shared reference plus post-alignment on timestamps is, and that
+  is written down with its resolution floor (~240 ns, set by the vendor's own
+  `double`). Wired into the doctests, so its snippets cannot rot.
+
+### Breaking changes
+- **`get_master_stream_time()` is now `master_stream_time_ns()`**, on
+  `NativeSdkSource`, `SdkSink` and `UnifiedSink`, returning `i64` nanoseconds
+  instead of `f64` seconds. One unit per dimension, matching every other clock
+  the crate reports. `TxBurst` still carries the vendor's `f64` seconds — it is
+  written straight into the packet header — so convert with the new
+  `utils::epoch_nanos_to_seconds`.
+- **`utils::gps_seconds_to_nanos` is now `utils::epoch_seconds_to_nanos`.**
+  Two of the vendor's clocks arrive as `float64` epoch seconds, not one, and
+  the old name claimed otherwise.
+
+### Fixed
+- **A timed-out read no longer discards the staging buffer.**
+  `spectran_source_read_samples_timeout` returned early on timeout, past the
+  point where it hands the buffer back, so the next read reallocated it — the
+  allocation that path exists to avoid.
+- **An unrecognised `rx_channel=` is reported, not silently taken as `Rx1`.**
+  A typo used to yield a single-channel stream indistinguishable from a working
+  dual request.
+- **Reading the wrong payload for the open mode is refused instead of answered.**
+  Neither the SDK nor the packet says what a stream carries, so asking a
+  spectrum pipeline for IQ returned dBm bins reinterpreted as voltages, and
+  asking an IQ pipeline for spectra returned complex pairs reinterpreted as
+  two-bin frames whose bin spacing was the whole span. Both look like data.
+  Measured on a V6 ECO's `rtsa`: 200k "samples" spanning -130 to -59 with a
+  mean of -77 and not one value near zero — a dBm distribution, not a voltage
+  one. `read_samples`, `read_samples_dual` and `read_spectra` now check the
+  open mode and say which payload it carries.
+
+  This also corrects a doc claim: `spectranv6eco/rtsa` was documented as
+  yielding IQ at "~0.4 MS/s regardless of the requested rate". It yields no IQ
+  at all; that figure was the spectra misread. `spectranv6/raw` genuinely does
+  both, IQ on stream 0 and spectra on stream 2, and is unaffected.
+- **Capability lists no longer advertise options the device will refuse.** The
+  config tree carries a bitmask of enum entries the device is currently
+  rejecting, and it was ignored: a V6 ECO with no GPS antenna offered `GPS` and
+  `GPS Provider` as clock sources, and `set_clock_source("GPS")` then failed
+  against a list that said it would not. Those entries are filtered out, so what
+  `clock_sources()` and `gps_modes()` return is what the device accepts.
+  Verified live: the six sources advertised are exactly the six it takes.
+
+## [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
+- **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.
+
+### 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
+
 ### Added
 - **SoapySDR: device sensors.** The plugin exposed one sensor
   (`cumulative_drops`); it now surfaces the device's live telemetry from

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

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

{python_aaronia-0.9.0 → python_aaronia-0.11.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.9.0"
+version = "0.11.0"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"

{python_aaronia-0.9.0 → python_aaronia-0.11.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
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.9.0
+Version: 0.11.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -63,21 +63,24 @@ fix for each failure.
 ```python
 import aaronia
 
-with aaronia.open("http://localhost:54664", freq=2.44e9, bandwidth=10e6) as src:
+with aaronia.open(
+    "http://localhost:54664", center_frequency_hz=2.44e9, bandwidth_hz=10e6
+) as src:
     for block in src.blocks(65536):           # numpy complex64 arrays
         process(block)
 ```
 
-`aaronia.open()` connects and starts streaming in one call. `bandwidth`
+`aaronia.open()` connects and starts streaming in one call. `bandwidth_hz`
 asks for that much usable spectrum and picks a sample rate the hardware
-can actually run; pass `rate=` instead to name one exactly. Use
+can actually run; pass `sample_rate_hz=` instead to name one exactly.
+Use
 `file="capture.rtsa"` in place of the URL to play back a recording.
 
 Iterating with `blocks()` ends when the stream closes. To read on your
 own schedule, or for Apache Arrow:
 
 ```python
-src = aaronia.open(freq=2.44e9, rate=15.36e6, format="I16")
+src = aaronia.open(center_frequency_hz=2.44e9, sample_rate_hz=15.36e6, format="I16")
 ```
 
 `sdk=True` opens the device through the native SDK instead of a server
@@ -85,17 +88,17 @@ src = aaronia.open(freq=2.44e9, rate=15.36e6, format="I16")
 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)
+src = aaronia.open(sdk=True, center_frequency_hz=2.44e9, sample_rate_hz=15.36e6)
+src = aaronia.open(sdk=True, serial="C2-P-03000105", center_frequency_hz=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
+src.set_center_frequency_hz(2.41e9)              # live retune, no teardown
 print(src.cumulative_drops(), src.take_overrun(), src.last_timestamp_ns())
 src.stop_streaming()
 ```
 
-For full control, build an `AaroniaConfig` and pass it to
-`AaroniaSource.start_streaming()`; `open()` is a shorthand for the
+For full control, build a `SpectranConfig` and pass it to
+`SpectranSource.start_streaming()`; `open()` is a shorthand for the
 common fields.
 
 The
@@ -154,18 +157,18 @@ most of the capture was dropped. Either half-width format fits.
 quantisation step is `1 / scale`, and the default of 16384 gives a step
 of 6.1e-5. A quiet band's noise floor is smaller than that — on the
 same server, **68% of `I16` samples came back exactly zero** while
-`F32` had none. Pass `scale=`, or lower `reference_level` for more
+`F32` had none. Pass `scale=`, or lower `reference_level_dbm` for more
 gain:
 
 ```python
-aaronia.open(url, freq=2.44e9, rate=15.36e6, format="I16", scale=1e6)
+aaronia.open(url, center_frequency_hz=2.44e9, sample_rate_hz=15.36e6, format="I16", scale=1e6)
 ```
 
 At `scale=1e6` the zero fraction measured 0.0% and the amplitude
 matched `F32`. `F16` needs no such tuning, which makes it the simpler
 choice when the link is the constraint.
 
-## Configuration (`AaroniaConfig`)
+## Configuration (`SpectranConfig`)
 
 Every field is readable and writable.
 
@@ -174,14 +177,14 @@ 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 |
+| `force_native_sdk` | `True` pins the source to the native SDK; missing SDK is an error |
+| `center_frequency_hz` | Center frequency, Hz |
+| `sample_rate_hz` | IQ sample rate (Fs), Hz |
+| `reference_level_dbm` | Reference level, dBm |
 | `format` | HTTP wire format: `"F32"`, `"F16"` or `"I16"`. `I16` is the low-bandwidth network mode |
 | `scale` | Integer encode multiplier for `I16` (see below). None uses the server default |
 | `receiver_channel` | `"Rx1"` (default), `"Rx2"`, or `"Rx1And2"` (native SDK, full V6) |
-| `read_timeout` | Seconds a blocking read waits before `AaroniaTimeoutError` (default `30.0`) |
+| `read_timeout_s` | Seconds a blocking read waits before `SpectranTimeoutError` (default `30.0`) |
 | `auto_reconnect` | Reconnect the HTTP stream after a drop (default `True`) |
 
 Unknown `format`/`receiver_channel` strings raise `ValueError` instead of
@@ -194,8 +197,8 @@ silently defaulting.
   indefinitely. This is not zero-copy; one copy is the accurate count.
 - **Blocking calls release the GIL.** Other Python threads keep running;
   `KeyboardInterrupt` is delivered between calls. Reads block until
-  `count` samples arrive or `cfg.read_timeout` seconds (default 30)
-  elapse, which raises `AaroniaTimeoutError`.
+  `count` samples arrive or `cfg.read_timeout_s` seconds (default 30)
+  elapse, which raises `SpectranTimeoutError`.
 - **Connecting retries transient failures**, up to 4 attempts within a
   10 second budget, so a cold `*.local` hostname or a server that is
   still starting does not fail on the first attempt.
@@ -203,12 +206,12 @@ silently defaulting.
   enabled, which is the default. The reader reopens the stream,
   re-applies the current tuning, and flags the first read after the gap
   through `take_overrun()`. After five failed attempts the stream ends
-  and reads raise `AaroniaStreamClosed`.
-- **Typed exceptions.** `AaroniaConnectionError` (unreachable endpoint),
-  `AaroniaTimeoutError`, `AaroniaHardwareError` (device and SDK errors)
+  and reads raise `SpectranStreamClosed`.
+- **Typed exceptions.** `SpectranConnectionError` (unreachable endpoint),
+  `SpectranTimeoutError`, `SpectranHardwareError` (device and SDK errors)
   and `ValueError` (invalid configuration), mapped from the Rust error
   enum with the full cause chain in the message.
-  `AaroniaStreamClosed` subclasses `AaroniaConnectionError` and means
+  `SpectranStreamClosed` subclasses `SpectranConnectionError` and means
   the stream finished rather than failed; `blocks()` ends on it, while
   a timeout or transport failure still raises.
 - **Dual-channel** reads (`receiver_channel = "Rx1And2"` with
@@ -227,7 +230,7 @@ silently defaulting.
 | `read_samples_numpy(count)` | NumPy `complex64` array |
 | `read_samples_arrow(count)` | PyArrow `FixedSizeListArray` of `[re, im]` float32 pairs |
 | `read_samples_dual_numpy(count)` | `(rx1, rx2)` NumPy arrays (dual-channel captures) |
-| `set_center_frequency(hz)` / `set_sample_rate(hz)` / `set_reference_level(dbm)` | Live retuning |
+| `set_center_frequency_hz(hz)` / `set_sample_rate_hz(hz)` / `set_reference_level_dbm(dbm)` | Live retuning |
 | `cumulative_drops()` | Timestamp gaps detected in the stream so far (gap events, not samples) |
 | `take_overrun()` | True once per detected receive-side overrun |
 | `last_timestamp_ns()` | Epoch-ns timestamp of the last received block (HTTP backend; 0 otherwise) |
@@ -236,7 +239,7 @@ silently defaulting.
 
 | Function | Purpose |
 | --- | --- |
-| `open(url=None, *, freq, rate, bandwidth, ref_level, file, format, scale, read_timeout)` | Configure, connect and start streaming in one call |
+| `open(url=None, *, center_frequency_hz, sample_rate_hz, bandwidth_hz, reference_level_dbm, file, format, scale, read_timeout_s)` | Configure, connect and start streaming in one call |
 | `sample_rates()` | The V6 ECO's sample rates, highest first (see [Sample rates](#sample-rates)) |
 | `sample_rate_for_bandwidth(hz)` | Lowest rate covering that much spectrum |
 | `diagnose(url)` | `(ok, message, fix)` for each setup check; what `aaronia-doctor` prints |

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

@@ -12,10 +12,10 @@ To use the Seify plugin, enable the `seify` feature in your `Cargo.toml`:
 
 ```toml
 [dependencies]
-sdr-aaronia-rs = { version = "0.8", features = ["seify"] }
+sdr-aaronia-rs = { version = "0.10", 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.
+Instantiate the device with `SpectranSeifyDevice::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
@@ -23,13 +23,15 @@ 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
+`SpectranSeifyDevice` 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;
+```rust,no_run
+# #[cfg(feature = "seify")]
+# fn demo() {
+use sdr_aaronia_rs::seify_impl::SpectranSeifyDevice;
 use seify::{Args, RxDevice, RxStreamer, DeviceInfo};
 use seify::dev::DynDeviceBackend;
 
@@ -38,7 +40,7 @@ let mut args = Args::new();
 args.set("url", "http://localhost:54664");
 
 // Open the device
-let dev = AaroniaSeifyDevice::from_args(&args).expect("Failed to open Aaronia device");
+let dev = SpectranSeifyDevice::from_args(&args).expect("Failed to open Aaronia device");
 
 // Start streaming (CF32 complex floats)
 let rx = dev.rx_device().expect("Failed to get RX device");
@@ -48,6 +50,8 @@ streamer.activate_at(None).expect("Failed to activate stream");
 let mut buffer = [num_complex::Complex32::new(0.0, 0.0); 1024];
 let read = streamer.read(&mut [&mut buffer], 1_000_000).expect("Read failed");
 println!("Read {} samples", read);
+# }
+# fn main() {}
 ```
 
 > **Note on Bandwidth:** Seify's `RxStreamer` trait natively expects `Complex32` (CF32) buffers, so data will be transferred as 32-bit floats.
@@ -227,3 +231,32 @@ 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.
+
+### Clock source
+
+`device/sclksource` selects what disciplines the receiver's clock. A V6 ECO
+offers `Consumer`, `Oscillator`, `GPS`, `PPS`, `10MHz` and three `... Provider`
+variants; `listClockSources` reports whatever the device actually offers.
+
+```python
+print(sdr.listClockSources())   # ['Consumer', 'Oscillator', 'GPS', 'PPS', '10MHz', ...]
+sdr.setClockSource("10MHz")     # lock to a house 10 MHz reference
+print(sdr.getClockSource())
+```
+
+`setClockSource` now writes the device; it previously only reported the current
+source and told you to change it in RTSA-Suite. Over HTTP the write is read back
+to confirm, because a `/remoteconfig` PUT naming a block that is not in the
+running mission answers 200 and changes nothing.
+
+If the device does not take the source — usually because it does not offer it —
+the plugin logs a `SOAPY_SDR_ERROR` naming the sources it *does* offer, and does
+not cache the requested value. `getClockSource()` therefore keeps reporting what
+the device is actually running on, never what you asked for.
+
+**Why this matters for multi-device work.** Point several receivers at one
+10 MHz / PPS / GPS reference and their per-packet hardware timestamps share a
+timebase, so captures can be correlated afterwards. There is no commanded
+synchronous start: the SDK exposes no set-time and no arm-at-time call, so you
+align on timestamps in post rather than arming devices at an instant.
+