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

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

@@ -4,6 +4,168 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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.12.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.12.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"
@@ -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.12.0"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3621,21 +3578,19 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.11.2"
+version = "0.12.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",

{python_aaronia-0.11.2 → python_aaronia-0.12.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.12.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 }

{python_aaronia-0.11.2 → python_aaronia-0.12.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.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.11.2
+Version: 0.12.0
 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.11.2 → python_aaronia-0.12.0}/README.md

@@ -58,6 +58,17 @@ Consumers:     ├── Native Rust API
                └── Python Bindings (PyO3: python-aaronia) ──► NumPy / Arrow
 ```
 
+## Listening to an analyser that is not yours
+
+A start writes to the device before it reads a sample — the RTSA block's connect/run
+switches, a tune to the requested centre and rate, a `/control` start — and the end of a
+stream writes a stop. On an analyser shared with other users, none of that is yours to do.
+`HttpSourceBuilder::listen_only(true)` skips all of it: the stream is read as the device is
+running it, the requested centre and rate only describe what to expect, the reference level
+is not pushed, no reconnect ever tunes, and the device is left running at the end. The
+stall fix below was verified live in this mode against a shared SPECTRAN V6 streaming its
+own 30.72 MS/s, the device's `/remoteconfig` identical before and after.
+
 ## Link requirements
 
 The server streams IQ at a fixed number of bytes per sample, so the span
@@ -68,7 +79,7 @@ waterfall and defeat any digital demodulator.
 | Real-time bandwidth | Sample rate | Needs (4 B/sample) | Link |
 |---|---|---|---|
 | up to 12.2 MHz | 15.36 MS/s | 61.4 MB/s | gigabit |
-| up to 24.5 MHz | 30.72 MS/s | 122.9 MB/s | gigabit measured 1024 skips; prefer 2.5GbE |
+| up to 24.5 MHz | 30.72 MS/s | 122.9 MB/s | **2.5GbE** — a 1000baseT hop at a 1500-byte MTU carries ~118 MB/s of TCP payload (measured 114–116.5); 10GbE measured 123.2 and carried 90 s at 30.72 MS/s without a gap |
 | up to 49.1 MHz | 61.44 MS/s | 245.8 MB/s | **2.5GbE** |
 
 **An ECO 100 needs 2.5GbE.** Its 44 MHz of real-time bandwidth only fits on
@@ -79,18 +90,161 @@ format: stay on `int16` or `float16`.
 Treat the table as a starting point. `link_budget` measures *your* path end
 to end and names the widest span that fits.
 
+Arithmetic can rule a link out; only a measurement rules it in. A 1000baseT
+hop at the usual 1500-byte MTU carries about 118 MB/s of TCP payload however
+the client reads, so 30.72 MS/s at 4 bytes a sample is 4 % short before a
+sample is processed (jumbo frames on every hop would lift the ceiling to
+~124 MB/s, 0.7 % above the need — untested). Measured 2026-09-28 through a USB
+gigabit adapter: 114–116.5 MB/s off the socket with nothing behind it, 5–7 %
+short, and the whole receiver delivered exactly that — 28.5–29.0 MS/s with
+about 35 server skips a second and no client-side trim — whatever its
+buffering (a deeper chunk channel, a larger reservoir and a full-batch
+consumer were each tried and changed nothing). The same stream with the
+client on a Wi-Fi 7 link read 123.3 MB/s in each one-second window once it
+had ramped, the first five seconds at 103 and hundreds of skips before it
+settled; wireless varies with the air, and a station-to-station Wi-Fi 7 path
+measured 75 MB/s (`link_budget`). Over a direct 10GbE link the same receiver
+ran 90 s at 30.72 MS/s with no gap at all, the socket reading 123.0–123.5 MB/s
+from its first second.
+
+## HTTP sample conversion
+
+Float16 IQ payloads use `half`'s bulk conversion, which selects SIMD at
+runtime on supported CPUs (AArch64 FP16 or x86 F16C) and retains a portable
+fallback. On little-endian targets, aligned payloads are borrowed directly;
+odd-aligned payloads pass through a 1 KiB stack buffer. Big-endian targets
+retain scalar little-endian decoding. Tests compare every half-float bit
+pattern with the preceding scalar implementation, including subnormals,
+signed zeros, and NaN payloads, at both alignments and with odd IQ counts.
+
+On the local macOS ARM64 host, release-mode conversion time fell as follows.
+Each result compares median elapsed times from three alternating A/B rounds,
+with 20,000 conversions per round after 2,000 warm-up calls:
+
+| IQ pairs per payload | Aligned payload | Odd-aligned payload |
+| --- | ---: | ---: |
+| 49,152 | 35.6% less time | 9.5% less time |
+| 65,535 | 36.3% less time | 9.8% less time |
+
+These measurements include output allocation, but exclude HTTP framing,
+networking, and application DSP; they are not Raspberry Pi measurements.
+This change applies to Float16 IQ, not the default Int16 capture format.
+Run the same comparison without concurrent builds or other benchmarks:
+
+```bash
+cargo test --release --lib --no-default-features --features http \
+  float16_bulk_throughput_meter -- --ignored --nocapture
+```
+
+## Stream continuity
+
+A source hands its consumer a flat run of samples, and that run *claims* to be
+continuous. Six things break the claim, and `HttpSource` knows about all six:
+
+| event | cause |
+| --- | --- |
+| server gap | the RTSA server dropped what it could not send; seen as a jump between one packet's `endTime` and the next's `startTime` larger than a tolerance measured from the stream (half a packet, or above the observed timestamp jitter, capped at 1 ms — see `DropDetector`; not yet verified live at high rates) |
+| backward timestamp | a packet's `startTime` precedes the previous packet's `endTime` by more than the same tolerance: nothing is missing, but the two do not follow one another |
+| undecodable packet | an IQ packet, or one whose header could not be read, framed but could not be decoded; it is skipped and its neighbours kept, and the hole is a gap where it sat |
+| capacity trim | the buffer reached its memory bound and the oldest samples were discarded. The trim sits one fetch sweep above the refill target, so a consumer that falls behind backs up the socket instead, and any loss then shows as a server gap; it is reached only by a JSON stream, whose samples have no fixed width, or if the headroom's assumptions — chunk and packet sizes, each learned before it is parsed — stop holding |
+| reconnect | the stream ended, errored, or delivered nothing for 5 s, and was reopened; the parser resets and the drop detector forgets the last timestamp (keeping its jitter calibration) |
+| retune | the device's centre frequency or sample rate changed mid-stream |
+
+`HttpSource` outputs IQ only. Spectra, histogram and category packets on a
+mixed mission are skipped and counted in `StreamStats::non_iq_packets_skipped`;
+they feed neither the output, the drop detector nor the frequency tracking. That
+includes the ones the parser cannot decode — a compressed spectra packet carries
+no byte length to frame it by — which cost no IQ and so mark no gap.
+
+Counters for these have always been available through `StreamStats`. What a
+counter cannot say is *which* samples belong to the old epoch — and that is the
+only thing a consumer can act on, because symbol timing, carrier tracking and
+burst framing are all carried across the boundary between one delivery and the
+next. `link_budget`'s own warning applies here: every dropped sample is an
+unsignalled phase discontinuity that breaks digital symbol lock.
+
+`with_stream_breaks` reports each one against the **absolute index of the first
+sample after it**, counted in this source's output stream:
+
+```rust,no_run
+# // `HttpSourceBuilder` is the FutureSDR block: compiled only with that feature.
+# #[cfg(feature = "futuresdr")]
+# fn main() -> Result<(), sdr_aaronia_rs::Error> {
+use std::sync::Arc;
+use sdr_aaronia_rs::{HttpSourceBuilder, RecordingBreakSink, StreamDiscontinuity};
+
+let breaks = Arc::new(RecordingBreakSink::new());
+let source = HttpSourceBuilder::new("http://atc.local:54664")
+    .center_frequency_hz(146.52e6)
+    .sample_rate_hz(1e6)
+    .with_stream_breaks(breaks.clone())
+    .build()?;
+
+// …later, after the flowgraph has run:
+for (at_sample, cause) in breaks.breaks() {
+    match cause {
+        StreamDiscontinuity::Gap => println!("reset decoder state at {at_sample}"),
+        StreamDiscontinuity::Initial { center_hz, rate_hz }
+        | StreamDiscontinuity::Retune { center_hz, rate_hz } => {
+            println!("samples from {at_sample} are {center_hz} Hz at {rate_hz} Sa/s")
+        }
+    }
+}
+# Ok(())
+# }
+# #[cfg(not(feature = "futuresdr"))]
+# fn main() {}
+```
+
+Implement `StreamBreakSink` yourself to push into whatever queue the consumer
+already reads; `RecordingBreakSink` is the built-in one, for tests and for
+looking at a finished run.
+
+Two properties make the index usable. A break is recorded **before** the
+samples it precedes are published, so by the time a consumer can see sample
+`i`, every break at or before `i` is already in the sink. And samples the
+source discards — trimmed, or cleared on a reconnect — never occupy an index,
+so the coordinate is simply how many samples the block has produced. Breaks are
+held against the samples still queued and emitted only as those are produced,
+which is what makes a reported index final: a trim that arrives later rebases
+what is still pending rather than invalidating what was already said.
+
+A `Retune` is measured against the geometry **last announced**, not against the
+previous packet. A baseline that moved with every packet would let a device
+creeping by less than a tolerance per packet travel arbitrarily far without
+ever reporting a change, since each step would be judged against the step
+before it rather than against what the consumer believes. Centre moves of more
+than 1 Hz and rate moves outside the crate's 10% band count; the rate ladder
+steps in powers of two, so a real change clears that band by a wide margin
+while a rate the parser had to infer from `samples / duration` wobbles well
+inside it. A packet declaring no usable rate at all is ignored for this
+purpose rather than taken as a new baseline. A restart that clears the buffer
+also discards any announcement still queued in it, so the baseline goes back to
+the last geometry actually *reported* — a retune the restart swallowed is then
+announced after it.
+
+`Initial` is emitted at sample 0 of every run, whether or not it differs from
+what was requested. The server serves the nearest rung of its own rate ladder
+and the span its mission is configured for, so the first packet is exactly
+where a disagreement with the request appears — and a consumer comparing
+packets only against each other would never see it. Breaks at one index are
+reported as one boundary — at most a gap, then at most one geometry — so when
+a trim before the first sample discards the band the run opened on, the
+consumer gets a single `Initial` naming the geometry its first sample actually
+arrived under.
+
 ## 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.8"
+# By default, includes HTTP, File and C FFI backend support
+sdr-aaronia-rs = "0.12"
 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.8", features = ["native-sdk", "futuresdr"] }
+# sdr-aaronia-rs = { version = "0.12", features = ["native-sdk", "futuresdr"] }
 ```
 
 HTTP reads use one timeout budget for the entire requested block and return partial data at a timeout, frequency change, sample-rate change, or detected gap. `capture_frequency_hz()` and `capture_sample_rate_hz()` describe the returned samples even when newer packets are queued. File tuning setters preserve the recording's metadata.
@@ -222,7 +376,6 @@ Functionality is grouped behind Cargo features so unused dependencies stay out o
 | `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 `SpectranSdrSource` implementing the native `SdrSource` traits. | **Yes** |
 | `ffi` | Builds the C-API export layer. | **Yes** |
 
 ## Testing & Contributing

{python_aaronia-0.11.2 → python_aaronia-0.12.0}/docs/HTTPSPEC.md

@@ -124,7 +124,7 @@ The stream server supports multiple data formats for high-performance streaming:
 | `minPower` | Minimum power in dBm | `integer` (e.g., `-95`, `-2`, `-165`); this crate parses it as `i32` |
 | `maxPower` | Maximum power in dBm | `integer` (e.g., `5`, `2`); this crate parses it as `i32` |
 | `sampleFrequency` | Sample rate in Hz | `double` (e.g., `100000000.0`) |
-| `compression` | Compression scheme of the binary payload; drives the wavelet decompression path when present | `integer` |
+| `compression` | Compression factor of the binary payload (0 = uncompressed). Not in the v9 endpoints document, and the server accepts `compression=N` only with `format=rtsa`. A compressed payload's byte length is not in the header, so a `spectra` or `histogram` packet with `compression > 0` on the JSON-plus-binary wire **cannot be framed**: `StreamParser` reports it lost and resynchronises on the next header rather than consuming an assumed length | `integer` |
 | `startFrequency` | Start of a frequency range | `double` (e.g., `2400250000`, `2402250128`) |
 | `endFrequency` | End of a frequency range | `double` (e.g., `2487750000`, `2489750128`) |
 | `sampleDepth` | Number of sample sets per sample, e.g., bins in a histogram | `integer` (e.g., `1`, `2`, `256`) |
@@ -197,6 +197,18 @@ announces the loss; it shows up only as a gap between the timestamps of
 two adjacent packets. A slow consumer, a slow link, or a rate the
 network cannot carry all end here, so reducing the wire format
 (`format=int16`) is the fix rather than a larger client-side buffer.
+
+How large a jump counts as a gap is measured from the stream itself.
+`DropDetector` flags a gap larger than half the shorter of the two
+packets' own durations — a lost packet opens a gap of a whole one — or
+four times the residual it has seen between contiguous packets, if that
+is larger (up to three quarters of a packet), never less than 4 µs (the
+server prints `startTime` to the microsecond) and never more than 1 ms.
+A fixed 1 ms was the old rule, and above roughly 16 MS/s with 16 384-sample
+packets a whole lost packet is shorter than that and went unreported.
+The calibration is unit-tested on synthetic timestamps; **live
+verification against a real RTSA stream at a high rate is still
+pending.**
 Narrowing the span works too, since it moves the device down its
 decimation ladder. `rate_reduction=n` does not help here either — it is
 time compression for frame-based payloads (see the parameter note above).

{python_aaronia-0.11.2 → python_aaronia-0.12.0}/docs/USAGE.md

@@ -460,7 +460,6 @@ code you can run. CI builds them, so they stay current:
 | --- | --- |
 | HTTP IQ streaming, first samples | [`http_iq_quickstart.rs`](../examples/http_iq_quickstart.rs) |
 | Health checks, server info, input enumeration | [`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_aaronia-0.11.2 → python_aaronia-0.12.0}/include/spectran.h

@@ -25,9 +25,9 @@ typedef enum SpectranFfiError {
 
 // --- C-compatible SourceType --- //
 typedef enum CSpectranSourceType {
-    NativeSdk,
-    Http,
-    File,
+    NativeSdk = 0,
+    Http = 1,
+    File = 2,
 } CSpectranSourceType;
 
 // --- C-compatible Complex struct --- //
@@ -137,9 +137,10 @@ void spectran_source_builder_device_serial(SpectranSourceBuilder* builder, const
 
 /* Pin the source to one backend instead of auto-detecting. Forcing
  * NativeSdk makes a missing SDK a build error rather than a silent
- * fallback to localhost HTTP. */
+ * fallback to localhost HTTP. `source_type` is a CSpectranSourceType
+ * value, passed as int; a value outside the enum is ignored. */
 void spectran_source_builder_force_source_type(SpectranSourceBuilder *builder,
-                                              CSpectranSourceType source_type);
+                                              int source_type);
 
 /* Whether the native SDK library is present, by the search the builder
  * uses; does not load it. */

{python_aaronia-0.11.2 → python_aaronia-0.12.0}/python-aaronia/Cargo.toml

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