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

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

@@ -4,6 +4,55 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.6.1] - 2026-08-12
+
+### Fixed
+- **The SoapySDR plugin advertised sample rates the hardware cannot
+  produce.** Seven of the ten rates it listed, 1, 2, 5, 10 and 20 MHz
+  among them, do not exist on the device, which runs at 61.44 MHz
+  divided by a power of two. Applications build their rate dropdowns
+  from that list, so choosing 10 MHz ran the device at a different rate
+  while the application went on displaying 10. The list is now the real
+  ladder, 61.44 MHz down to 120 kHz, and `setSampleRate` snaps to the
+  nearest one and logs when it has to.
+- **The crate reported the requested sample rate rather than the one in
+  use.** The device adjusts a rate it cannot produce, so
+  `get_source_info()` described a capture that was not happening. HTTP
+  sources now report the rate, centre frequency and usable bandwidth
+  from the stream's own metadata once packets arrive.
+
+### Added
+- `iq_sample_rates`, `usable_bandwidth_hz`, `nearest_iq_sample_rate` and
+  `iq_sample_rate_for_bandwidth` in `utils`, with the constants
+  `IQ_CLOCK_HZ` and `USABLE_BANDWIDTH_RATIO`. The device samples at
+  61.44 MHz divided by a power of two and delivers 0.8 of that as
+  alias-free bandwidth. Callers were deriving their own rates from
+  guesses, so the relationships now live in one tested place. Wanting
+  8 MHz of spectrum needs 10 MHz of sampling, and
+  `iq_sample_rate_for_bandwidth` returns the 15.36 MHz that provides it.
+
+### Fixed (native SDK)
+- **Sweep mode set the wrong resolution-bandwidth key.** It sent
+  `main/rbw`, which no Aaronia sample uses; the key is `main/rbwfreq`.
+  Checked against Aaronia's published `SweepSpectrumEco` sample, which
+  also confirms `main/startfreq`, `main/stopfreq`, `main/reflevel` and
+  the `spectranv6eco/sweepsa` open string that this crate already used.
+  The sweep path remains hardware-unverified.
+
+### Documentation
+- **GPS time needs GPS switched on, and the crate does not do it.**
+  Devices ship with `device/gpsmode` disabled, so `get_gps_time` would
+  return `None` indefinitely and appear broken. Aaronia's `GPSTime`
+  sample sets `device/gpsmode` to "Location and Time" and
+  `device/sclksource` to "GPS Provider" before starting the device;
+  `get_gps_time` now says so.
+- Documented what `/control`'s `frequencySpan` actually means. It is a
+  request for usable bandwidth, not a sample rate: the device picks the
+  rate whose alias-free span is nearest, so 2.5 MHz yields 3.84 MHz and
+  10 MHz yields 15.36 MHz. Values on the rate ladder round-trip exactly,
+  which is why the field looks like a sample rate in ordinary use.
+  Verified across nine requests on a V6 ECO.
+
 ## [v0.6.0] - 2026-08-11
 
 Reliability and documentation release. The HTTP backend now handles a
@@ -80,9 +129,9 @@ hardware and which have not.
 ### Release
 - Release archives now carry the module, install instructions and the
   licence, and their names state the version, OS and architecture.
-- The Linux module ships stripped of debug symbols, down from about
-  19 MB. The release job checks the stripped module still loads before
-  publishing it.
+- The Linux module ships stripped of debug symbols, 19.1 MB down to
+  15.4 MB. The rest is statically linked Rust, not symbols. The release
+  job checks the stripped module still loads before publishing it.
 - GitHub releases now use this file's entry for the tag as their
   description, with the generated commit list below it.
 

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

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

{python_aaronia-0.6.0 → python_aaronia-0.6.1}/Cargo.toml

@@ -2,7 +2,7 @@
 name = "sdr-aaronia-rs"
 description = "Unified Rust interface for Aaronia Spectran Spectrum Analyzers / SDRs, featuring Python bindings, a SoapySDR plugin, HTTP streaming, and native SDK support."
 license = "GPL-3.0-or-later"
-version = "0.6.0"
+version = "0.6.1"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"

{python_aaronia-0.6.0 → python_aaronia-0.6.1}/DESIGN.md

@@ -51,7 +51,7 @@ Available on Windows and Linux only, behind the non-default `native-sdk` feature
 - **IQ mode constraint**: enforces `span * 1.5 <= receiverclock` by reading the live device clock before streaming.
 - **Data path (RX)**: polls `GetPacket` on the C++ side every 5 ms. Where the packet stride allows, the raw sample buffer is reinterpreted in place as `Complex32` (no per-sample conversion) before being copied into the caller's buffer.
 - **Data path (TX)**: provides an experimental `TxStream` API built on `SendPacket`. This path is hardware-unverified pending full V6 testing, as the ECO model lacks TX.
-- **Sweep-spectra mode**: configures non-IQ sweeping via `SweepsaConfig` by modifying `"main/startfreq"`, `"main/stopfreq"`, `"main/rbw"`, and related keys (these config paths are inferred from the SDK naming convention and are hardware-unverified). Supports the `"spectranv6/sweepsa"` and `"spectranv6eco/sweepsa"` open strings.
+- **Sweep-spectra mode**: configures non-IQ sweeping via `SweepsaConfig` by modifying `"main/startfreq"`, `"main/stopfreq"`, `"main/rbwfreq"` and `"main/reflevel"`. These key names match Aaronia's own `SweepSpectrumEco` sample; the code previously sent `"main/rbw"`, which no sample uses. Supports the `"spectranv6/sweepsa"` and `"spectranv6eco/sweepsa"` open strings, both of which the samples confirm. The path itself remains hardware-unverified.
 - **Health and GPS telemetry**: exposes `HealthState` and `GpsState` structs populated by a recursive configuration tree-walker (`walk_health_tree`) that fetches device diagnostics dynamically. Not yet exercised against live hardware.
 
 ### 4.2 HTTP Streaming
@@ -72,7 +72,7 @@ Available on Windows and Linux only, behind the non-default `native-sdk` feature
 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:
 
 - **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). The RTSA-Suite "Remote Config" license gates the separate `/remoteconfig` write path, which the hopping code deliberately avoids — hopping is not gated on the license probe.
+- **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.)
 - **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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.6.0
+Version: 0.6.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)

{python_aaronia-0.6.0 → python_aaronia-0.6.1}/PLUGINS.md

@@ -122,7 +122,15 @@ Two different knobs, easy to confuse:
 sdr = SoapySDR.Device("driver=aaronia,url=http://atc.local:54664,format=I16")
 ```
 
-## 3. Metrics and Error Handling
+## 3. Transmit
+
+TX is available through the SoapySDR plugin only when it is built
+against the native SDK on Windows or Linux. Elsewhere `setupStream` for
+TX fails with a descriptive error. Bursts are sent for immediate
+transmission; timed TX is not supported. The whole TX path is
+hardware-unverified. See [docs/VERIFICATION.md](docs/VERIFICATION.md).
+
+## 4. Metrics and Error Handling
 
 Both the native Rust API and the Python/C++ bindings expose critical metrics to monitor the health of your RTSA stream:
 

python_aaronia-0.6.1/README.md

@@ -0,0 +1,212 @@
+# sdr-aaronia-rs
+
+[![Crates.io](https://img.shields.io/crates/v/sdr-aaronia-rs.svg)](https://crates.io/crates/sdr-aaronia-rs)
+[![Docs.rs](https://docs.rs/sdr-aaronia-rs/badge.svg)](https://docs.rs/sdr-aaronia-rs)
+[![CI](https://github.com/isaacbentley/sdr-aaronia-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/isaacbentley/sdr-aaronia-rs/actions/workflows/ci.yml)
+[![License: GPL-3.0-or-later](https://img.shields.io/github/license/isaacbentley/sdr-aaronia-rs.svg)](https://choosealicense.com/licenses/gpl-3.0/)
+
+One API for Aaronia SPECTRAN analyzers and SDRs, whether the samples
+come from the native SDK, an RTSA-Suite HTTP server, or a recorded file.
+Python bindings and a SoapySDR plugin come from the same engine.
+
+*Disclaimer: This project is not affiliated with Aaronia AG. Aaronia, SPECTRAN, and RTSA-Suite PRO are trademarks of Aaronia AG.*
+
+Working with a SPECTRAN usually means choosing a transport first and
+then writing against whatever API that transport exposes. `AaroniaSource`
+removes the choice: point it at a file, a URL, or nothing at all, and it
+selects a backend and presents the same interface either way.
+
+| What you configure | What it uses |
+| --- | --- |
+| `file_path` | Buffered playback of an RTSA capture file |
+| `http_base_url` | HTTP streaming from an RTSA-Suite server block |
+| Neither | The native SDK, falling back to `localhost:54664` |
+| `force_source_type` | Exactly the backend you name |
+
+## What it does
+
+- **Streams IQ and spectra over HTTP** in JSON, Int16, Float16 or
+  Float32, with Basic and token authentication. Retuning mid-stream
+  needs no Aaronia licence, and dropped streams reconnect on their own.
+- **Reads `.rtsa` capture files** through buffered I/O, with metadata
+  extraction and multi-stream support.
+- **Talks to the hardware directly** through the Aaronia SDK on Windows
+  and Linux, including transmit. The SDK is not available for macOS.
+- **Controls and monitors the device**: streaming parameters, health,
+  input enumeration and the configuration tree.
+- **Plugs into FutureSDR** with `HttpSource` and `HttpSink` flowgraph
+  blocks.
+
+## Installation
+
+Add the following to your `Cargo.toml`:
+
+```toml
+[dependencies]
+# By default, includes HTTP, File, native sdr-source trait, and C FFI backend support
+sdr-aaronia-rs = "0.6"
+tokio = { version = "1.43", features = ["rt-multi-thread", "macros"] }
+
+# To enable additional backends, opt into their features (e.g. native-sdk, futuresdr)
+# sdr-aaronia-rs = { version = "0.6", features = ["native-sdk", "futuresdr"] }
+```
+
+## Quickstart
+
+Set the RF parameters and read:
+
+```rust,no_run
+use sdr_aaronia_rs::{AaroniaSource, AaroniaConfig};
+use anyhow::Result;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let config = AaroniaConfig::default()
+        .center_frequency(446.0e6)     // 446 MHz
+        .span_frequency(10.0e6)        // 10 MHz span
+        .reference_level(-30.0);       // -30 dBm
+
+    let mut source = AaroniaSource::new(config).await?;
+
+    let mut buffer = Vec::with_capacity(1024);
+    let n = source.read_samples(&mut buffer, 1024).await?;
+    println!("Received {} IQ samples", n);
+
+    Ok(())
+}
+```
+
+## Usage
+
+[docs/USAGE.md](docs/USAGE.md) has worked examples for everything the
+quickstart leaves out: the builder pattern, explicit backend selection,
+wire formats and network bandwidth, configuration profiles, device
+control, FutureSDR integration, authentication and low-level stream
+access. Its Rust snippets are compiled as doctests, and it indexes the
+runnable programs in [`examples/`](examples/).
+
+[docs/QUICKSTART.md](docs/QUICKSTART.md) covers configuring the
+RTSA-Suite HTTP Server block, which all of the above depends on.
+
+## Using it from other tools
+
+The Rust crate is the engine. The same code drives three other
+surfaces, so an Aaronia device works in the tools people already use.
+
+### Python
+
+```bash
+pip install python-aaronia
+```
+
+```python
+import aaronia
+
+cfg = aaronia.AaroniaConfig()
+cfg.http_base_url = "http://localhost:54664"
+cfg.center_freq = 2.44e9
+cfg.sample_rate = 15.36e6
+
+src = aaronia.AaroniaSource()
+src.start_streaming(cfg)
+samples = src.read_samples_numpy(65536)   # numpy complex64
+src.stop_streaming()
+```
+
+Reads land in NumPy or PyArrow with one copy out of the receive buffer.
+Blocking calls release the GIL, errors arrive as typed exceptions, and
+the package ships type stubs. Wheels are abi3 for CPython 3.9 and
+later. Full reference: [python-aaronia/README.md](python-aaronia/README.md).
+
+### SoapySDR: GQRX, SDR++, GNU Radio and others
+
+```bash
+SoapySDRUtil --probe="driver=aaronia,url=http://localhost:54664"
+```
+
+Every release attaches a prebuilt plugin for Linux, macOS and Windows,
+so no toolchain is needed. The plugin streams CF32 and CS16, honours
+`timeoutUs` with partial reads, stays safe to retune while streaming,
+and reports timestamps and dropped-block counts.
+
+Per-application setup is in [docs/APPS.md](docs/APPS.md). Installation,
+building from source and the wire-format trade-offs are in
+[PLUGINS.md](PLUGINS.md); pass `format=I16` to halve network bandwidth,
+which is a real wire-format change rather than a client-side conversion.
+
+### seify (Rust-native)
+
+Enable the `seify` feature and construct the device with
+`AaroniaSeifyDevice::from_args`. It is not part of seify's built-in
+enumeration, so it will not appear in `seify::enumerate()`. See
+[PLUGINS.md](PLUGINS.md).
+
+### What has been tested
+
+Not every path has run against hardware. Transmit, dual-channel capture
+and the native-SDK backend have not.
+[docs/VERIFICATION.md](docs/VERIFICATION.md) gives the status of each
+feature and how it was checked.
+
+## Connection Resilience
+
+Connecting (the `/info` probe and initial tuning PUT) retries transient
+failures up to 4 times with exponential backoff, bounded by a 10 second
+total budget. Refused connections, unresolved DNS and 5xx/408/429
+responses are retried; 4xx and configuration errors fail on the first
+attempt. This matters for `*.local` hostnames, which refuse the first
+connection from a cold process while mDNS resolves.
+
+`AaroniaConfig::read_timeout` (default 30 s) bounds `read_samples`.
+`read_samples_deadline`, and therefore the SoapySDR and seify paths, uses
+its caller's per-call deadline instead.
+
+A dropped HTTP stream, from an RTSA restart or a network interruption,
+reconnects automatically. This is `AaroniaConfig::auto_reconnect`,
+enabled by default. The reader reopens the stream, re-applies the
+current tuning (a restarted server returns to its mission's frequency),
+and flags the first packet after the gap as an overrun so callers know
+samples were missed. After 5 attempts, roughly 8 seconds of backoff, it
+stops and reads report a closed stream, matching the behaviour of
+`auto_reconnect(false)`.
+
+## Feature Flags
+
+Functionality is grouped behind Cargo features so unused dependencies stay out of your build:
+
+| Feature | Description | Default |
+|---|---|---|
+| `http` | HTTP streaming via `reqwest` and `tokio`. | **Yes** |
+| `file` | Buffered RTSA file parsing. | **Yes** |
+| `native-sdk` | Links the proprietary Aaronia C++ SDK. Windows/Linux only. | No |
+| `futuresdr` | Enables the FutureSDR block API: `HttpSource`, `HttpSink`, and their builders. Implies `http`. | No |
+| `sdr-source` | Integrates `AaroniaSdrSource` implementing the native `SdrSource` traits. | **Yes** |
+| `ffi` | Builds the C-API export layer. | **Yes** |
+
+## Testing & Contributing
+
+The test suite consists of unit tests, integration tests against LFS captures, and property tests enforcing specification invariants.
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on running the test suite, generating coverage reports, and formatting your code before submitting a Pull Request.
+
+## Documentation
+
+Start here:
+
+- [Quickstart](docs/QUICKSTART.md) — configuring an RTSA-Suite mission, first samples in Rust, Python and SoapySDR, and troubleshooting for common setup failures.
+- [Usage](docs/USAGE.md) — worked examples for each part of the API, plus the `AARONIA_SDK_PATH` and `AARONIA_USER_AGENT` environment variables.
+- [Using existing SDR apps](docs/APPS.md) — SDR++, GQRX, GNU Radio, SoapySDR from Python.
+
+Reference:
+
+- [Verification status](docs/VERIFICATION.md) — which features have been tested against real hardware.
+- [SDR plugins](PLUGINS.md) — SoapySDR and seify setup, wire-format trade-offs, metrics.
+- [Architecture & Design](DESIGN.md) — Internal architecture and execution flow.
+- [RTSA File Format Specification](docs/FILESPEC.md) — On-disk `.rtsa` capture-file format and how this crate parses it.
+- [HTTP API Specification](docs/HTTPSPEC.md) — The RTSA HTTP streaming and control API, including Remote Config licence detection.
+- [Native SDK Specification](docs/SDKSPEC.md) — The Aaronia RTSA-Suite PRO SDK surface and the Rust binding notes.
+- [Changelog](CHANGELOG.md) — Release history.
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later) - see the LICENSE file for details.

{python_aaronia-0.6.0 → python_aaronia-0.6.1}/docs/APPS.md

@@ -73,7 +73,7 @@ from SoapySDR import SOAPY_SDR_RX, SOAPY_SDR_CF32
 import numpy as np
 
 sdr = SoapySDR.Device("driver=aaronia,url=http://localhost:54664")
-sdr.setSampleRate(SOAPY_SDR_RX, 0, 12.288e6)
+sdr.setSampleRate(SOAPY_SDR_RX, 0, 15.36e6)
 sdr.setFrequency(SOAPY_SDR_RX, 0, 2.44e9)
 
 rx = sdr.setupStream(SOAPY_SDR_RX, SOAPY_SDR_CF32)

{python_aaronia-0.6.0 → python_aaronia-0.6.1}/docs/HTTPSPEC.md

@@ -283,6 +283,16 @@ packet-metadata object, so `payload`, `minPower`, `maxPower`, and
 }
 ```
 
+> **`frequencySpan` is a usable-bandwidth request, not a sample rate.**
+> The device runs at 61.44 MHz divided by a power of two. Given a span
+> it cannot produce, it selects the rate whose alias-free bandwidth
+> (0.8 x Fs) is nearest the request: 2.5 MHz yields Fs = 3.84 MHz,
+> 1.3 MHz yields 1.92 MHz, and 10 MHz yields 15.36 MHz. A value that is
+> itself on the rate ladder round-trips exactly, which is why the field
+> behaves like a sample rate in ordinary use. `sampleFrequency` in the
+> packet metadata reports the rate in force; `startFrequency` and
+> `endFrequency` bound the usable span. Verified on a V6 ECO.
+
 > **Both frequency fields are required for a retune to apply.** Live
 > testing against RTSA-Suite PRO (HTTP server block fed by a SPECTRAN
 > V6 ECO) shows the server returns `{"success":true}` for a capture
@@ -388,6 +398,44 @@ packet-metadata object, so `payload`, `minPower`, `maxPower`, and
 }
 ```
 
+**Full PUT form** (config tree). Aaronia's own automation example uses this
+shape for every setting it changes:
+
+```json
+{
+  "request": 11,
+  "receiverName": "Block_Spectran_V6B_0",
+  "config": {
+    "type": "group",
+    "items": [
+      {
+        "type": "group",
+        "name": "main",
+        "items": [
+          { "type": "float", "name": "centerfreq", "value": 2440000000 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Notes verified against a live V6 ECO:
+
+- **Field names are model-specific.** The V6B example writes `centerfreq`;
+  a V6 ECO exposes `centerfreq0` and `centerfreq1` for its two channels.
+  Read `GET /remoteconfig` and use the names that device reports.
+- **A frequency change needs only the frequency field.** This differs from
+  `/control`, where a capture request is ignored unless `frequencyCenter`
+  and `frequencySpan` are both present.
+- **The `receiverName` key is case-tolerant.** `receivername` was accepted
+  identically.
+- Enum-valued settings are written as their label string, for example
+  `decimation` as `"1 / 128"`, not as an index.
+- Other keys the example writes: `run` (bool), `preamp` (`"Auto"`),
+  `reflevel` (float), and `filerecord` (bool) plus a filename template on
+  a FileWriter block, which is how it starts and stops recording.
+
 **Simplified PUT form**: in addition to the full `{request, config}` shape, the server accepts a shorter per-block write (used by the SDR++ and SDRangel Aaronia plugins), exposed via `HttpEndpointsClient::simple_remote_config`:
 ```json
 {
@@ -552,10 +600,23 @@ Data captured using antennas with location or directional information.
 - `/info` - Device information
 - `/healthstatus` - Device health monitoring
 
-**Remote Configuration** (Requires separate license):
-- `/remoteconfig` - Device parameter configuration
-- **License Required**: "Remote Config" license from Aaronia
-- **Alternative**: Use Native SDK for configuration without HTTP licensing restrictions
+**Remote Configuration** (`/remoteconfig`):
+- Device parameter configuration.
+- Aaronia sells a "Remote Config" license, and this document previously
+  stated that `/remoteconfig` writes fail without it. **That is not what
+  a live system does.** On RTSA-Suite PRO driving a SPECTRAN V6 ECO whose
+  license list contains no Remote Config entry, `PUT /remoteconfig`
+  retuned the device repeatedly, in both the config-tree and simplified
+  forms, returning HTTP 200 with the change applied.
+- What that license actually gates is therefore unconfirmed. It may
+  cover a different feature, or a different edition or version, or
+  parameters other than the ones tested. Treat any claim that
+  `/remoteconfig` writes require it as unverified.
+- The system tested did hold "Block: HTTP Server" and "Block: HTTP
+  Client" licenses, so the HTTP surface itself is licensed separately
+  and may be what actually matters.
+- This crate does not depend on the answer: it tunes through `/control`,
+  which needs no license.
 
 **License Detection Methods**:
 
@@ -564,7 +625,7 @@ Data captured using antennas with location or directional information.
 The client therefore exposes two methods:
 
 - `detect_remote_config_license()` — **read-only**. Never touches device state. Classifies 401/403 responses; on read success it returns `Unknown` (write capability unproven).
-- `probe_remote_config_write_license()` — **active probe**. Performs a read-modify-restore cycle on `reflevel` (+1 dB, restored best-effort) to positively verify write capability. Use only when you genuinely need proof of `/remoteconfig` write access. Frequency hopping does **not** need it — retuning goes through the license-free `/control` endpoint (see the capture-control note above; the silent-ignore behavior once attributed to licensing was traced to partial capture payloads).
+- `probe_remote_config_write_license()` — **active probe**. Performs a read-modify-restore cycle on `reflevel` (+1 dB, restored best-effort) to positively verify write capability. Use only when you genuinely need proof of `/remoteconfig` write access. `AaroniaSource::probe_remote_config_license()` delegates to it for HTTP sources, and reports `Active` for the file and native-SDK backends, which do not need the licence. Frequency hopping does **not** need it — retuning goes through the license-free `/control` endpoint (see the capture-control note above; the silent-ignore behavior once attributed to licensing was traced to partial capture payloads).
 
 **Practical Detection (Active Probe)**:
 ```rust
@@ -707,6 +768,7 @@ consult:
 
 - **RTSA-Suite PRO HTTP streaming** (Aaronia V6 forum) — [v6-forum.aaronia.de/forum/topic/rtsa-suite-pro-http-streaming](https://v6-forum.aaronia.de/forum/topic/rtsa-suite-pro-http-streaming/)
 - Aaronia RTSA-Suite PRO product documentation — <https://rtsa-manual.aaronia.com/>
+- **Aaronia's own automation example** — [Aaronia-Open-source/python_RTSA_HTTP_API_Sequence_Example](https://github.com/Aaronia-Open-source/python_RTSA_HTTP_API_Sequence_Example). A Python script that runs a measurement sequence and records to disk, driving the device entirely through `PUT /remoteconfig`. It is the source of the config-tree write example below.
 
 The content here is derived from the above plus empirical analysis of live
 RTSA-Suite PRO streams. "Aaronia", "RTSA", and "Spectran" are the property of

{python_aaronia-0.6.0 → python_aaronia-0.6.1}/docs/QUICKSTART.md

@@ -60,7 +60,7 @@ use sdr_aaronia_rs::{AaroniaConfig, AaroniaSource};
 async fn main() -> anyhow::Result<()> {
     let config = AaroniaConfig::from_http("http://localhost:54664")
         .center_frequency(2.44e9)
-        .span_frequency(12.288e6)   // sample rate, not RF bandwidth
+        .span_frequency(15.36e6)    // sample rate (Fs), not RF bandwidth
         .reference_level(-20.0);
 
     let mut source = AaroniaSource::new(config).await?;
@@ -77,7 +77,7 @@ async fn main() -> anyhow::Result<()> {
 
 ```bash
 # args: <center-hz> <sample-rate-hz> <url>
-cargo run --example http_iq_quickstart --features http -- 2440e6 12.288e6 http://localhost:54664
+cargo run --example http_iq_quickstart --features http -- 2440e6 15.36e6 http://localhost:54664
 ```
 
 ### Python
@@ -92,7 +92,7 @@ import aaronia
 cfg = aaronia.AaroniaConfig()
 cfg.http_base_url = "http://localhost:54664"
 cfg.center_freq = 2.44e9
-cfg.sample_rate = 12.288e6
+cfg.sample_rate = 15.36e6
 
 src = aaronia.AaroniaSource()
 src.start_streaming(cfg)
@@ -124,22 +124,41 @@ Usually the missing connection from step 4: the device block's output is
 not wired to the HTTP Server block. `curl /sample` shows whether data is
 present.
 
-**Span and sample rate.**
+**Span, sample rate and the "1 / 4" in the GUI.**
 `span_frequency` is the IQ sample rate (Fs). The name comes from the
-Aaronia API. It is not the usable RF bandwidth, which is smaller because
-of the anti-alias filter (roughly 49 MHz usable within a 61.44 MHz Fs
-capture). The device derives its decimation steps from a 61.44 MHz
-clock. Over HTTP the RTSA-Suite accepts rates across its supported
-range, and the crate rejects a rate that would violate the IQ-mode
-constraint before streaming starts.
+Aaronia API. Three numbers describe the same capture and they are all
+different:
+
+| Where you see it | Example | Meaning |
+| --- | --- | --- |
+| `span_frequency`, and `sampleFrequency` in packet metadata | 15.36 MHz | The sample rate, Fs |
+| `startFrequency`..`endFrequency` in packet metadata | 12.288 MHz | Usable alias-free bandwidth, which measures 0.8 x Fs |
+| The Span control in the RTSA GUI | `1 / 4` | Decimation of the 61.44 MHz clock, so Fs = 61.44 / 4 |
+
+The device runs at 61.44 MHz divided by a power of two, ten rates from
+61.44 MHz down to 120 kHz, shown in the GUI as Full through `1 / 512`.
+
+**Pass one of those rates and you get it exactly.** Anything else is
+silently adjusted, and not to the nearest rate: the server reads the
+requested span as the *usable bandwidth* you want and picks the rate
+whose usable span is closest. Asking for 2.5 MHz gives Fs = 3.84 MHz,
+whose usable span is 3.07 MHz, rather than the numerically closer
+1.92 MHz. Verified across nine requests on a V6 ECO.
+
+`AaroniaSource::get_source_info()` reports the rate the server is
+actually sending once packets are flowing, so read it back rather than
+assuming.
+
+The crate rejects a rate that would violate the IQ-mode constraint
+before streaming starts, but it does not second-guess the ladder.
 
 **Retuning has no effect.**
 The `/control` endpoint applies a frequency change only when
 `frequencyCenter` and `frequencySpan` are both present. A request
 carrying one of them returns `{"success":true}` and is ignored. This
 crate always sends the complete tuple, so use `set_center_frequency`
-instead of issuing PUTs directly. No Aaronia licence is involved; the
-licence gates `/remoteconfig`, which the crate does not use for tuning.
+instead of issuing PUTs directly. No Aaronia licence is involved: the
+crate tunes through `/control`, which needs none.
 
 **Network saturation at high sample rates.**
 Float32 requires roughly 740 MB/s at 92 MSPS. On anything other than
@@ -165,7 +184,7 @@ use sdr_aaronia_rs::{AaroniaConfig, AaroniaSource};
 let config = AaroniaConfig::default()
     .force_native_sdk()
     .center_frequency(2.44e9)
-    .span_frequency(12.288e6);
+    .span_frequency(15.36e6);
 let mut source = AaroniaSource::new(config).await?;
 # Ok(())
 # }

{python_aaronia-0.6.0 → python_aaronia-0.6.1}/docs/USAGE.md

@@ -5,7 +5,7 @@ compiled as a doctest, so it stays valid as the API changes.
 
 For first-time setup of the RTSA-Suite HTTP Server block, see
 [QUICKSTART.md](QUICKSTART.md). For runnable programs, see
-[`examples/`](../examples/).
+[Runnable examples](#runnable-examples) below.
 
 ## Unified API with auto-detection
 
@@ -303,9 +303,35 @@ async fn main() -> Result<()> {
 }
 ```
 
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `AARONIA_SDK_PATH` | Overrides the RTSA-Suite installation directory used for SDK / `RTSAFileTool` detection. Works on every platform. On macOS — which has no default install path and no native SDK build — it only affects `RTSAFileTool` and XML-config detection. |
+| `AARONIA_USER_AGENT` | Overrides the HTTP `User-Agent` string sent by every outbound request (default: `sdr-aaronia-rs/<version>`). |
+
+## Runnable examples
+
+The programs in `examples/` cover the same ground as this document, as
+code you can run. CI builds them, so they stay current:
+
+| Task | Example |
+| --- | --- |
+| HTTP IQ streaming, first samples | [`http_iq_quickstart.rs`](../examples/http_iq_quickstart.rs) |
+| Health checks, input enumeration, recording control, license probing | [`device_control.rs`](../examples/device_control.rs) |
+| Frequency hopping via the `sdr-source` traits | [`channel_hopping.rs`](../examples/channel_hopping.rs) |
+| FutureSDR flowgraph with FM demodulation | [`noaa_scanner.rs`](../examples/noaa_scanner.rs) |
+| Native SDK capture and transmit | [`native_sdk_basic.rs`](../examples/native_sdk_basic.rs), [`native_sdk_transmit.rs`](../examples/native_sdk_transmit.rs) |
+| RTSA file playback and metadata inspection | [`read_rtsa_file.rs`](../examples/read_rtsa_file.rs), [`dump_metadata.rs`](../examples/dump_metadata.rs) |
+| Python (NumPy and Arrow), SoapySDR from Python | [`python_arrow_example.py`](../examples/python_arrow_example.py), [`soapy_python_example.py`](../examples/soapy_python_example.py) |
+
+```bash
+# args: <center-hz> <sample-rate-hz> <url>
+cargo run --example http_iq_quickstart --features http -- 2440e6 15.36e6 http://localhost:54664
+```
+
 ## Related
 
 - [QUICKSTART.md](QUICKSTART.md) — RTSA-Suite mission setup and troubleshooting.
 - [APPS.md](APPS.md) — SDR++, GQRX, GNU Radio and SoapySDR from Python.
 - [HTTPSPEC.md](HTTPSPEC.md) — the RTSA HTTP API this crate speaks.
-- [`examples/`](../examples/) — the same material as runnable programs.

python_aaronia-0.6.1/docs/VERIFICATION.md

@@ -0,0 +1,47 @@
+# Hardware verification status
+
+Not every code path has been exercised against hardware. The
+development device is a SPECTRAN V6 ECO with a single RX channel and no
+TX licence, driven through RTSA-Suite PRO over HTTP from macOS. Paths
+requiring a second RX input, a transmitter, or the Windows/Linux native
+SDK are marked unverified.
+
+| Capability | Backend | Status |
+| --- | --- | --- |
+| IQ streaming, all four wire formats (F32 / F16 / I16 / JSON) | HTTP | **Live-verified** |
+| Spectra streaming | HTTP | **Live-verified** |
+| Mid-stream retuning (centre, span) | HTTP | **Live-verified** |
+| Mid-stream reference-level change | HTTP | Confirmed manually against the device; no automated live assertion |
+| Auto-reconnect after a dropped stream | HTTP | Streaming live-verified; the drop-and-recover path is mock-tested |
+| Drop/overrun detection, rate reduction, `scale=N` | HTTP | **Live-verified** |
+| Long-run stability (>120 s continuous) | HTTP | **Live-verified** |
+| Connect retry | HTTP | Mock-tested; the mDNS race it addresses did not reproduce on demand |
+| `.rtsa` playback and metadata | File | **Verified against real captures**, byte-compared with the official format specification |
+| seify backend | HTTP | **Live-verified** |
+| SoapySDR plugin RX | HTTP | Verified manually (~9.7 Msps via `SoapySDRUtil`); no automated live test, as a `soapysdr` dev-dependency would make `cargo test` unbuildable without system SoapySDR |
+| Python bindings RX | HTTP | Verified manually (NumPy and Arrow); no automated live test |
+| TX (`UnifiedSink`, `aaronia_sink_*`, SoapySDR TX) | Native SDK | **Hardware-unverified**. No TX-licensed device available |
+| Dual-channel RX (`Rx1And2`, `read_samples_dual`) | Native SDK | **Hardware-unverified**. Requires a full V6 |
+| GPS hardware time | Native SDK | **Hardware-unverified** |
+| Native SDK capture generally | Native SDK | **Hardware-unverified**; compiled and unit-tested in a Linux VM each release |
+| HTTP TX push (`/sample`) | HTTP | Endpoint exercised live; RF output not measured |
+
+"Live-verified" means an `#[ignore]`d test in
+[`tests/live_smoke.rs`](../tests/live_smoke.rs) asserts the behaviour
+against hardware, and is reproducible by anyone with a device. Entries
+marked "verified manually" were observed working but have no automated
+assertion and can regress without detection. Run the automated set
+with:
+
+```bash
+cargo test --all-features --test live_smoke -- --ignored --nocapture
+```
+
+Contributions that convert an unverified row, particularly from users
+with a full V6 or a TX licence, are welcome.
+
+## Related
+
+- [QUICKSTART.md](QUICKSTART.md) — setting up an RTSA-Suite mission.
+- [USAGE.md](USAGE.md) — worked examples for each part of the API.
+- [../CHANGELOG.md](../CHANGELOG.md) — what changed in each release.