Skip to content

Overview

Jump to bottom
Anthony Romaniello edited this page May 10, 2024 · 6 revisions

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:

Browsable API Root

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

Browsable API Submission

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

Browsable API Schedule 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 definition 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.
  • 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.
Clone this wiki locally