Telemetry C++ API

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

Telemetry 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 trek::ApiClient::Connect() call when using the trek::TelemetryApi class. If you use the Release 3 Compatiable API, it will always work with the default data store name. It is anticipated that 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).

Telemetry C++ API Details
The trek::TelemetryApi provides methods to retrieve data from the associated data store. The data retrieved can be processed with the associated trek::Packet class.

Methods to Retrieve Data

• trek::TelemetryApi::GetNewestPacket() - retrieves the last packet received.
• trek::TelemetryApi::GetNextPacket() - retrieves the packet following the last packet retrieved.
• trek::TelemetryApi::GetThisPacket() - retrieves the packet specified by the token.
• trek::TelemetryApi::GetNewestParameterValueAsString() - retrieves the value of a parameter formatted as a string.

Methods for Packet Arrival Notification

• trek::TelemetryApi::RegisterPacketSemaphore() - register to receive notification of when a new packet arrives.
• trek::TelemetryApi::WaitForPacket() - waits for a packet to arrive and then releases.
• trek::TelemetryApi::UnregisterPacketSemaphore() - used to identify that packet arrival noticiation is no longer required.

General Methods

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

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

C++ API Newest Data
Uses the C++ Telemetry API class to connect to a data store. This example shows how to get the last packet to arrive. This 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:
tlm_api_cpp_newest/cpp_newest_main.cpp

C++ API Next Data
Uses the C++ Telemetry API class to connect to a data store. This example shows techniques to use to get all of the data that arrives. This code uses the trek::TelemetryApi::WaitForPacket() function to know when a packet arrives. You can also use a timer to periodically check for data.
Source File:
tlm_api_cpp_next/cpp_next_main.cpp


Additional Dependencies
The TReK Telemetry API (trek_telemetry_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