All notable changes to tinySA_python / tsapython are documented here.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Work on the current development branch. Entries move to a versioned section on release.
4.0.0 - 2026-10-18
API changes. See the README section "Upgrading to 4.0.0". Verified on a tinySA
Ultra ZS405 running tinySA4_v1.4-252 (identification, the gates, scan_raw_stream(),
and the signal-generator sequence with the output on into a load); the Basic and
Ultra+ boards are from the firmware source.
- A command the device rejects (
usage:line,name?, or a refusal such asusb disk mode active) returns the library's error value (b'', orb'ERROR'withset_error_byte_return(True)) instead of the device's text.command()still returns the raw text. - The generator output is gated:
output("on"),set_output_on()andcal_output()with any value other than"off"return the error value and send nothing untilset_output_allowed(True)has been called. - The library identifies the device at
connect()/autoconnect()(sendsversion,info,help) and applies a per-model profile. Commands the device lacks, words its model lacks, out-of-rangeif/level/levelchangevalues and marker/trace numbers above the model's count are refused before sending.identifyOnConnect = Falseskips identification. scan_raw()acceptsunbuf0 or 1 only.- The serial read timeout defaults to 120 s instead of waiting indefinitely.
tinySA.DEFAULT_SERIAL_TIMEOUT,tinySA(serial_timeout=...)andset_serial_timeout(None)adjust or disable it. - Oldest supported firmware is v1.4-182 (October 2024). Older firmware connects
with a warning and a
firmware-below-floorlog event.
_profiles.py:DeviceProfiledataclass and theBASIC,ZS405,ZS406,ZS407profiles;identify(),get_profile(),profile,profileDetected,deviceCommands,firmwareBuild;select_existing_device()now selects a profile by name.set_output_allowed(),get_output_allowed(),setup_generator(),set_generator(). Both helpers pause the sweep around settings changes: in output mode the firmware serviceslevel/sweep/modeonly between generator sweeps (about 20 s on hardware), immediately while paused.- The text reader requires the command's own echo before accepting a prompt, so a late reply from a timed-out command is discarded instead of being returned as the answer to the next command.
scan_raw_stream(): the device-side continuous scanraw (firmware v1.4-177 or later), verified on hardware.get_last_status(): how the last command ended (ok,blocked,usage,unknown-command,device-refused,timeout,read-failed), independent of the return value. In the default error mode an accepted setter and a rejected one both returnb''; this tells them apart.tinySA.MAX_COMMAND_LENGTH(47): commands longer than the firmware's command line are refused before sending instead of running truncated on the device and timing out in the library.DeviceProfileandPROFILESare exported from the package.- The deprecated aliases
set_mod_AM_1khz(),set_mod_AM_10Hz()andtrace_clear()emit aDeprecationWarning. tests/test_hardware_output.py(hardware_outputmarker, output on into a load),tests/bench_generator.py(receiver bench script, run by hand),TSAPYTHON_LOG=<path>for the hardware fixtures.- CI: Dependabot, CodeQL, weekly scheduled run, wheel install smoke test,
version-metadata and changelog checks, Python 3.14 in the matrix,
uv sync --locked;build-release.ymlbuilds a tag's files onto a draft release andrelease.ymlpublishes those same files to PyPI. - Issue and PR templates updated for 4.0.0 (log file, firmware build, board, device mode; profile gating and hardware runs in the PR checklist).
- README sections: Upgrading to 4.0.0, Device Profiles, RF Output Setting; web UI link (https://lc-linkous.github.io/tinysa-web/).
- Hardware tests for identification, the gates and the output setting.
- Output mode: a between-sweeps command (
pause,level,sweep,resume,mode, ...) sent within a few ms ofoutput,modulation,caloutputorleveloffsetwas dropped by the firmware and answered withCommand timeout20 s later (ZS405, v1.4-252). The library now waitsSETTLE_AFTER_IMMEDIATE_SETTER_S(0.4 s) after those four commands and resends a command once when the device repliesCommand timeout. Only idempotent setters are resent (_RETRY_AFTER_COMMAND_TIMEOUT);menu,touchcal,restart,saveand the like are reported as refused instead. setup_generator()andset_generator()now detect a refused step in the default error mode (they compared return values, andb''is also what an accepted setter returns). They stop at the first refused step, resume the sweep, and return False.direct(),ultra(),restart(),sd_delete(),sd_read()andfreq_corr()are refused before sending on a Basic, like the other Ultra-only commands.sd_read()on a firmware without the command (or with a bad argument) read the text reply as a 4-byte file length and waited the whole timeout; the text is now returned and classified.connect()closes the port and clearsserwhen the device cannot be read after the port opened;disconnect()clearsser, so the next command raises the library'sRuntimeErrorrather than pyserial'sPortNotOpenError.- A timed-out or short
scanrawframe is a failure (None, log statustimeout) instead of being returned as data and loggedok. The binary read's time limit follows the serial read timeout instead of a fixed 10 s. tests/test_hardware_output.pyalso carries thehardwaremarker, so-m "not hardware"(CI, README) deselects it; a command-line-mreplaces the one inaddopts.hop()with bad arguments returns the error value (it returnedNone, the timeout value, with a message the log did not record).trigger_level()/trigger(None, level)accept a numeric string such as"-52.5";wait("5")is accepted andwait("five")returns the error value instead of raisingTypeError.reset()returnsNonewhen the port drops, as it does on every reset, instead of raisingSerialException.modulation_depth()/modulation_deviation()on a Basic say the setting is not available on that model (the message namedfminstead).- The settle after
output/modulation/caloutput/leveloffsetapplies to the setter form only; the bare or?query forms no longer wait 0.4 s.
- numpy is no longer a dependency of the library (it was used for four range
checks, now
range()); it moved to theplottingextra with matplotlib for theexamples/scripts:pip install "tsapython[plotting]".
FakePortbehaves like a real port:reset_input_buffer()flushes, replies are queued per write withanswer(), andanswer(..., chunks=n)/answer_chunked([...])deliver a reply in several reads. New tests cover a prompt split asch+>, the trailing prompt space in a later packet, a stale prompt arriving alone,Command timeoutsplit across packets, and the capture, scanraw and sd_read readers fed in many packets.- Timing asserts loosened to bounds a slow CI runner cannot miss; smoke tests assert the setting round-trips; dead fixture seeding and a stale module docstring removed.
- CI:
twine check, an sdist install, the documentedpip install -e ".[test]"path, and a compile check ofexamples/and the helper scripts. Command timeout(firmware v1.4-222+) is recognised as the end of a reply, so a dropped command costs about 20 s instead of the full read timeout.- A log record for a read that timed out now keeps the bytes that did arrive.
tests/test_hardware_output.py: the fixture releases the port and restores the device when setup fails, so later tests no longer skip with "no tinySA device connected";TSAPYTHON_LOG=<path>turns logging on.
3.1.0 - 2026-10-17
Non-breaking firmware-compatibility release: every call that worked before behaves the same. Read from the tinySA firmware source (v1.4-244). Verified on hardware with a tinySA Ultra ZS405 running tinySA4_v1.4-143 (the probe script matched its predictions 36 of 36 times); the Basic and Ultra+ boards are from firmware source only.
- Optional JSON Lines log file:
set_log_file(path, level),close_log_file(),get_log_file(). Records every command, the reply, a status (ok,usage,unknown-command,device-refused,timeout,read-failed,blocked) and the reason. Off by default; nothing is kept in memory. set_serial_timeout(seconds)/get_serial_timeout(). The default staysNone(wait indefinitely), so long sweeps are unaffected.- Signal generator:
modulation()accepts the current firmware words (am,fm,nfm,wfm,extern,off); newmodulation_freq(),modulation_depth(),modulation_deviation(),set_mod_AM(),set_mod_FM();output()acceptsnormalandmixerwith aliasesset_output_path_normal()/set_output_path_mixer(). calc()acceptsaver,quasi,log,lin;spur()acceptsauto(spur_auto());trace_units()acceptsdBV;level_offset()acceptshigh,shift4,direct_output,low_output;set_IF()accepts the Ultra (975M..979M) and Ultra+ (1067M..1073M) ranges.trace_freeze(ID, val="on"|"off"),trace_unfreeze(ID), and an optional third argument ontrace_action().- Getters:
get_rbw(),get_attenuation(),get_sweep_time(),get_IF(),get_scanraw_offset(),get_noise_figure(),get_dac_value(),get_calc(),get_sweep_range();decode_number()for the pre-v1.4-230:artifact. - New command wrappers:
waitscan(),channel(),avoid(),usbdisk(),time(),correction_reset(),sweep_mode(),marker_mode(),marker_all_off(),marker_read(),resume(count),sd_list(pattern). - SD card:
list_sd_files(),save_sd_file(),save_firmware_dump()(copies the device's own firmware dump, made with DUMP FIRMWARE on the device, to the computer). tests/probe_firmware_returns.py: manual hardware probe with JSON/markdown reports; seven hardware set-and-read-back tests intests/test_hardware.py.- README sections: Logging, Firmware Compatibility, Change Summary, Deprecated Functions, Reading Values Back, Commands added in 3.1.0.
- Internal helpers
identify_device()andclassify_reply()(_identify.py).
level(),level_change(),rbw()andtrigger_level()accept decimals;level_change()accepts -90..90.scan()andscan_raw()acceptstart == stop(zero span);scan_raw()acceptsunbuf=0.calc("quasip")andset_calc_quasip()sendcalc quasi. The firmware renamed the keyword in May 2022 and rejectsquasip.modulation("AM_1kHz" | "AM_10Hz" | "NFM" | "WFM")and their aliases send the current firmware equivalent; the firmware has rejected the old keywords since Nov 2020.capture()is read by length and returns exactlywidth * height * 2bytes.sd_read()reads the 4-byte size prefix and returns exactly the file's bytes.- A text reply is complete at the
ch>prompt rather than at the first>byte, so replies containing>are no longer cut short. - The serial read loop sleeps 1 ms when no data is waiting, instead of spinning a CPU core.
tsapython.__version__is read from the installed package metadata.
set_mod_AM_1khz(),set_mod_AM_10Hz(),trace_clear(). Still callable; see the README section "Deprecated Functions".
hop()raisedUnboundLocalErrorfor anyoutmaskother than 1, 2 orNone. 3 (the firmware default) is now accepted; other values return the error value.wait()with no argument returned the error value; it now sendswait.attenuate(31)andcolor(31, ...)were refused by an off-by-one.trace_freeze(ID)senttrace {ID} freeze, which the firmware parses and ignores; it now sendstrace {ID} freeze on.capture()stopped at the first0x3Epixel byte and returned one byte too few.examples/using_command_func.pyand the README sentscan 150e6 200e6, which the firmware reads as 150 Hz to 200 Hz.
3.0.1 - 2026-09-19
Tooling, metadata, and repository-hygiene release. No API or behavior
changes: the shipped package gains full type annotations (now CI-enforced,
making the long-standing py.typed marker a kept promise) and the
repository gains the quality gates and health files below.
- Repository and packaging polish, ported from the hackrfpy hardening pass:
SECURITY.md(private vulnerability reporting, scope, and the hardware-damage carve-out), a.gitattributesline-ending policy (LF everywhere, binary protections, one-time renormalize), PyPI metadata (HomepageandChangelogproject URLs,keywords, richer classifiers), a CI coverage gate at 85% minimum (measured 86% at adoption), the ruff blocking ruleset expanded toE9 + F + W(pre-existing whitespace findings autofixed; fullEremains a deferred, reviewed cleanup), a written coverage-and-platform policy plus PR expectations in CONTRIBUTING, and Keep-a-Changelog compare links in this file. - Continuous integration: GitHub Actions workflow running the hardware-free test suite across Windows, Linux, and macOS on Python 3.10–3.13, plus a ruff + mypy lint job and a package build check, on every push and pull request.
- Type annotations across the entire shipped package (all 226 definitions),
and
mypyadded as a blocking CI gate (disallow_untyped_defs). The package has always shipped apy.typedmarker, which tells downstream type-checkers the inline annotations are real; previously 0 of 226 definitions were annotated, so that marker was a false promise. It is now enforced. MixinHostbase class (_host.py) making the contract between thetinySAhost class and the command mixins explicit and type-checkable. At runtime it is an empty class; composition and behavior are unchanged.- Committed
uv.lockand a PEP 735devdependency group, makinguv sync/uv run pytestthe blessed development workflow (the previous README warning againstuv run pytestno longer applies). - Ruff configuration in
pyproject.toml. The blocking ruleset is deliberately small (E9 syntax errors + F pyflakes); style rules are a planned follow-up. - Release workflow now runs the test suite, lint, and type check before building or publishing, so a release cannot ship with a red suite.
- Community health files:
CONTRIBUTING.md,CODE_OF_CONDUCT.md,SECURITY.md,CHANGELOG.md, issue templates, and a pull request template. - Captured-fixture provenance:
tests/collect_samples.pynow records the device model and firmware in the generated fixture header, and the existingcaptured_responses.pyheader was retrofitted (tinySA ULTRA, tinySA4_v1.4-143-g864bb27). zenodo.jsonnow carries aversionfield matchingCITATION.cff.
get_color()crashed with aTypeErrorwhenever a color lookup matched: it applied astrregex pattern to the rawbytearraydevice reply. Found by the new type checking. The reply is now decoded before matching, and aNonereply no longer crashes the length check.color()no longer crashes if called with a valid ID butRGB=None; it returns the error byte instead.- Serial-touching methods now raise a clear
RuntimeError("not connected: call connect() or autoconnect() first") instead of an opaqueAttributeErroronNoneTypewhen used before connecting. - A failed serial read inside
tinySA_serial()now propagatesNoneinstead of crashing inclean_return(). - Out-of-range string inputs to
correction()andset_IF1()now return the error byte instead of raisingTypeErroron comparison. - README no longer references
requirements.txt/test_requirements.txt, which were removed from the repository in the 3.0.0 packaging restructure; install instructions now go through thepyproject.tomlextras. - README repository-structure diagrams updated to match the actual tree
(added
examples/filtering_scan_artifacts.py,examples/find_peaks.py, andtests/diagnose_reset.py; removed the requirements files). - Removed unused imports and dead local variables flagged by lint. No behavior change.
- Removed
examples/__init__.py— the examples directory is a collection of runnable scripts, not a package. - Merged two near-duplicate README sections documenting
tests/collect_samples.py.
- Alias-function signatures aligned with the methods they delegate to
(
set_color,preform_touch,restart_device,get_sample_pts,trigger_level,set_ultra_start/set_ultra_harmonic).
- Published to PyPI as
tsapython. - Automated test suite (pytest): command-construction tests via a recorded
serial seam, parsing tests against captured device responses, and
@pytest.mark.hardwaretests that self-skip without a connected device. tests/collect_samples.pyhelper for freezing real device responses into parsing fixtures.- Runnable examples under
examples/, including scan/scanraw plotting, static and realtime waterfalls, artifact filtering, and peak finding. - Trusted-publishing release workflow (
release.yml) building with uv and publishing to PyPI on GitHub release. - Zenodo archival with DOI (
zenodo.json,CITATION.cff).
- Restructured into an installable package with a
src/layout: thetinySAclass is now composed from per-category mixins undersrc/tsapython/_commands/, with shared state, serial handling, and helpers incore.py. The public API (from tsapython import tinySA) is unchanged. - Packaging moved fully to
pyproject.toml(uv build backend), withplottingandtestextras replacing the loose requirements files.
See the GitHub releases for pre-3.0.0 history, when the library shipped as a single-class module.