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

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", freq=2.44e9, bandwidth=10e6) as src:
    for block in src.blocks(65536):           # numpy complex64 arrays
        process(block)

aaronia.open() connects and starts streaming in one call. bandwidth asks for that much usable spectrum and picks a sample rate the hardware can actually run; pass rate= 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(freq=2.44e9, rate=15.36e6, format="I16")
samples = src.read_samples_numpy(65536)       # numpy complex64 array
batch = src.read_samples_arrow(65536)         # pyarrow FixedSizeListArray of [re, im]
src.set_center_frequency(2.41e9)              # live retune, no teardown
print(src.cumulative_drops(), src.take_overrun(), src.last_timestamp_ns())
src.stop_streaming()

For full control, build an AaroniaConfig and pass it to AaroniaSource.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 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.

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.

Configuration (AaroniaConfig)

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
center_freq Center frequency, Hz
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
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)

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 seconds (default 30) elapse, which raises AaroniaTimeoutError.
  • 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 AaroniaStreamClosed.
  • Typed exceptions. AaroniaConnectionError (unreachable endpoint), AaroniaTimeoutError, AaroniaHardwareError (device and SDK errors) and ValueError (invalid configuration), mapped from the Rust error enum with the full cause chain in the message. AaroniaStreamClosed subclasses AaroniaConnectionError 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) / set_sample_rate(hz) / set_reference_level(dbm) Live retuning
cumulative_drops() Total server-reported dropped 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, *, 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
sample_rate_for_bandwidth(hz) Lowest rate covering that much spectrum
diagnose(url) (ok, message, fix) for each setup check; what aaronia-doctor prints

Project links

Data verified by PyPI on Aug 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.11.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ibentley from gravatar.com ibentley

GitHub Statistics

Data verified by PyPI on Aug 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU General Public License v3 or later (GPLv3+) (GPL-3.0-or-later)

Requires

Python >=3.9

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_aaronia-0.7.3.tar.gz (427.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

python_aaronia-0.7.3-cp39-abi3-win_amd64.whl (3.0 MB view details)

Uploaded CPython 3.9+Windows x86-64

python_aaronia-0.7.3-cp39-abi3-manylinux_2_39_x86_64.whl (4.0 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.39+ x86-64

python_aaronia-0.7.3-cp39-abi3-macosx_11_0_arm64.whl (3.4 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

File details

Details for the file python_aaronia-0.7.3.tar.gz.

File metadata

  • Download URL: python_aaronia-0.7.3.tar.gz
  • Upload date:
  • Size: 427.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for python_aaronia-0.7.3.tar.gz
Algorithm Hash digest
SHA256 1e4271e847e197fc1e6378ccf4fdcaa5a5e94e025eacd601eaae907f2c79da80
MD5 9e31e578c129c51e2a1911b083d3546d
BLAKE2b-256 21b78123c1a1fee96269b06d1181cc02d8c8bbf6be2c3b2baf9b236a59089436

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_aaronia-0.7.3.tar.gz:

Publisher: release.yml on isaacbentley/sdr-aaronia-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_aaronia-0.7.3-cp39-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for python_aaronia-0.7.3-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 0ef577d5a6ec3f28b087d92280927722cd90f7c6db5bcf658e693af08fe881f0
MD5 48d6cfc4273c71e2283cb0791ca02341
BLAKE2b-256 79389716ab099f51e38c2f2dd41511c85190cdb90bf992d47fd7ab13f26887e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_aaronia-0.7.3-cp39-abi3-win_amd64.whl:

Publisher: release.yml on isaacbentley/sdr-aaronia-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_aaronia-0.7.3-cp39-abi3-manylinux_2_39_x86_64.whl.

File metadata

File hashes

Hashes for python_aaronia-0.7.3-cp39-abi3-manylinux_2_39_x86_64.whl
Algorithm Hash digest
SHA256 ef654be2d3e506601d5353d47182694b19ee66a4c52887f7d6f23cd65ecbe595
MD5 40869cc8b62dfba9dce2ef525ad46490
BLAKE2b-256 72bb99e2c32663d4f1d020c6c3b7cfe512e178611e36008c3e75f74e6e9c6c53

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_aaronia-0.7.3-cp39-abi3-manylinux_2_39_x86_64.whl:

Publisher: release.yml on isaacbentley/sdr-aaronia-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_aaronia-0.7.3-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for python_aaronia-0.7.3-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d6135be90a45975672050ad02bfcbeb3fe16712d1f054d9347b21870034d7a5c
MD5 67bc98499a60d30665a818f80fd506cd
BLAKE2b-256 6fdebefb2c38d7f5843d09056b21fac3ff6bd3e0203f0d6d201821c1ba26c4dc

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_aaronia-0.7.3-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on isaacbentley/sdr-aaronia-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.11.2

4 files

0.11.1

4 files

0.11.0

4 files

0.10.0

4 files

0.9.0

4 files

0.8.2

4 files

0.8.1

4 files

0.8.0

4 files

0.7.7

4 files

0.7.6

4 files

0.7.5

4 files

0.7.4

4 files

This release

0.7.3 This release

4 files

0.7.2

4 files

0.7.1

4 files

0.7.0

4 files

0.6.2

4 files

0.6.1

4 files

0.6.0

4 files

0.5.1

4 files

0.5.0

4 files

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