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

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

@@ -2,6 +2,139 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [v0.11.1] - 2026-09-10
+
+### Fixed
+- **A stream gap now ends the block it precedes, instead of hiding inside
+  one.** Read assembly noted a dropped chunk and carried on concatenating,
+  so a returned block held samples from both sides of the hole while
+  `take_overrun` said only "somewhere in there". A consumer resetting its
+  filters once, before the block, still ran the discontinuity through
+  them — and for an FM discriminator that is a phase step, i.e. a
+  frequency spike that reads downstream as a sync edge.
+
+  A gap has a position, and the only position a consumer can act on is a
+  read boundary. The post-gap chunk is now stashed and the block ends,
+  exactly as it already did for a retune, with the flag carried to the
+  read that begins there. A gap on a read's first chunk still reports
+  against that read, since nothing precedes it to split from.
+
+  This also reaches reconnects, which are discontinuities for the same
+  reason: the stream stopped and resumed, so the samples either side are
+  not adjacent. Reads continue across a reconnect as before, they just
+  no longer splice across it.
+
+
+## [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

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/Cargo.lock

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

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

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.10.0
+Version: 0.11.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.10.0 → python_aaronia-0.11.1}/README.md

@@ -236,6 +236,7 @@ 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.
+- [Synchronising receivers](docs/SYNC.md) — what the hardware can and cannot do for multi-device timing, and the recipe that works.
 
 Reference:
 

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/docs/SDKSPEC.md

@@ -258,7 +258,16 @@ The Aaronia RTSA SDK (`aaroniartsaapi.h`) exposes a C-style API for maximum comp
 *   **`AARTSAAPI_AvailPackets(AARTSAAPI_Device * dhandle, int32_t channel, int32_t * num)`**: Gets the number of available packets in a specified data `channel`.
 *   **`AARTSAAPI_GetPacket(AARTSAAPI_Device * dhandle, int32_t channel, int32_t index, AARTSAAPI_Packet * packet)`**: Retrieves a specific packet from the output queue.
 *   **`AARTSAAPI_ConsumePackets(AARTSAAPI_Device * dhandle, int32_t channel, int32_t num)`**: Consumes (removes) a number of packets from the data channel. Essential to prevent blocking and data drops.
-*   **`AARTSAAPI_GetMasterStreamTime(AARTSAAPI_Device * dhandle, double * stime)`**: Gets the current master stream time.
+*   **`AARTSAAPI_GetMasterStreamTime(AARTSAAPI_Device * dhandle, double * stime)`**:
+    Gets the current master stream time, seconds since the epoch. The
+    header declares the out-parameter as a C++ *reference* (`double &`),
+    which is a pointer in the ABI — hence `*mut f64` here. Exposed as
+    `NativeSdkSource::master_stream_time_ns` and
+    `SpectranSource::master_stream_time_ns`, converted to nanoseconds so
+    it reads in the same unit as every other clock the crate reports.
+    This is the device's own timebase: it paces streams against it, TX
+    burst times are expressed in it, and it is what a multi-device
+    capture is aligned on — see [SYNC.md](SYNC.md).
 *   **`AARTSAAPI_SendPacket(AARTSAAPI_Device * dhandle, int32_t channel, const AARTSAAPI_Packet * packet)`**: Sends a packet to an inbound channel (for transmission modes).
 
 ### File I/O API
@@ -461,7 +470,7 @@ values an `f64`'s step is about **238 ns**, which is the real resolution of
 any GPS timestamp this device gives — no conversion downstream can improve
 on it.
 
-`utils::gps_seconds_to_nanos` converts to `i64` nanoseconds by handling the
+`utils::epoch_seconds_to_nanos` converts to `i64` nanoseconds by handling the
 whole and fractional seconds separately. That is not pedantry: epoch
 nanoseconds are around `1.7e18`, where an `f64`'s step is 256 ns, so a single
 `seconds * 1e9` multiply discards tens of nanoseconds the reading still had.
@@ -541,6 +550,13 @@ never sees), so the second path errors instead of corrupting silently.
 `stop_streaming` clears both carry buffers and the latch, so a
 restarted session starts clean.
 
+The SoapySDR plugin exposes the same capture as two RX channels:
+`rx_channel=Rx1And2` at open time makes `getNumChannels(RX)` report 2,
+and `setupStream(RX, …, {0, 1})` switches `readStream` onto the paired
+read. The channel count follows the request rather than the model,
+because dual capture must be configured before the device is opened —
+a full V6 opened single-channel really does have one channel to offer.
+
 > **Hardware-unverified:** like the rest of the `Rx2`/`Rx1+Rx2` paths,
 > the interleave layout follows the packet contract (`stride` = floats
 > from sample to sample), not a live dual-channel capture — the

python_aaronia-0.11.1/docs/SYNC.md

@@ -0,0 +1,118 @@
+# Synchronising two or more receivers
+
+The short version: **the SPECTRAN V6 is a shared-reference machine, not a
+commanded-time one.** You cannot tell it to start capturing at a stated
+instant. You can lock several devices to one reference, timestamp
+everything they produce, and align the streams afterwards. That is
+enough for RDF, TDOA and coherent multi-channel work; it is not enough
+for the UHD-style `set_start_time()` pattern, and no amount of API
+wrapping will make it so.
+
+## What the hardware offers
+
+| Primitive | Where |
+| --- | --- |
+| Common frequency reference (10 MHz, PPS, GPS) | `device/sclksource` — `set_clock_source()` |
+| GPS discipline and time of day | `device/gpsmode` — `set_gps_mode()`, `gps_time_ns()` |
+| Per-packet hardware timestamps | `AARTSAAPI_Packet::startTime`/`endTime` — `last_timestamp_ns()` |
+| The device's own stream clock | `AARTSAAPI_GetMasterStreamTime` — `master_stream_time_ns()` |
+| Two phase-coherent RX inputs (full V6) | `device/receiverchannel` — `read_samples_dual()` |
+
+A V6 ECO with no GPS antenna accepts six clock sources: `Consumer`,
+`Oscillator`, `PPS`, `10MHz`, `Oscillator Provider` and `PPS Provider`.
+The `Provider` variants make that device the reference for others rather
+than a consumer of one. `GPS` and `GPS Provider` appear in the tree but
+are masked out when no antenna is attached, and `clock_sources()`
+filters them for that reason — the list reports what the device will
+accept, not what it can spell.
+
+## What it does not offer
+
+The vendor API is 34 functions. There is no set-time, no arm-at-time and
+no trigger among them: the closest thing to time control is
+`AARTSAAPI_GetMasterStreamTime`, which reads. Nothing writes a clock,
+and nothing schedules a capture.
+
+Transmission is the exception, and it proves the rule — a `TxBurst`
+carries `startTime`/`endTime` and the device schedules it. The
+capability exists in the FPGA; the API simply does not expose it for
+receive.
+
+So a two-receiver capture cannot be started simultaneously by command.
+Both devices are started as promptly as software allows, and the offset
+between them is measured rather than commanded.
+
+## The recipe
+
+1. **Discipline every device from one reference.** One device (or an
+   external source) provides; the rest consume:
+
+   ```rust,no_run
+   # async fn discipline() -> sdr_aaronia_rs::Result<()> {
+   use sdr_aaronia_rs::{SpectranConfig, SpectranSource};
+
+   let mut provider =
+       SpectranSource::new(SpectranConfig::from_http("http://ref.local:54664")).await?;
+   let mut consumer =
+       SpectranSource::new(SpectranConfig::from_http("http://sat.local:54664")).await?;
+
+   provider.set_clock_source("PPS Provider").await?;
+   consumer.set_clock_source("PPS").await?;
+   # Ok(())
+   # }
+   ```
+
+   Confirm by reading back — `set_clock_source` already does, and errors
+   if the device did not take it. This is what makes the sample clocks
+   agree in *rate*. It does not make them agree in *phase*.
+
+2. **Start the streams.** In whatever order; the offset between them is
+   not controlled and does not need to be.
+
+3. **Timestamp everything.** Each packet carries device time.
+   `last_timestamp_ns()` reports the most recent one, and every
+   SoapySDR buffer comes back flagged `SOAPY_SDR_HAS_TIME`.
+
+4. **Align afterwards.** Compute the offset between the streams from
+   their timestamps, then refine it by cross-correlating a common
+   signal. The timestamps get you to within the resolution below; the
+   correlation gets you the rest of the way, and is what actually
+   determines the answer in TDOA work.
+
+For two channels on a *single* full V6, none of this applies: `Rx1` and
+`Rx2` share one tuner and one converter, arrive interleaved in one
+packet, and are sample-aligned by construction. Read them with
+`read_samples_dual()` — see [SDKSPEC.md](SDKSPEC.md#receiver-channel-selection-and-dual-channel-capture).
+
+## The resolution floor
+
+The device reports both its GPS time and its master stream time as
+`float64` seconds since the epoch. At present-day epoch values an `f64`
+steps about **238 ns**, so those two clocks are quantised at roughly
+that — before any conversion this crate performs, and not something it
+can improve on.
+
+For TDOA, 240 ns of timing uncertainty is about **70 m** of ranging
+uncertainty. That is the floor for *timestamp-based* alignment. It is
+not the floor for the technique: cross-correlating a common signal
+resolves far below one sample period, and the timestamps only have to be
+good enough to identify which samples to correlate. Build the geometry
+on the correlation, and use the timestamps to get there.
+
+The per-packet stream timestamps are the better of the two clocks for
+this. GPS time is for disciplining and for wall-clock labelling.
+
+## Status
+
+Hardware-unverified. The clock-source writes are exercised against a
+single V6 ECO; nothing here has been run across two devices, and the
+crate has never seen a full V6. See
+[VERIFICATION.md](VERIFICATION.md).
+
+## Related
+
+- [SDKSPEC.md](SDKSPEC.md) — the native SDK surface, including the
+  packet layout and dual-channel capture.
+- [USAGE.md](USAGE.md) — worked examples for each part of the API.
+- [VERIFICATION.md](VERIFICATION.md) — what has been tested against
+  hardware.

python_aaronia-0.11.1/docs/VERIFICATION.md

@@ -0,0 +1,73 @@
+# Hardware verification status
+
+The development device is a SPECTRAN V6 ECO — single RX channel, no TX
+licence, no GPS antenna — driven over HTTP through RTSA-Suite PRO from
+macOS and, since 0.8.2, through the native SDK on the Windows machine it
+is attached to.
+
+**Live-verified** means an `#[ignore]`d test asserts it against hardware,
+so it cannot regress unnoticed. **Manual** means it was seen working but
+nothing asserts it.
+
+| Capability | HTTP | Native SDK |
+| --- | --- | --- |
+| IQ streaming (F32 / F16 / I16 / JSON) | **Live** | **Live** |
+| Spectra streaming | **Live** | **Live** — the ECO's `rtsa` pipeline, 512 frames x 88 bins per packet |
+| Retuning, rate and reference level mid-stream | **Live** | **Live** |
+| Long-run stability, drop and overrun counters | **Live** | **Live** |
+| Sample-rate ladder and usable bandwidth | **Live** | **Live** |
+| Device capability and health reporting | **Live** | Partial — the raw SDK's health tree reads zeros, so sensors are HTTP-only by design |
+| Clock-source and GPS-mode writes | **Live** | Unverified |
+| Auto-reconnect and connect retry | Mock-tested | n/a |
+| End-to-end IQ correctness (`validate-iq-live.py`) | **Live** | — |
+| seify backend | **Live** | **Live** |
+| Python bindings | Manual | Manual |
+| SoapySDR plugin | Manual | Manual |
+| `.rtsa` file playback | **Verified against real captures** | — |
+| TX (`UnifiedSink`, `spectran_sink_*`) | Endpoint only, no RF measured | Unverified |
+| Dual-channel RX (Rust, C, Python, SoapySDR) | — | Unverified — needs a full V6 |
+| GPS time (`gps_time_ns`) | — | Unverified — needs a GPS antenna |
+| Master stream clock (`master_stream_time_ns`) | — | Unverified |
+
+## What is not verified, and why
+
+**TX, dual-channel RX, GPS time and multi-device sync** need hardware
+this project does not have: a TX licence, a full V6, a GPS antenna, or a
+second device. If you
+have any of them, exercising one of these paths is the most valuable
+contribution you can make here — the first native-SDK run against a real
+device found five defects that compile-checking never would.
+
+**Native-SDK clock and GPS-mode writes** share their shape with the
+HTTP path, which is live-verified, but are not themselves exercised.
+
+**Drops.** The live drop test does not assert that drops *occur* — that
+is a property of the link, not the crate, and a fast enough link never
+drops anything. It checks the stream stays coherent and the counters
+agree; the gap logic itself is unit-tested.
+
+## Running them
+
+```bash
+cargo test --all-features --test live_smoke -- --ignored --test-threads=1
+```
+
+The native-SDK set needs the machine the device is attached to, with
+RTSA-Suite PRO closed — it holds the device:
+
+```bash
+cargo test --release --features native-sdk --test native_sdk_live -- --ignored --test-threads=1
+```
+
+`--test-threads=1` matters: one live test writes device state, and a
+concurrent streaming test would see the reference change underneath it.
+
+Both suites were re-run in full for 0.10.0 — 21 and 14 tests, all
+passing — along with a SoapySDR probe through the renamed C ABI.
+
+## Related
+
+- [QUICKSTART.md](QUICKSTART.md) — setting up an RTSA-Suite mission.
+- [SYNC.md](SYNC.md) — what multi-device timing the hardware supports.
+- [USAGE.md](USAGE.md) — worked examples for each part of the API.
+- [../CHANGELOG.md](../CHANGELOG.md) — what changed in each release.

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/examples/native_sdk_transmit.rs

@@ -67,10 +67,12 @@ async fn main() -> anyhow::Result<()> {
 
     // Read the current master stream time from the device
     // This is required to correctly schedule our packets on the device's FPGA
-    let mut current_time = sdk_sink.get_master_stream_time()?;
+    let now_ns = sdk_sink.master_stream_time_ns()?;
 
-    // Pre-buffer by scheduling the first packet 200 ms in the future
-    current_time += 0.2;
+    // Burst times go into the vendor's packet header, which is seconds:
+    // convert once, here. Pre-buffer by scheduling the first packet
+    // 200 ms in the future.
+    let mut current_time = sdr_aaronia_rs::utils::epoch_nanos_to_seconds(now_ns) + 0.2;
 
     let duration_per_burst = SAMPLES_PER_BURST as f64 / config.sample_rate_hz;
 

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/include/spectran.h

@@ -187,6 +187,12 @@ intptr_t spectran_source_read_samples_timeout(SpectranSource* source, FfiComplex
 // the native-SDK backend): fills rx1/rx2 with equal numbers of
 // time-aligned samples; returns the pair count or -1.
 intptr_t spectran_source_read_samples_dual(SpectranSource* source, FfiComplex* rx1, FfiComplex* rx2, uintptr_t len);
+// Deadline-bounded dual read, the pair to
+// spectran_source_read_samples_timeout: waits at most timeout_us and
+// returns the pairs collected within the deadline; returns -3 only when
+// the deadline passes with zero pairs. timeout_us == 0 drains without
+// waiting. Both buffers receive the same count, so they stay aligned.
+intptr_t spectran_source_read_samples_dual_timeout(SpectranSource* source, FfiComplex* rx1, FfiComplex* rx2, uintptr_t len, uint64_t timeout_us);
 bool spectran_source_take_overrun(SpectranSource* source);
 uint64_t spectran_source_get_cumulative_drops(SpectranSource* source);
 int64_t spectran_source_get_last_timestamp_ns(SpectranSource* source);
@@ -196,6 +202,12 @@ int64_t spectran_source_get_last_timestamp_ns(SpectranSource* source);
 // library now, so callers no longer split whole/fractional seconds
 // themselves. Resolution is ~240 ns, set by the vendor's own double.
 bool spectran_source_get_gps_time_ns(SpectranSource* source, int64_t* out_gps_time_ns);
+// The device's master stream clock, nanoseconds since the Unix epoch:
+// the timebase it paces streams against, readable before the first
+// packet (unlike get_last_timestamp_ns, which is 0 until one arrives).
+// Native-SDK backend only; false over HTTP and file playback.
+// out_time_ns may be NULL to probe only whether the clock is readable.
+bool spectran_source_get_master_stream_time_ns(SpectranSource* source, int64_t* out_time_ns);
 SpectranFfiError spectran_source_start_streaming(SpectranSource* source);
 SpectranFfiError spectran_source_stop_streaming(SpectranSource* source);
 SpectranFfiError spectran_source_set_center_frequency_hz(SpectranSource* source, double hz);

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/python-aaronia/Cargo.toml

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

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/python-aaronia/aaronia.pyi

@@ -143,6 +143,12 @@ class SpectranSource:
     def read_samples_numpy(self, count: int) -> npt.NDArray[np.complex64]:
         """Read up to ``count`` IQ samples into a NumPy ``complex64`` array.
 
+        A read never spans a retune: if the centre frequency changes
+        part-way through, the read returns the samples captured before
+        it and the rest arrive on the next call. Expect a short array
+        around a :meth:`set_center_frequency_hz`, rather than one whose
+        samples come from two different frequencies.
+
         Raises ``SpectranTimeoutError`` if no data arrives within
         ``config.read_timeout_s``, ``SpectranConnectionError`` if the
         stream is closed, and ``ValueError`` if ``count`` exceeds the
@@ -181,6 +187,18 @@ class SpectranSource:
         """Epoch-nanosecond timestamp of the most recent block.
         HTTP backend only; 0 otherwise."""
 
+    def master_stream_time_ns(self) -> Optional[int]:
+        """The device's master stream clock, in epoch nanoseconds.
+
+        The timebase the device paces streams against, readable before
+        the first block arrives. Native-SDK backend only; None otherwise."""
+
+    def gps_time_ns(self) -> Optional[int]:
+        """The latest GPS time in epoch nanoseconds, or None without a fix.
+
+        Native-SDK backend only, and only once ``device/gpsmode`` is
+        enabled — the device ships with GPS off."""
+
 class BlockIterator:
     """Iterator returned by :meth:`SpectranSource.blocks`."""
 

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/python-aaronia/src/lib.rs

@@ -601,6 +601,31 @@ impl PySpectranSource {
             .ok_or_else(|| SpectranHardwareError::new_err("Not streaming"))?;
         Ok(source.last_timestamp_ns())
     }
+
+    /// The device's master stream clock (epoch ns) — the timebase it
+    /// paces streams against. Unlike `last_timestamp_ns` it is readable
+    /// before the first block arrives. Native-SDK backend only; `None`
+    /// otherwise.
+    fn master_stream_time_ns(&mut self) -> PyResult<Option<i64>> {
+        let source = self
+            .source
+            .as_mut()
+            .ok_or_else(|| SpectranHardwareError::new_err("Not streaming"))?;
+        Ok(source.master_stream_time_ns())
+    }
+
+    /// The latest GPS time (epoch ns), or `None` without a valid fix.
+    /// Native-SDK backend only, and only once `device/gpsmode` has been
+    /// enabled — the device ships with GPS off, in which state this
+    /// stays `None`. Quantised at roughly 240 ns by the device's own
+    /// reading.
+    fn gps_time_ns(&mut self) -> PyResult<Option<i64>> {
+        let source = self
+            .source
+            .as_mut()
+            .ok_or_else(|| SpectranHardwareError::new_err("Not streaming"))?;
+        Ok(source.gps_time_ns())
+    }
 }
 
 /// Iterator over fixed-size sample blocks, returned by

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/scripts/ci-local.sh

@@ -95,7 +95,7 @@ if ! skipped fences; then
             }
         }
         END { exit rc }
-    ' README.md docs/QUICKSTART.md docs/USAGE.md PLUGINS.md
+    ' README.md docs/QUICKSTART.md docs/USAGE.md PLUGINS.md docs/SYNC.md
 fi
 
 if ! skipped test; then

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/soapy-aaronia/README.md

@@ -120,6 +120,39 @@ receiver clock and reaches higher, by how much is unsettled — see [the
 note in HTTPSPEC](../docs/HTTPSPEC.md#unresolved-the-full-v6s-top-rate).
 There, `getSampleRate` while streaming is the number to trust.
 
+## Dual-channel RX
+
+A full SPECTRAN V6 has two RF inputs. Ask for both at open time and the
+plugin advertises two RX channels:
+
+```python
+sdr = SoapySDR.Device("driver=aaronia,sdk=1,rx_channel=Rx1And2")
+sdr.getNumChannels(SOAPY_SDR_RX)          # 2
+stream = sdr.setupStream(SOAPY_SDR_RX, SOAPY_SDR_CF32, [0, 1])
+```
+
+`readStream` then fills both buffers with the same number of samples,
+index-aligned in time. Channel 0 is Rx1, channel 1 is Rx2.
+
+It has to be requested before the device opens, so a V6 opened without
+it reports one channel — the count describes this session, not the
+model. The request needs the native-SDK backend; over HTTP it is
+ignored with a warning.
+
+Valid channel sets are `{0}`, `{0, 1}` and `{1, 0}` — the list order
+decides which receiver each buffer gets. `{1}` is not one: the SDK
+interleaves both receivers into a single packet, so Rx2 never arrives
+without Rx1. Open with `rx_channel=Rx2` for a single-channel stream from
+the second input.
+
+Both channels share one tuner: centre frequency, sample rate and
+reference level are device-wide, and setting them on either channel sets
+them for both.
+
+> **Hardware-unverified.** The development device is a single-channel V6
+> ECO, so this path follows the packet contract rather than a live
+> capture. See [VERIFICATION.md](../docs/VERIFICATION.md).
+
 ## What the probe reports
 
 Over the HTTP backend, `SoapySDRUtil --probe` reports the attached
@@ -166,6 +199,11 @@ it does offer. `listClockSources` reports the device's own vocabulary.
 - `hasHardwareTime("GPS")` reports a value rather than a capability —
   true only on the native-SDK backend with a valid fix.
   `getHardwareTime("GPS")` returns epoch nanoseconds.
+- `getHardwareTime("master")` returns the device's own stream clock in
+  epoch nanoseconds — the timebase it paces streams against, and the one
+  to align two receivers on. Native-SDK backend only. Unlike the default
+  it is readable before the first packet, so a probe gets a real answer.
+  See [SYNC.md](../docs/SYNC.md).
 - The single gain element, `REF`, is the Aaronia reference level in dBm.
   It is not an amplifier gain: raising it reduces sensitivity. Range and
   step come from the device — −55…+23 dBm in 0.5 dB steps on a V6 ECO.
@@ -174,8 +212,6 @@ it does offer. `listClockSources` reports the device's own vocabulary.
 
 ## Known limitations
 
-- One RX channel through the plugin. `rx_channel=Rx2` selects the second
-  antenna input; simultaneous dual-channel reads are available through
-  the crate's Rust, Python and C APIs, not the SoapySDR interface.
+- Dual RX is hardware-unverified — see [Dual-channel RX](#dual-channel-rx).
 - Enumeration advertises a default localhost candidate without probing
   it, because `find()` must not block on the network.

{python_aaronia-0.10.0 → python_aaronia-0.11.1}/soapy-aaronia/Registration.cpp

@@ -167,8 +167,17 @@ static SoapySDR::Device *makeAaronia(const SoapySDR::Kwargs &args) {
     // itself streams channel 0; Rx2 selects the second antenna input.
     if (args.count("rx_channel") != 0) {
         const std::string &ch = args.at("rx_channel");
-        int32_t sel = ch == "Rx2" ? 1 : (ch == "Rx1And2" ? 2 : 0);
-        spectran_source_builder_receiver_channel(builder, sel);
+        // Warn rather than silently fall back to Rx1: a typo used to
+        // hand back a single-channel Rx1 stream that looked exactly
+        // like a working dual request.
+        if (ch != "Rx1" && ch != "Rx2" && ch != "Rx1And2") {
+            SoapySDR::logf(SOAPY_SDR_WARNING,
+                           "aaronia: ignoring rx_channel=%s; expected Rx1, Rx2 or Rx1And2",
+                           ch.c_str());
+        } else {
+            int32_t sel = ch == "Rx2" ? 1 : (ch == "Rx1And2" ? 2 : 0);
+            spectran_source_builder_receiver_channel(builder, sel);
+        }
     }
     // read_timeout=<seconds>: only affects the crate's own blocking
     // reads. readStream always passes SoapySDR's per-call timeoutUs, so