Usage
Window Configuration
Prior to the start of a payload window, the satellite bus will boot up the payload. It will then place a window configuration JSON file with information for the upcoming payload window on the payload's file system. 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 2.
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.
Example window config file contents (exact schema will vary depending on the mission):
{
"version": 2,
"signal_parameters": {
"tasking_parameters": {
"key1": "some value",
"Key2": "some other value"
}
}
}
Uplink
Files submitted for uplink through the Tasking API are made available to payloads through the Spire Linux Agent. A payload executable can use the Spire Linux Agent API to get a list of available files and, using the unique ID associated with each file, it can request to retrieve a file to a location on the filesystem.
During the signaling configure step of a payload window, the bus may be transferring available files to the payload Spire Linux Agent at any point. As such, the payload executable should poll the Spire Linux Agent multiple times throughout the configure step to ensure it receives the latest list of available files.
Metadata provided with each file contains a set of delivery hints configured through the Tasking API which the payload executable can inspect to decide how to handle a particular file. These include, but are not limited to, a destination path and a UNIX mode string. It is up to the payload executable if/how it makes use of available delivery hints. For a complete list of available delivery hints, please see FileInfo
Configure
Following payload start-up, 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 specific window config provided by the bus or otherwise prepare for the upcoming window execution.
The payload should use at least some of the configure step time to query the Spire Linux Agent for any uplinked files.
As it will be invoked synchronously, the configure signal call must return by the deadline provided via the -t <step_end_time_epoch> parameter, otherwise the bus will consider that the payload hasn't been successfully configured and will abort the payload window.
A non-zero return code for the configure signal call will also lead to the bus aborting the payload window and gracefully powering off the payload without sending the execute signal.
For example: If a payload window with ID 1304893 is expected to complete its configure signal call by Friday, 26 July 2024 06:29:33Z (epoch 1721975373), the bus config signal call to the payload_exec on the payload would be:
/usr/bin/payload_exec -w 1304893 -u john -e -t 1721975373 > /dev/null
The configure signal call to the payload_exec will now include the -t <step_end_time_epoch> parameter similar to the execution signal call, which indicates the time the bus expects the configure signal call to return by.
Arguments
| Argument | Type | Description |
|---|---|---|
| -e | flag | A flag that indicates this call is the configure signal call |
| -t | float | Configure signal end time in UNIX timestamp format |
| -u | string | ID of the user that created the window via the Tasking API |
| -w | int | ID of upcoming window |
/usr/bin/payload_exec -u john -e -w 1304893 > /dev/null
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.
For example: If a payload window with ID has an end time (end_time as defined by the Tasking API) of Friday, 26 July 2024 09:39:53 (epoch 1721986793), the bus execute signal call to the payload_exec on the payload would be:
nohup /usr/bin/payload_exec -u john -w 1304893 -t 1611718292 &> /dev/null &
Arguments
| Argument | Type | Description |
|---|---|---|
| -w | int | ID of upcoming window |
| -u | string | ID of the user that created the window via the Tasking API |
| -t | float | Execute signal end time in UNIX timestamp format |
The payload_exec will never be called with any parameters other than the ones specified above for a respective Signaling API step. Any extra parameters/information the payload_exec requires should be added to the tasking_parameters section of the window parameters at scheduling time and it will then be made available to the payload_exec through the window config file.
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 log files should be sent through the Spire Linux Agent. 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 Spire Linux Agent. Additionally, following the window start signal, ethernet for the payload may be shut down before the window completes.