Command C++ API

The Command C++ API provides the full capabilities of the Command API as a single C++ class to integrate commanding functionality into user developed applications. The Command C++ API is thread-safe. This API also uses the trek::Packet and trek::Parameter classes available in the Data API.

Command Terminology
The descriptions below of the functionality available in the Command APIs use some terminology that requires explanation.

• Destination - A destination is where you will send a command. A destination is configured through the TReK Command application. A destination may not have the ability to use all of the functionality of the Command APIs. 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 a capability. 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 interface differences among the supported destination types. You will never directly use the command controller, but all of the commands sent will go through one. You may get error codes back from API function calls that indicate an issue with the command controller.
• Blocking - Some destinations allow blocking of function calls until the destination returns information that indicates it is safe to send another request. 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.

Sending Commands
There are five methods provided to send commands. The availability of any of 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.

• trek::CommandApi::SendThisCommand() - Builds the command passed as a function parameter. This method provides a mechanism for sending commands that are not part of the current command configuration.
• trek::CommandApi::SendBinaryCommand() - Sends the binary command passed as a function parameter.
• trek::CommandApi::SendTrekCommand() - Sends a command that is defined locally to the destination. The local command can be updated prior to sending as needed.
• trek::CommandApi::InsertDataAndSendCommand() - Inserts command data passed as a function parameter into a predefined command structure and sends the command to the destination.
• trek::CommandApi::InitiateCommand() - Sends a request to the destination to initiate a command uplink for the specified command.

Command Track
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 such as command responses. The capabilities for tracking commands include:

• trek::CommandApi::GetTrack() - Get command track information for a single command.
• trek::CommandApi::GetCommandResponseList() - Get a list of command responses available for a destination.
• trek::CommandApi::GetCommandResponse() - Get the details about a command response.

Destination Specifics
If a destination provides configuration or status information, you can obtain it through the Command API. The destination specific information can be retrieved in a generic fashion. You will get a list of the any available information and then can request details for each piece of information.

• trek::CommandApi::GetStatusMessageList() - Get a list of status messages available for a destination.
• trek::CommandApi::GetStatusMessage() - Get the details for a status messages.
• trek::CommandApi::GetConfigurationMessageList() - Get a list of configuration messages available for a destination.
• trek::CommandApi::GetConfigurationMessage() - Get the details for a configuration message.
• trek::CommandApi::GetStatusItem() - Get a value for a single status item.
• trek::CommandApi::SetConfigurationItem() - 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.

• trek::CommandApi::GetCommandList() - Get a list of commands available for a destination.
• trek::CommandApi::GetCommand() - Get the command definition.
• trek::CommandApi::UpdateCommand() - Update the command with the user specified data.
• trek::CommandApi::UpdateDestinationCommand() - 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
The following examples are provided to show how to use Command APIs:

C++ API Example
Uses the C++ Command API class to connect to a destination. The example also shows how to discover what status messages exist for a destination. It determines what, if any, responses exists for the destination. A command is sent and tracked prior to disconnecting from the API.
Source File:
cmd_api_cpp/cmd_api_cpp_main.cpp


Additional Dependencies
The TReK Command API (trek_command_api) is also dependent on the following libraries. See the Libraries main help page for more information.

trek_toolkit_common_api
trek_toolkit_data_api
trek_toolkit_utilities_api
xerces-c_3_1