tekrsa-api-wrap 1.2.1

NTIA/ITS Python wrapper for the Tektronix RSA API for Linux

NTIA/ITS Python Wrapper for Tektronix® RSA API for Linux

This Python package provides a module which wraps the Tektronix Python/Ctypes RSA API, 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 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 instead of using this wrapper.

Table of Contents

• Installation
• Usage
• Development
• License
• Contact
• Disclaimer

Installation

Requires python>=3.7, numpy>=1.21, and the Tektronix RSA API for Linux.

First, download and install the RSA API for Linux 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 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 below for an example of how to do this.

Next, download the most recent release of this package, and install it using pip:

pip install tekrsa_api_wrap-1.2.0.tar.gz

Usage

Interface with a supported Tektronix RSA device using Python as follows:

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_Tempfile) # Requires initialized RSA device
help(rsa_api.RSA.IQSTREAM_Tempfile)  # 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.
• IQSTREAM_GetIQData()
  • IQSTREAM_Tempfile() is 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:

• IQBLK_Acquire()
• IQBLK_Configure()
• SPECTRUM_Acquire()
• IQSTREAM_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 (up-to-date as of version 1.0.0014):

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:

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 and for the 500A/600A series devices. 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.

Development

Backend

This project uses Hatchling as a backend. Hatchling makes version control and building new releases easy. First, install hatchling into your development environment:

pip install hatchling

After making updates, the package version can be updated easily using any of the following:

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 distribution and source distribution, run:

hatchling build

When using hatchling version, there's no need to update package metadata with the new version number.

Committing

This project uses pre-commit, a utility which automates setting up pre-commit hooks. These hooks run the auto-formatters Black and isort. In addition to Black and isort, various other pre-commit tools are enabled including markdownlint. See .pre-commit-config.yaml for the list of pre-commit tools enabled for this repository. Install pre-commit by running:

pip install pre-commit

Then simply type the following once, and each time you make a commit, it will be appropriately auto-formatted.

pre-commit install

You can also manually run the pre-commit hooks on the entire project:

pre-commit run --all-files

License

See LICENSE

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, [e-mail]

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.