NTIA/ITS SCOS Tektronix® RSA Plugin

This repository is a plugin to add support for the Tektronix RSA306, RSA306B, RSA503A, RSA507A, RSA513A, RSA518A, RSA603A, and RSA607A real-time spectrum analyzers to SCOS Sensor, developed by NTIA/ITS. See the SCOS Sensor documentation for more information about SCOS Sensor, especially the section about Actions and Hardware Support.

This plugin requires the RSA API for Linux by Tektronix. A custom Python wrapper for this API is also used to mask Ctypes syntax, handle error-checking, and implement helper methods.

This repository also includes many 700 MHz band actions in scos_tekrsa/configs/actions-300 and CBRS band (3550-3700 MHz) actions in scos_tekrsa/configs/actions-500-600. Actions are defined separately for RSA300- and RSA500/600-series devices, allowing for preamp and attenuation control of the RSA500/600-series devices. Action classes, SignalAnalyzerInterface, and signals are used from the SCOS Actions Plugin.

For information on adding actions, see the SCOS Actions Plugin documentation.

Table of Contents

• Overview of Repo Structure
• Running in SCOS Sensor
• Development
• License
• Contact
• Disclaimer

Overview of Repo Structure

• scos_tekrsa/configs: Contains YAML files with the parameters used to initialize the Tektronix RSA supported actions
• scos_tekrsa/discover: Includes the code to read YAML files and make actions available to scos-sensor
• scos_tekrsa/hardware: Includes an implementation of the signal analyzer interface for Tektronix RSA devices, along with supporting test code

Running in SCOS Sensor

Requires git, python>=3.9, pip>=18.1, and pip-tools>=6.6.2

Below are the steps to run SCOS Sensor with the SCOS Tektronix RSA plugin:

1. Clone scos-sensor:

   git clone https://github.com/NTIA/scos-sensor.git

2. Navigate to the cloned scos-sensor directory:

   cd scos-sensor

3. If testing locally, generate the necessary SSL certificates by running:

   cd scripts && ./create_localhost_cert.sh

4. While in the scos-sensor directory, create the env file by copying the template file:

   cp env.template ./env

5. In the newly-created env file, set the following environment variables:

   DEVICE_MODEL=RSA507A  # Or 'RSA306B', 'RSA517A', etc.
   # These are the same for all supported Tektronix RSA devices:
   BASE_IMAGE=ghcr.io/ntia/scos-tekrsa/tekrsa_usb:latest
   USB_DEVICE=Tektronix
   SIGAN_CLASS=TekRSASigan
   SIGAN_MODULE=scos_tekrsa.hardware.tekrsa_sigan
   

6. Get environment variables:

   source ./env

7. In scos-sensor/src/requirements.in, remove or comment any unnecessary dependencies (such as scos_usrp), then add the scos_tekrsa dependency:

   # Be sure to provide the correct tag for the desired version
   scos_tekrsa @ git+https://github.com/NTIA/[email protected]
   

8. Compile requirements by running:

   cd src
   pip-compile requirements.in
   pip-compile requirements-dev.in

9. Download the RSA API for Linux from Tektronix. Place the three files libRSA_API.so, libcyusb_shared.so, and cyusb.conf in the directory scos-sensor/drivers.

10. Create a files.json file in scos-sensor/drivers containing:

    {
        "scos_files": [
            {
                "source_path": "cyusb.conf",
                "dest_path": "/etc/cyusb.conf"
            }
        ]
    }

11. Build and start containers (and optionally, view logs):

    docker-compose build --no-cache
    docker-compose up -d --force-recreate
    docker-compose logs -f

Development

Development Environment

Set up a development environment using a tool like Conda or venv, with python>=3.9. Then, from the cloned directory, install the development dependencies by running:

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:

pre-commit install

The pre-commit tool will auto-format Python code using Black and isort. Other pre-commit hooks are also enabled, and can be found in .pre-commit-config.yaml.

Updating the scos_tekrsa package

This project uses Hatchling as a backend. Hatchling makes versioning and building new releases easy. The package version can be updated easily by using any of the following commands.

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 new release (both wheel and sdist/tarball), run:

hatchling build

Updating the tekrsa_usb package

To build, tag the version as X.X.X, and push the updated image to the GitHub Container Registry, run:

docker build -f docker/Dockerfile -t tekrsa_usb .
docker tag tekrsa_usb ghcr.io/ntia/scos-tekrsa/tekrsa_usb:X.X.X
docker tag tekrsa_usb ghcr.io/ntia/scos-tekrsa/tekrsa_usb:latest
docker push ghcr.io/ntia/scos-tekrsa/tekrsa_usb:X.X.X
docker push ghcr.io/ntia/scos-tekrsa/tekrsa_usb:latest

Running Tests

The scos_tekrsa plugin is tested using tox and the pytest framework. The following commands can be used to run tests and show coverage reports.

pytest          # faster, but less thorough
tox             # test code in virtual environments for multiple versions of Python
tox --recreate  # To recreate the virtual environments used for testing

License

See LICENSE

TEKTRONIX and TEK are registered trademarks of Tektronix, Inc.

Contact

For technical questions about scos_tekrsa, contact the ITS Spectrum Monitoring Team.

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.