Package: tekrsa-api-wrap
NTIA/ITS Python Wrapper for Tektronix® RSA API for LinuxThis Python package provides a module which wraps theTektronix 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 comprehensiveRSA API Programming Reference manualoffered 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 theTektronix Python/Cython RSA APIinstead of using this wrapper.Table of ContentsInstallationUsageDevelopmentLicenseContactDisclaimerInstallationRequirespython>=3.8,numpy>=1.22, and the Tektronix RSA API for Linux.First, download and install theRSA API for Linuxfrom Tektronix. Follow the included installation instructions, then copy thelibRSA_API.soandlibcyusb_shared.sofiles into your project.These shared object files are required, and this API wrapper by default expects to find
them in theSCOS Sensordrivers directory
(/drivers/). If you are running without SCOS Sensor, you will need to specify your
drivers directory when instantiating the API wrapper. See theUsage sectionbelow for an example of how to do this.Next download and install this API wrapper usingpip:pipinstalltekrsa-api-wrapUsageInterface with a supported Tektronix RSA device using Python as follows:importrsa_api# Directory which contains both libRSA_API.so and libcyusb_shared.sodrivers_path='/path/to/shared_objects/'# Initialize an RSA device using the API wrapperrsa=rsa_api.RSA(so_dir=drivers_path)# Example usage: connect, print current center frequency, then disconnectrsa.DEVICE_SearchAndConnect()print(f"Current Center Frequency (Hz):{rsa.CONFIG_GetCenterFreq()}")rsa.DEVICE_Disconnect()# Print docstrings for any implemented API functionhelp(rsa.IQSTREAM_Acquire)# Requires initialized RSA devicehelp(rsa_api.RSA.IQSTREAM_Acquire)# Does not require initalized RSA deviceList of API functions NOT implementedAll functions not supported by the RSA API for Linux (see "Known Issues" below)AllDPX,PLAYBACK,IFSTREAMandTRKGENfunctionsDEVICE_GetErrorString()Alternate error handling is implemented.DEVICE_GetNomenclatureW()andIQSTREAM_SetDiskFilenameBaseW()DEVICE_GetNomenclature()andIQSTREAM_SetDiskFilenameBase()are used instead.IQBLK_GetIQDataCplx()IQBLK_GetIQData()andIQBLK_GetIQDataDeinterleaved()are used instead.List of API "Helper" functionsA 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 withhelp().Known IssuesKnown 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
theTektronix RSA API for Linux release notes(up-to-date as of version 1.0.0014).TODO: Update this section after resolvingAdditionally, 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 usingIQSTREAM_Tempfile,IQSTREAM_Tempfile_NoConfigorIQSTREAM_Acquiremethods. 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 inIQSTREAM_StatusParser.DevelopmentDevelopment EnvironmentSet up a development environment using a tool likeCondaorvenv, withpython>=3.8.
Then, from the cloned directory, install the development dependencies by running:pipinstall.[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:pre-commitinstallThe pre-commit tool will auto-format Python code usingBlackandisort. Other pre-commit hooks are also enabled, and
can be found in.pre-commit-config.yaml.Building New ReleasesThis project usesHatchlingas a
backend. Hatchling makes version control and building new releases easy. The package
version can be updated easily using any of the following commands.hatchlingversionmajor# 1.0.0 -> 2.0.0hatchlingversionminor# 1.0.0 -> 1.1.0hatchlingversionmicro# 1.0.0 -> 1.0.1hatchlingversion"X.X.X"# 1.0.0 -> X.X.XTo build a wheel and source distribution, run:hatchlingbuildRunning TestsA testing file is included in thetestsdirectory of this repository. The test usesunittestto 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:exportSO_DIR=/path/to/drivers
python-Xfaulthandler-munittestReplacing<path-to-shared-objects>with the path to a directory containing bothlibRSA_API.soandlibcyusb_shared.so.This testing code was been adapted from theTektronix Cython RSA API testing code for the 306Bandfor 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.LicenseSeeLICENSETEKTRONIX and TEK are registered trademarks of Tektronix, Inc.Microsoft and Windows are trademarks of the Microsoft group of companies.ContactFor technical questions, contact Anthony Romaniello,aromaniello@ntia.govDisclaimerCertain 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.