Skip to content

Commit 18c25fc

Browse files
LC-LinkousLC-Linkous
committed
library readme updated
1 parent 4f42d63 commit 18c25fc

1 file changed

Lines changed: 62 additions & 26 deletions

File tree

‎tsapython/README.md‎

Lines changed: 62 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,80 +3,116 @@
33
**An Unofficial Python API for the tinySA Device Series**
44

55
[![PyPI version](https://badge.fury.io/py/tsapython.svg)](https://badge.fury.io/py/tsapython)
6+
[![Python versions](https://img.shields.io/pypi/pyversions/tsapython.svg)](https://pypi.org/project/tsapython/)
7+
[![PyPI - Wheel](https://img.shields.io/pypi/wheel/tsapython.svg)](https://pypi.org/project/tsapython/)
8+
[![Downloads](https://static.pepy.tech/badge/tsapython)](https://pepy.tech/project/tsapython)
69
[![License: GPL v2](https://img.shields.io/badge/License-GPL_v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
10+
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20546764.svg)](https://doi.org/10.5281/zenodo.20546764)
711

8-
A Non-GUI Python API for the tinySA series of spectrum analyzer devices. This library provides programmatic control over tinySA devices for automated measurements, data collection, and analysis.
12+
A non-GUI Python API for the tinySA series of spectrum analyzer devices. This library provides programmatic control over tinySA devices for automated measurements, data collection, and analysis.
913

10-
Popular features:
14+
This repository uses official resources and documentation but is **NOT** endorsed by the official tinySA product, owner, or company. Refer to official resources and support for product information. This library was built for the official tinySA device line(s); knock-off or custom devices may not be compatible and have not been tested.
1115

12-
- **Device Discovery**: Automatic detection and serial connection to tinySA devices
13-
- **Frequency Sweeps**: Collect data across specified frequency ranges
14-
- **Multiple Modes**: Support for both input and output modes (device dependent)
15-
- **Data Export**: Easy integration with matplotlib and numpy
16-
- **Error Handling**: Error checking and verbose output options
17-
- **Device Control**: Full programmatic control of tinySA settings and measurements
16+
## Features
1817

18+
- **Device Discovery** — automatic detection and serial connection to tinySA devices
19+
- **Frequency Sweeps** — collect data across specified frequency ranges
20+
- **Multiple Modes** — support for both input and output modes (device dependent)
21+
- **Data Export** — easy integration with `matplotlib` and `numpy`
22+
- **Error Handling** — input checking and verbose output options
23+
- **Device Control** — full programmatic control of tinySA settings and measurements
1924

20-
This repository uses official resources and documentation but is **NOT** endorsed by the official tinySA product, owner, or company. Refer to official resources and support for product information. This library was built for the official tinySA device line(s), so any knock-off or custom devices may not be compatible with the library. Unofficial devices have not been tested.
25+
## Installation
2126

27+
```bash
28+
pip install tsapython
29+
```
2230

31+
The library itself depends only on `numpy` and `pyserial`. The plotting examples need an optional extra:
2332

33+
```bash
34+
pip install "tsapython[plotting]"
35+
```
2436

25-
## Full Code Examples:
37+
## Quick Start
38+
39+
```python
40+
from tsapython import tinySA
41+
42+
tsa = tinySA()
43+
found, connected = tsa.autoconnect()
44+
if connected:
45+
print(tsa.device_id())
46+
tsa.disconnect()
47+
```
48+
49+
## Examples
50+
51+
The [main GitHub repository](https://github.com/LC-Linkous/tinySA_python) provides runnable examples, grouped by what they demonstrate.
2652

27-
28-
The README on the [main GitHub repo](https://github.com/LC-Linkous/tinySA_python) provides runnable examples, grouped by what they demonstrate:
29-
3053
**Getting started / device control**
54+
3155
- `using_autoconnect.py` — detect and connect to a tinySA, read the device ID
3256
- `identifying_serial_ports.py` — manually identify serial ports (useful if autoconnect has trouble)
3357
- `using_command_func.py` — send raw device commands for functionality not yet wrapped by the library
3458
- `hardware_walkthrough.py` — a guided walkthrough of connecting and reading device info/data
3559
- `complete_workflow.py` — end-to-end: connect, read info, collect a sweep, and plot it
60+
3661
**Plotting scan data**
62+
3763
- `plotting_scan.py` — plot a single `scan`
3864
- `plotting_scanraw.py` — compare `scan` vs. the binary `scanraw` (with decoding to dBm)
3965
- `plotting_waterfall_static.py` — collect several sweeps and render a static waterfall plot
4066
- `plotting_waterfall_realtime.py` — a live, continuously updating waterfall plot
67+
4168
**Continuous acquisition**
69+
4270
- `continuous_scanraw_live.py` — loop `scan_raw` and live-plot each frame
4371
- `continuous_scanraw_collect.py` — loop `scan_raw`, decode to dBm, and save sweeps to CSV
72+
73+
**Analysis**
74+
75+
- `find_peaks.py` — find the strongest signal(s) two ways: the device's marker peak, and a Python multi-peak finder over scan data
76+
- `filtering_scan_artifacts.py` — show the `:` firmware artifact and compare a median filter against a moving average on one figure
77+
4478
**Exporting data**
79+
4580
- `save_scan_csv.py` — run a scan and write frequency/power pairs to a CSV file
81+
4682
> Most plotting examples require the optional plotting dependencies:
4783
> `pip install "tsapython[plotting]"`
4884
49-
50-
## Documentation & Examples
85+
## Documentation
5186

5287
For comprehensive documentation, advanced examples, and troubleshooting:
5388

54-
- **Library GitHub Repository**: [https://github.com/LC-Linkous/tinySA_python/](https://github.com/LC-Linkous/tinySA_python/)
55-
- **Official tinySA Documentation**: [https://tinysa.org/wiki/](https://tinysa.org/wiki/), not associated with this library
89+
- **Library GitHub repository**: [https://github.com/LC-Linkous/tinySA_python/](https://github.com/LC-Linkous/tinySA_python/)
90+
- **Official tinySA documentation**: [https://tinysa.org/wiki/](https://tinysa.org/wiki/) (not associated with this library)
5691

5792
## Contributing
5893

5994
This is an unofficial community project. Contributions welcome!
6095

61-
- Report bugs and request features on [GitHub]( https://github.com/LC-Linkous/tinySA_python)
96+
- Report bugs and request features on [GitHub](https://github.com/LC-Linkous/tinySA_python)
97+
- For device information and OFFICIAL resources, see the official tinySA community at [https://groups.io/g/tinysa](https://groups.io/g/tinysa)
98+
- Please do **NOT** request features or report bugs on the official community! This is an unofficial project and they do not maintain it.
99+
100+
## Citing
62101

63-
- For device information and OFFICIAL resources, check the official tinySA community at [https://groups.io/g/tinysa](https://groups.io/g/tinysa)
64-
- Please do NOT request features or report bugs on the official community! This is an unofficial project and they do not maintain it.
102+
If you use this library in your work, citation details are in the repository's `CITATION.cff`, or use the Zenodo DOI: [10.5281/zenodo.20546764](https://doi.org/10.5281/zenodo.20546764).
65103

66104
## License
67105

68-
GPL-2.0 - This is unofficial software with no warranty, offered AS-IS. Use at your own risk.
106+
GPL-2.0 — this is unofficial software with no warranty, offered AS-IS. Use at your own risk.
69107

70108
The licensing of this software does NOT take priority over the official releases and the decisions of the official tinySA team. This licensing does NOT take priority for any of their products, including the devices that can be used with this software.
71109

72110
## Acknowledgments
73111

74-
- tinySA device creators and community, who have created an awesome device
75-
- Official tinySA documentation and resources, especially www.tinysa.org/wiki/
112+
- The tinySA device creators and community, who have created an awesome device
113+
- Official tinySA documentation and resources, especially [www.tinysa.org/wiki/](https://www.tinysa.org/wiki/)
76114
- All contributors to this library, including those who have contributed code and reached out with questions
77115

78116
---
79117

80-
**Disclaimer**: This software is unofficial and not supported by the tinySA team. For official software and support, visit [tinysa.org](https://tinysa.org). The tinySA team does not offer tech support for this software, does not maintain it, and has no responsibility for any of the contents.
81-
82-
118+
**Disclaimer**: This software is unofficial and not supported by the tinySA team. For official software and support, visit [tinysa.org](https://tinysa.org). The tinySA team does not offer tech support for this software, does not maintain it, and has no responsibility for any of the contents.

0 commit comments

Comments
 (0)