NAV
shell

Payload Signaling API - v1.0

The Signaling API defines the interface that payloads must expose for the satellite bus to inform the payloads of upcoming events.

The API consists of:

  1. A payload executable used to respond to satellite bus events. This executable will be called by the bus using SSH.
  2. Conventions of where window configuration files and uplinked files are placed on the payload file system by the satellite bus.
  3. Window configuration file schemas provided by the satellite bus for payload executables to use. These window configuration files contains bus information about the signal as well as relevant data passed through from the Tasking API.
  4. Argument schemas that payload executables must accept to handle satellite bus signals.

Transmission of data from the payload to the ground is handled via the OORT Agent process on the payload.

It is the responsibility of the payload to implement an executable that can be called with certain parameters after the window configuration file is placed on the payload file system. This executable will interpret the window configuration file and perform the necessary payload actions.

Prerequisites

The Signaling API requires payloads to:

  1. Run a linux operating system
  2. Have an ethernet connection to the satellite bus
  3. Have an SSH daemon running
  4. Provision a user for the Signaling API to use for SSH commands

Filesystem Conventions

The Signaling API requires that certain conventions be followed when using the payload filesystem to place configuration files and uploaded data.

/usr/bin/payload_exec - Executable used by the satellite bus when signal commands are executed. Signaling API user must have execute permissions.

/signaling/inbox/ - Directory used by satellite bus to place uplinked files destined for the payload. Signaling API user must have write access.

/signaling/window_configs/ - Directory used by satellite bus to place window configuration .json files. Signaling API user must have write access.

Additional Permissions

The Signaling API user must also have root or sudo privileges to alter the system clock for time synchronization and to issue halt/shutdown commands at the completion of a payload window

Usage

Window Configuration

Prior to the start of a payload window, the satellite bus will boot up the payload and place on it's file system a window configuration JSON file containing configuration for the upcoming payload window. This configuration includes information provided by the bus and any parameters defined during the creation of the window in the Tasking API.

Additionally there will be a version number included in the root dictionary. The current version is 1.

The filename is constructed using the window id and the json file extension. For example, for a window with id = 1304893, the window configuration file location would be /signaling/window_configs/1304893.json

{
    "version": 1,
    "signal_parameters": {
        "lunch_money": 1.72,
        "greeting": "hello, world!",
        "tasking_parameters": {
            "key1": "some value",
            "Key2": "some other value"
        }
    }
}

On payload startup the satellite bus will place any files uploaded through the tasking API into the payload's inbox directory under the Tasking API user that has requested it.

For example if Tasking API user john requested an upload of file foo.sh the satellite bus will place the file on the payload at path /signaling/inbox/john/foo.sh

Configure

The payload will be switched on in advance of a scheduled window. Following payload startup the satellite bus will issue a configure signal, invoking payload_exec and supplying the -e argument.

The configure signal allows the payload to reconfigure itself based on the ID of the window. The payload may, for example, move any new uplinked files out of the inbox directory. As it will be invoked synchronously, the configure step should complete quickly, within 15 seconds or less.

/usr/bin/payload_exec -u john -e -w 1304893 > /dev/null

Arguments

-w - ID of upcoming window

-u - ID of the user that created the window via the Tasking API

Window Start

At the start of a payload window (start_time, as defined by the Tasking API), the satellite bus will issue a window start signal, asynchronously.

nohup /usr/bin/payload_exec -u john -w 1304893 -t 1611718292 &> /dev/null &

Arguments

-w - Window ID

-t - Window end time in UNIX timestamp format

-u - ID of the user that created the window via the Tasking API

Window End

At the end of a window the satellite bus will issue a shutdown command to the payload. At some time after this command, power to the payload will be cut.

Error Handling

The configure step may return a nonzero exit code, this will cause the whole window to be aborted. It may also output to stderr, but generally it should send log files through the OORT API. Ethernet will be switched on throughout the configure step.

The window start signal is issued asynchronously. Its exit code, stdout and stderr will not be captured. The payload_exec program is responsible for sending down any log files through the OORT API. Additionally, following the window start signal, ethernet for the payload may be shut down before the window completes.