Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Gateways connect a system (a satellite or ground station) to Major Tom using Major Tom's WebSocket-based Gateway API.

New to Major Tom?

We recommend running our Example Python Gateway locally to get started!
It's intended to give you a feel for how to interact with satellites from Major Tom and give an example of how to use the API documented below.
No coding is required to use it! Just follow the README instructions in the repository.

Gateways in Major Tom

Major Tom's concept of a Gateway is simply a named channel of communication. Gateways have a token that is used to authenticate with Major Tom. Setup a Gateway on your Mission and copy the token.

  • Gateways are just named communication channels with authentication.

  • If you want to have dev and prod environments, make two Gateways.

Connecting to Major Tom

  1. Open a WebSocket connection to Major Tom at /gateway_api/v1.0 (this probably looks like: wss://you.majortom.cloud/gateway_api/v1.0).

  2. Include the X-Gateway-Token HTTP header or gateway_token query param, set to a token from one of your Major Tom Gateways.

  3. Provide Basic Auth credentials for your Major Tom deployment. If your websocket client supports it, you may be able to include these in the connection string (e.g. wss://user:password@you.majortom.cloud/gateway_api/v1.0). Alternatively, your websocket client may allow you to provide the username and password as options. If not, you can do it yourself by encoding them in the HTTP Authorization header. See information on correct encoding.

  4. You should receive a message like {'type': 'hello', 'hello': { 'mission': 'your-mission' }} on connection if your X-Gateway-Token header (or gateway_token param) and Authorization header are valid.

Response Codes

  • 401 - If the server requires Basic Auth credentials and you haven't provided them, you will receive a 401 error.

  • 403 - If the Gateway Token is invalid, you will receive a 403 error.

  • 404 or 503 - If the Major Tom service is temporarily unavailable, you may receive a 404 or 503 error. You should wait a few seconds and try again.

Rate Limits

RATE_LIMIT_MESSAGE

<p>For message details, see <a href="#rate_limit">rate_limit</a>.</p>

General implementation advice

  • In order to be forward compatible, ignore messages and message fields that you don't understand.

  • Reconnect on disconnection after a short delay.

  • Buffer telemetry, events, and command updates until successful reconnection.

  • Dual-write any critical telemetry & events to local log files for redundancy.

Interactive Testing

<p>
You can issue test messages against this Gateway <a href="./tester">here</a>. Warning: this is a live connection to your Gateway!
</p>

File Transfer in Major Tom

<div>
There are examples of uplink and downlink flows, and suggestions of how to use the API to accomplish file transfers, in the
<a href="#file_transfer">file transfer section</a>. The examples assume knowledge of how Commands interact with a Gateway.
</div>

Messages from Major Tom

A Gateway will receive the following message types from Major Tom:

<ul>
<li>hello</li>
<li><a href="#command">command</a></li>
<li><a href="#cancel">cancel</a></li>
<li><a href="#rate_limit">rate_limit</a></li>
<li><a href="#error">error</a></li>
</ul>

Messages to Major Tom

A Gateway can send the following message types to Major Tom:

<ul>
<li><a href="#command">command_update</a></li>
<li><a href="#measurements">measurements</a></li>
<li><a href="#event">event</a></li>
<li><a href="#command_definitions_update">command_definitions_update</a></li>
<li><a href="#file_list">file_list</a></li>
<li><a href="#file_metadata_update">file_metadata_update</a></li>
</ul>

Other API actions

Some flows occur over a RESTful API:

<ul>
<li><a href="#file_upload">file_upload</a></li>
<li><a href="#file_download">file_download</a></li>
</ul>

<a name="command"></a>

Commands

A command from Major Tom represents a user's action to create and queue a Command based on a CommandDefinition.

Code Block
languagejson
{
  "type": "command",
  "command": {
    "id": 20,
    "type": "PowerUp",
    "system": "hamilton",
    "fields": [
      { "name": "parameter-1", "value": 1 },
      { "name": "parameter-2", "value": "foo" }
    ]
  }
}

Updating Commands

Note: Major Tom previously updated commands using a command_status message. This is (currently) still supported, but
we recommend upgrading to the new command_update message, detailed here.

Setting Command state

Commands in Major Tom transition through a series of states based on messages sent by your Gateway. The current state of a
command is displayed in the Major Tom UI along with the command's payload representation, current status, progress bars,
final output, and any errors that you report. It is up to you and your Gateway how you use these fields and the
available states, which are:

...

Code Block
languagejson
{
  "type": "command_update",
  "command": {
    "id": 20,
    "state": "acked_by_system"
  }
}
Validating the Command

When you first receive a Command, you should validate that the Command's fields are valid and correctly formatted for
your system given the command's type. If there is a validation error, your Gateway should transition the Command to
the failed state and provide one or more errors. For example:

Code Block
languagejson
{
  "type": "command_update",
  "command": {
    "id": 20,
    "state": "failed",
    "errors": ["parameter-2 must be longer than 5 characters", "PowerUp is invalid in the current run level"]
  }
}
Providing a Command payload & status

If the Command is valid, you will likely want to transition to preparing_on_gateway or uplinking_to_system,
whichever is appropriate for your Command lifecycle. At the same time, we recommend that you provide a payload
containing the domain-specific command representation that will be sent to your remote system. E.g., a HEX code or JSON
blob. This is optional, but if provided, Major Tom will show it in the UI for future debugging.

...

Code Block
languagejson
{
  "type": "command_update",
  "command": {
    "id": 20,
    "state": "uplinking_to_system",
    "status": "Waiting for pass",
    "payload": "mutation { powerUp { success, errors, pid } }"
  }
}
Update your Command fields as often as needed

When updating payload, errors, status, and the progress and output fields explained below, you do not have to
also provide state, although you can. You can provide any combination of these fields in a command_update message,
allowing you to repeatedly update the Major Tom UI when inside of a state.

Note: to ensure correct Command update ordering, Commands are updated directly by the Gateway thread in Major Tom, so
you should avoid updating Commands faster than an average of a few times per second or the Gateway can back up. This is
particularly important for statuses and progress bars (outlined below) where you should be sure to avoid sending repeated
updates for some common event, such as on every byte received or fractional percent complete.

Completing or failing your Command

When your Command completes, you should move it into the completed state and provide an optional output field for
the operator.

...

Note that output and errors can only be set in the completed and failed states, as they're intended to represent
the final results of a Command.

Progress bars

Finally, in any of the ing progress states (e.g., preparing_on_gateway, uplinking_to_system, executing_on_system,
downlinking_from_system, and processing_on_gateway), Major Tom can display progress bars to provide visual feedback
to the operator. A progress bar will be displayed in a progress state when you provide progress_1_current,
progress_1_max, and (optionally) progress_1_label. Example usage would be to show progress of an analysis step on
your Gateway or of queue state on a remote system.

...

Code Block
languagejson
{
  "type": "command_update",
  "command": {
    "id": 20,
    "state": "preparing_on_gateway",
    "status": "Compressing",
    "progress_1_current": 5,
    "progress_1_max": 100,
    "progress_1_label": "percent compressed"
  }
}
Summary

In summary, the following fields can be set on commands:

Field

Type

Available in States

Cleared on State Transition

Suggested Usage

state

string enum

all

n/a

Indicate phase of command lifecycle

payload

string

all

No

Record command payload representation for future debugging

status

string

all

Yes

Display what is currently happening with the command

output

string

completed or failed

Yes

Final command output

errors

array of strings

completed or failed

Yes

Final command errors

progress_1_current

integer

Progress states (those containing ing)

Yes

Current value of a process to display as a progress bar

progress_1_max

integer

Progress states (those containing ing)

Yes

Max value of a process to display as a progress bar

progress_1_label

string

Progress states (those containing ing)

Yes

Label for the progress bar (e.g., "bytes uplinked")

progress_2_current

integer

Progress states (those containing ing)

Yes

Current value of a secondary process to display as a second progress bar

progress_2_max

integer

Progress states (those containing ing)

Yes

Max value of a secondary process to display as a second progress bar

progress_2_label

string

Progress states (those containing ing)

Yes

Label for the second progress bar (e.g., "chunks ACKed")

<a name="cancel"></a>

Command Cancellation

If a user requests command cancellation, Major Tom will send the Gateway a cancel message of the following form:

...

<a name="rate_limit"></a>

Rate Limit

There is a maximum allowed Gateway messaging rate. If you exceed this rate, Major Tom will ignore your message

...

until the next message will be accepted.

<a name="error"></a>

Errors

If Major Tom needs to send your gateway an error, you'll receive a message of type: "error" with an error field indicating the cause.

...

Code Block
languagejson
{
  "type": "error",
  "error": "This Gateway's token has been rotated. Please use the new one.",
  "disconnect": true
}

Sending data to Major Tom

<a name="measurements"></a>

Sending Measurements to Major Tom

To send measurements to Major Tom, send messages of the form:

...

Please note: it is significantly more performant to send Major Tom batches of telemetry in a single "type": "measurements" message instead of via many separate messages. You may send up to 10,000 measurements per measurements messages.

<a name="event"></a>

Sending events to Major Tom

To send events to Major Tom, send messages of the form:

...

<a name="command_definitions_update"></a>

Updating the Command Definitions for a System

Given the name of a System (Satellite or GroundStation), you can update its Command Definitions via a message sent over

...

As with a Command Definition upload in the Major Tom UI, the uploaded Command Definitions will completely replace the existing ones for the given System.

<a name="file_list"></a>

Updating the File List for a System

Major Tom can display a list of remote files for downlink under each top-level System. The list for each system is

...

<a name="file_metadata_update"></a>

Updating the metadata of a DownlinkedFile

Given the id of a DownlinkedFile (see the previous section), you can update the JSON string key-value pairs

...

<a name="file_transfer"></a>

File Transfer in Major Tom

Major Tom serves as an interface for interacting with the file transfer system that works with your remote system

...

"Download" refer to interaction with Major Tom.

Example Flows

Uplink a file to the satellite/system:

<ol>

<li>User uploads a file under the "Uplink" tab under the desired system. This stages the file so it's accessible by the Gateway.</li>

...

<li>The Gateway either confirms the file was transferred successfully by setting the command state to "complete" or lists any errors that occurred by setting the command state to "failed" and submitting the errors. </li>

</ol>

Downlink a file from the satellite/system:

<ol>

<li>(Optional) The Gateway uploads a <a href="#file_list">file_list</a> which represents the files on the system that are available for downlinking. </li>

...

<a name="file_upload"></a>

Uploading DownlinkedFiles to Major Tom

In the Major Tom UI, under the appropriate System, you can view the contents of the latest File List in the Downlink tab.

...

this bash script that demonstrates the flow via

curl.

Step 1: Request permission to upload a file

Make a JSON POST request to /rails/active_storage/direct_uploads including your Gateway token in the X-Gateway-Token

...

You will need these fields in the next two steps.

Step 2: Upload the file with a PUT request

Make an HTTP PUT request to the URL provided in the direct_upload.url field in the response from the previous step.

...

Code Block
languagebash
curl \
  -H 'Content-Type: binary/octet-stream' \
  -H "Content-MD5: CHECKSUM" \
  --upload-file "file.txt" \
  "<http://THE-LONG-UPLOAD-URL">

Step 3: Tell Major Tom about the file's details

When the upload has completed successfully, tell Major Tom about the System, remote timestamp, name, and optional

...

<a name="file_download"></a>

Downloading StagedFiles from Major Tom

In order to uplink files from Major Tom to your remote system, a user will upload files from their web browser to

...