A Non-GUI Python API for the tinySA series of devices. This repository uses official resources and documentation but is NOT endorsed by the official tinySA product or company. See the[references](#references) section for further reading. See the[official tinySA resources](https://www.tinysa.org/wiki/) for device features.

This library covers most documented commands for the tinySA device series, and is planned to include configurable, device-specific commands and memory. The documentation (after the examples) is sorted based on the serial command for the device, with some provided usage examples. While some error checking exists in both the device and the library, it is not exhaustive. It is strongly advised to read the official documentation before attempting to script with your tinySA device. Operating the device experimentally or without referencing the official documents runs the risk of**destroying your device**. See the[tinySA First use page](https://tinysa.org/wiki/pmwiki.php?n=Main.FirstUse) for some setup tips and warnings.

This library is now avilable via PyPI, local install, or just using the class. We reccomend one of the library install options.

This library is now available via PyPI, local install, or just using the class. We recommend one of the library install options.

Several usage examples are provided in the[Example Implementations](#example-implementations) section, including working with the hardware and plotting results with matplotlib.

`pyQt5` is used with`matplotlib` to draw the figures. It needs to be installed on Linux systems to follow the examples included in tinySA_python, but is not needed on all Windows machines.

OUT OF DATE - GETTING MAJOR OVERHAUL

This library is currently only available as the tinySA class in 'tinySA_python.py' in this repository. It is very much under development and missing some key error checking and handling. HOWEVER, ‘any’ error checking is currently more than the ‘no’ error checking provided by interfacing directly with the device. The code that is included in this repository has been tested on at least one tinySA device and is relatively stable.

Several usage examples are provided in the[Example Implementations](#example-implementations) section, including working with the hardware and plotting results with matplotlib.

The`tsapython` library, as it is avilable on PyPI is structured as follows:

├── test_basic.py

├── test_example_workflow.py

└── test_hardware.py

A`docs` repository for the library will be added later in development for stable releases.

This library is also part of the`tinySA_python` repository, which includes more extensive documentation and the working development. The GitHub repository is structured as follows:

tinySA_python/

├──README

├── requirements.txt

├── test_requirements.txt

├── media/

│ └──README images, screenshots

└──tsapython/

├── .python-version

├── pyproject.toml

├──README.md

├──LICENSE

├── .gitignore

├── examples/

│ ├──__init__.py

│ ├── identifying_serial_ports.py

│ ├── plotting_scan.py

│ ├── plotting_scanraw.py

│ ├── plotting_waterfall_realtime.py

│ ├── save_scan_csv.py

│ ├── using_autoconnect.py

│ └── using_command_func.py

├── src/

│ └── tsapython/

│ ├──__init__.py

│ ├── core.py

│ └── py.typed

└── tests/

├──__init__.py

├── run_all_tests.py

├── test_basic.py

├── test_example_workflow.py

└── test_hardware.py

running tests:

Tests should be run from the root`tsapython` directory.

uv run python tests/test_basic.py

uv run python tests/test_hardware.py

python tests/test_basic.py

python tests/run_all_tests.py

OUT OF DATE - GETTING MAJOR OVERHAUL

This project requires numpy, pandas and pyserial.

Use 'pip install -r requirements.txt' to install the following dependencies:

pyserial

numpy

pandas

The above dependencies are only for the API interfacing of the tinySA_python library. Additional dependencies should be installed if you are following the examples in this README. These can be installed with 'pip install -r test_requirements.txt':

pyserial

numpy

pandas

matplotlib

pillow

pyQt5

For anyone unfamiliar with using requirements files, or having issues with the libraries, these can also be installed manually in the terminal (we recommend a Python virtual environment) with:

pip install pyserial numpy pandas matplotlib pillow pyQt5

`pyQt5` is used with`matplotlib` to draw the figures. It needs to be installed on Linux systems to follow the examples included in tinySA_python, but is not needed on all Windows machines.

Some error handling has been implemented for the individual functions in this library, but not for the device configuration. Most functions have a list of acceptable formats for input, which is included in the documentation and the`library_help` function. The`tinySA_help` function will get output from the current version of firmware running on the connected tinySA device.

This library was developed on Windows and has been lightly tested on Linux. The main difference (so far) has been in the permissions for first access of the serial port, but there may be smaller bugs in format that have not been detected yet.

To start, a serial connection between the tinySA and user PC device must be created. There are several ways to list available serial ports. The library supports some rudimentary autodetection, but if that does not work instructions in this section also support manual detection.

from src.tinySA_pythonimport tinySA

from tsapythonimport tinySA

tsa= tinySA()

from src.tinySA_pythonimport tinySA

from tsapythonimport tinySA

tsa= tinySA()

from src.tinySA_pythonimport tinySA

from tsapythonimport tinySA

tsa= tinySA()

import numpyas np

import matplotlib.pyplotas plt

from src.tinySA_pythonimport tinySA

from tsapythonimport tinySA

from src.tinySA_pythonimport tinySA

from tsapythonimport tinySA

import csv

The second part of the example is a realtime waterfall plot with peak tracking and a sample of the last reading.

import numpyas np

from src.tinySA_pythonimport tinySA

from tsapythonimport tinySA

In some cases, this library may not cover all possible command versions, or new features might not be included yet. The tinySA can be accessed directly using the`command()` function. There is NO ERROR CHECKING on this function. It takes the full argument, just as if arguments were entered on the command line.

from src.tinySA_pythonimport tinySA

from tsapythonimport tinySA

***CLI Wrapper Usage:**

***Notes:**

All numbers are binary coded 2 bytes little endian. The pixel data is encoded as 2 bytes per pixel. This is data returned by the device when in AUTO REFRESH mode. NOTE: may need to be paired with acontinious buffer read and dump, which will be tested in the next update

All numbers are binary coded 2 bytes little endian. The pixel data is encoded as 2 bytes per pixel. This is data returned by the device when in AUTO REFRESH mode. NOTE: may need to be paired with acontinuous buffer read and dump, which will be tested in the next update

***CLI Wrapper Usage:**

***Notes:**

* NOTE: no frequency checking is done for this function yet.

* might be tinySA Ultraannd newer only.

* might be tinySA Ultraand newer only.

* Related to NORMAL, DIRECT, ADF, and MIXER

* None, see direct library function calls

* it is also suggested to use the`command()` function to preform more complex actions because this is a complicated command structure

***CLI Wrapper Usage:**

***Notes:** For readability, this command was split into multiple functionsintitially rather than using complex alias functions. There is a mismatch of information of commands between versions, so this library uses the documentation returned by the device.

***Notes:** For readability, this command was split into multiple functionsinitially rather than using complex alias functions. There is a mismatch of information of commands between versions, so this library uses the documentation returned by the device.

*`select_trace()`: tinySA Ultra has 4 traces to choose from. Other devices may have other numbers of traces.

*`trace_reflevel(...)` : adjusts the reference level of a trace. Levels are specified in dB(m) and can be specified using a floating point notation. E.g. 10 or 2.5[https://tinysa.org/wiki/pmwiki.php?n=Main.USBInterface](https://tinysa.org/wiki/pmwiki.php?n=Main.USBInterface)

* Python Packaging and Library Setup: