Command

Table of Contents

• Imports
• Connect API
• Sending Commands
  • Initiate
  • Send Trek
  • Insert Data
  • Send This
  • Send Binary
• Handle responses

Telemetry and commands are sent/recieved in a packet. A packet is a collection of digital data in a prescribed layout of bits / bytes. The individual values in the collection are referred to as parameters. Each parameter has properties: type, size, modifiable, location within a packet, current value, and others.

Command

This tutorial walks through a simple example using the Python Trek API to send commands.

Sending TReK commands follows the following pattern:

1. Connect TReK API to a destination.
2. Send command.
3. Handle resulting responses.
4. Disconnect from destination (when finished).

Imports

Each Python class is hosted in a seperate module to minimalize the collective size of your Python application.

Note

Only import the modules you need. Using "import *" is considered poor practice because It may include more information than you need.

Connect API

To get started for commanding, we connect to the API using the CommandApi class.

from trek import CommandApi

CommandApi connects and disconnects from a Trek Data application's destination providing a destination to send commands.
This example script shows connecting to your destination:

from trek import CommandApi, TrekError
 
MY_CRAFT_DESTINATION = "UberSat"
 
try:
    command_api = CommandApi()
    command_api.connect(MY_CRAFT_DESTINATION)      # The name of your destination.
 
    # SEND COMMMANDS HERE
 
    command_api.disconnect()
 
except TrekError as err:
    print(err.find_error_code())

Sending Commands

The TReK API has multiple methods for sending commands depending on your specific needs:

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

Initiate

initiate_command() tells the final destination to send a command.

# Initiate the command
command_api.initiate_command("TURN_ON_RECORDING")

Send Trek

Similar to initiate_command(), send_trek_command() sends a predefined command within the command controller.

token = command_api.send_trek_command("MY_COMMAND")

Insert Data

insert_data_and_send_command() provides a mechanism to issue a command with a single command parameter value packet. The value is providede in the form of bytes. The first parameter is the name of the packet definition file to use followed by the parameter value to send (in bytes).

my_hex_value = b'0x050xA3'   # Hexadecimal representation of the value to send.
token = command_api.insert_data_and_send_command("SET_ANGLE", my_value)

In this example, you have saved a packet definition named file, "SET_ANGLE.xml", that a packet is constructed from and the provided value is placed in the Data Zone of this packet.

Send This

send_this_command() is able to send command using the TRek API Packet class.

my_cmd_packet = Packet()
 
# Construct/Load Packet, then Set Values Here.
 
# Send completed packet
token = command_api.send_this_command("SET_ANGLE", my_cmd_packet)

See trek.Packet, ex_packet_define.py, ex_packet_build.py

Send Binary

send_binary_command() provides a mechanism to issue a properly formed packet that you have constructed and built.

# Hexadecimal representation of the packet to send.
# Allows you to use your own methods akin to trek.packet.Packet.build()
# to create a packet.
my_bytes_packet = b'0x050xA30x150x25'     # <-- not a real packet
 
token = command_api.send_binary_command("MY_COMMAND", my_bytes_packet)

Handle responses

All of the command sending methods return a "token". This unique-per-command number is usable by the command api to retrieve more information associated with the command such as command tracking information.

The TrackItem class can be used to retrieve and hold that tracking information.

# Create a track item.
track_it = TrackItem()
 
# Load tracking informatino into created TrackItem.
command_api.get_track(token, track_it)

Finally, once you have your TrackItem, you can use it to get CommandResponse items useful retrieving the response.

• CommandResponse - Holds all response information associated with a command.
• ResponseInfo - Individual response item within a CommandResponse.

for idx in range(track_item.get_number_of_responses()):
    resp_item = track_item.get_response(idx)
 
    if resp_item.name in response_dictionary:
        my_command_res: CommandResponse = response_dictionary[resp_item.name]
        resp_info = my_command_res.get_error_details(resp_item.value)
        print(f"Response {resp_info.name}: {resp_info.info}.\n")