majortom-gateway

v1.0.25

Published

8 months ago

NodeJS TypeScript API for Major Tom

Downloads

117

0High
0Medium
0Low

dmitrydwhite

Major Tom Gateway Package

Version 1 - Breaking Change from Version 0

Version 1 is a breaking change from the previous version, with major changes to both the API and the paradigm. This version takes advantage of the intrinsically asynchronous eventing paradigm of Node.js. This version also is provided in TypeScript.

Installation

TypeScript

// my_gateway.ts

import MajorTomGateway from 'majortom-gatway';

const myGateway = new MajorTomGateway();

JavaScript

// my_gateway.js

const MajorTomGateway = require('majortom-gateway').default;

const myGateway = new MajorTomGateway();

Majortom Gateway

New MajortomGateway()

Extends EventEmitter

import MajortomGateway from 'majortom-gateway';

new MajortomGateway();

Event: MajortomMessageType.hello_event 'mt_hello_event'

Event: MajortomMessageType.command_event 'mt_command_event'

Event: MajortomMessageType.transit_event 'mt_transit_event'

Event: MajortomMessageType.error_event 'mt_error_event'

Event: MajortomMessageType.rate_limit_event 'mt_rate_limit_event'

Event: MajortomMessageType.cancel_event 'mt_cancel_event'

Event: MajortomMessageType.received_blob_event 'mt_received_blob_event'

Event: MajortomMessageType.blob_data_finished_event 'mt_blob_data_finished_event'

Event: MajortomMessageType.majortom_connection_drop_event 'mt_connection_drop_event'

Event: MajortomMessageType.unknown_message_event 'mt_unknown_message_event'

A MajortomGateway will emit events based on the known message types from Major Tom. See the Gateway API Documentation for details on the expected messages that can be received from Major Tom.

The MajortomMessageType provides the available string event types. The shape of each message is described in the documentation referenced above. Type hints will be provided when an implementer sets a listener for a recognized MajortomMessageType

majortomGateway.on(eventName, listener)

majortomGateway.addListener(eventName, listener)

eventName <MajortomMessageType> One of the Major Tom gateway message types
listener <Function> The event handler function

Calling '.on' or '.addListener' will provide type assistance for the implementer, ensuring that the eventName field is an event emitted by the running gateway, and providing message shape information to the listner callback. To listen for non-Major Tom events, use the alias .addEventListener.

majortomGateway.addEventListener(eventName, listener)

eventName <string | symbol> The name of the event being listened for
listener <Function> The event handler function

An alias for EventEmitter.on super methd.

majortomGateway.setHostAndToken(host, token)

host <string> The host for your Major Tom app connection
token <string> The gateway token for the specific gateway connection

Sets the required connection parameters for making the gateway connection to Major Tom.

majortomGateway.setAltRestHost(host)

host <string> The alternate host to use for REST interactions

This is not typically needed for production environments.

majortomGateway.setBasicAuth(basicAuth)

basicAuth <string> The username/password combination for basic auth, if your installation requires it.

majortomGateway.setUseHttp(useHttp)

useHttp <boolean> True to use non-secure connection; typically used for development

majortomGateway.connect()

Use to connect your gateway implementation to Major Tom over WebSocket.

import MajortomGateway from 'majortom-gateway';

const myGateway = new MajortomGateway();

myGateway.setHostAndToken('my.majortom.cloud', '12345678');
myGateway.setBasicAuth('me:my_password@');

myGateway.connect();

majortomGateway.disconnect()

Use to intentionally disconnect the WebSocket connection from Major Tom.

transmit(mtMsg)

mtMsg <Buffer | string | any> The message to send

This is the underlying method to send data over the WebSocket to Major Tom. We recommend using one of the more specific methods described below. Buffers will be converted to strings. Arguments of type any will attempt to be JSON-stringified. If JSON-stringifying fails, this method will throw.

majortomGateway.transmitCommandUpdate(id, state, opts)

id <number> The ID of the command to update
state <CommandUpdateState> A command state recognized by Major Tom
opts? <CommandUpdateOptions> Object with the update properties for the command.

See the Major Tom Gateway API Documentation for details on how commands may be updated from the gateway.

majortomGateway.transmitEvents(eventParam)

eventParam <EventObject | EventObject[]>

Send one or more gateway events to Major Tom.

majortomGateway.transmitMetrics(metrics)

metrics <MetricObject[]> The metrics data

Transmit an array of metrics from your systems to Major Tom. See the Gateway API Docs for details.

majortomGateway.transmitBlobForUplink(blob, metadata)

blob <Buffer> The raw data in byte form
metadata? <Object> Optional metadata object of any shape

Use this method to send uplink data through a connected Ground Station Network through your Major Tom installation.

Note: this method will fail silently if you do not have a Ground Station Network set up and connected to your Major Tom account.

majortomGateway.cancelCommand(id)

id <number> The id of the cancelled command

Alias for calling majortomGateway.transmitCommandUpdate(id, 'cancelled')

majortomGateway.completeCommand(id, output)

id <number> The id of the completed command
output <string | number> Output from the completed command

Alias for calling majortomGateway.transmitCommandUpdate(id, 'completed', { output })

majortomGateway.failCommand(id, errors)

id <number> The id of the failed command
errors <(string | Error)[]> At least one error message

Alias for calling majortomGateway.transmitCommandUpdate(id, 'failed', { errors })

majortomGateway.transmittedCommand(id, payload)

id <number> The id of the command that has been transmitted to system
payload? <string | number> Optional payload sent along with the command

Alias for calling majortomGateway.transmitCommandUpdate(id, 'transmitted_to_system', { payload })

majortomGateway.updateCommandDefinitions(system, definitions)

system <string> The name of one of your defined systems in Major Tom
definitions: <Definitions> The command definitions for the system

majortomGateway.updateFileList(system, files, timestamp)

system <string> The name of one of your defined systems in Major Tom
files <FileData>
timestamp? <number> Optional timestamp intended to represent the time that the file list was generated on the System; will default to when the method was called

Sends an updated file list for the given system.

majortomGateway.downloadStagedFile(downloadPath)

downloadPath <string> The path where the file is stored, usually sent in a Major Tom command.
Returns <Promise<Buffer>>

Download a file as a Buffer from where it is stored on Major Tom servers. You may then send the raw downloaded data to a system.

import MajortomGateway from 'majortom-gateway';

const myGateway = new MajortomGateway();
const myUplinkConnection = new Writable(options);

myGateway.setHostAndToken('my.majortom.cloud', '12345678');
myGateway.connect();

myGateway.on(MajortomGateway.command_event, ({ command }) => {
    if (command.type === 'uplink_file') {
        // Find the downloadPath value from the command fields
        const downloadPath = command.fields.find(({ name }) => name === 'gateway_download_path').value;

        // Asynchronously download the file from Major Tom
        myGateway.downloadStagedFile(downloadPath).then(fileBuffer => {
            // Once the download is complete, write the file to the uplink connection
            myUplinkConnection.write(fileBuffer);
        });
    }
});

You must have staged the file you wish to download for uplink through Major Tom. (Check the Staged Files tab on the desired system in the Major Tom UI.)

majortomGateway.uploadDownlinkedFile(uploadParam)

uploadParam <UploadParams>
- fileBuffer? <Buffer> The raw file data _ fileName? <string> Required if fileBuffer is provided
- filePath? <string> The location of the file in the local file system
- system <string> The name of the system where the file originated
- contentType? <string> The MIME type of the file data; defaults to 'binary/octet-stream'
- commandId? <number> Optionally associate this transfer with a Major Tom command id
- metadata? <Object> Optional information about the file in any shape of JavaScript object

Only one of fileBuffer or filePath may be provided. If fileBuffer is provided, then fileName is required.

Returns <Promise<any>>

import MajortomGateway from 'majortom-gateway';

const mySatConnection = new SatelliteConnection();
const myGateway = new MajortomGateway();

myGateway.setHostAndToken('my.majortom.cloud', '12345678');
myGateway.connect();

// Assume that you receive an event when you have received a complete file downlink from your satellite:
mySatConnection.on('all_file_data_packets_received', (fileName: string, fileBuffer: Buffer) => {
    myGateway.uploadDownlinkedFile({
        fileName,
        fileBuffer,
        system: 'JavaScript-One',
        metadata: { custom: true, scale: '1:1000' },
    }).then(() => {
        console.log('finished file upload');
    });
});

Class FieldParser

new FieldParser(fields)

fields <CommandField[]> The array of entered fields received from Major Tom

This is a helper class to make it easier for the implementer to find a required or optional field in the array of CommandFields sent with the command.

import { Writable } from 'stream';
import MajortomGateway, { FieldParser, MajortomMessageType } from 'majortom-gateway';

const myGateway = new MajortomGateway();
const myUplinkChannel = new Writable();

myGateway.setHostAndToken('my.majortom.cloud', '12345678');
myGateway.connect();

myGateway.on(MajortomMessageType.command_event, ({ command }) => {
    try {
        const field = new FieldParser(command.fields);
        const frequency = field.required('frequency');
        const elements = field.optional('elements');

        myUplinkChannel.write(Buffer.from(`1 ${frequency} ${elements}`.trim()));
    } catch (err) {
        myGateway.failCommand(command.id, [err]);
    }
});

fieldParser.required(fieldName)

fieldName <string> The name of the field to find
Returns string | number
Throws if there is no field with the passed field name

fieldParser.optional(fieldName)

fieldName <string> The name of the field to find
Returns string | number | void