Skip to main content

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 for HTTP sources. Native SDK sources do not require that server.

Sample rate and RF span

The module-level sample_rates() and sample_rate_for_bandwidth() functions remain legacy HTTP/ECO helpers. They are not capabilities of every native device. For a native IQ receiver, request RF span separately and inspect packet geometry:

cfg = aaronia.SpectranConfig()
cfg.force_native_sdk = True
cfg.device_serial = "YOUR_DEVICE_SERIAL"
cfg.native_mode = "iqreceiver"
cfg.rf_span_hz = 44e6
cfg.center_frequency_hz = 280e6
cfg.reference_level_dbm = -50
src = aaronia.SpectranSource()
src.start_streaming(cfg)
print(src.capabilities())                 # schema_version + capabilities
samples = src.read_samples_numpy(65536)
print(src.source_info())                  # observed rate and RF span
src.set_rf_span_hz(20e6)
src.stop_streaming()

IQ sample clock and valid RF span are distinct. The tested ECO delivered 44 MHz RF span at about 59.214 MS/s, and 20 MHz at 30 MS/s. Native configuration bounds may exceed the model's rated bandwidth. Neither those bounds nor RF span certifies amplitude calibration. Unknown metadata stays unknown. See the qualification matrix.

For HTTP only, the legacy helper uses the measured 0.8×Fs filter width and ECO rate ladder. Prefer source_info() for what the stream actually delivered.

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_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.

Field Meaning
http_base_url RTSA-Suite HTTP server URL; pins the HTTP backend
file_path Path to a recorded .rtsa file; pins the file backend
device_serial Device selection for the native-SDK backend
force_native_sdk True pins the source to the native SDK; missing SDK is an error
native_family Optional bare SDK family, e.g. "spectranv6eco"
native_mode Optional receive-only "iqreceiver" or "raw"
rf_span_hz Optional requested native IQ receiver RF span, Hz
receiver_clock Optional enabled raw-mode SDK clock label
decimation_factor Optional raw-mode power-of-two factor
center_frequency_hz Center frequency, Hz
sample_rate_hz IQ sample rate (Fs), Hz
reference_level_dbm 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_s Seconds a blocking read waits before SpectranTimeoutError (default 30.0)
auto_reconnect Reconnect the HTTP stream after a drop (default True)

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

Method Purpose
start_streaming(cfg) / stop_streaming() Session lifecycle
with src: ... Stops streaming on the way out, including after an exception
blocks(count) Iterate count-sample arrays until the stream closes
read_samples_numpy(count) NumPy complex64 array
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(hz) / set_sample_rate_hz(hz) / set_reference_level_dbm(dbm) Live retuning
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)

Module functions

Function Purpose
open(url=None, *, center_frequency_hz, sample_rate_hz, bandwidth_hz, reference_level_dbm, file, format, scale, read_timeout_s) Configure, connect and start streaming in one call
sample_rates() The V6 ECO's sample rates, highest first (see 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

Metadata

Release files for python-aaronia 0.13.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-aaronia 0.13.3
File Size Uploaded Provenance Actions
python_aaronia-0.13.3.tar.gz 683.8 kB With provenance Details for python_aaronia-0.13.3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for python-aaronia 0.13.3
File Interpreter ABI Platform Actions
python_aaronia-0.13.3-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for python_aaronia-0.13.3-cp39-abi3-win_amd64.whl
python_aaronia-0.13.3-cp39-abi3-manylinux_2_39_x86_64.whl CPython 3.9 abi3 Linux glibc 2.39+ x86-64 Details for python_aaronia-0.13.3-cp39-abi3-manylinux_2_39_x86_64.whl
python_aaronia-0.13.3-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for python_aaronia-0.13.3-cp39-abi3-macosx_11_0_arm64.whl

Total release size: 12.6 MB

Release files / python_aaronia-0.13.3.tar.gz

Download URL python_aaronia-0.13.3.tar.gz
Size 683.8 kB
Tags Source
SHA-256 checksum
How to use checksums
673a3ddd7d5b237de7952364fb830a45d2ee79bbc029e3524827fea49a734943
BLAKE2b-256 checksum
How to use checksums
612026b7a19c45513c78cdcf2f34e8247a517623b81744e34402bea842a8a4e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / python_aaronia-0.13.3-cp39-abi3-win_amd64.whl

Download URL python_aaronia-0.13.3-cp39-abi3-win_amd64.whl
Size 3.5 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
bf0e79e1c5610c6c52d6f5d97c0f0c97a7cdc514a0488cae02c68ce382c35dde
BLAKE2b-256 checksum
How to use checksums
307aaa5eac98cc52cf7b554831300bc09e09f9175a0f59a7cb71d55ff434f8a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / python_aaronia-0.13.3-cp39-abi3-manylinux_2_39_x86_64.whl

Download URL python_aaronia-0.13.3-cp39-abi3-manylinux_2_39_x86_64.whl
Size 4.6 MB
Tags CPython 3.9 Linux glibc 2.39+ x86-64 abi3
SHA-256 checksum
How to use checksums
513ec227cf515f91d52eeb2efd306694d706e649ff646a4e0645968e9f3dc927
BLAKE2b-256 checksum
How to use checksums
deb2c25ea313d773159bb87aa65fb2475b92ed93a03c6b07b2e303ac3bc513b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / python_aaronia-0.13.3-cp39-abi3-macosx_11_0_arm64.whl

Download URL python_aaronia-0.13.3-cp39-abi3-macosx_11_0_arm64.whl
Size 3.8 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
9cc18ae9c1fc248159d5ccc3e3627b69fe9cdd45c1601dccb3d335c88bd699ac
BLAKE2b-256 checksum
How to use checksums
202f61f1845ecced5ef6f0f41136095e1946fc8ad492f58c36f0c714da936861
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for python-aaronia 0.13.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for python_aaronia-0.13.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page