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

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

@@ -4,6 +4,166 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.7.6] - 2026-08-15
+
+All of this is about the FutureSDR `HttpSource` block (the `futuresdr`
+feature), whose streaming path turned out to be losing most of the
+stream. Found and measured against a live SPECTRAN V6 ECO running a
+49 MHz survey for a trunking decoder.
+
+### Fixed
+- **The sample buffer guillotined every packet bigger than itself.**
+  The capacity trim runs as each packet lands, and with capacity fixed
+  at `buffer_size * 2` a device sending 49k-sample packets into a
+  16384-sample capacity lost ~75% of every packet before the consumer
+  was offered any of it. Measured live: 61.4 MS/s at the device,
+  0.33 MS/s reaching the pipeline, and digital decode unable to hold
+  frame sync. The capacity now floors at four times the largest packet
+  observed, learned from the stream; the floor only ever raises the
+  configured value.
+- **The initial tune could claim success while the device never
+  moved.** `/control` answers `success=true` whether or not any block
+  applies the command — the same device has been measured both
+  honouring and ignoring the identical full-tuple payload in different
+  mission states. The block's start-up tune now writes the real field
+  names (`centerfreq0`, `decimation0`, `reflevel0`) via `/remoteconfig`
+  to the block discovered by walking the config tree, then reads them
+  back and warns about anything that did not take. Where no such block
+  exists (an IQ-demodulator mission exposes different fields), it falls
+  back to the old `/control` capture command and says the result is
+  unverified. The tune is one-shot: stream restarts after an external
+  retune no longer re-push the source's stale target over it.
+- **Launching an app no longer overwrites the operator's gain.** The
+  builder's reference level was a bare number pushed on every start, so
+  merely starting a flowgraph reset the device to the builder default.
+  It is now optional and left untouched unless the caller set one.
+- **`work()` spun.** The runtime ran it whenever the output port had
+  any room — measured at 106,000–390,000 calls a second averaging 14
+  free samples each — burning ~60% of a core and starving the
+  downstream block. The output port now requires a worthwhile block of
+  room before `work()` runs; call rate dropped to ~14/s.
+
+### Changed
+- **The HTTP socket is drained by a dedicated task**, not inside
+  `work()`. The socket used to be read only while the scheduler happened
+  to run the block, which capped throughput at a tenth of what `curl`
+  pulls from the same endpoint. A background task now pushes chunks
+  into a bounded channel (~10 MB), whose fill is the backpressure point:
+  consumer falls behind → channel fills → reader blocks → TCP flow
+  control stops the server. Measured at a 49 MHz span: 1.8 → ~7–9 MS/s.
+  The honest ceiling is the link (~57 MB/s ≈ 14 MS/s as float32);
+  61.44 MS/s over this transport is 2 Gbit/s and not reachable.
+- Buffer-overflow drops are now counted and logged geometrically
+  rather than once per occurrence, which at wide span was 5040 log
+  lines in 25 seconds for one piece of information.
+- File playback decodes little-endian cf32 with a zero-copy read
+  straight into the sample buffer; the explicit per-sample decode
+  remains for big-endian hosts, and a round-trip test pins the two to
+  identical output.
+
+### Fixed (in review, before this release shipped)
+- The refill loop kept iterating through its 50 ms idle sleeps when the
+  channel was empty, holding samples already in the buffer for up to
+  800 ms before producing them. It now flushes immediately and sleeps
+  only when there is nothing to flush.
+- A parse error mid-stream reconnected without reaping the reader task,
+  which on a stalled socket keeps holding a server connection — on the
+  free licence, the one connection the reconnect needs.
+- Two comments overstated the `/control` finding as "this endpoint does
+  not carry these fields on a Spectran V6". Measured today, the same
+  device honours the identical full-tuple payload — the accurate claim
+  is that `success=true` proves nothing either way, which is the reason
+  the verified `/remoteconfig` path exists. Where no `centerfreq0`
+  block is found, the initial tune now falls back to `/control` rather
+  than silently not tuning (an IQ-demodulator mission exposes
+  `centerfreq`, not `centerfreq0`).
+
+### Added
+- `iq_sample_rate_for_decimation_index`, `decimation_index_for_rate`
+  and `decimation_index_for_bandwidth` in `utils`: the RTSA "Span"
+  enum (`Full` … `1 / 512`) mapped onto the sample-rate ladder and
+  back, so a requested span becomes the enum index the device actually
+  takes.
+- `HttpEndpointsClient::apply_capture_config` — retune via
+  `/remoteconfig` with read-back confirmation — plus
+  `find_block_name_with_field`, which discovers the receiver block by
+  the field the write will target instead of assuming its category.
+
+## [v0.7.5] - 2026-08-13
+
+### Added
+- **`scale` on the Python config and `aaronia.open()`**, the integer
+  encode multiplier for the `I16` wire format. Rust, the C API and the
+  SoapySDR plugin all had it; Python did not, so a Python program
+  choosing `I16` for bandwidth had no way out of the trap below.
+- **`scripts/validate-iq-live.py`**, an end-to-end check that the
+  samples an application receives are the ones the device sent, rather
+  than that bytes arrived. Every wire format must decode to the same
+  spectrum, the Python and SoapySDR paths must agree, and a known
+  transmitter must land where it should. Run against a live server it
+  places a NOAA weather-radio carrier within 312 Hz of 162.400 MHz and
+  on the correct side of zero — the one check that catches transposed
+  I and Q, which nothing comparing the radio against itself can see.
+
+### Fixed
+- **`format="I16"` silently discards weak signals at the default
+  scale.** The server sends `round(value * scale)`, so the step is
+  `1 / scale`, and the default of 16384 gives 6.1e-5 — coarser than a
+  quiet band's noise floor. Measured against a live server, **68% of
+  int16 samples came back exactly zero** where float32 had none. At
+  `scale=1e6` the zero fraction was 0.0% and the amplitude matched
+  float32. Documented, with the measurements, in the Python README.
+
+### Changed
+- **The Homebrew formula is no longer a release asset.** It is uploaded
+  as the `homebrew-formula` workflow artifact instead. Homebrew 4 and
+  later cannot install from a formula URL, so on the release page it
+  was a file no user could act on, listed among ones they can. Its only
+  reader is whoever updates the tap, and the checksums are still
+  rendered against the published archives so none are computed by hand.
+
+### Documentation
+- **Wire format is a throughput decision, and the default is the
+  expensive one.** At 15.36 MS/s over a LAN, float32 needs 123 MB/s:
+  measured, it delivered 6.5 MS/s with 290 drops, while float16 and
+  int16 both delivered 15.1 MS/s. The Python README now carries the
+  numbers rather than a general warning.
+- **Measured what the 80% usable-bandwidth figure actually is, and
+  explained it in one sentence.** Sample rate and RF bandwidth were
+  described as related by a ratio without saying what the ratio was or
+  where it came from. RTSA declares exactly 0.8 x Fs as the packet's
+  frequency range at every rate — a fixed rule, checked at 61.44,
+  15.36, 7.68 and 3.84 MHz — and every sample still arrives, so an FFT
+  spans the whole rate while only that 80% is flat and calibrated.
+  Sweeping the receiver's own noise floor on a V6 ECO confirms it: the
+  response is flat within 0.5 dB across 0.80 of the rate at 15.36 MHz
+  sampling and 0.89 at 7.68 MHz, and at full span the analog filter is
+  about 1 dB down by the declared edge — which is where Aaronia's
+  44 MHz data-sheet figure comes from, against the 49.152 MHz the
+  device itself declares. The guidance readers need is one line: to see
+  N Hz of spectrum, sample at N / 0.8.
+- **The READMEs stated the V6 ECO's sample-rate ladder as if it were
+  every device's.** "The device runs a fixed ladder of rates: 61.44 MHz
+  halved down to 120 kHz" is measured and true for an ECO, but a full
+  V6 selects its receiver clock and starts higher — by how much is the
+  open question the specs already record, and the user-facing pages did
+  not carry it. The Python, SoapySDR, quickstart and applications docs
+  now say whose ladder it is and point at the note, and
+  `iq_sample_rates` says so in its own documentation.
+- The SoapySDR README gained a Sample rates section: why
+  `listSampleRates` reports the real ladder, that `setSampleRate` snaps
+  and logs, and that `getSampleRate` while streaming is the number to
+  trust on hardware the advertised ladder does not describe.
+- SDKSPEC still gave the eco family's clock as 61.44 MHz in a second
+  place, contradicting the correction made elsewhere in the same
+  document. It is 92.16 MHz; 61.44 MHz is the top IQ rate.
+- The same sweep caught the claim in `unified_source`'s own
+  documentation, in the `/control` span note in HTTPSPEC, and in the
+  0.8 usable-bandwidth ratio, all of which read as universal and are
+  measurements from one device. `seify_impl`'s sample-rate range is
+  capped at 61.44 MHz for the same reason and now says so: seify has no
+  device handle at that point to ask for something better.
+
 ## [v0.7.4] - 2026-08-12
 
 ### Fixed

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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.7.4
+Version: 0.7.6
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -88,17 +88,66 @@ above depends on.
 
 ## Sample rates
 
-The device runs a fixed ladder of rates: 61.44 MHz halved down to
-120 kHz. Ask for anything else and it quietly uses the nearest rung,
-leaving your program computing against a rate that is not in use.
+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.
 
 ```python
 aaronia.sample_rates()                  # every rate, highest first
 aaronia.sample_rate_for_bandwidth(8e6)  # 15.36e6: the lowest rate covering 8 MHz
 ```
 
-A rate carries only 80% of itself as alias-free bandwidth, which is why
-8 MHz of spectrum needs 15.36 MHz of sampling.
+**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 quotes a
+more conservative figure still — 44 MHz for the ECO against the
+49.152 MHz it declares at full span — because the analog filter is
+already about 1 dB down at 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 ladder for a SPECTRAN V6 ECO — 61.44 MHz
+down to 120 kHz — which is measured, rung by rung. A full V6 has a
+selectable receiver clock and can go higher, and exactly how much
+higher is not settled; see
+[the note in HTTPSPEC](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/HTTPSPEC.md#unresolved-the-full-v6s-top-rate).
+On that hardware, take the rate the device reports over the computed
+ladder: it arrives in the stream metadata, and `diagnose()` prints it.
+
+## Choosing a wire format
+
+`format` decides what crosses the network, and it matters more than it
+looks. Measured against a live server at 15.36 MS/s over a LAN:
+
+| format | bytes/sample | delivered | drops |
+| --- | --- | --- | --- |
+| `F32` (default) | 8 | 6.5 MS/s | 290 |
+| `F16` | 4 | 15.1 MS/s | 9 |
+| `I16` | 4 | 15.1 MS/s | 12 |
+
+`F32` needs 123 MB/s at that rate and the link could not carry it, so
+most of the capture was dropped. Either half-width format fits.
+
+`I16` has one trap: the server sends `round(value * scale)`, so the
+quantisation step is `1 / scale`, and the default of 16384 gives a step
+of 6.1e-5. A quiet band's noise floor is smaller than that — on the
+same server, **68% of `I16` samples came back exactly zero** while
+`F32` had none. Pass `scale=`, or lower `reference_level` for more
+gain:
+
+```python
+aaronia.open(url, freq=2.44e9, rate=15.36e6, format="I16", scale=1e6)
+```
+
+At `scale=1e6` the zero fraction measured 0.0% and the amplitude
+matched `F32`. `F16` needs no such tuning, which makes it the simpler
+choice when the link is the constraint.
 
 ## Configuration (`AaroniaConfig`)
 
@@ -113,6 +162,7 @@ Every field is readable and writable.
 | `sample_rate` | IQ sample rate, Hz (the Aaronia "span") |
 | `reference_level` | Reference level, dBm |
 | `format` | HTTP wire format: `"F32"`, `"F16"` or `"I16"`. `I16` is the low-bandwidth network mode |
+| `scale` | Integer encode multiplier for `I16` (see below). None uses the server default |
 | `receiver_channel` | `"Rx1"` (default), `"Rx2"`, or `"Rx1And2"` (native SDK, full V6) |
 | `read_timeout` | Seconds a blocking read waits before `AaroniaTimeoutError` (default `30.0`) |
 | `auto_reconnect` | Reconnect the HTTP stream after a drop (default `True`) |
@@ -169,8 +219,8 @@ silently defaulting.
 
 | Function | Purpose |
 | --- | --- |
-| `open(url=None, *, freq, rate, bandwidth, ref_level, file, format, read_timeout)` | Configure, connect and start streaming in one call |
-| `sample_rates()` | Every sample rate the hardware can run |
+| `open(url=None, *, freq, rate, bandwidth, ref_level, file, format, scale, read_timeout)` | Configure, connect and start streaming in one call |
+| `sample_rates()` | The V6 ECO's sample rates, highest first (see [Sample rates](#sample-rates)) |
 | `sample_rate_for_bandwidth(hz)` | Lowest rate covering that much spectrum |
 | `diagnose(url)` | `(ok, message, fix)` for each setup check; what `aaronia-doctor` prints |
 

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

@@ -50,9 +50,12 @@ driver=aaronia,url=http://localhost:54664
 ```
 
 Select the sample rate from GQRX's list. The plugin advertises the
-device's real ladder: 61.44 MHz halved down to 120 kHz, which the RTSA
-GUI labels Full through 1/512. The hardware produces no other rate, so a
-request in between snaps to the nearest rung and logs a warning.
+device's real ladder rather than round numbers it cannot produce: on a
+V6 ECO that is 61.44 MHz halved down to 120 kHz, which the RTSA GUI
+labels Full through 1/512. Nothing in between exists, so a request
+between rungs snaps to the nearest and logs a warning. A full V6 has a
+selectable receiver clock and reaches higher; the plugin advertises the
+ECO ladder, so check the rate the device reports if you are on one.
 
 The single gain element is `REF`, the Aaronia reference level in dBm. It
 is not an amplifier gain: raising it reduces sensitivity. Start near
@@ -101,8 +104,13 @@ directly and skip the SoapySDR layer.
 
 ## General notes
 
-- Sample rate is the Aaronia "span", not the usable RF bandwidth. The
-  alias-free span is smaller, roughly 49 MHz within a 61.44 MHz capture.
+- Sample rate is the Aaronia "span", not the usable RF bandwidth. Every
+  sample reaches the application, so the display spans the full rate,
+  but only the middle 80% is flat and calibrated — RTSA reports exactly
+  0.8 x Fs as the packet's frequency range. Set the rate whose 80%
+  covers the span you want to see: 61.44 MHz of sampling gives roughly
+  49 MHz of calibrated spectrum. The edges are real data, just rolled
+  off.
 - `readStream` honours `timeoutUs` and returns partial reads within the
   deadline, per the SoapySDR contract.
 - Retuning mid-stream is safe and requires no Aaronia licence.

{python_aaronia-0.7.4 → python_aaronia-0.7.6}/docs/HTTPSPEC.md

@@ -302,7 +302,12 @@ from `/remoteconfig` first if you need to target one block.
 
 These are one-off requests. Aaronia's own words: if they cannot be
 executed, or conflict with the local configuration, the behaviour is
-undefined — nothing reports the conflict.
+undefined — nothing reports the conflict. That is not theoretical: the
+same device has been measured both honouring and ignoring an identical
+full-tuple capture command in different mission states, answering
+`success=true` both times. A retune that must be provable goes through
+`/remoteconfig` and reads the value back
+(`HttpEndpointsClient::apply_capture_config` does exactly this).
 
 **The settings each `type` accepts**, per Aaronia support (January
 2024), which goes well beyond the published specification:
@@ -357,7 +362,17 @@ configuration of zones is not supported.
 ```
 
 > **`frequencySpan` is a usable-bandwidth request, not a sample rate.**
-> The device runs at 61.44 MHz divided by a power of two. Given a span
+> The device halves its top rate down a ladder — 61.44 MHz on the V6
+> ECO this was measured against. The usable RF bandwidth it declares in
+> `startFrequency..endFrequency` is exactly 0.8 x Fs at every rate,
+> checked at 61.44, 15.36, 7.68 and 3.84 MHz; every sample still
+> arrives, so an FFT spans the whole rate, but only that 80% is flat
+> and calibrated. Sweeping the receiver's own noise floor puts the real
+> filter at or beyond the declared edge at decimated rates (flat within
+> 0.5 dB across 0.80 x Fs at 15.36 MHz, 0.89 at 7.68 MHz) and just
+> inside it at full span (about 1 dB down at the declared edge, 3 dB at
+> 0.84 x Fs), which is where Aaronia's 44 MHz data-sheet figure for the
+> ECO comes from. Given a span
 > it cannot produce, it selects the rate whose alias-free bandwidth
 > (0.8 x Fs) is nearest the request: 2.5 MHz yields Fs = 3.84 MHz,
 > 1.3 MHz yields 1.92 MHz, and 10 MHz yields 15.36 MHz. A value that is

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

@@ -141,11 +141,41 @@ different:
 | Where you see it | Example | Meaning |
 | --- | --- | --- |
 | `span_frequency`, and `sampleFrequency` in packet metadata | 15.36 MHz | The sample rate, Fs |
-| `startFrequency`..`endFrequency` in packet metadata | 12.288 MHz | Usable alias-free bandwidth, which measures 0.8 x Fs |
-| The Span control in the RTSA GUI | `1 / 4` | Decimation of the 61.44 MHz clock, so Fs = 61.44 / 4 |
-
-The device runs at 61.44 MHz divided by a power of two, ten rates from
-61.44 MHz down to 120 kHz, shown in the GUI as Full through `1 / 512`.
+| `startFrequency`..`endFrequency` in packet metadata | 12.288 MHz | Usable RF bandwidth: exactly 0.8 x Fs, at every rate |
+| The Span control in the RTSA GUI | `1 / 4` | Decimation of the top rate, so Fs = 61.44 / 4 on an ECO |
+
+**You get every sample, but only the middle 80% is calibrated.** An FFT
+of the samples spans the full Fs. RTSA reports 0.8 x Fs as the packet's
+frequency range, at every rate — a fixed rule, not a per-rate
+measurement — and that is the part the anti-alias filter keeps flat and
+the calibration covers. Data outside it still arrives, attenuated and
+uncalibrated.
+
+So **to see N Hz of spectrum, sample at N / 0.8**: 8 MHz of signal needs
+10 MHz of sampling, and the lowest rung providing it is 15.36 MHz.
+`iq_sample_rate_for_bandwidth` does that arithmetic;
+`aaronia.sample_rate_for_bandwidth` is the Python equivalent.
+
+The 80% figure holds up when measured. Averaging the receiver's own
+noise floor on a V6 ECO, the response is flat to within 0.5 dB across
+0.80 x Fs at 15.36 MHz sampling and 0.89 x Fs at 7.68 MHz — at or
+beyond what is declared. At full span it is tighter: the analog filter
+is about 1 dB down by the declared edge and 3 dB down at 0.84 x Fs,
+which is why Aaronia's data sheet quotes 44 MHz of real-time bandwidth
+for the ECO rather than the 49.152 MHz the device declares. Take the
+declared span as the working figure and the data sheet as the
+guaranteed one.
+
+That sweep sees the antenna as well as the receiver, so the full-span
+roll-off is an upper bound on how good the filter is, not a
+measurement of it alone. It is enough to show the declared 80% is
+physically grounded rather than an arbitrary number, which is what the
+figure is used for here.
+
+The device halves its top rate down a ten-rung ladder, shown in the GUI
+as Full through `1 / 512`. On a V6 ECO that is 61.44 MHz down to
+120 kHz, measured rung by rung. A full V6 has a selectable receiver
+clock and starts higher.
 
 **Pass one of those rates and you get it exactly.** Anything else is
 silently adjusted, and not to the nearest rate: the server reads the

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

@@ -275,9 +275,11 @@ actually 92.16 MHz, etc. Use `receiver_clock_for_label` to convert.
 | `245MHz` | 245.76 MHz     | README + ConfigTree |
 | `492MHz` | 491.52 MHz     | ConfigTree          |
 
-The eco family runs at a fixed `61.44 MHz` clock and does not expose the
+The eco family runs at a fixed clock and does not expose the
 `device/receiverclock` config key — `configure_iq_receiver` skips the
-write on that family (see `DeviceOpenMode::EcoIqReceiver`).
+write on that family (see `DeviceOpenMode::EcoIqReceiver`) and uses
+`DEFAULT_RECEIVER_CLOCK_HZ`, 92.16 MHz. Its top IQ rate is 61.44 MHz,
+which is that clock over 1.5; do not confuse the two.
 
 ### `read_samples` polling cadence
 

{python_aaronia-0.7.4 → python_aaronia-0.7.6}/docs/VERIFICATION.md

@@ -25,6 +25,7 @@ SDK are marked unverified.
 | Spectra reads (`read_spectra`) | Native SDK | **Hardware-unverified**. Packet layout and stream index follow Aaronia's `RawSpectrum` sample |
 | Device-family detection (`open_detected_device`) | Native SDK | **Hardware-unverified**. Enumerates each known family in turn |
 | Sample-rate ladder and usable bandwidth | Both | **Live-verified at the default clock** on a V6 ECO, rung by rung. Faster receiver clocks are inferred from the documented constraint, not measured |
+| End-to-end IQ correctness | HTTP | **Live-verified** by `scripts/validate-iq-live.py`: every wire format decodes to the same spectrum, the Python and SoapySDR paths agree, and a NOAA weather-radio carrier lands within 312 Hz of its known frequency on the correct side of zero |
 | GPS hardware time | Native SDK | **Hardware-unverified** |
 | Native SDK capture generally | Native SDK | **Hardware-unverified**; compiled and unit-tested in a Linux VM each release |
 | HTTP TX push (`/sample`) | HTTP | Endpoint exercised live; RF output not measured |

{python_aaronia-0.7.4 → python_aaronia-0.7.6}/packaging/homebrew/README.md

@@ -23,12 +23,19 @@ Homebrew pulls in SoapySDR, drops the module into
 
 ## Each release
 
-The release workflow renders this file against the published archives
-and attaches the result to the release as `soapy-aaronia.rb`, with the
-version and both SHA-256 checksums filled in. Copy that file into the
-tap repository as `Formula/soapy-aaronia.rb` and commit. Nothing needs
+The release workflow renders this file against the published archives,
+with the version and both SHA-256 checksums filled in, and uploads it
+as the **`homebrew-formula` workflow artifact** — not a release asset.
+Download it from the release run's Artifacts section, copy it into the
+tap repository as `Formula/soapy-aaronia.rb`, and commit. Nothing needs
 hashing by hand.
 
+It is deliberately not attached to the release page: Homebrew 4 and
+later cannot install from a formula URL, so there it would be a file no
+user could act on, sitting among ones they can. Once the tap exists,
+the better move is to have the workflow commit to it directly and skip
+this step.
+
 Before pushing, `brew audit --strict --online soapy-aaronia` checks the
 formula, and `brew install --build-from-source` proves it works.
 

{python_aaronia-0.7.4 → python_aaronia-0.7.6}/packaging/homebrew/soapy-aaronia.rb

@@ -12,7 +12,7 @@
 class SoapyAaronia < Formula
   desc "SoapySDR plugin for Aaronia SPECTRAN V6 spectrum analyzers"
   homepage "https://github.com/isaacbentley/sdr-aaronia-rs"
-  version "0.7.4"
+  version "0.7.6"
   license "GPL-3.0-or-later"
 
   # Prebuilt modules: the plugin statically links its Rust core, so there

{python_aaronia-0.7.4 → python_aaronia-0.7.6}/python-aaronia/Cargo.toml

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

{python_aaronia-0.7.4 → python_aaronia-0.7.6}/python-aaronia/README.md

@@ -73,17 +73,66 @@ above depends on.
 
 ## Sample rates
 
-The device runs a fixed ladder of rates: 61.44 MHz halved down to
-120 kHz. Ask for anything else and it quietly uses the nearest rung,
-leaving your program computing against a rate that is not in use.
+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.
 
 ```python
 aaronia.sample_rates()                  # every rate, highest first
 aaronia.sample_rate_for_bandwidth(8e6)  # 15.36e6: the lowest rate covering 8 MHz
 ```
 
-A rate carries only 80% of itself as alias-free bandwidth, which is why
-8 MHz of spectrum needs 15.36 MHz of sampling.
+**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 quotes a
+more conservative figure still — 44 MHz for the ECO against the
+49.152 MHz it declares at full span — because the analog filter is
+already about 1 dB down at 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 ladder for a SPECTRAN V6 ECO — 61.44 MHz
+down to 120 kHz — which is measured, rung by rung. A full V6 has a
+selectable receiver clock and can go higher, and exactly how much
+higher is not settled; see
+[the note in HTTPSPEC](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/HTTPSPEC.md#unresolved-the-full-v6s-top-rate).
+On that hardware, take the rate the device reports over the computed
+ladder: it arrives in the stream metadata, and `diagnose()` prints it.
+
+## Choosing a wire format
+
+`format` decides what crosses the network, and it matters more than it
+looks. Measured against a live server at 15.36 MS/s over a LAN:
+
+| format | bytes/sample | delivered | drops |
+| --- | --- | --- | --- |
+| `F32` (default) | 8 | 6.5 MS/s | 290 |
+| `F16` | 4 | 15.1 MS/s | 9 |
+| `I16` | 4 | 15.1 MS/s | 12 |
+
+`F32` needs 123 MB/s at that rate and the link could not carry it, so
+most of the capture was dropped. Either half-width format fits.
+
+`I16` has one trap: the server sends `round(value * scale)`, so the
+quantisation step is `1 / scale`, and the default of 16384 gives a step
+of 6.1e-5. A quiet band's noise floor is smaller than that — on the
+same server, **68% of `I16` samples came back exactly zero** while
+`F32` had none. Pass `scale=`, or lower `reference_level` for more
+gain:
+
+```python
+aaronia.open(url, freq=2.44e9, rate=15.36e6, format="I16", scale=1e6)
+```
+
+At `scale=1e6` the zero fraction measured 0.0% and the amplitude
+matched `F32`. `F16` needs no such tuning, which makes it the simpler
+choice when the link is the constraint.
 
 ## Configuration (`AaroniaConfig`)
 
@@ -98,6 +147,7 @@ Every field is readable and writable.
 | `sample_rate` | IQ sample rate, Hz (the Aaronia "span") |
 | `reference_level` | Reference level, dBm |
 | `format` | HTTP wire format: `"F32"`, `"F16"` or `"I16"`. `I16` is the low-bandwidth network mode |
+| `scale` | Integer encode multiplier for `I16` (see below). None uses the server default |
 | `receiver_channel` | `"Rx1"` (default), `"Rx2"`, or `"Rx1And2"` (native SDK, full V6) |
 | `read_timeout` | Seconds a blocking read waits before `AaroniaTimeoutError` (default `30.0`) |
 | `auto_reconnect` | Reconnect the HTTP stream after a drop (default `True`) |
@@ -154,7 +204,7 @@ silently defaulting.
 
 | Function | Purpose |
 | --- | --- |
-| `open(url=None, *, freq, rate, bandwidth, ref_level, file, format, read_timeout)` | Configure, connect and start streaming in one call |
-| `sample_rates()` | Every sample rate the hardware can run |
+| `open(url=None, *, freq, rate, bandwidth, ref_level, file, format, scale, read_timeout)` | Configure, connect and start streaming in one call |
+| `sample_rates()` | The V6 ECO's sample rates, highest first (see [Sample rates](#sample-rates)) |
 | `sample_rate_for_bandwidth(hz)` | Lowest rate covering that much spectrum |
 | `diagnose(url)` | `(ok, message, fix)` for each setup check; what `aaronia-doctor` prints |

{python_aaronia-0.7.4 → python_aaronia-0.7.6}/python-aaronia/aaronia.pyi

@@ -65,6 +65,16 @@ class AaroniaConfig:
     """IQ sample rate in Hz (the Aaronia "span")."""
     reference_level: float
     """Reference level in dBm."""
+    scale: Optional[float]
+    """Integer encode multiplier for the ``I16`` wire format
+    (``/stream?scale=N``), or None for the server default.
+
+    The server encodes ``round(value * scale)``, so the quantisation
+    step is ``1 / scale``. At the default the step is 1/16384, which is
+    coarser than a quiet band's noise floor — measured on a live
+    server, 70% of samples came back exactly zero. Raise it, or raise
+    the gain by lowering ``reference_level``. Must be positive and
+    finite."""
 
     # Transport behaviour. `format` and `receiver_channel` read back as
     # None when unset but only accept a string: assigning None raises
@@ -185,6 +195,7 @@ def open(
     ref_level: Optional[float] = None,
     file: Optional[str] = None,
     format: Optional[WireFormat] = None,
+    scale: Optional[float] = None,
     read_timeout: Optional[float] = None,
 ) -> AaroniaSource:
     """Open a source and start streaming, in one call.