Telemetry

The Telemetry API extends telemetry capabilities to user developed applications.

Terminology

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

• Data Store - Each Data GUI has an associated data store that is used to store incoming telemetry data. The first instance of a data store will use the default data store name. If you run a second instance of the Data GUI, you will be asked to supply a name for the data store. This is the same name you would use in the TelemetryApi.connect() call when using the TelemetryApi class. The Release 3 Compatiable API will always work with the default data store name. Most users will only run a single Data GUI and will therefore always be using the default data store.
• Packet Key - A packet key is a string that uses the packet type and all identifiers to produce a unique reference to a packet in the data store. You can see the packet key strings in the Data GUI by showing the debug statistics and expanding them.
• Token - Any Telemetry API function that retrieves data uses a token. The token identifies which data was retrieved. It is used internally by TReK and the user should not reset the value after initializing it to zero. The token for the trek.TelemetryApi is a single 32-bit unsigned integer. The token for the Release 3 Compatiable API is an array of three long integers. You should use a unique token for each packet or parameter being retrieved. Using the same token for multiple packets or parameters can cause the functions to perform unexpectedly (e.g., miss data).

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.

TelemetryApi

The TelemetryApi provides methods to retrieve data from the associated data store. The data retrieved can be processed with the associated Packet class.

Methods to Retrieve Data*

• TelemetryApi.get_newest_packet() - retrieves the last packet received.
• TelemetryApi.get_next_packet() - retrieves the packet following the last packet retrieved.

• TelemetryApi.get_this_packet() - retrieves the packet specified by the token.

  Methods for Packet Arrival Notification*

• TelemetryApi.register_packet_semaphore() - register to receive notification of when a new packet arrives.
• TelemetryApi.wait_for_packet() - waits for a packet to arrive and then releases.

• TelemetryApi.unregister_packet_semaphore() - used to identify that packet arrival noticiation is no longer required.

  General Methods*

• TelemetryApi.get_source_list() - gets a list of all packet keys currently being processed for the data store
• TelemetryApi.get_packet_definition() - get the detailed information for the packet (trek.Packet)

Examples

The following examples are provided to show how to use Telemetry APIs:

Tutorial of the "process" - Telemetry

Newest Data
Shows how to get the last packet to arrive. The newest packet is typically used to show the most recent data in user applications such as displays. The code here could be used with a timer to update at the needed frequency.
Source File: ex_telem_get_newest.py

Next Data
Shows how to get all of the data that arrives. This code uses the TelemetryApi.wait_for_packet() function to know when a packet arrives. You can also use a timer to periodically check for data.
Source File: ex_telem_get_next.py