Tutorial 2: Run SCOS Sensor with an Attached Signal Analyzer

This tutorial provides instructions to spin up a production-grade SCOS sensor using a Tektronix® RSA or Ettus B2xx signal analyzer. If you don't have an available signal analyzer, you can try out SCOS Sensor using mocked hardware as shown in Tutorial 1.

Requirements

• Linux computer (ARM devices, such as Raspberry Pi, are not currently supported)
• Tektronix RSA 3xx, 5xx, or 6xx USB spectrum analyzer, OR
• Ettus USRP B2xx software-defined radio
• Python 3.9 or newer
• Docker and Docker Compose

Background: Hardware Support

Hardware support for devices including signal analyzers and preselectors is provided using SCOS Plugins. For more information, see the Hardware Support wiki page.

Tutorial

By default, SCOS Sensor is configured to support Tektronix RSA spectrum analyzers. The steps below provide additional instructions to modify the configuration if using an Ettus USRP B2xx device instead. These additional steps are not required when using a Tektronix RSA device.

1. Install Git, Docker, and Docker Compose

2. Download SCOS Sensor by cloning the GitHub repository:

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

3. [If using USRP] Update the required signal analyzer plugin. In src/requirements.in, replace the scos_tekrsa requirement with the latest version of scos_usrp, for example:

   scos_usrp @ git+https://github.com/NTIA/[email protected]
   

   After editing this file, recompile the full requirements files by running:

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

   Using the pip-tools command will ensure that any additional required dependencies are located and written to the requirements.txt and requirements-dev.txt files.

4. Optionally, populate the sensor definition file. This is highly recommended for a production sensor, but not required if you're just testing locally. For more information, see the Component Definition Files page. This step can be skipped entirely if desired.

5. Copy the template environment variables file, env.template, and modify it if needed. The default settings in this file are configured to run a development environment on your local system. See Configuring SCOS Sensor for details about each of these options.

   cp env.template env

6. [If using USRP] Modify the following settings inside the new env file, to configure SCOS Sensor to use a USRP device:

   BASE_IMAGE=ghcr.io/ntia/scos-usrp/scos_usrp_uhd:0.0.2
   SIGAN_MODULE=scos_usrp.hardware.usrp_sigan
   SIGAN_CLASS=USRPSignalAnalyzer

   Additionally, remove or comment out the following setting:

   USB_DEVICE=Tektronix

7. Source the changes to the environment variables:

   source ./env

8. Create the sensor certificate. A script is provided to generate a certificate authority (CA) and localhost SSL certificate for the sensor. The CA and sensor certificate will have dummy values for the subject and password, and should only be used for testing purposes. This testing setup will allow you to connect to the SCOS Sensor web API from the same computer where it is hosted. To create a certificate specific to your host and organization, see the Security page.

   bash ./scripts/create_localhost_cert.sh

9. Run the Dockerized stack.

   docker compose up -d --build
   docker compose logs --follow api

Success! Check out the SCOS Sensor browsable API at localhost!