tsapython 3.0.0

Release Notes — tsapython 3.0.0

This is a major release. The version bump to 3.0.0 is required by one breaking
API change (trace_units); everything else is bug fixes and additions. All
the fixes in this release were confirmed against a physical tinySA Ultra.

---

Breaking changes

trace_units now takes a trace number.
The signature changed from trace_units(val) to trace_units(ID, val). The
device requires a trace number for this command, so the old single-argument form
could not target a specific trace. If you called trace_units("dBm"), update it
to trace_units(1, "dBm") (or whichever trace number you intend).

Trace commands are now 1-indexed and validated.
The trace command family (trace_select, trace_toggle, trace_freeze,
trace_copy, trace_subtract, trace_value, etc.) now requires trace numbers
of 1 or greater, matching the device, which rejects trace 0. There is no enforced
upper bound, since the number of traces is model-dependent and the device rejects
values that are too high. Code that relied on the previous (incorrect) acceptance
of trace 0 will now receive an error instead.

---

Fixed

scanraw no longer returns truncated data at high point counts.
scan_raw previously returned randomly truncated frames at larger point counts
(e.g. 450 points), because the binary read terminated at the first byte that
happened to match a text terminator. Binary scanraw data can contain those byte
values as ordinary samples. The binary read now reads by expected length, so it
returns the full frame regardless of the sample values. Confirmed on hardware at
200, 400, and 450 points.

Trace command grammar corrected.
Several trace commands were building malformed strings the device rejected
(missing the space before the trace number, sending the wrong sub-command, or
using a toggle form the device does not accept). These now use the device's
documented trace {n} {action} {arg} grammar. Confirmed on hardware.

Example data cleaning handles all forms of the : firmware artifact.
Some firmware builds emit a malformed value (a : where a digit should be) in
scan output. The plotting examples previously only handled the signed form and
would crash on the unsigned form. All affected examples now handle both.

clear_and_reset tolerates the reset disconnect.
reset() disconnects the serial port immediately, which raises a
SerialException. clear_and_reset now catches this so it does not propagate an
unexpected exception to callers. Confirmed on hardware (reset raises a catchable
exception rather than hanging).

Assorted command fixes.
A number of individual command methods were corrected, including mode()
(argument handling), the set_cal_output_* aliases (wrong method name),
set_direct_on/off (missing default argument), modulation() (wrong command
word), get_status() (infinite recursion), get_zero_offset() (missing default
argument), the marker_* aliases (missing return values), and correction()
(dead bounds checks). run_sweep no longer appends a stray digit to the command.
Most of these were left as todo items from the last update and none of them
had impact on the core functions.

---

Added

continious_scanraw — continuous SCANRAW acquisition.
Previously an unimplemented stub, this is now a generator that yields one decoded
frame per iteration. Because the device returns a single frame per scanraw call
(it does not open an unbounded stream over USB), continuous acquisition is done
by looping scan_raw. Supports a count limit or indefinite operation.
Confirmed on hardware.

direct() argument validation.
The start and stop forms now require the frequency to be a positive number.
No upper bound is enforced, since the valid range is model-dependent and the
device rejects out-of-range values.

New examples.

• continuous_scanraw_live.py — loop scan_raw and live-plot each frame.
• continuous_scanraw_collect.py — loop scan_raw and save sweeps to CSV.
• find_peaks.py — find the strongest signal(s) two ways: the device's marker
  peak, and a Python multi-peak finder over scan data.
• filtering_scan_artifacts.py — show the : artifact and compare a median
  filter (removes spikes) with a moving average (smears them) on one figure.

---

Removed

read_until_end_marker — dead code. It was never wired into the read path
and its marker-scanning approach was unreliable for binary data. The working
scanraw read path is the new length-based binary reader.

---

Notes

• The library exposes the same public entry point: from tsapython import tinySA.
• The package source depends only on numpy and pyserial; plotting for the
  examples is an optional extra: pip install "tsapython[plotting]".
• This release is archived on Zenodo with a DOI; see the repository for citation
  details (CITATION.cff).

tsapython 2.0.0

About

This is the first release of tsapython, from August 2025.

tsapython is an unofficial Python API for the tinySA device line. This repository uses official resources and documentation but is NOT endorsed by the official tinySA product or company. See the references section for further reading, and the official tinySA resources for device features.