python-aaronia

Python bindings for sdr-aaronia-rs. Stream IQ samples from Aaronia SPECTRAN V6 devices, through an RTSA-Suite PRO HTTP server block or the native SDK, or play back recorded .rtsa files, into NumPy or Apache Arrow.

• PyPI package: python-aaronia · importable module: aaronia
• Wheels: abi3, CPython ≥ 3.9, one wheel per OS and architecture, plus an sdist for other platforms. Building from the sdist requires a Rust toolchain.
• License: GPL-3.0-or-later

Install

pip install python-aaronia

From a checkout, which requires Rust and maturin:

cd python-aaronia
maturin develop --release

To reach the Aaronia native SDK as well — a Spectran on this machine's USB, with RTSA-Suite PRO installed, on Windows or Linux — build with the feature; the default wheel speaks only HTTP and files:

maturin develop --release --features native-sdk

Check your setup before writing any code:

aaronia-doctor http://localhost:54664

It reports whether the server is reachable, whether the mission has an input carrying IQ, and what rate the device is running, and names the fix for each failure.

Quickstart

import aaronia

with aaronia.open(
    "http://localhost:54664", center_frequency_hz=2.44e9, bandwidth_hz=10e6
) as src:
    for block in src.blocks(65536):           # numpy complex64 arrays
        process(block)

aaronia.open() connects and starts streaming in one call. bandwidth_hz asks for that much usable spectrum and picks a sample rate the hardware can actually run; pass sample_rate_hz= instead to name one exactly. Use file="capture.rtsa" in place of the URL to play back a recording.

Iterating with blocks() ends when the stream closes. To read on your own schedule, or for Apache Arrow:

src = aaronia.open(center_frequency_hz=2.44e9, sample_rate_hz=15.36e6, format="I16")

sdk=True opens the device through the native SDK instead of a server (serial= picks one of several). It is an error, not a fallback, when the SDK is missing — a capture never quietly comes from another backend:

src = aaronia.open(sdk=True, center_frequency_hz=2.44e9, sample_rate_hz=15.36e6)
src = aaronia.open(sdk=True, serial="C2-P-03000105", center_frequency_hz=2.44e9)
samples = src.read_samples_numpy(65536)       # numpy complex64 array
batch = src.read_samples_arrow(65536)         # pyarrow FixedSizeListArray of [re, im]
src.set_center_frequency_hz(2.41e9)              # live retune, no teardown
print(src.cumulative_drops(), src.take_overrun(), src.last_timestamp_ns())
src.stop_streaming()

For full control, build a SpectranConfig and pass it to SpectranSource.start_streaming(); open() is a shorthand for the common fields.

The quickstart covers configuring the RTSA-Suite HTTP Server block, which everything above depends on.

Sample rates

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.

aaronia.sample_rates()                  # every rate, highest first
aaronia.sample_rate_for_bandwidth(8e6)  # 15.36e6: the lowest rate covering 8 MHz

Sample rate is not RF bandwidth. You get every sample, so an FFT of them spans the full rate — but only the middle 80% is flat and calibrated. That is not an approximation: RTSA reports exactly 0.8 x Fs as the packet's frequency range at every rate. Outside it, data still arrives, attenuated and uncalibrated.

So to see N Hz of spectrum, sample at N / 0.8, which is what sample_rate_for_bandwidth() computes. Aaronia's data sheet is more conservative still — 44 MHz for the ECO against the 49.152 MHz it declares at full span — because the analog filter is ~1 dB down by that edge. The quickstart has the measurements.

sample_rates() returns the V6 ECO's ladder, 61.44 MHz down to 120 kHz. A full V6 selects its receiver clock and goes higher, by how much is unsettled; see the note in HTTPSPEC. There, trust the rate the device reports in stream metadata, which diagnose() prints.

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:

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_dbm for more gain:

aaronia.open(url, center_frequency_hz=2.44e9, sample_rate_hz=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 (SpectranConfig)

Every field is readable and writable.

Unknown format/receiver_channel strings raise ValueError instead of silently defaulting.

Behaviour

• One copy per read. Samples are copied once from the Rust receive buffer into a NumPy or Arrow owned buffer, which is then safe to hold indefinitely. This is not zero-copy; one copy is the accurate count.
• Blocking calls release the GIL. Other Python threads keep running; KeyboardInterrupt is delivered between calls. Reads block until count samples arrive or cfg.read_timeout_s seconds (default 30) elapse, which raises SpectranTimeoutError.
• Connecting retries transient failures, up to 4 attempts within a 10 second budget, so a cold *.local hostname or a server that is still starting does not fail on the first attempt.
• Dropped streams reconnect automatically when auto_reconnect is enabled, which is the default. The reader reopens the stream, re-applies the current tuning, and flags the first read after the gap through take_overrun(). After five failed attempts the stream ends and reads raise SpectranStreamClosed.
• Typed exceptions. SpectranConnectionError (unreachable endpoint), SpectranTimeoutError, SpectranHardwareError (device and SDK errors) and ValueError (invalid configuration), mapped from the Rust error enum with the full cause chain in the message. SpectranStreamClosed subclasses SpectranConnectionError and means the stream finished rather than failed; blocks() ends on it, while a timeout or transport failure still raises.
• Dual-channel reads (receiver_channel = "Rx1And2" with read_samples_dual_numpy(count), returning two time-aligned arrays) require the native-SDK backend: Windows or Linux with the Aaronia SDK installed, and a two-input V6. This path is hardware-unverified; the development device is a single-channel V6 ECO.

Source methods

Module functions