| Name | tekrsa-api-wrap JSON |
| Version |
1.3.2
JSON |
| download |
| home_page | |
| Summary | NTIA/ITS Python wrapper for the Tektronix RSA API for Linux |
| upload_time | 2023-04-18 20:44:35 |
| maintainer | |
| docs_url | None |
| author | The Institute for Telecommunication Sciences |
| requires_python | >=3.8 |
| license | SOFTWARE DISCLAIMER / RELEASE This software was developed by employees of the National Telecommunications and Information Administration (NTIA), an agency of the Federal Government and is provided to you as a public service. Pursuant to Title 15 United States Code Section 105, works of NTIA employees are not subject to copyright protection within the United States. The software is provided by NTIA “AS IS.” NTIA MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. NTIA does not warrant or make any representations regarding the use of the software or the results thereof, including but not limited to the correctness, accuracy, reliability or usefulness of the software. To the extent that NTIA holds rights in countries other than the United States, you are hereby granted the non-exclusive irrevocable and unconditional right to print, publish, prepare derivative works and distribute the NTIA software, in any medium, or authorize others to do so on your behalf, on a royalty-free basis throughout the World. You may improve, modify, and create derivative works of the software or any portion of the software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the software and should note the date and nature of any such change. You are solely responsible for determining the appropriateness of using and distributing the software and you assume all risks associated with its use, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This software is not intended to be used in any situation where a failure could cause risk of injury or damage to property. Please provide appropriate acknowledgments of NTIA’s creation of the software in any copies or derivative works of this software. |
| keywords |
api
linux
rf
rsa
scos
sdr
tektronix
analyzer
radio
spectrum
wrapper
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# NTIA/ITS Python Wrapper for Tektronix® RSA API for Linux
[](https://github.com/psf/black)
This Python package provides a module which wraps the
[Tektronix Python/Ctypes RSA API](https://github.com/tektronix/RSA_API/tree/master/Python),
with the goal of masking the Ctypes dependency and streamlining use of the API in a
Python development environment. It implements most of the available RSA API functionality
(see below for more information). Basic documentation is included in docstrings for quick
reference during development, but this is not meant as a substitute for the comprehensive
[RSA API Programming Reference manual](https://www.tek.com/spectrum-analyzer/rsa306-manual/rsa306-rsa306b-and-rsa500a-600a-0)
offered by Tektronix. The manual details many peculiarities in API or device behavior
which are not immediately obvious, and yet are important for developing software to
control an RSA device.
This wrapper was developed for applications involving programmatic control of Tektronix
RSA devices from Linux. Depending on your use case, and especially if you plan to run
your program from Microsoft Windows®, it may be worth looking into the
[Tektronix Python/Cython RSA API](https://github.com/tektronix/RSA_API/tree/master/Python/Cython%20Version)
instead of using this wrapper.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Development](#development)
- [License](#license)
- [Contact](#contact)
- [Disclaimer](#disclaimer)
## Installation
Requires `python>=3.8`, `numpy>=1.22`, and the Tektronix RSA API for Linux.
First, download and install the
[RSA API for Linux](https://www.tek.com/spectrum-analyzer/rsa306-software/rsa-application-programming-interface--api-for-64bit-linux--v100014)
from Tektronix. Follow the included installation instructions, then copy the
`libRSA_API.so` and `libcyusb_shared.so` files into your project.
These shared object files are required, and this API wrapper by default expects to find
them in the [SCOS Sensor](https://github.com/NTIA/scos-sensor/) drivers directory
(`/drivers/`). If you are running without SCOS Sensor, you will need to specify your
drivers directory when instantiating the API wrapper. See the [Usage section](#usage)
below for an example of how to do this.
Next download and install this API wrapper using `pip`:
```bash
pip install tekrsa-api-wrap
```
## Usage
Interface with a supported Tektronix RSA device using Python as follows:
```python
import rsa_api
# Directory which contains both libRSA_API.so and libcyusb_shared.so
drivers_path = '/path/to/shared_objects/'
# Initialize an RSA device using the API wrapper
rsa = rsa_api.RSA(so_dir=drivers_path)
# Example usage: connect, print current center frequency, then disconnect
rsa.DEVICE_SearchAndConnect()
print(f"Current Center Frequency (Hz): {rsa.CONFIG_GetCenterFreq()}")
rsa.DEVICE_Disconnect()
# Print docstrings for any implemented API function
help(rsa.IQSTREAM_Acquire) # Requires initialized RSA device
help(rsa_api.RSA.IQSTREAM_Acquire) # Does not require initalized RSA device
```
### List of API functions NOT implemented
- All functions not supported by the RSA API for Linux (see "Known Issues" below)
- All `DPX`, `PLAYBACK`, `IFSTREAM` and `TRKGEN` functions
- `DEVICE_GetErrorString()`
- Alternate error handling is implemented.
- `DEVICE_GetNomenclatureW()` and `IQSTREAM_SetDiskFilenameBaseW()`
- `DEVICE_GetNomenclature()` and `IQSTREAM_SetDiskFilenameBase()` are used instead.
- `IQBLK_GetIQDataCplx()`
- `IQBLK_GetIQData()` and `IQBLK_GetIQDataDeinterleaved()` are used instead.
### List of API "Helper" functions
A handful of useful functions are included in this wrapper which streamline some common
tasks. These "helper functions" include:
- `IQSTREAM_Acquire()`
- `IQBLK_Acquire()`
- `IQBLK_Configure()`
- `SPECTRUM_Acquire()`
- `IQSTREAMFileInfo_StatusParser()`
- `IQSTREAMIQInfo_StatusParser()`
- `IQSTREAM_Tempfile()`
- `IQSTREAM_Tempfile_NoConfig()`
- `DEVICE_SearchAndConnect()`
- `DEVICE_GetTemperature()`
To read more about these functions, check their docstrings with `help()`.
### Known Issues
Known issues exist in the underlying Tektronix RSA API for Linux, and therefore this
wrapper is limited in certain ways. The list of known issues is provided by Tektronix in
the [Tektronix RSA API for Linux release notes](https://download.tek.com/software/supporting_files/ReleaseNotes_1_0_0014_64bit_066207701.txt)
(up-to-date as of version 1.0.0014).
### TODO: Update this section after resolving
Additionally, a known issue exists with parsing IQ streaming status data structures.
There appears to be a discrepancy between the documented status message encoding scheme
and the implemented encoding scheme. In its current implementation, this API wrapper has
been tested to ensure that ADC overrange events are properly flagged when using
`IQSTREAM_Tempfile`, `IQSTREAM_Tempfile_NoConfig` or `IQSTREAM_Acquire` methods. Buffer
overflow warnings and errors should work, but have not been tested. The USB data
discontinuity status is unable to be parsed. Unknown IQ stream status codes are treated
as errors and handled as configured in `IQSTREAM_StatusParser`.
## Development
### Development Environment
Set up a development environment using a tool like
[Conda](https://docs.conda.io/en/latest/)
or [venv](https://docs.python.org/3/library/venv.html#module-venv), with `python>=3.8`.
Then, from the cloned directory, install the development dependencies by running:
```bash
pip install .[dev]
```
This will install the project itself, along with development dependencies for pre-commit
hooks, building distributions, and running tests. Set up pre-commit, which runs
auto-formatting and code-checking automatically when you make a commit, by running:
```bash
pre-commit install
```
The pre-commit tool will auto-format Python code using [Black](https://github.com/psf/black)
and [isort](https://github.com/pycqa/isort). Other pre-commit hooks are also enabled, and
can be found in [`.pre-commit-config.yaml`](.pre-commit-config.yaml).
### Building New Releases
This project uses [Hatchling](https://github.com/pypa/hatch/tree/master/backend) as a
backend. Hatchling makes version control and building new releases easy. The package
version can be updated easily using any of the following commands.
```bash
hatchling version major # 1.0.0 -> 2.0.0
hatchling version minor # 1.0.0 -> 1.1.0
hatchling version micro # 1.0.0 -> 1.0.1
hatchling version "X.X.X" # 1.0.0 -> X.X.X
```
To build a wheel and source distribution, run:
```bash
hatchling build
```
### Running Tests
A testing file is included in the `tests` directory of this repository. The test uses
`unittest` to test supported API functions. Running a test requires an RSA device to be
connected. The same test is used for any supported RSA device, with some tests being
enabled, disabled, or modified as needed depending on the device's specific supported
API functions. For example, tests of the preamp configuration are not run when testing
with an RSA which does not have a preamp.
From the top-level directory of this repository, run the test by running:
```bash
export SO_DIR=/path/to/drivers
python -X faulthandler -m unittest
```
Replacing `<path-to-shared-objects>` with the path to a directory containing both
`libRSA_API.so` and `libcyusb_shared.so`.
This testing code was been adapted from the
[Tektronix Cython RSA API testing code for the 306B](https://github.com/tektronix/RSA_API/blob/master/Python/Cython%20Version/test_rsa306b.py)
and [for the 500A/600A series devices](https://github.com/tektronix/RSA_API/blob/master/Python/Cython%20Version/test_rsa500-600.py).
In addition to adapting this code to work with this API wrapper, various tests were also
added which were not present in the original versions, and the test was made to be
universal for all supported RSA devices.
## License
See [LICENSE](LICENSE.md)
TEKTRONIX and TEK are registered trademarks of Tektronix, Inc.
Microsoft and Windows are trademarks of the Microsoft group of companies.
## Contact
For technical questions, contact Anthony Romaniello, aromaniello@ntia.gov
## Disclaimer
Certain commercial equipment, instruments, or materials are identified in this project
were used for the convenience of the developers. In no case does such identification
imply recommendation or endorsement by the National Telecommunications and Information
Administration, nor does it imply that the material or equipment identified is necessarily
the best available for the purpose.
Raw data
{
"_id": null,
"home_page": "",
"name": "tekrsa-api-wrap",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Anthony Romaniello <aromaniello@ntia.gov>",
"keywords": "API,Linux,RF,RSA,SCOS,SDR,Tektronix,analyzer,radio,spectrum,wrapper",
"author": "The Institute for Telecommunication Sciences",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/9e/f2/65185b18eb7fde6dfa4a10fba20fb1e2ae5c0a25b819447ec53430830742/tekrsa_api_wrap-1.3.2.tar.gz",
"platform": null,
"description": "# NTIA/ITS Python Wrapper for Tektronix\u00ae RSA API for Linux\n\n\n\n\n[](https://github.com/psf/black)\n\nThis Python package provides a module which wraps the\n[Tektronix Python/Ctypes RSA API](https://github.com/tektronix/RSA_API/tree/master/Python),\nwith the goal of masking the Ctypes dependency and streamlining use of the API in a\nPython development environment. It implements most of the available RSA API functionality\n(see below for more information). Basic documentation is included in docstrings for quick\nreference during development, but this is not meant as a substitute for the comprehensive\n[RSA API Programming Reference manual](https://www.tek.com/spectrum-analyzer/rsa306-manual/rsa306-rsa306b-and-rsa500a-600a-0)\noffered by Tektronix. The manual details many peculiarities in API or device behavior\nwhich are not immediately obvious, and yet are important for developing software to\ncontrol an RSA device.\n\nThis wrapper was developed for applications involving programmatic control of Tektronix\nRSA devices from Linux. Depending on your use case, and especially if you plan to run\nyour program from Microsoft Windows\u00ae, it may be worth looking into the\n[Tektronix Python/Cython RSA API](https://github.com/tektronix/RSA_API/tree/master/Python/Cython%20Version)\ninstead of using this wrapper.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Development](#development)\n- [License](#license)\n- [Contact](#contact)\n- [Disclaimer](#disclaimer)\n\n## Installation\n\nRequires `python>=3.8`, `numpy>=1.22`, and the Tektronix RSA API for Linux.\n\nFirst, download and install the\n[RSA API for Linux](https://www.tek.com/spectrum-analyzer/rsa306-software/rsa-application-programming-interface--api-for-64bit-linux--v100014)\nfrom Tektronix. Follow the included installation instructions, then copy the\n`libRSA_API.so` and `libcyusb_shared.so` files into your project.\n\nThese shared object files are required, and this API wrapper by default expects to find\nthem in the [SCOS Sensor](https://github.com/NTIA/scos-sensor/) drivers directory\n(`/drivers/`). If you are running without SCOS Sensor, you will need to specify your\ndrivers directory when instantiating the API wrapper. See the [Usage section](#usage)\nbelow for an example of how to do this.\n\nNext download and install this API wrapper using `pip`:\n\n```bash\npip install tekrsa-api-wrap\n```\n\n## Usage\n\nInterface with a supported Tektronix RSA device using Python as follows:\n\n```python\nimport rsa_api\n\n# Directory which contains both libRSA_API.so and libcyusb_shared.so\ndrivers_path = '/path/to/shared_objects/'\n\n# Initialize an RSA device using the API wrapper\nrsa = rsa_api.RSA(so_dir=drivers_path)\n\n# Example usage: connect, print current center frequency, then disconnect\nrsa.DEVICE_SearchAndConnect()\nprint(f\"Current Center Frequency (Hz): {rsa.CONFIG_GetCenterFreq()}\")\nrsa.DEVICE_Disconnect()\n\n# Print docstrings for any implemented API function\nhelp(rsa.IQSTREAM_Acquire) # Requires initialized RSA device\nhelp(rsa_api.RSA.IQSTREAM_Acquire) # Does not require initalized RSA device\n```\n\n### List of API functions NOT implemented\n\n- All functions not supported by the RSA API for Linux (see \"Known Issues\" below)\n- All `DPX`, `PLAYBACK`, `IFSTREAM` and `TRKGEN` functions\n- `DEVICE_GetErrorString()`\n - Alternate error handling is implemented.\n- `DEVICE_GetNomenclatureW()` and `IQSTREAM_SetDiskFilenameBaseW()`\n - `DEVICE_GetNomenclature()` and `IQSTREAM_SetDiskFilenameBase()` are used instead.\n- `IQBLK_GetIQDataCplx()`\n - `IQBLK_GetIQData()` and `IQBLK_GetIQDataDeinterleaved()` are used instead.\n\n### List of API \"Helper\" functions\n\nA handful of useful functions are included in this wrapper which streamline some common\ntasks. These \"helper functions\" include:\n\n- `IQSTREAM_Acquire()`\n- `IQBLK_Acquire()`\n- `IQBLK_Configure()`\n- `SPECTRUM_Acquire()`\n- `IQSTREAMFileInfo_StatusParser()`\n- `IQSTREAMIQInfo_StatusParser()`\n- `IQSTREAM_Tempfile()`\n- `IQSTREAM_Tempfile_NoConfig()`\n- `DEVICE_SearchAndConnect()`\n- `DEVICE_GetTemperature()`\n\nTo read more about these functions, check their docstrings with `help()`.\n\n### Known Issues\n\nKnown issues exist in the underlying Tektronix RSA API for Linux, and therefore this\nwrapper is limited in certain ways. The list of known issues is provided by Tektronix in\nthe [Tektronix RSA API for Linux release notes](https://download.tek.com/software/supporting_files/ReleaseNotes_1_0_0014_64bit_066207701.txt)\n(up-to-date as of version 1.0.0014).\n\n### TODO: Update this section after resolving\n\nAdditionally, a known issue exists with parsing IQ streaming status data structures.\nThere appears to be a discrepancy between the documented status message encoding scheme\nand the implemented encoding scheme. In its current implementation, this API wrapper has\nbeen tested to ensure that ADC overrange events are properly flagged when using\n`IQSTREAM_Tempfile`, `IQSTREAM_Tempfile_NoConfig` or `IQSTREAM_Acquire` methods. Buffer\noverflow warnings and errors should work, but have not been tested. The USB data\ndiscontinuity status is unable to be parsed. Unknown IQ stream status codes are treated\nas errors and handled as configured in `IQSTREAM_StatusParser`.\n\n## Development\n\n### Development Environment\n\nSet up a development environment using a tool like\n[Conda](https://docs.conda.io/en/latest/)\nor [venv](https://docs.python.org/3/library/venv.html#module-venv), with `python>=3.8`.\nThen, from the cloned directory, install the development dependencies by running:\n\n```bash\npip install .[dev]\n```\n\nThis will install the project itself, along with development dependencies for pre-commit\nhooks, building distributions, and running tests. Set up pre-commit, which runs\nauto-formatting and code-checking automatically when you make a commit, by running:\n\n```bash\npre-commit install\n```\n\nThe pre-commit tool will auto-format Python code using [Black](https://github.com/psf/black)\nand [isort](https://github.com/pycqa/isort). Other pre-commit hooks are also enabled, and\ncan be found in [`.pre-commit-config.yaml`](.pre-commit-config.yaml).\n\n### Building New Releases\n\nThis project uses [Hatchling](https://github.com/pypa/hatch/tree/master/backend) as a\nbackend. Hatchling makes version control and building new releases easy. The package\nversion can be updated easily using any of the following commands.\n\n```bash\nhatchling version major # 1.0.0 -> 2.0.0\nhatchling version minor # 1.0.0 -> 1.1.0\nhatchling version micro # 1.0.0 -> 1.0.1\nhatchling version \"X.X.X\" # 1.0.0 -> X.X.X\n```\n\nTo build a wheel and source distribution, run:\n\n```bash\nhatchling build\n```\n\n### Running Tests\n\nA testing file is included in the `tests` directory of this repository. The test uses\n`unittest` to test supported API functions. Running a test requires an RSA device to be\nconnected. The same test is used for any supported RSA device, with some tests being\nenabled, disabled, or modified as needed depending on the device's specific supported\nAPI functions. For example, tests of the preamp configuration are not run when testing\nwith an RSA which does not have a preamp.\n\nFrom the top-level directory of this repository, run the test by running:\n\n ```bash\n export SO_DIR=/path/to/drivers\n python -X faulthandler -m unittest\n ```\n\nReplacing `<path-to-shared-objects>` with the path to a directory containing both\n`libRSA_API.so` and `libcyusb_shared.so`.\n\nThis testing code was been adapted from the\n[Tektronix Cython RSA API testing code for the 306B](https://github.com/tektronix/RSA_API/blob/master/Python/Cython%20Version/test_rsa306b.py)\nand [for the 500A/600A series devices](https://github.com/tektronix/RSA_API/blob/master/Python/Cython%20Version/test_rsa500-600.py).\nIn addition to adapting this code to work with this API wrapper, various tests were also\nadded which were not present in the original versions, and the test was made to be\nuniversal for all supported RSA devices.\n\n## License\n\nSee [LICENSE](LICENSE.md)\n\nTEKTRONIX and TEK are registered trademarks of Tektronix, Inc.\n\nMicrosoft and Windows are trademarks of the Microsoft group of companies.\n\n## Contact\n\nFor technical questions, contact Anthony Romaniello, aromaniello@ntia.gov\n\n## Disclaimer\n\nCertain commercial equipment, instruments, or materials are identified in this project\nwere used for the convenience of the developers. In no case does such identification\nimply recommendation or endorsement by the National Telecommunications and Information\nAdministration, nor does it imply that the material or equipment identified is necessarily\nthe best available for the purpose.\n",
"bugtrack_url": null,
"license": "SOFTWARE DISCLAIMER / RELEASE This software was developed by employees of the National Telecommunications and Information Administration (NTIA), an agency of the Federal Government and is provided to you as a public service. Pursuant to Title 15 United States Code Section 105, works of NTIA employees are not subject to copyright protection within the United States. The software is provided by NTIA \u201cAS IS.\u201d NTIA MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. NTIA does not warrant or make any representations regarding the use of the software or the results thereof, including but not limited to the correctness, accuracy, reliability or usefulness of the software. To the extent that NTIA holds rights in countries other than the United States, you are hereby granted the non-exclusive irrevocable and unconditional right to print, publish, prepare derivative works and distribute the NTIA software, in any medium, or authorize others to do so on your behalf, on a royalty-free basis throughout the World. You may improve, modify, and create derivative works of the software or any portion of the software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the software and should note the date and nature of any such change. You are solely responsible for determining the appropriateness of using and distributing the software and you assume all risks associated with its use, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This software is not intended to be used in any situation where a failure could cause risk of injury or damage to property. Please provide appropriate acknowledgments of NTIA\u2019s creation of the software in any copies or derivative works of this software.",
"summary": "NTIA/ITS Python wrapper for the Tektronix RSA API for Linux",
"version": "1.3.2",
"split_keywords": [
"api",
"linux",
"rf",
"rsa",
"scos",
"sdr",
"tektronix",
"analyzer",
"radio",
"spectrum",
"wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f8534775707295cd15a62ac3cbc9744974d0762878851d03250b26c5003105c6",
"md5": "9135ed2f556d9c198fbd613c6cef4a47",
"sha256": "3b71582c8d2cec07f62922699b59059786258173373bf5038febc7e37bac8803"
},
"downloads": -1,
"filename": "tekrsa_api_wrap-1.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9135ed2f556d9c198fbd613c6cef4a47",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25998,
"upload_time": "2023-04-18T20:41:51",
"upload_time_iso_8601": "2023-04-18T20:41:51.055174Z",
"url": "https://files.pythonhosted.org/packages/f8/53/4775707295cd15a62ac3cbc9744974d0762878851d03250b26c5003105c6/tekrsa_api_wrap-1.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9ef265185b18eb7fde6dfa4a10fba20fb1e2ae5c0a25b819447ec53430830742",
"md5": "c9358c37fa12cec9f3590fcd0bae52b8",
"sha256": "8f3c3ebf4741f7e283e368339a09151a8c6063a145c34306c4456eaf4915575a"
},
"downloads": -1,
"filename": "tekrsa_api_wrap-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "c9358c37fa12cec9f3590fcd0bae52b8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 30785,
"upload_time": "2023-04-18T20:44:35",
"upload_time_iso_8601": "2023-04-18T20:44:35.677736Z",
"url": "https://files.pythonhosted.org/packages/9e/f2/65185b18eb7fde6dfa4a10fba20fb1e2ae5c0a25b819447ec53430830742/tekrsa_api_wrap-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-18 20:44:35",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "tekrsa-api-wrap"
}
