Telemetry

Table of Contents

• Imports
• Connect API
• Packet Definitions
• Locate parameters
• Extract Data
• Parameter Values

This tutorial walks through a simple example using the Python Trek API to retrieve telemetry.

Retrieving telemetry follows the following pattern:

1. Connect TReK API to a data store.
2. Load packet definition (packet layout information).
3. Locate desired parameters within definition (like indices into the information).
4. Loop Until Done:
   1. Get packet "bytesarray" (Next/Newest).
   2. Extract "bytesarray" into packet class (breaks packets into parameter values).
   3. Access parameter values using located indicies.

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 telemetry, we connect to the API using the TelemetryApi class.

from trek import TelemetryApi

TelemetryApi connects and disconnects from a Trek Data application's Data Store. In addition, it is able to retrieve telemetry data and place it in your binary bytearray buffer for saving or parameter extraction.

This example script shows connecting to your data store:

from trek import TelemetryApi, TrekError
 
try:
    telem_api = TelemetryApi()
    telem_api.connect("Default Datastore")      # The name of your data store.
 
    # IMPLEMENT TELEMETRY ACTIONS HERE
 
    telem_api.disconnect()
 
except TrekError as err:
    print(err.find_error_code())

Note

TReK API will return error codes by raising a TrekError() exception. The example above will do a look up of these codes for more understandable explanation of the problem. In addition, you can find_error_code all error codes in the TReK API documentation. find_error_code() searches a CSV file for the code, so you would only call this when your program is ending or requires the failure text.

Packet Definitions

A packet definition is an XML file exported from Packet.save_file() that defines the layout of bits/bytes enabling extraction to parameters. Packet save files that are used as packet definitions are located in TReK'same /workspace/metadata folder. The TelemetryApi loads this XML file from this folder using the file's prefix.

# Use TelemetryApi to place the packet definition information into the packet class.
packet = Packet()
telem_api.get_packet_definition("MYPACKET_DEFINITION", packet)

See Data (Packet) for define, build and extracting of packets and how to export to an XML file.

Locate parameters

Once loaded, the Packet contains the definitions of any expected parameters that will be sent or recieved. The Parameter class instances can be retrieved from a packet providing an "reference" to a packet's internal instance useful for retrieving values.

# creates an instance of the Parameter class indexing into where the data will be located.
my_parameter1 = packet.find_parameter("MY_PARAM_NAME")
my_parameter2 = packet.find_parameter("MY_PARAM_NAME2")

Note

In contrast to packet construction ex_packet_define.py where you see a single parameter is re-used because adding to a collection makes a copy, Parameter.find_parameter() returns a reference instance from within the packet that remains connected to your packet. Syntactically, they are the same, adding to a collection makes a copy where Parameter.find_parameter() makes a reference.

Extract Data

The next step is retrieving the desired packet, extracting the the bit/bytes and finally requesting the parameter values.

The TelemetryApi provides the methods for requesting packets from the data store:

• get_newest_packet() will give the most recent packet.
• get_next_packet() will give the next packet after the last requested.

# Load a byte array with the newest packet.
packet_buffer = bytearray(4096)
telem_api.get_newest_packet(PACKET_DEFINITION, packet_buffer)

Once the packet is retrieved, you extract() the packet to it's parameter values.

# Extract the byte array, starting at the first bit.
packet.extract(packet_buffer)

Note

Length of the buffer is provided if you which to extract only part of the buffer. The "start_bit" assignment is provided for clarity (i.e. could have just been 0. Both are syntactically correct in Python). See Python PEP-3102.

Parameter Values

After a packet is extracted, your parameters should now contain values for the requested parameters.

print(f"my parameter {my_parameter1.get_value()}")

To get you started, we have several examples for you to see the whole process in action.

Examples

• ex_telem.py - Follows this tutorials process to create a packet using code.
• ex_telem_get_next.py - Example shows getting each packet sequentially and waiting if necessary.
• ex_telem_get_newest.py - Example shows getting the newest packet and extracting a parameter.