Overview

SCOS Sensor was designed by NTIA/ITS with the following goals in mind:

• Easy-to-use sensor control and data retrieval via IP network
• Low-cost, open-source development resources
• Design flexibility, to allow developers to evolve sensor technologies and metrics
• Hardware agnostic
• Discoverable sensor capabilities
• Task scheduling, using start/stop times, repeat intervals, and/or task priority
• Standardized metadata/data format that supports cooperative sensing and open data initiatives
• Security controls to prevent unauthorized users from accessing sensor functionality
• Easy-to-deploy with provisioned and configured OS
• Quality assurance of software via automated testing prior to release

Design and Usage

Sensor control is accomplished through a RESTful API. The API is designed to be rich enough that multiple heterogeneous sensors can be automated effectively while being simple enough to still be useful for single-sensor deployments. For example, by advertising capabilities and location, an owner of multiple sensors can easily filter by frequency range, available actions, or geographic location. Yet, since each sensor hosts its own Browsable API, controlling small deployments is as easy as clicking around a website.

Opening the URL to your sensor (localhost if you followed Tutorial 1) in a browser, you will see a frontend to the API that allows you to do anything the JSON API allows. Relationships in the API are represented by URLs which you can click to navigate from endpoint to endpoint. The full API is discoverable simply by following these links:

Scheduling an action is as simple as filling out a short form on /schedule:

Actions that have been scheduled show up in the schedule entry list:

We have tried to remove the most common hurdles to remotely deploying a sensor while maintaining flexibility in two key areas. First, the API itself is hardware agnostic, and the implementation assumes different hardware will be used depending on sensing requirements. Second, we introduce the high-level concept of "actions" which gives the sensor owner control over what the sensor can be tasked to do. Read more about actions on the dedicated Actions wiki page. For more information about hardware support, refer to the Hardware Support page. Finally, for a glossary of terms, see Glossary

Repository Structure

• .github/workflows: workflow configurations for automated testing with GitHub Actions
• configs/: contains the sensor definition file and, optionally, a preselector configuration file and one or more calibration files.
  • configs/actions: used for sideloading actions. Placing YAML action files in this directory will cause the action to be initialized when SCOS Sensor starts.
  • configs/certs: CA, server, and client certificates.
  • configs/switches: configuration files for relays to be loaded by the preselector module
• docker/: Dockerfiles used by SCOS Sensor: one for the API container, one for the autoheal container, and one for the NGINX container.
• docs/: documentation, including the documentation hosted on GitHub pages generated from the OpenAPI specification.
• drivers/: Location to place driver files required by hardware. The drivers/files.json file is used to programmatically copy driver files into the Docker container as-needed. See the drivers directory README for more information about this functionality.
• entrypoints/: Docker entrypoint scripts which are executed when starting a container.
• gunicorn/config.py: Gunicorn configuration file.
• nginx/: NGINX configuration template and SSL certificates.
• scripts: Various utility scripts.
• src: Contains the SCOS Sensor source code.
  • src/authentication: Code related to user authentication.
  • src/capabilities: Code used to generate capabilities endpoint.
  • src/constants: Constants shared by the other source code folders.
  • src/handlers: Code to handle signals received from actions.
  • src/initialization: Code for handling initialization, including action loading
  • src/schedule: Schedule API endpoint for scheduling actions.
  • src/scheduler: Scheduler responsible for executing actions.
  • src/sensor: Core app which contains the settings, generates the API root endpoint.
  • src/static: Django will collect static files (JavaScript, CSS, …) from all apps to this location.
  • src/status: Status endpoint.
  • src/tasks: Tasks endpoint used to display upcoming and completed tasks.
  • src/templates: HTML templates used by the browsable API.
  • src/test_utils: Utility code used in tests.
  • src/utils: Utility code shared by the other source code folders.
  • src/conftest.py: Used to configure pytest fixtures.
  • src/manage.py: Django’s command line tool for administrative tasks.
  • src/requirements.in and src/requirements-dev.in: Direct Python dependencies.
  • src/requirements.txt and src/requirements-dev.txt: Python dependencies including transitive dependencies.
  • src/tox.ini: Used to configure tox.
• compose.yaml: Used by Docker Compose to create services from containers. This is needed to run SCOS Sensor.
• env.template: Template file for setting environment variables used to configure SCOS Sensor.