Glossary

This page provides an overview and definitions of high-level concepts used by SCOS Sensor.

• Action: A function that the sensor owner implements and exposes to the API. Actions are the things that the sensor owner wants the sensor to be able to do. Since actions block the scheduler while they run, they have exclusive access to the sensor's resources (like the signal analyzer). Currently, there are several logical groupings of actions, such as those that create acquisitions, or admin-only actions that handle administrative tasks. However, actions can theoretically do anything a sensor owner can implement. Some less common (but perfectly acceptable) ideas for actions might be to rotate an antenna, or start streaming data over a socket and only return when the recipient closes the connection.

• Acquisition: The combination of data and metadata created by an action (though an action does not have to create an acquisition). Metadata is accessible directly though the API, while data is retrievable in an easy-to-use archive format with its associated metadata.

• Admin: A user account that has full control over the sensor and can create schedule entries and view, modify, or delete any other user's schedule entries or acquisitions.

• Capability: Available actions, installation specifications (e.g., mobile or stationary), and operational ranges of hardware components (e.g., frequency range of signal analyzer). These values are generally hard-coded by the sensor owner and rarely change.

• Plugin: A Python package with actions designed to be integrated into SCOS Sensor.

• Schedule: The collection of all schedule entries (active and inactive) on the sensor.

• Scheduler: A thread responsible for executing the schedule. The scheduler reads the schedule at most once a second and consumes all past and present times for each active schedule entry until the schedule is exhausted. The latest task per schedule entry is then added to a priority queue, and the scheduler executes the associated actions and stores/POSTs task results. The scheduler operates in a simple blocking fashion, which significantly simplifies resource deconfliction. When executing the task queue, the scheduler makes a best effort to run each task at its designated time, but the scheduler will not cancel a running task to start another task, even one of higher priority.

• Schedule entry: Describes a range of scheduler tasks. A schedule entry is at minimum a human readable name and an associated action. Combining different values of start, stop, interval, and priority allows for flexible task scheduling. If no start time is given, the first task is scheduled as soon as possible. If no stop time is given, tasks continue to be scheduled until the schedule entry is manually deactivated. Leaving the interval undefined results in a "one-shot" entry, where the scheduler deactivates the entry after a single task is scheduled. One-shot entries can be used with a future start time. If two tasks are scheduled to run at the same time, they will be run in order of priority. If two tasks are scheduled to run at the same time and have the same priority, execution order is implementation-dependent (undefined).

• Signals: Django event driven programming framework. Actions use signals to send results to SCOS Sensor. These signals are handled by SCOS Sensor so that the results can be processed (such as storing measurement data and metadata).

• Task: A representation of an action to be run at a specific time. When a task acquires data, that data is stored on disk, and a significant amount of metadata is stored in a local database. The full metadata can be read directly through the self-hosted website or retrieved in plain text via a single API call. Our metadata and data format is an extension of, and compatible with, the SigMF specification - see sigmf-ns-ntia.

• Task Result: A record of the outcome of a task. A result is recorded for each task after the action function returns, and includes metadata such as when the task started, when it finished, its duration, the result (success or failure), and a freeform detail string. A TaskResult JSON object is also POSTed to a schedule entry's callback_url, if provided.