python-aaronia 0.11.2__tar.gz → 0.13.0__tar.gz

{python_aaronia-0.11.2 → python_aaronia-0.13.0}/CHANGELOG.md

@@ -4,6 +4,222 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.13.0] - 2026-10-08
+
+### Added
+- Native IQ packet RF span and centre metadata, independent of the actual IQ
+  sample clock. Mono and dual reads preserve that geometry with carried samples.
+- Direct SDK capability queries: configuration bounds, clock/channel/decimation
+  options with their original enum indices and disabled flags, selected mode,
+  and SDK version. Missing metadata stays unknown; no RTSA app is required.
+- Receive-only `NativeReceiverOptions`: explicit family/mode, IQ receiver RF
+  span, or enabled raw clock/decimation selection. SDK configuration bounds are
+  checked before writes. They are not a hardware qualification certificate.
+- Versioned capability JSON and RF-span controls in C and Python; device-derived
+  ranges and observed RF bandwidth in seify and SoapySDR. Windows/Linux Python
+  release wheels now enable `native-sdk` (the proprietary SDK remains separate).
+- An opt-in, serial-selected `native_sdk_qualification` example for receive-only
+  span changes and repeated device stop/reopen checks.
+
+### Fixed
+- Failed SDK opens close any partially allocated device. Connect/start failures
+  attempt stop, disconnect and close while preserving the original error.
+- Stop attempts all cleanup steps, returns the first failure, clears carried IQ
+  and observed metadata, and retains a failed-close handle for a Drop retry.
+  Repeated start/stop calls are idempotent; unified restart reopens the same
+  selected serial and settings, without silently switching devices or backend.
+- SDK global initialization/shutdown reference counting is serialized across the
+  initialized-state transition.
+- IQ receiver span validation uses the opened mode's `main/spanfreq` bounds,
+  rather than the legacy V6 raw-clock constraint. Runtime native setters use the
+  same configuration path as construction.
+- Reads stop before a queued packet changes centre, IQ rate or RF span, and a
+  carry-only read does not wait for another SDK packet.
+- Native capabilities and sensors no longer come from an unrelated HTTP server.
+- Unknown SDK modes cannot reinterpret spectra as IQ or IQ as spectra.
+- SoapySDR tolerates an unknown discrete sample-rate ladder and reports native
+  bandwidth from packet metadata. An RX open no longer attempts TX setup.
+- Release publication is gated on full CI, with semver checked against the
+  previous reachable release instead of a fixed historical tag.
+
+### Migration and qualification
+- This 0.x minor release adds public config fields and SDK mode enum variants.
+  Build `SpectranConfig` with `..Default::default()` and review exhaustive mode
+  matches. Existing C struct layouts and functions are retained.
+- Explicit `spectranv6eco/raw` is preserved; automatic ECO selection remains
+  `iqreceiver`. Explicit raw clock/decimation controls replace the legacy rate
+  request; the actual delivered rate comes from IQ packets.
+- Soapy TX setup requires explicit `tx=true`, a native backend and compatible
+  licensed hardware. TX and dual-RX remain hardware-unverified here.
+- Windows ECO mono qualification passed five stop/reopen cycles at RF spans
+  44, 20, 10, 5 and 44 MHz. The 44 MHz span carried about 59.214 MS/s; the lower
+  spans carried 30, 15 and 7.5 MS/s. One initial discontinuity was reported, with
+  no additional discontinuities during this short trial. Signals was restored.
+  This is not an endurance, amplitude-calibration or all-model certification.
+  See [native SDK compatibility](docs/NATIVE_SDK_COMPATIBILITY.md).
+
+## [v0.12.0] - 2026-09-29
+
+### Removed
+- **The `sdr-source` feature, and with it the dependency on `orecchiette-sdr-source-rs`.**
+  `SpectranSdrSource` and `SpectranBackend` (the `SdrSource`-trait facade over the async
+  source), the `sdr_source` re-export module and the `channel_hopping` example were one
+  consumer's adapter, and they live beside that consumer now (Specola's `sdr-aaronia-source`
+  crate), so this crate stands on its own: `default` is `http`, `file` and `ffi`, and
+  `crossbeam-channel` goes with the adapter. A caller that used the facade builds the same
+  thing from `SpectranSourceBuilder` and its own trait; the code is 670 lines and GPL, take it.
+
+### Added
+- **`HttpSource` reports where the stream broke**, not just how often.
+  `HttpSourceBuilder::with_stream_breaks` takes a `StreamBreakSink` (see the
+  new `stream_break` module) and the source calls it with the **absolute index
+  of the first sample after each discontinuity**, in its own output stream:
+  a server gap the drop detector saw, a capacity trim, a reconnect, and a
+  centre or rate change the device declared. Optional; a caller that does not
+  ask pays nothing.
+
+  The counters that were there before cannot be acted on. A consumer carrying
+  state across deliveries — symbol timing, carrier tracking, burst framing, a
+  recording's contiguity — needs to know *which* samples belong to the old
+  epoch, and "the server skipped 3 times" does not say. Breaks are held against
+  the samples still queued and emitted only as those samples are produced, so a
+  later trim cannot move an index already reported; samples the source discards
+  never occupy an index at all.
+
+- `StreamParser::process_data_recovering` and `ParsedItem`: a malformed
+  packet becomes a `ParsedItem::Lost` in stream order instead of an `Err` that
+  discards the rest of the chunk. `process_data` keeps its contract.
+- `StreamStats::non_iq_packets_skipped` and
+  `StreamStats::packets_lost_to_parse_errors`.
+
+### Fixed
+- **A catch-up after a stall no longer trims what it just fetched.** One
+  `fetch_samples` sweep drained every chunk the reader task had queued — up to
+  64, about a million int16 samples — into a buffer that trimmed a few packets
+  deep, so any stall of the consumer longer than a few milliseconds discarded
+  most of what arrived during it. Measured live from bigear against a
+  Spectran V6 at 15.36 MS/s, where the trim sat at 147 456 samples (~9.6 ms):
+  with one flowgraph executor every 45 s run lost samples, 2 to 10 times; with
+  two, two runs in five. The trim now sits one sweep above the refill target
+  (`catch_up_headroom`: `CHUNK_CHANNEL_DEPTH` chunks of the largest size seen,
+  in samples, plus a carried packet), and a sweep takes at most
+  `CHUNK_CHANNEL_DEPTH` chunks, so a catch-up always fits. A consumer that falls
+  behind now backs up the chunk channel and the socket instead of being
+  trimmed, and any loss moves upstream, where the packet timestamps report it
+  as a server gap. Re-measured live, same span: one executor 1 gap in 5 runs,
+  two executors 0 in 3. The overflow warning no longer names "the first
+  moments of a stream" as the expected cause.
+
+  What changes with it, so nothing reads as a regression later:
+  `StreamStats::buffer_capacity` still reports the enforced capacity, which now
+  includes the headroom and jumps once the first chunk sizes it (about eight
+  times the old figure at 15.36 MS/s int16), so a fill ratio reads lower. A
+  consumer that stalls now reads its backlog rather than a gap: up to the buffer
+  plus the channel, about 150 ms at 15.36 MS/s, which a pipeline faster than
+  real time then catches up — including a retune that arrived behind it. The
+  buffer can grow to about 10 MB (int16) or 20 MB (float32) during a stall, on
+  top of the channel's 4 MB. And because a slow consumer now throttles the
+  reads the link-budget meter counts, a window in which a sweep found the chunk
+  channel full is marked (`ThroughputMeter::note_consumer_limited`) and yields
+  no verdict, rather than one blaming the path for the consumer.
+- **A lost packet at a high sample rate is now reported.** `DropDetector`
+  flagged a gap only past a fixed 1 ms, and at 61.44 MS/s a 16 384-sample
+  packet lasts 267 µs, so a whole lost packet was spliced over silently. The
+  tolerance is now relative to the stream: half the packet's own duration, or
+  four times the residual observed between contiguous packets (at most three
+  quarters of a packet), floored at the timestamps' microsecond resolution
+  and still capped at 1 ms, so low rates behave as before.
+  `DropDetector::observed_jitter_seconds` exposes the calibration. Not yet
+  verified live against a real RTSA stream at a high rate.
+- **A compressed spectra or histogram packet no longer swallows the IQ behind
+  it.** It was framed at its *uncompressed* size, but a compressed payload is
+  a bitstream whose length the header does not carry. It is now reported as
+  `ParsedItem::Skipped` where it sat and the parser resynchronises on the next
+  header.
+- **A skipped non-IQ packet is no longer reported as a gap in the IQ.** Any
+  packet whose header was read but whose non-IQ payload could not be decoded
+  was a `ParsedItem::Lost`, which `HttpSource` recorded as a `Gap` and counted
+  in `packets_lost_to_parse_errors` — a hole claimed in an IQ stream that had
+  none. The new `ParsedItem::Skipped { payload, reason }` carries the declared
+  payload type; `HttpSource` counts it in `non_iq_packets_skipped` and records
+  no break. An undecodable IQ packet, or one whose extent could not be trusted,
+  is still `Lost`. (Breaking for exhaustive matches on `ParsedItem`.)
+- **A timestamp that steps backwards is a break, not continuity.**
+  `DropDetector::observe` returned `Continuous` for a packet starting before
+  the previous one ended, however far, and fed the step into the jitter
+  estimate, holding the tolerance at its ceiling afterwards. A backward step
+  past the tolerance is now `DropResult::Backward { overlap_seconds }`, counted
+  in `DropDetector::backward_steps` and kept out of the jitter estimate and
+  the drop totals; `HttpSource` records a `Gap` there and `UnifiedSource`
+  flags the buffer. (Breaking for exhaustive matches on `DropResult`.)
+- **`DropDetector::resync` keeps the jitter calibration.** It was cleared on
+  every lost packet and reconnect, and since the estimate grows only from
+  residuals already judged contiguous, a server whose residuals sit above
+  half a packet raised false drops until it was relearned. `reset` still
+  clears it.
+- **Compressed spectra decode on a frames × bins grid.** The wavelet grid was
+  sized from the square root of one frame's bins, ignoring the frame count
+  and dropping bins. Shapes whose layout is undocumented — more than one
+  16-spectrum block, depth planes, histograms — are refused instead of
+  decoded into a wrong shape.
+- **`HttpSource` no longer outputs spectra, histogram or category scalars as
+  IQ.** They were queued with the IQ, fed the drop detector (whose timeline
+  they are not on) and overwrote `current_frequency` (a marker declares 0 Hz).
+  They are now counted and skipped.
+- **One undecodable packet no longer costs the connection.** `HttpSource`
+  skips it, keeps the packets either side, and records a gap where it sat;
+  only an unrecoverable framing error still reconnects.
+- **The README's stream-break example is doctested only where it compiles.**
+  It uses `HttpSourceBuilder`, which needs the `futuresdr` feature, so
+  `cargo test` with default features failed on it; the body is now gated on
+  that feature.
+- **A stalled `/stream` reconnects.** The reader waited forever on a socket
+  that stayed open and sent nothing; it now gives up after 5 s and the source
+  takes its ordinary reconnect path.
+- **A retune swallowed by a restart is announced after it.** The restart
+  discarded the queued `Retune` but kept the baseline it had advanced, so the
+  new band was never reported. The baseline now rewinds to the last geometry
+  reported.
+- **A trim before the first sample publishes one `Initial`**, carrying the
+  geometry the first sample arrived under, instead of `Initial` for a
+  discarded band followed by `Retune` at the same index.
+- **The first-start tune runs even when the connect/run write fails**, takes
+  its target from the builder rather than from packet-tracked fields, and is
+  marked done once attempted. The connect/run failure is logged at warn.
+- **`UnifiedSource` HTTP reads no longer split on a derived-rate wobble.** The
+  read boundary compared rates with `!=`; it uses the crate's 10% band.
+- **RTSA files:** resync over a corrupt region scans in 64 KiB blocks instead
+  of one `seek` per byte (16 MiB of zeroes: 34 s → well under a second); an IQ
+  `SAMP` chunk declaring other than one I/Q pair per sample is refused rather
+  than read with a mismatched stride; `seek_to_sample` indexes chunks per
+  sub-stream, as reads do; and `validate_structure` no longer overflows on an
+  absurd sample count.
+- **C ABI:** `spectran_source_builder_force_source_type` takes the source type
+  as `int` and ignores an unknown value. Taking the `#[repr(C)]` enum by value
+  made an out-of-range value from C undefined behaviour. Source-compatible for
+  C and C++ callers passing an enumerator.
+- **Native SDK:** a packet consumed without being delivered (bad stride,
+  oversized, undemuxable) now counts in `cumulative_drops` and sets
+  `take_overrun`, like a packet the device itself flagged as dropped.
+
+### Changed
+- **Gap detection and sample queuing share one pass over each batch.** They
+  were two loops, so every packet's gap was measured against the buffer length
+  *before* any of the batch had been appended — the right answer only for the
+  first packet in it. No change to what is reported, only to where.
+- **Float16 IQ payloads convert in bulk.** The per-sample `f16::to_f32` loop is
+  replaced by `half`'s slice conversion, which selects SIMD at runtime on
+  AArch64 FP16 and x86 F16C and keeps a portable fallback. Aligned
+  little-endian payloads are borrowed in place; an odd-aligned payload — a JSON
+  header can leave one at any address — passes through a 1 KiB stack buffer
+  rather than a second packet-sized allocation. Big-endian targets keep the
+  scalar path. Measured on macOS ARM64 in release, against the scalar
+  implementation over three alternating A/B rounds: 36% less time for an
+  aligned payload, 10% for an odd-aligned one, at 49 152 and 65 535 IQ pairs.
+  Every half-float bit pattern — subnormals, signed zeros and NaN payloads
+  included — is compared against the previous implementation at both
+  alignments and with odd IQ counts.
+
 ## [v0.11.2] - 2026-09-11
 
 ### Added

{python_aaronia-0.11.2 → python_aaronia-0.13.0}/CONTRIBUTING.md

@@ -78,7 +78,7 @@ git lfs pull
 cargo test --test integration_test
 ```
 
-Beyond the tiers named here, `tests/` also contains focused suites for the HTTP mock server (`http_mock_test.rs`), the HTTP sink (`http_sink_test.rs`, requires `futuresdr`), the C API (`c_api_test.rs`), the `sdr-source` implementation (`sdr_source_impl_test.rs`), RTSA negative cases (`rtsa_negative_test.rs`), CW fixtures (`test_cw_mag.rs`, `test_cw_meta.rs`), SDK library loading (`native_sdk_load.rs`), and opt-in live-hardware smoke tests (`live_smoke.rs`). All of these run as part of `cargo test` where their features and environment allow.
+Beyond the tiers named here, `tests/` also contains focused suites for the HTTP mock server (`http_mock_test.rs`), the HTTP sink (`http_sink_test.rs`, requires `futuresdr`), the C API (`c_api_test.rs`), RTSA negative cases (`rtsa_negative_test.rs`), CW fixtures (`test_cw_mag.rs`, `test_cw_meta.rs`), SDK library loading (`native_sdk_load.rs`), and opt-in live-hardware smoke tests (`live_smoke.rs`). All of these run as part of `cargo test` where their features and environment allow.
 
 ### 3. Property Tests (`tests/properties.rs`)
 

{python_aaronia-0.11.2 → python_aaronia-0.13.0}/Cargo.lock

@@ -1010,28 +1010,6 @@ dependencies = [
  "itertools",
 ]
 
-[[package]]
-name = "crossbeam"
-version = "0.8.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1137cd7e7fc0fb5d3c5a8678be38ec56e819125d8d7907411fe24ccb943faca8"
-dependencies = [
- "crossbeam-channel",
- "crossbeam-deque",
- "crossbeam-epoch",
- "crossbeam-queue",
- "crossbeam-utils",
-]
-
-[[package]]
-name = "crossbeam-channel"
-version = "0.5.16"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d85363c37faeca707aef026efa9f3b34d077bce547e48f770770625c6013679e"
-dependencies = [
- "crossbeam-utils",
-]
-
 [[package]]
 name = "crossbeam-deque"
 version = "0.8.7"
@@ -1051,15 +1029,6 @@ dependencies = [
  "crossbeam-utils",
 ]
 
-[[package]]
-name = "crossbeam-queue"
-version = "0.3.13"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "803d13fb3b09d88be9f4dbc29062c66b19bf7170867ceb746d2a8689bf6c7a26"
-dependencies = [
- "crossbeam-utils",
-]
-
 [[package]]
 name = "crossbeam-utils"
 version = "0.8.22"
@@ -1319,7 +1288,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -2096,7 +2065,7 @@ checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
 dependencies = [
  "hermit-abi",
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -2770,18 +2739,6 @@ dependencies = [
  "hashbrown 0.14.5",
 ]
 
-[[package]]
-name = "orecchiette-sdr-source-rs"
-version = "0.1.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a940ff866bdff8ad17ba9b9881c73789c61824ab083d1db56b6b4944fce216b"
-dependencies = [
- "anyhow",
- "crossbeam",
- "num-complex",
- "thiserror 2.0.20",
-]
-
 [[package]]
 name = "parking"
 version = "2.2.1"
@@ -3092,7 +3049,7 @@ dependencies = [
 
 [[package]]
 name = "python-aaronia"
-version = "0.11.2"
+version = "0.13.0"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3163,7 +3120,7 @@ dependencies = [
  "once_cell",
  "socket2",
  "tracing",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3469,14 +3426,14 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "rustls"
-version = "0.23.43"
+version = "0.23.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0283386ce02abc0151e1761d08802dfe86c173b0b494af5cbc086574e453da06"
+checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
 dependencies = [
  "aws-lc-rs",
  "once_cell",
@@ -3526,7 +3483,7 @@ dependencies = [
  "security-framework",
  "security-framework-sys",
  "webpki-root-certs",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3621,21 +3578,19 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.11.2"
+version = "0.13.0"
 dependencies = [
  "anyhow",
  "bitflags 2.13.1",
  "byteorder",
  "bytes",
  "criterion",
- "crossbeam-channel",
  "futures",
  "futures-timer",
  "futuresdr",
  "half",
  "libloading",
  "num-complex",
- "orecchiette-sdr-source-rs",
  "proptest",
  "reqwest",
  "seify",
@@ -4203,10 +4158,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.4.3",
+ "getrandom 0.3.4",
  "once_cell",
  "rustix",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -4864,7 +4819,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]

{python_aaronia-0.11.2 → python_aaronia-0.13.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.11.2"
+version = "0.13.0"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"
@@ -11,7 +11,7 @@ categories = ["hardware-support", "api-bindings", "science"]
 exclude = ["tests/*.rtsa", "tests/sdk/", "tests/asan/", ".github/"]
 
 [package.metadata.docs.rs]
-features = ["http", "file", "sdr-source", "ffi", "native-sdk"]
+features = ["http", "file", "ffi", "native-sdk"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [lib]
@@ -42,8 +42,6 @@ futures-timer = { version = "3.0", optional = true }
 num-complex = "0.4"
 tempfile = { version = "3.8", optional = true }
 anyhow = { version = "1.0", optional = true }
-crossbeam-channel = { version = "0.5", optional = true }
-orecchiette-sdr-source-rs = { version = "0.1.3", optional = true }
 # default-features = false: seify's defaults include its own driver
 # backends (soapy -> soapysdr-sys, which needs system SoapySDR +
 # libclang at build time and is BSL-1.0-licensed). We only need the
@@ -101,12 +99,11 @@ name = "http_sink_test"
 required-features = ["futuresdr"]
 
 [features]
-default    = ["http", "file", "sdr-source", "ffi"]
+default    = ["http", "file", "ffi"]
 http       = ["dep:reqwest", "dep:tokio", "dep:serde", "dep:serde_json",
               "dep:url", "dep:bytes", "dep:futures", "dep:half"]
 file       = ["dep:byteorder", "dep:bitflags", "dep:tempfile"]
 futuresdr  = ["http", "dep:futuresdr", "dep:futures-timer", "dep:anyhow"]
-sdr-source = ["http", "file", "dep:crossbeam-channel", "dep:anyhow", "dep:orecchiette-sdr-source-rs"]
 seify      = ["http", "file", "dep:seify"]
 ffi        = ["http", "file"]
 native-sdk = ["dep:libloading", "dep:widestring"]
@@ -135,9 +132,6 @@ required-features = ["http"]
 name = "read_rtsa_file"
 required-features = ["file"]
 
-[[example]]
-name = "channel_hopping"
-required-features = ["sdr-source"]
 
 [target.'cfg(any(target_os = "windows", target_os = "linux"))'.dependencies]
 libloading = { version = "0.7", optional = true }
@@ -145,3 +139,7 @@ widestring = { version = "1.1", optional = true }
 
 [workspace]
 members = ["python-aaronia"]
+
+[[example]]
+name = "native_sdk_qualification"
+required-features = ["native-sdk", "http", "file"]

{python_aaronia-0.11.2 → python_aaronia-0.13.0}/DESIGN.md

@@ -69,22 +69,20 @@ Available on Windows and Linux only, behind the non-default `native-sdk` feature
 
 ## 5. Channel Hopping and Dwell Control
 
-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:
+Retuning mid-stream is `SpectranSource::set_center_frequency_hz`, 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**: `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.
+The hop loop itself — which channel next, how long to dwell there, and the ~75 ms settle after a retune that rides out the RTSA's apply-config latency and flushes stale samples — is the consumer's. Until 0.12.0 this crate carried one behind the `sdr-source` feature (`SpectranSdrSource`, an implementation of `orecchiette-sdr-source-rs`'s `SdrSource` trait); it lives beside its consumer now (Specola's `sdr-aaronia-source`), and a caller with its own trait builds the same thing from `SpectranSourceBuilder`.
 
 ## 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 `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 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. A consumer's read loop calls `take_overrun()` once per block it hands on, so a drop detected anywhere since the last read surfaces on the next block (Specola's adapter sets its `IqPacket::overrun` from it). 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 (`SpectranSdrSource::start`) is wrapped in `catch_unwind`: a panic inside the pump loop is logged rather than silently unwinding the thread.
-
 ## 7. FutureSDR Integration
 
 FutureSDR integration is available under the `futuresdr` feature gate. The crate exposes lower-level builder variants (e.g. `HttpSourceBuilder`) so `HttpSource` can be used as a source block in FutureSDR flowgraphs:

{python_aaronia-0.11.2 → python_aaronia-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.11.2
+Version: 0.13.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -103,41 +103,39 @@ common fields.
 
 The
 [quickstart](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/QUICKSTART.md)
-covers configuring the RTSA-Suite HTTP Server block, which everything
-above depends on.
+covers configuring the RTSA-Suite HTTP Server block for HTTP sources. Native SDK sources do not require that server.
 
-## Sample rates
+## Sample rate and RF span
 
-The device runs a ladder of rates rather than a continuous range: each
-rung is half the one above it. Ask for anything else and it quietly
-uses the nearest rung, leaving your program computing against a rate
-that is not in use.
+The module-level `sample_rates()` and `sample_rate_for_bandwidth()` functions
+remain legacy HTTP/ECO helpers. They are not capabilities of every native device.
+For a native IQ receiver, request RF span separately and inspect packet geometry:
 
 ```python
-aaronia.sample_rates()                  # every rate, highest first
-aaronia.sample_rate_for_bandwidth(8e6)  # 15.36e6: the lowest rate covering 8 MHz
+cfg = aaronia.SpectranConfig()
+cfg.force_native_sdk = True
+cfg.device_serial = "YOUR_DEVICE_SERIAL"
+cfg.native_mode = "iqreceiver"
+cfg.rf_span_hz = 44e6
+cfg.center_frequency_hz = 280e6
+cfg.reference_level_dbm = -50
+src = aaronia.SpectranSource()
+src.start_streaming(cfg)
+print(src.capabilities())                 # schema_version + capabilities
+samples = src.read_samples_numpy(65536)
+print(src.source_info())                  # observed rate and RF span
+src.set_rf_span_hz(20e6)
+src.stop_streaming()
 ```
 
-**Sample rate is not RF bandwidth.** You get every sample, so an FFT of
-them spans the full rate — but only the middle 80% is flat and
-calibrated. That is not an approximation: RTSA reports exactly 0.8 x Fs
-as the packet's frequency range at every rate. Outside it, data still
-arrives, attenuated and uncalibrated.
-
-So **to see N Hz of spectrum, sample at N / 0.8**, which is what
-`sample_rate_for_bandwidth()` computes. Aaronia's data sheet is more
-conservative still — 44 MHz for the ECO against the 49.152 MHz it
-declares at full span — because the analog filter is ~1 dB down by that
-edge. The
-[quickstart](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/QUICKSTART.md#4-troubleshooting)
-has the measurements.
-
-`sample_rates()` returns the V6 ECO's ladder, 61.44 MHz down to 120 kHz.
-A full V6 selects its receiver clock and goes higher, by how much is
-unsettled; see
-[the note in HTTPSPEC](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/HTTPSPEC.md#unresolved-the-full-v6s-top-rate).
-There, trust the rate the device reports in stream metadata, which
-`diagnose()` prints.
+IQ sample clock and valid RF span are distinct. The tested ECO delivered 44 MHz
+RF span at about 59.214 MS/s, and 20 MHz at 30 MS/s. Native configuration bounds
+may exceed the model's rated bandwidth. Neither those bounds nor RF span certifies
+amplitude calibration. Unknown metadata stays unknown. See the
+[qualification matrix](../docs/NATIVE_SDK_COMPATIBILITY.md).
+
+For HTTP only, the legacy helper uses the measured 0.8×Fs filter width and ECO
+rate ladder. Prefer `source_info()` for what the stream actually delivered.
 
 ## Choosing a wire format
 
@@ -178,6 +176,11 @@ Every field is readable and writable.
 | `file_path` | Path to a recorded `.rtsa` file; pins the file backend |
 | `device_serial` | Device selection for the native-SDK backend |
 | `force_native_sdk` | `True` pins the source to the native SDK; missing SDK is an error |
+| `native_family` | Optional bare SDK family, e.g. `"spectranv6eco"` |
+| `native_mode` | Optional receive-only `"iqreceiver"` or `"raw"` |
+| `rf_span_hz` | Optional requested native IQ receiver RF span, Hz |
+| `receiver_clock` | Optional enabled raw-mode SDK clock label |
+| `decimation_factor` | Optional raw-mode power-of-two factor |
 | `center_frequency_hz` | Center frequency, Hz |
 | `sample_rate_hz` | IQ sample rate (Fs), Hz |
 | `reference_level_dbm` | Reference level, dBm |