Command

The Command API extends command capabilities to user developed applications.

Terminology

The terminology below is found in the API documentation.

• Destination - A destination to send commands is configured through the TReK Command application. Not all API capability is available to all destinations. For example, some destinations provide status information to the user. The functions that provide status information will fail (gracefully) for destinations that do not support status. You will always have to give a name to a destination. This name is used by the Command API to route your command to the correct destination.
• Command Controller - A command controller is how TReK handles differences between supported destination types. You will never directly use the command controller, but all of the commands sent will go through one. However, you may get error codes back from API function calls that indicate an issue with the command controller.
• Blocking - Some destinations allow blocking of calls until the destination indicates another request is safe to send. If a destination allows blocking it will be on by default. The API call will block until it is safe to send another request.
• Token - Some Command API functions use a token to correlate a specific instance of a command to other information such as command responses.

API Overview

The full list of documented classes can be found in the Class List, but here is a high level summary of some of the most useful / common classes. Each of them can be saved to a file and loaded from a file. The format of the save file is XML.

CommandApi

The CommandApi provides methods to send data to the destination. The data sent can be processed with the associated Packet class.

Sending Commands

There following methods are used to send commands. The methods are dependent on the destination and also the version of the Command API being used. All of the methods will fail safely if not available for a destination.

• CommandApi.send_this_command() - Sends a command Packet. This allows for sending commands that are not part of the current command configuration.
• CommandApi.send_binary_command() - Sends the binary command passed as a function parameter.
• CommandApi.send_trek_command() - Sends a command that is defined locally to the destination. The local command can be updated prior to sending as needed.
• CommandApi.insert_data_and_send_command() - Inserts command data passed as a function parameter into a predefined command structure and sends the command to the destination.
• CommandApi.initiate_command() - Sends a request to the destination to initiate a command uplink for the specified command.

Command Tracking

Once a command is sent to a destination it is possible to track the command. All destinations will provide at least the time that the command was sent. Some destinations may provide additional information through command responses. Theses tracking commands include:

• CommandApi.get_track() - Get command track information for a single command.
• CommandApi.get_command_response_list() - Get a list of command responses available for a destination.
• CommandApi.get_command_response() - Get the details about a command response.

Destination Specifics

If a destination provides configuration or status information, you can use these API methods to determine what messages are available to retrieve the information:

• CommandApi.get_status_message_list() - Get a list of status messages available for a destination.
• CommandApi.get_status_message() - Get the details for a status messages.
• CommandApi.get_configuration_message_list() - Get a list of configuration messages available for a destination.
• CommandApi.get_configuration_message() - Get the details for a configuration message.
• CommandApi.get_status_item() - Get a value for a single status item.
• CommandApi.set_configuration_item() - Set the value for a single configuration item.

Updating Commands

Any command that is added from the GUI can be updated through the Command API.

• CommandApi.get_command_list() - Get a list of commands available for a destination.
• CommandApi.get_command() - Get the command definition.
• CommandApi.update_command() - Update the command with the user specified data.
• CommandApi.update_destination_command() - Updates the destination's copy of the command with the local copy.

Status Details

Currently, only the POIC destination provides status information. The table below lists all of the status items that are available for the destination.

Status Parameter	Expected Values
UserEnablement	Enabled or Disabled
NonEhsCommandingEnablement	Enabled or Disabled
RemoteEhsEnablement	Enabled or Disabled
PoicConnection	Connected or Not Connected
PoicEnablement	Enabled or Disabled
McchConnection	Connected or Not Connected
McchEnablement	Enabled or Disabled
UplinkPath	9 different string values
AosLos	AOS or LOS
CurrentStationMode	8 different string values
ClearToSendMechanism	ERR, CAR, or FSV
CarProcessingEnablement	Enabled or Disabled
FsvProcessingEnablement	Enabled or Disabled
CrrProcessingEnablement	Enabled or Disabled
MinimumTimeDelay	unsigned integer in milliseconds
CarTimeout	unsigned integer in seconds
FsvTimeout	unsigned integer in seconds
MaximumRetries	unsigned integer
SourceMessageKey	unsigned integer
ConnectionStatus	7 different string values
Project	Various string values
Mission	Various string values
OperationalSupportMode	Various string values
CommandDatabaseVersion	Various string values

Configuration Items

Currently, only the POIC destination provides any configuration items. The table below lists all of the configuration items that are available for the destination. The configuration parameter will be set with a string through the Command API. The 'Data Type Required' column indicates the expected format of the input string for the Command API call.

Configuration Parameter	Data Type Required	Default Value
NumberOfRetries	Unsigned Integer	0

Examples

Tutorial of the "process" - Command

The following example is provided to show using the Command API with Python. It illustrates how to discover what status messages exist for the destination. Then it determines what responses exist. A command is sent and tracked prior to disconnecting from the API.