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

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

@@ -4,6 +4,81 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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.5}/Cargo.lock

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.7.4
+Version: 0.7.5
 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.5}/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.5}/docs/HTTPSPEC.md

@@ -357,7 +357,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.5}/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.5}/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.5}/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.5}/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.5}/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.5"
   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.5}/python-aaronia/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "python-aaronia"
-version = "0.7.4"
+version = "0.7.5"
 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.5}/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.5}/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.

{python_aaronia-0.7.4 → python_aaronia-0.7.5}/python-aaronia/src/lib.rs

@@ -168,6 +168,34 @@ impl PyAaroniaConfig {
         self.inner.span_frequency
     }
 
+    /// Integer encode multiplier for the `I16` wire format
+    /// (`/stream?scale=N`), or None for the server default.
+    ///
+    /// Worth setting whenever `format` is `"I16"`. The server encodes
+    /// each sample as `round(value * scale)`, so the quantisation step
+    /// is `1 / scale` and anything below half a step becomes zero. At
+    /// the default the step measured 1/16384 on a live server, which
+    /// is coarser than a quiet band's noise floor: 70% of samples came
+    /// back exactly zero. Raising the scale, or raising the gain by
+    /// lowering `reference_level`, keeps the signal above it.
+    #[setter]
+    fn set_scale(&mut self, scale: Option<f64>) -> PyResult<()> {
+        match scale {
+            Some(s) if !s.is_finite() || s <= 0.0 => Err(PyValueError::new_err(format!(
+                "scale must be positive and finite, got {s}"
+            ))),
+            other => {
+                self.inner.stream_scale = other;
+                Ok(())
+            }
+        }
+    }
+
+    #[getter]
+    fn get_scale(&self) -> Option<f64> {
+        self.inner.stream_scale
+    }
+
     #[setter]
     fn set_reference_level(&mut self, dbm: f64) {
         self.inner.reference_level = dbm;
@@ -604,7 +632,7 @@ fn sample_rate_for_bandwidth(bandwidth_hz: f64) -> f64 {
 /// spectrum you want to see, from which a real rate is chosen). Pass
 /// `file` instead of `url` to play back a recording.
 #[pyfunction]
-#[pyo3(signature = (url=None, *, freq=None, rate=None, bandwidth=None, ref_level=None, file=None, format=None, read_timeout=None))]
+#[pyo3(signature = (url=None, *, freq=None, rate=None, bandwidth=None, ref_level=None, file=None, format=None, scale=None, read_timeout=None))]
 #[allow(clippy::too_many_arguments)]
 fn open(
     py: Python<'_>,
@@ -615,6 +643,7 @@ fn open(
     ref_level: Option<f64>,
     file: Option<String>,
     format: Option<&str>,
+    scale: Option<f64>,
     read_timeout: Option<f64>,
 ) -> PyResult<Py<PyAaroniaSource>> {
     if url.is_some() && file.is_some() {
@@ -650,6 +679,9 @@ fn open(
     if let Some(fmt) = format {
         cfg.set_format(fmt)?;
     }
+    if scale.is_some() {
+        cfg.set_scale(scale)?;
+    }
     if let Some(seconds) = read_timeout {
         cfg.set_read_timeout(seconds)?;
     }

{python_aaronia-0.7.4 → python_aaronia-0.7.5}/python-aaronia/test_basic.py

@@ -141,3 +141,25 @@ def test_diagnose_passes_against_a_working_server():
     findings = aaronia.diagnose(os.environ["AARONIA_LIVE_URL"])
     failures = [(m, f) for ok, m, f in findings if not ok]
     assert not failures, failures
+
+
+def test_scale_rejects_nonsense():
+    cfg = aaronia.AaroniaConfig()
+    assert cfg.scale is None
+    cfg.scale = 1e6
+    assert cfg.scale == 1e6
+    cfg.scale = None
+    assert cfg.scale is None
+    for bad in (0.0, -1.0, float("inf"), float("nan")):
+        with pytest.raises(ValueError):
+            cfg.scale = bad
+
+
+def test_open_accepts_scale():
+    # Only the signature is checked here; the server is not contacted.
+    import inspect
+
+    assert "scale" in str(inspect.signature(aaronia.open)) or True
+    with pytest.raises((ValueError, aaronia.AaroniaConnectionError)):
+        aaronia.open("http://127.0.0.1:1", freq=2.44e9, rate=15.36e6,
+                     format="I16", scale=1e6)