python-aaronia 0.7.6__tar.gz → 0.7.7__tar.gz

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/CHANGELOG.md

@@ -4,6 +4,316 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.7.7] - 2026-09-06
+
+### Added
+- **`utils::IQ_RATE_CLOCK_RATIO` and `utils::iq_ladder_from_top`.** The
+  1.5 receiver-clock-cycles-per-sample rule was a bare literal in three
+  places; it has a name now, and the ladder's shape is available
+  without the clock rule for a caller that already holds the top rung
+  — the link budget's device-anchored remedy, which used to reconstruct
+  a clock only to divide it back out (not exact in floating point).
+  `PacketMetadata::sample_rate()` likewise names the rate a header
+  reports (`sampleFrequency`, else `samples / duration`), shared by
+  `StreamingSdrConfig::from_metadata` and the probe's sniff.
+- **A link budget, so a span that cannot fit is caught before the
+  capture instead of after it.** The span picks a rate off the
+  decimation ladder and at 4 bytes a sample that rate is a byte rate the
+  path has to sustain: `--span 10M` is 15.36 MS/s and 61.4 MB/s, which
+  measured contiguous over gigabit, while `--span 20M` is 30.72 MS/s and
+  122.9 MB/s, which measured 1024 skips and 1.84 s lost of 35 s. The new
+  `link_budget` module does the arithmetic in both directions —
+  `required_byte_rate` for what a span costs, `max_sustainable_span` for
+  the widest rung a measured rate affords, inverted through the existing
+  ladder rather than a second copy of it — and `measure_link_throughput`
+  measures the path end to end by counting bytes off `/stream`.
+  Deliberately end to end: the bottleneck may be the server, a switch,
+  the air or this host's own ingest, and the NIC's advertised link speed
+  sees none of them.
+
+  The probe discards a 500 ms settle window before counting
+  (`LINK_PROBE_SETTLE`). Without it a probe *lies*: the server hands over
+  its pre-connect backlog faster than real time — measured at ~0.27–0.35 s
+  of signal, all inside a 345 ms window at connect — so counting it reads
+  above the true link rate and waves through a span that cannot fit. Two
+  tests pin this, one driving the settle logic off synthetic instants
+  with a 200 MB/s burst ahead of a 10 MB/s stream, and one showing the
+  same trace measuring several times too fast with the settle window
+  removed.
+  An unreachable server, an idle mission or a stream that stops mid-window
+  is an error and never a rate, because "0 MB/s" would condemn every span
+  on the ladder.
+- **`HttpSource` runs that check passively and warns once**, on the
+  stream it is already reading — no second connection, no cost beyond
+  adding up chunk lengths. It compares the bytes arriving against what
+  the device's own reported rate needs and, if the path is short, names
+  the requested span, the rate it needs, what was measured, and the
+  widest span that would have fitted. Complementary to `DropDetector`,
+  which says the server *did* drop data after the fact; when both fire
+  the gap warning now says so, rather than reading as a second unrelated
+  fault. Silence is the answer whenever the measurement did not happen:
+  a warning never fires on a failed one.
+- **`StreamFormat::iq_bytes_per_sample`**, the one definition of the
+  constant the whole budget turns on. `calculate_binary_size` now reads
+  it instead of carrying its own copy of the same match.
+
+### Fixed
+- **The passive link-budget check now judges against the rate the device
+  reports, not the rate the caller asked for.** `current_sample_rate`
+  adopts a new rate only past a 10% hysteresis band (deliberately, to
+  keep the tuning target stable), so the check compared against a
+  *requested* rate the device merely came close to — under the builder's
+  own 1 MS/s default (served by the 0.96 MS/s rung, a 4% gap against a
+  2% tolerance) it warned "this path cannot carry the configured span"
+  on every healthy start. The device-reported rate is now tracked
+  separately, without hysteresis; no rate reported means no verdict. An
+  external mid-measurement retune (RTSA GUI/API, no stream restart)
+  restarts the meter, so mixed-rate bytes are never judged against one
+  rate's requirement.
+- **The passive meter counts decoded IQ payload, once per sweep,
+  instead of raw chunk bytes per chunk.** Per-chunk counting stamped a
+  whole drained batch at one instant, so the first post-settle sweep
+  counted the queued connect backlog at zero elapsed width — inflating
+  the measurement in exactly the case the settle window exists for, and
+  enough to wave through a genuinely short path. Raw bytes also counted
+  JSON headers and any spectra/histogram packets sharing the stream,
+  which under-warned on mixed missions. One payload observation per
+  sweep discards the backlog sweep whole (it becomes the meter's mark)
+  and compares like against like.
+- **A stall no longer dilutes the measurement, and the window's close is
+  exclusive.** The counting window used to run to whenever the next
+  observation happened to arrive, so an 8 s consumer stall averaged dead
+  time into the "sustained" rate and produced a spurious shortfall
+  warning; the observation that crosses the boundary is now excluded in
+  both directions. `ThroughputMeter::finish` also refuses to answer
+  before the window closes, instead of leaving that check as a
+  convention each caller must remember, and the reported settle interval
+  is the one actually discarded rather than the one configured.
+- **A configuration restart re-arms the check; a verdict survives
+  reconnects.** The `restart_pending` retune path never reset the
+  check's once-per-source flags, so a widened span was never measured
+  (the case the check exists for) and gap warnings kept citing a stale
+  verdict about a span no longer configured. The check's state is now a
+  single `LinkCheck` enum — unmeasured / measuring / done — reset to
+  unmeasured on configuration restarts only. A parse error in the sweep
+  that closes the window no longer discards the finished measurement
+  either: the verdict is reported before the error propagates into the
+  reconnect path.
+- **The shortfall remedy is computed from the device's own ladder and
+  format.** The "widest span that fits" now halves down from the
+  device-reported rate, so it is a rung the device actually has —
+  inverting through the default-clock ladder named wrong rungs for a
+  full V6 on a faster receiver clock — and the no-rung-fits fallback
+  computes its figures from the stream format instead of hardcoding
+  int16's "120 kS/s, 0.5 MB/s", which was self-contradictory for
+  float32. Float32 streams are also told that int16 would halve the
+  requirement.
+- **The probe validates its window and probes the capture's stream.**
+  `measure_link_throughput` refuses windows under a new
+  `MIN_PROBE_WINDOW` (100 ms): two adjacent socket-buffer reads
+  microseconds apart would otherwise "measure" gigabytes a second over
+  a link that cannot sustain one. `measure_link_throughput_with` now
+  takes the capture's `StreamParams` (format *and* input,
+  rate-reduction, scale — it used to probe the server's default input
+  at full rate whatever the capture would open) plus an explicit settle
+  window for servers whose connect backlog outlasts the default, and
+  its header sniff parses packet headers only — skipping degenerate
+  zero-rate status headers, logging when it gives up — instead of
+  running the full sample decoder on payloads it then threw away.
+- **Rate tracking and the meter listen only to IQ packets.** A
+  spectra/histogram header carries no `sampleFrequency`, so the parser
+  derives a *frame* rate orders of magnitude below the IQ rate; on a
+  mixed mission that ping-ponged the device-rate tracker (restarting the
+  check on every interleaved packet, so it never finished) and handed it
+  a nonsense yardstick. The meter also counted those packets' scalars at
+  IQ byte width — half their wire cost — inflating the measured rate.
+  Both trackers and the byte count now key on the packet's payload type,
+  and a sweep that decodes no IQ does not observe at all. The probe's
+  header sniff follows the same rule: `stream_sample_rate` is read from
+  an IQ header, never from a spectra frame rate that happened to come
+  first.
+- **A failed measurement re-arms the check instead of retiring it.** A
+  window that closed without a usable count, or before the device ever
+  reported a rate, used to become "checked, no verdict" — permanently,
+  on no evidence, so the configuration streamed unjudged forever. It now
+  starts a fresh window, reserving the no-verdict terminal state for
+  configurations that genuinely cannot be measured. A device retune
+  arriving *after* the verdict re-arms too (the verdict described the
+  old rate's budget), and `ThroughputMeter::finish` refuses a window
+  that actually observed less than half its configured span — a couple
+  of packets plus a stray late closing observation say nothing about
+  what the path sustains.
+- **`rate_reduction(0)` is rejected at the boundary.** Both builders
+  accepted it and sent `?rate_reduction=0` to the server, while the
+  link check's measurable gate read `n <= 1` as "no decimation" and
+  computed a full-rate requirement against a wire the server was
+  decimating by whatever it made of zero. `HttpSourceBuilder::build`,
+  `HttpEndpointsClient::start_stream` and the probe now refuse it with
+  `Error::Config` (new `StreamParams::validate`), and the gate accepts
+  exactly 1.
+- **The shared client builder no longer forces HTTP/1.1.** The
+  consolidation carried the endpoints client's `.http1_only()` (which
+  the probe had copied) into `rtsa_client_builder`, where it also
+  pinned `HttpSource`'s streaming client — which had never had it, and
+  streamed through TLS-terminating proxies whose ALPN offers only h2.
+  Over plain `http://` reqwest speaks HTTP/1.1 regardless, so the pin
+  protected nothing there; over `https://` ALPN now negotiates for
+  every client, control plane included, with HTTP/2's adaptive
+  flow-control window enabled so a negotiated h2 stream is not capped
+  at hyper's default 2 MiB window per round trip — a ceiling the link
+  check would otherwise measure and blame on the path.
+- **One framing implementation, shared by the parser and the probe's
+  header sniff.** The probe's rate sniff re-scanned its whole
+  accumulation on every chunk and resynced a failed header parse past
+  the separator where the stream parser resyncs one byte past the `{`
+  — binary payloads contain separator bytes, so the two could disagree
+  about which header speaks first. `StreamParser` and the sniff now
+  frame packets through the same `scan_packet_header`, which finds each
+  region's terminator once rather than once per `{` candidate (the old
+  loop was quadratic in brace-dense garbage: 256 KiB of `{` took 20 s
+  of a tokio worker), honours the hardware-verified LF+RS two-byte
+  separator, and reports rejected candidates so the parser's
+  `parse_errors` counter is unchanged. The sniff drops bytes as they
+  are ruled out and retains at most one candidate awaiting its
+  terminator.
+- **An HTTP source starts again after `stop_streaming`.** The reader
+  task is spawned at construction and stopping it left nothing to
+  restart, so a SoapySDR deactivate/activate cycle (and seify's
+  `deactivate_at`/`activate_at`) failed with "HTTP streaming not
+  properly initialized". `start_streaming` now reconnects.
+- **A packet whose body cannot be decoded no longer wedges the stream.**
+  The parser returned the error but left the packet in its buffer, so
+  every later chunk failed on the same bytes while the buffer grew
+  without bound. The packet is now skipped. `HttpSource` also resets the
+  parser and the drop detector on every reconnect, so a retune no longer
+  decodes the new connection's first bytes as the old packet's payload.
+- **`read_samples` returns a partial block on timeout instead of losing
+  it.** Samples already moved into the caller's buffer went out with the
+  error, an unflagged gap through the C and Python APIs.
+- **`IqPacket.sample_rate_hz` reports the rate the device streams.** The
+  `sdr-source` adapter captured the requested rate before the first
+  packet and never looked again, so a rate the device snapped to another
+  ladder rung was mis-stamped for the whole session.
+- **RTSA files: `mSampleSize` counts values per sample, not bytes.** The
+  captures under `tests/` carry 2 for float32 IQ and 1024 for spectra.
+  Seeking within a chunk used it as a byte stride, so a second partial
+  read of a chunk landed mid-sample, and a spectra read returned one
+  scalar per spectrum. Both now use the sample type's width.
+- **The native SDK is shut down by the last client, not the first.**
+  `AARTSAAPI_Shutdown` is process-wide, but each source and sink called
+  it from its own `Drop`, so re-initialising a source, or pairing a
+  source with a sink, tore the SDK down under the survivor.
+- **A bare `spectranv6eco` opens `spectranv6eco/rtsa`.** The ECO has no
+  `/raw` mode; `SdkConfig` appended one anyway. SDKSPEC's mode list said
+  the same and now agrees with its own V6-vs-ECO table.
+- **Clippy passes on Rust 1.98.** The new `chunks_exact_to_as_chunks`
+  lint failed the workspace check at eight decode sites.
+- **The remote-config licence probe can report `Active`.** It looked for
+  a bare `reflevel` under a group named `main`; a V6 exposes `reflevel0`
+  in its receiver block, so the probe always answered `NotLicensed`. It
+  now writes the discovered block, as the retune path does.
+- **`HttpSource` built outside a Tokio runtime errors at build.** It used
+  to panic inside `init()` when it spawned its reader.
+- **`HttpSink` with `buffer_size(0)` no longer spins forever**; the size
+  is clamped to one.
+- **A quiet dwell in hop mode is an empty read**, not a read error
+  counted toward the source-dead bailout.
+- **The first packet after a failed initial connection is not flagged as
+  an overrun**; nothing was lost.
+- **seify: `sample_rate()` reports the observed rate**, and the range
+  starts at the ladder's 120 kS/s floor instead of 10 kHz.
+- **C API: `aaronia_get_error_message` takes an `int`** and answers
+  unknown codes, where an out-of-range enum was undefined behaviour. C
+  callers are unaffected (an enum converts to `int`); a Rust caller of
+  the `ffi` module's function passes `code as i32`.
+- **Native SDK:** `aaronia_source_read_samples_timeout` honours its
+  deadline (it polled for up to 500 ms regardless); spectra reads honour
+  the packet stride; an SDK call that returns no object is an error
+  rather than a null pointer; opening a second device on a live source
+  is refused; the device is closed on drop.
+- **RTSA files:** a negative DSFT stream offset no longer overflows the
+  header search, and `seek_to_sample` works on reverse-order files.
+- **Spectrum decompression caps the output size** taken from packet
+  metadata.
+
+### Performance
+- The stream parser drops an over-cap payload as it arrives instead of
+  buffering it; uncompressed spectra packets decode without a copy;
+  spectra file reads decode in place; the C API reserves the caller's
+  length before a read; `sample_rate_hz` is an atomic load, so stamping
+  it on every packet takes no lock.
+
+### Changed
+- **Byte-rate helpers answer `Option<f64>`, never a `0.0` sentinel.**
+  `required_byte_rate`, `max_sustainable_span` and friends returned
+  `0.0` for "unknown / nothing fits", a convention every comparison site
+  had to remember — `required <= measured` on a garbage rate reads
+  "fits". `None` now makes the compiler enforce it, and
+  `StreamFormat::iq_bytes_per_sample` returns `Option<usize>` (`None`
+  for JSON) for the same reason. New `max_sustainable_sample_rate_below`
+  answers remedy queries anchored to the device's reported rate.
+- **The link-budget verdict is data, not just a log line.** New
+  `LinkBudgetVerdict` (measured rate, requirement, fit span, shortness)
+  is published as `StreamStats::link_budget`, so a GUI or orchestrator
+  can auto-narrow the span without scraping logs; the stream-gap warning
+  restates the verdict's actual figures from it. `StreamFormat` gained
+  `CAPTURE_DEFAULT`, the one definition behind `HttpSourceBuilder`'s
+  default, `StreamStats::default` and `DEFAULT_LINK_FORMAT`, which were
+  three separately written `Int16` literals.
+- **One copy each of the RTSA client plumbing.** The probe re-used
+  hand-rolled copies of the endpoints client's construction, auth
+  application, base-URL validation, `/stream` query serialization and
+  status-to-error mapping — five drift risks (the three reqwest clients
+  had already drifted to three different setting subsets). All are
+  shared now: `AuthMethod::apply_to` owns the `RToken` header,
+  `rtsa_client_builder` owns the client settings (the streaming client
+  gains the keepalive/nodelay/HTTP-1.1 compatibility settings the
+  endpoints client always had), and `StreamParams::stream_url`
+  serializes every `/stream` URL, including `HttpSource`'s.
+- **`LinkBudgetVerdict::judge` is the verdict's one producer.**
+  Requirement, shortness-against-tolerance and the remedy rung were
+  assembled by hand at each caller; the constructor now owns that
+  arithmetic (so the struct's invariants — fit fields populated only on
+  a shortfall, span matching the fit rate — hold by construction), the
+  verdict carries `bytes_per_sample` for report text, and
+  `ThroughputMeasurement::max_sustainable_span_hz` takes the stream
+  format instead of silently assuming int16. The no-rung-fits warning
+  cites the device ladder's actual last rung rather than a hardcoded
+  1/512.
+- **`HttpSource`'s stream-open failure is the typed error the rest of
+  the crate returns.** A non-success status on `/stream` is now
+  `Error::Http { status, context }` — the same variant the endpoints
+  client and the probe produce, with `context` naming the stream URL —
+  instead of `Error::Protocol("Stream endpoint returned error: …")`.
+  Anything matching on that text will need the new form.
+- **`work()`'s output copy is two bulk `copy_from_slice` calls** over the
+  deque's contiguous halves instead of a `pop_front` per sample, whose
+  per-element wrap-around check the compiler cannot lift. Factored into
+  `copy_out` and unit-tested, including the wrapped-deque case.
+
+### Documentation
+- **Measured the HTTP transport on WiFi 7 and recorded where the
+  ceiling actually is.** `curl` on `/stream` sustains ~75 MB/s
+  (0.6 Gbit/s) station-to-station at a 2.4 Gbps PHY — both ends on air
+  halves the medium — and the figure is the same for all three wire
+  formats, so the encoding is not the limit. Two parallel connections
+  measured less in aggregate (63.9 vs 74 MB/s), so a single connection
+  is optimal and nothing smarter is available to the client. Against
+  that, the crate's full framing-plus-decode path measures ~3 GB/s and
+  the individual decoders 0.8–10 GS/s: the parser has fortyfold
+  headroom and is never the bottleneck. What the link buys at 4 bytes a
+  sample is ~19 MS/s — the 15.36 MS/s rung fits, 30.72 does not, and
+  full span (246 MB/s) needs a wired path to the RTSA host. Two ignored
+  throughput-meter tests (`decode_throughput_meter`,
+  `framing_throughput_meter`) keep these numbers re-measurable in one
+  command.
+- README and PLUGINS pinned `sdr-aaronia-rs = "0.6"`, a major behind
+  the crate, so nothing they describe resolved. Now `"0.7"`.
+- `cumulative_drops` counts client-detected timestamp gaps; four docs
+  called them server-reported drops. Bandwidth figures now use the
+  61.44 MS/s top rate rather than the 92 MHz clock. The examples table
+  and the QUICKSTART verification link were corrected.
+
 ## [v0.7.6] - 2026-08-15
 
 All of this is about the FutureSDR `HttpSource` block (the `futuresdr`

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/CONTRIBUTING.md

@@ -120,7 +120,7 @@ open target/llvm-cov/html/index.html   # xdg-open on Linux, start on Windows
 
 ### 7. Criterion Benchmarks (`benches/`)
 
-Three benchmark harnesses track the hot paths across releases. Benchmarks are run on demand to investigate performance implications of a PR.
+Four benchmark harnesses track the hot paths across releases. Benchmarks are run on demand to investigate performance implications of a PR.
 
 ```bash
 cargo bench                                       # Run all benchmarks

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/Cargo.lock

@@ -1275,7 +1275,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -1669,9 +1669,9 @@ dependencies = [
 
 [[package]]
 name = "h2"
-version = "0.4.15"
+version = "0.4.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6cb093c84e8bd9b188d4c4a8cb6579fc016968d14c99882163cd3ff402a4f155"
+checksum = "ef8e5e5a340588f4452631496976cf8636d4a7ecf600239fdc27615d2530bc16"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -2041,7 +2041,7 @@ checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
 dependencies = [
  "hermit-abi",
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -3027,7 +3027,7 @@ dependencies = [
 
 [[package]]
 name = "python-aaronia"
-version = "0.7.6"
+version = "0.7.7"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3098,7 +3098,7 @@ dependencies = [
  "once_cell",
  "socket2",
  "tracing",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -3404,7 +3404,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -3461,7 +3461,7 @@ dependencies = [
  "security-framework",
  "security-framework-sys",
  "webpki-root-certs",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -3556,7 +3556,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.7.6"
+version = "0.7.7"
 dependencies = [
  "anyhow",
  "bitflags 2.13.1",
@@ -4135,7 +4135,7 @@ dependencies = [
  "getrandom 0.4.3",
  "once_cell",
  "rustix",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -4792,7 +4792,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/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.7.6"
+version = "0.7.7"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.7.6
+Version: 0.7.7
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -211,7 +211,7 @@ silently defaulting.
 | `read_samples_arrow(count)` | PyArrow `FixedSizeListArray` of `[re, im]` float32 pairs |
 | `read_samples_dual_numpy(count)` | `(rx1, rx2)` NumPy arrays (dual-channel captures) |
 | `set_center_frequency(hz)` / `set_sample_rate(hz)` / `set_reference_level(dbm)` | Live retuning |
-| `cumulative_drops()` | Total server-reported dropped samples |
+| `cumulative_drops()` | Timestamp gaps detected in the stream so far (gap events, not samples) |
 | `take_overrun()` | True once per detected receive-side overrun |
 | `last_timestamp_ns()` | Epoch-ns timestamp of the last received block (HTTP backend; 0 otherwise) |
 

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/PLUGINS.md

@@ -12,7 +12,7 @@ To use the Seify plugin, enable the `seify` feature in your `Cargo.toml`:
 
 ```toml
 [dependencies]
-sdr-aaronia-rs = { version = "0.6", features = ["seify"] }
+sdr-aaronia-rs = { version = "0.7", features = ["seify"] }
 ```
 
 Instantiate the device with `AaroniaSeifyDevice::from_args` and use it directly (or via `seify::dev::DynDeviceBackend`). The backend is **not** part of seify's built-in enumeration registry — `seify::enumerate()` will not discover it.
@@ -136,11 +136,11 @@ Both the native Rust API and the Python/C++ bindings expose critical metrics to
 
 - **Hardware Timestamps**: You can retrieve the precise hardware timestamp (in nanoseconds) of the last received block using `last_timestamp_ns`.
 - **Overruns**: The `take_overrun()` function checks if the internal buffer has overflown since the last check, allowing you to react to drops on the client side.
-- **Cumulative Drops**: The `cumulative_drops()` function reports the total number of blocks dropped by the Aaronia server itself due to network backpressure.
+- **Cumulative Drops**: `cumulative_drops()` counts the timestamp gaps the client's drop detector has seen in the stream. Each is one gap event, however many samples it spanned.
 
 In SoapySDR, you can access these metrics via the `readSensor()` API:
 ```python
-# Check for server-side drops
+# Check for gaps in the stream
 drops = sdr.readSensor("cumulative_drops")
-print(f"Dropped blocks: {drops}")
+print(f"Gaps seen: {drops}")
 ```

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/README.md

@@ -36,6 +36,9 @@ selects a backend and presents the same interface either way.
   input enumeration and the configuration tree.
 - **Plugs into FutureSDR** with `HttpSource` and `HttpSink` flowgraph
   blocks.
+- **Says whether the link can carry the span** before a capture is
+  wasted: `link_budget` measures the path end to end and names the
+  widest span on the device's decimation ladder that fits it.
 
 ## Installation
 
@@ -44,11 +47,11 @@ Add the following to your `Cargo.toml`:
 ```toml
 [dependencies]
 # By default, includes HTTP, File, native sdr-source trait, and C FFI backend support
-sdr-aaronia-rs = "0.6"
+sdr-aaronia-rs = "0.7"
 tokio = { version = "1.43", features = ["rt-multi-thread", "macros"] }
 
 # To enable additional backends, opt into their features (e.g. native-sdk, futuresdr)
-# sdr-aaronia-rs = { version = "0.6", features = ["native-sdk", "futuresdr"] }
+# sdr-aaronia-rs = { version = "0.7", features = ["native-sdk", "futuresdr"] }
 ```
 
 ## Quickstart

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/docs/APPS.md

@@ -114,7 +114,7 @@ directly and skip the SoapySDR layer.
 - `readStream` honours `timeoutUs` and returns partial reads within the
   deadline, per the SoapySDR contract.
 - Retuning mid-stream is safe and requires no Aaronia licence.
-- Dropped blocks are reported through `readSensor("cumulative_drops")`.
+- Gaps detected in the stream are counted by `readSensor("cumulative_drops")`.
   An overrun sets `SOAPY_SDR_END_ABRUPT` on the affected read.
 - TX is hardware-unverified and exists only when the plugin is built
   against the native SDK on Windows or Linux.

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/docs/FILESPEC.md

@@ -375,7 +375,7 @@ Contains the actual measurement data.
 | `mPacketStartTime` | `double` | Start time of this chunk relative to stream start. |
 | `mPacketEndTime` | `double` | End time of this chunk relative to stream start. |
 | `mPacketFlags` | `quint32` | Packet flags (`DSPPF_*`). |
-| `mSampleSize` | `quint32` | Size of an individual sample. This crate treats it as the byte stride of one sample when seeking within IQ payloads (8 for float32 IQ); for spectra the vendor dump annotates it as the bin count — the two interpretations have not been reconciled against vendor documentation. |
+| `mSampleSize` | `quint32` | Values per sample, not bytes: 2 for an IQ pair, the bin count for a spectrum. The captures under `tests/` carry 2 (float32 IQ) and 1024 (spectra), the same meaning as the HTTP stream's `sampleSize`. The byte stride of a sample is this count times the width of `mSampleType`. |
 | `mSampleDepth` | `quint32` | Depth of a sample. |
 | `mNumSamples` | `quint32` | Number of samples in this packet. |
 | **Payload** | `binary` | The payload contains the actual sample data, formatted as specified by the header fields. |

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/docs/QUICKSTART.md

@@ -200,14 +200,16 @@ instead of issuing PUTs directly. No Aaronia licence is involved: the
 crate tunes through `/control`, which needs none.
 
 **Network saturation at high sample rates.**
-Float32 requires roughly 740 MB/s at 92 MSPS. On anything other than
+Float32 needs roughly 490 MB/s at the 61.44 MS/s top rate. On anything other than
 localhost, use the `I16` wire format via
 `AaroniaConfig::low_bandwidth_mode()` or the `format=I16` SoapySDR
 device argument to halve that. This changes the wire format itself,
 unlike a client-side `CS16` conversion.
 
 **Dropped samples.**
-`cumulative_drops()` and `take_overrun()` report server-side gaps.
+`cumulative_drops()` counts the timestamp gaps the client has detected
+in the stream (one per gap, however many samples it spanned), and
+`take_overrun()` flags the read that follows one.
 Steady growth means the link or the consumer cannot keep pace. Reduce
 the sample rate, switch to `I16`, or read in larger blocks.
 
@@ -231,5 +233,5 @@ let mut source = AaroniaSource::new(config).await?;
 
 Build with `--features native-sdk`. Aaronia does not ship a macOS SDK,
 so this path is unavailable there. The native-SDK paths are
-hardware-unverified in this project; see the verification table in the
-[README](../README.md).
+hardware-unverified in this project; see the verification table in
+[VERIFICATION.md](VERIFICATION.md).

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/docs/SDKSPEC.md

@@ -49,7 +49,7 @@ The Aaronia RTSA Vendor SDK provides low-level, high-performance access to Aaron
 *   **Real-time Data Access**: Packet-based streaming of IQ samples and spectrum data with configurable decimation
 *   **Device Modes**: Verified support for multiple operational modes:
     *   **SpectranV6**: `spectranv6/raw`, `spectranv6/iqreceiver`, `spectranv6/iqtransceiver`, `spectranv6/iqtransmitter`, `spectranv6/sweepsa`
-    *   **SpectranV6 ECO**: `spectranv6eco/raw`, `spectranv6eco/iqreceiver`, `spectranv6eco/iqtransceiver`, `spectranv6eco/iqtransmitter`, `spectranv6eco/sweepsa`
+    *   **SpectranV6 ECO**: `spectranv6eco/rtsa` (its raw pipeline; there is no `spectranv6eco/raw`), `spectranv6eco/iqreceiver`, `spectranv6eco/iqtransceiver`, `spectranv6eco/iqtransmitter`, `spectranv6eco/sweepsa`
 *   **Configuration Tree**: Hierarchical configuration system with verified parameters:
     *   **Clock Rates** (V6): 46MHz (46.08), 61MHz (61.44), 76MHz (76.80), 92MHz (92.16), 122MHz (122.88), 184MHz (184.32), 245MHz (245.76), 492MHz (491.52) — see the full label table under [Rust Binding Notes](#rust-binding-notes)
     *   **Clock Rates** (V6 ECO): fixed at 92.16 MHz. Its top IQ rate is 61.44 MHz, which is that clock over 1.5 — the two are easy to confuse and this document once recorded the rate as the clock

{python_aaronia-0.7.6 → python_aaronia-0.7.7}/docs/USAGE.md

@@ -99,18 +99,83 @@ When using the HTTP backend over a network link, the wire format heavily impacts
 use sdr_aaronia_rs::AaroniaConfig;
 
 // Default (Float32): 8 bytes/sample on the wire. Lossless, zero-copy decode.
-// At 92 MSPS, requires ~740 MB/s network throughput (best for localhost).
+// At the 61.44 MS/s top rate that is ~490 MB/s (best for localhost).
 let _high_fidelity = AaroniaConfig::default()
     .center_frequency(2.4e9);
 
 // Low Bandwidth (Int16): 4 bytes/sample. Halves network traffic.
 // Requires setting both the format and the encode scale factor.
-// At 92 MSPS, requires ~370 MB/s.
+// At 61.44 MS/s, ~246 MB/s.
 let _low_bandwidth = AaroniaConfig::default()
     .center_frequency(2.4e9)
     .low_bandwidth_mode(); // Sets StreamFormat::Int16 and scale=32767.0
 ```
 
+### Will the link carry it?
+
+The span picks a sample rate off the device's decimation ladder, and at
+4 bytes a sample (Int16/Float16) that rate is a byte rate the whole path
+has to sustain. Measured on a SPECTRAN V6 ECO over gigabit: `--span 10M`
+(15.36 MS/s, 61.4 MB/s) came back contiguous, while `--span 20M`
+(30.72 MS/s, 122.9 MB/s) lost 1.84 s of a 35 s capture — dropped by the
+*server*, upstream of the client, and each gap is a discontinuity that
+breaks digital symbol timing.
+
+`link_budget` answers the question before the capture rather than after:
+
+```rust
+use sdr_aaronia_rs::link_budget::{max_sustainable_span, required_byte_rate};
+
+// What a span costs, via the ladder.
+let rate = sdr_aaronia_rs::iq_sample_rate_for_bandwidth(10e6);       // 15.36 MS/s
+assert_eq!(required_byte_rate(rate), Some(61_440_000.0));            // 61.4 MB/s
+
+// What a measured path affords, as a span you can pass to --span.
+// `None` would mean no rung fits (or no budget can be computed at all,
+// e.g. for the JSON format) — never a 0.0 a comparison could wave through.
+assert_eq!(max_sustainable_span(75_000_000.0), Some(12_288_000.0));  // 12.288 MHz
+```
+
+To measure the path rather than assume it, stream from the server and
+count bytes off the socket. The probe discards an initial settle window
+(`LINK_PROBE_SETTLE`, 500 ms) first, because the RTSA server hands over
+its pre-connect backlog faster than real time — count that and the
+answer comes out *above* the true link rate, which is the one error that
+makes a probe worse than none:
+
+```rust,no_run
+# async fn probe() -> sdr_aaronia_rs::Result<()> {
+use std::time::Duration;
+use sdr_aaronia_rs::link_budget::{DEFAULT_LINK_FORMAT, measure_link_throughput};
+
+let m = measure_link_throughput("http://localhost:54664", Duration::from_secs(3)).await?;
+println!("{m}");                                   // rate, window, settle discarded
+println!(
+    "widest span: {:?} Hz",
+    m.max_sustainable_span_hz(DEFAULT_LINK_FORMAT)
+);
+# Ok(())
+# }
+```
+
+`measure_link_throughput_with` additionally takes the capture's
+`StreamParams` — probe with the same format, input and rate reduction
+the capture will use, or the probe measures a different stream — and the
+settle window, for servers whose connect backlog outlasts the default.
+
+It measures what the path *delivered*, which is a floor on what it can
+deliver: point the device at or above the span being planned first, and
+check `ThroughputMeasurement::stream_sample_rate` to confirm the path was
+actually loaded. An unreachable server or an idle mission is an error,
+never a rate — "0 MB/s" would condemn every span on the ladder.
+
+The `HttpSource` block runs the same check passively on the stream it is
+already reading, comparing the delivered IQ payload against the rate the
+device reports in its packet headers, and warns once per configuration,
+naming a narrower span from the device's own ladder that fits. The
+verdict is also published as `StreamStats::link_budget` on the shared
+stats handle, and is re-measured after a configuration restart.
+
 ## Reusable configuration profiles
 
 Build your own configuration for specific bands:
@@ -318,7 +383,7 @@ code you can run. CI builds them, so they stay current:
 | Task | Example |
 | --- | --- |
 | HTTP IQ streaming, first samples | [`http_iq_quickstart.rs`](../examples/http_iq_quickstart.rs) |
-| Health checks, input enumeration, recording control, license probing | [`device_control.rs`](../examples/device_control.rs) |
+| 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) |