Provides access to telemetry features of TReK. More...

#include <telemetry_api.h>

Public Member Functions
	TelemetryApi ()
	Default constructor. More...

virtual	~TelemetryApi ()
	Class destructor. More...

int32_t	RegisterPacketSemaphore (const char *pkt_key)
	Registers a semaphore to be signaled when a packet arrives. More...

int32_t	WaitForPacket (const char *pkt_key, uint32_t timeout=0)
	Waits for the specified packet to arrive. More...

int32_t	UnregisterPacketSemaphore (const char *pkt_key)
	Unregisters the packet arrival semaphore. More...

int32_t	GetNewestParameterValueAsString (const char pkt_key, const char param_name, uint32_t &token, char value, uint32_t value_len)
	Get the newest value of a parameter as a string. More...

int32_t	GetNewestParameterValueAsString (const char pkt_key, const char param_name, uint32_t &token, char value, uint32_t value_len, ParameterStatus &status)
	Get the newest value of a parameter as a string including a status. More...

int32_t	SetMonitorLogFile (const char *filename)
	Sets the filename used for writing monitor messages if monitor logging is on. More...

int32_t	StartMonitorLogging ()
	Starts the logging of monitor messages. More...

int32_t	StopMonitorLogging ()
	Stops the logging of monitor messages. More...

General API Methods
These methods control the behavior of the API.
int32_t	GetSourceList (StringArray &pkt_key_list)
	Gets the list of packet keys currently being processed. More...

int32_t	FindSourcePacket (const char filter, const char parameter, char match, uint32_t match_len)
	Looks for the parameter in one of the currently processed packets. More...

int32_t	GetPacketDefinition (const char *pkt_key, Packet &pkt)
	Retrieve the Packet definition for the specified key. More...

Packet Level Methods
These methods work at a packet level.
int32_t	GetNewestPacket (const char pkt_key, uint32_t &token, uint8_t buf, uint32_t &len)
	Gets a copy of the newest packet available from the data store. More...

int32_t	GetNextPacket (const char pkt_key, uint32_t &token, uint8_t buf, uint32_t &len)
	Gets a copy of the next packet available from the data store. More...

int32_t	GetThisPacket (const char pkt_key, uint32_t &token, uint8_t buf, uint32_t &len)
	Gets a copy of the specified packet from the data store. More...

Public Member Functions inherited from trek::ApiClient
int32_t	Connect (const char *name)
	Connects this instance of the API to TReK for the specified destination. More...

int32_t	Disconnect ()
	Disconnects from the destination. More...

void	SetWaitTimeout (uint32_t timeout)
	Sets the timeout value for API calls that require communicating with TReK. More...

uint32_t	GetWaitTimeout ()
	Returns the current timeout value for API calls. More...

int32_t	Cleanse ()
	Cleans up any resources from crashed user programs. More...

bool	IsConnected ()
	Returns true if API is connected. More...

	ApiClient ()
	Default constructor. More...

virtual	~ApiClient ()
	Class destructor. More...

Additional Inherited Members
Protected Member Functions inherited from trek::ApiClient

Detailed Description

Provides access to telemetry features of TReK.

This class provides access to the telemetry feature of TReK. Users of the class can get packets, convert and calibrate parameters and more.

Examples:
tlm_api_cpp_newest/cpp_newest_main.cpp - general example showing many API functions.
tlm_api_cpp_next/cpp_next_main.cpp - general example showing many API functions.

Examples: tlm_api_cpp_newest/cpp_newest_main.cpp, and tlm_api_cpp_next/cpp_next_main.cpp.

Constructor & Destructor Documentation

◆ TelemetryApi()

trek::TelemetryApi::TelemetryApi ( )

Default constructor.

There are no other constructors.

◆ ~TelemetryApi()

trek::TelemetryApi::~TelemetryApi ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

◆ FindSourcePacket()

int32_t trek::TelemetryApi::FindSourcePacket	(	const char *	filter,
		const char *	parameter,
		char *	match,
		uint32_t *	match_len
	)

Looks for the parameter in one of the currently processed packets.

The filter is used to restrict the packet types. If the parameter is not found, the match is set to an empty string.

Note: This method is used for Release 3 API compatibility. It is availabe for other use, but is likely not what you are looking for.

Parameters

[in]	filter	Filter to limit search.
[in]	parameter	Parameter name needed.
[out]	match	Match, if any.
[in,out]	match_len	The length available for the matched string on input. Needed space if return code is TLM_API_LENGTH_ERR.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_LENGTH_ERR; TCA_WAIT_TIMEOUT; TLM_API_DATA_STORE_WAIT_ERR; TLM_API_FILE_OPEN_ERR; TLM_API_NOT_ENOUGH_SPACE

Example:

TelemetryApi api;
int32_t ret_value;
std::string filter, parameter, match;
 
filter = "PDSS Payload.RT.PL";
parameter = "MSID016";
 
// assume API is already connected.
ret_value = api.FindSourcePacket( filter, parameter, match );
 
if( ret_value == SUCCESS )
    printf( "Match: %s\n", match.c_str() );
else
    printf( "Error: %d.\n", ret_value );

Longer examples that include this method:
None

◆ GetNewestPacket()

int32_t trek::TelemetryApi::GetNewestPacket	(	const char *	pkt_key,
		uint32_t &	token,
		uint8_t *	buf,
		uint32_t &	len
	)

Gets a copy of the newest packet available from the data store.

The returned packet can be processed with a Packet instance.

Parameters

[in]	pkt_key	The packet key.
[out]	token	A token value used to determine which packet instance was returned.
[out]	buf	An already allocated buffer to hold the copy of the packet data.
[in,out]	len	The length of the allocated buffer. Reset to the actual returned length upon SUCCESS. Reset to the number needed if return code is TLM_API_LENGTH_ERR.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_DATA_STORE_WAIT_ERR; TLM_API_LENGTH_ERR

Example:

TelemetryApi api;
int32_t ret_value;
uint8_t buf[4096];
uint32_t token;
uint32_t len;
 
ret_value = api.Connect();          // assumes success.
 
len = 4096;     // reset to actual length prior to each call
ret_value = api.GetNewestPacket( "PdssPayload.RT.PL.7", token, buf, len );
 
if( ret_value == SUCCESS )
{
    // Can process data with Packet class.
    // pkt.Extract( buf, len );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
tlm_api_cpp_newest/cpp_newest_main.cpp

Examples: tlm_api_cpp_newest/cpp_newest_main.cpp.

◆ GetNewestParameterValueAsString() [1/2]

int32_t trek::TelemetryApi::GetNewestParameterValueAsString	(	const char *	pkt_key,
		const char *	param_name,
		uint32_t &	token,
		char *	value,
		uint32_t *	value_len
	)

Get the newest value of a parameter as a string.

Returns the value of the parameter formatted as a string. The formatting is from Parameter::GetValueAsString(). Maximum supported string size is 1024 bytes.

Parameters

[in]	pkt_key	The packet key.
[in]	param_name	Name of the parameter.
[in,out]	token	A token value used to determine the packet to return.
[out]	value	The string value. Valid when the return code is SUCCESS.
[in,out]	value_len	The number of bytes available for writing. Reset to number needed if return code is TLM_API_LENGTH_ERR.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TLM_API_PARAM_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_DOES_NOT_EXIST; TLM_API_LENGTH_ERR; TCA_WAIT_TIMEOUT

Example:

TelemetryApi api;
int32_t ret_value;
uint32_t token = 0;
char value[1025];
uint32_t value_len;
 
ret_value = api.Connect();          // assumes success.
 
value_len = 1025;
ret_value = api.GetNewestParameterValueAsString( "PdssPayload.RT.PL.7", "MSID001", token, value, &value_len );
 
if( ret_value == SUCCESS )
    printf( "Success. Value is %s\n", value );
else
    printf( "Error: %d.\n", ret_value );

Longer examples that include this method:
None

◆ GetNewestParameterValueAsString() [2/2]

int32_t trek::TelemetryApi::GetNewestParameterValueAsString	(	const char *	pkt_key,
		const char *	param_name,
		uint32_t &	token,
		char *	value,
		uint32_t *	value_len,
		ParameterStatus &	status
	)

Get the newest value of a parameter as a string including a status.

Returns the value of the parameter formatted as a string. The formatting is from Parameter::GetValueAsString(). Maximum supported string size is 1024 bytes.

Parameters

[in]	pkt_key	The packet key.
[in]	param_name	Name of the parameter.
[in,out]	token	A token value used to determine the packet to return.
[out]	value	The string value. Valid when the return code is SUCCESS.
[in,out]	value_len	The number of bytes available for writing. Reset to number needed if return code is TLM_API_LENGTH_ERR.
[out]	status	The status associated with the parameter. Valid when the return code is SUCCESS.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TLM_API_PARAM_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_DOES_NOT_EXIST; TLM_API_LENGTH_ERR; TCA_WAIT_TIMEOUT

Example:

TelemetryApi api;
int32_t ret_value;
uint32_t token = 0;
char value[1025];
uint32_t value_len;
ParameterStatus status;
 
ret_value = api.Connect();          // assumes success.
 
value_len = 1025;
ret_value = api.GetNewestParameterValueAsString( "PdssPayload.RT.PL.7", "MSID115", token, value, &value_len, status );
 
if( ret_value == SUCCESS )
    printf( "Success. Value is %s\n", value );
else
    printf( "Error: %d.\n", ret_value );
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

◆ GetNextPacket()

int32_t trek::TelemetryApi::GetNextPacket	(	const char *	pkt_key,
		uint32_t &	token,
		uint8_t *	buf,
		uint32_t &	len
	)

Gets a copy of the next packet available from the data store.

The next packet available is determined by the token value. If this is the first request, the token value should be set to 0. If the next packet is not availible anymore, the oldest packet will be returned and the return value of the method will be TLM_API_MISSING_DATA. If additional data is available, the return code TLM_API_MORE_DATA_AVAILABLE will be returned. A return code of TLM_API_MISSING_DATA or TLM_API_MORE_DATA_AVAILABLE is not considered an error.
The returned packet can be processed with a Packet instance.

Parameters

[in]	pkt_key	The packet key.
[in,out]	token	A token value used to determine the previous packet returned and which packet instance is returned.
[out]	buf	An already allocated buffer to hold the copy of the packet data.
[in,out]	len	The length of the allocated buffer. Reset to the actual returned length upon SUCCESS. Reset to the number needed if return code is TLM_API_LENGTH_ERR.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_DATA_STORE_WAIT_ERR; TLM_API_LENGTH_ERR; TLM_API_MISSING_DATA; TLM_API_MORE_DATA_AVAILABLE

Example:

TelemetryApi api;
int32_t ret_value;
uint8_t buf[4096];
uint32_t token;
uint32_t len;
 
ret_value = api.Connect();          // assumes success.
 
token = 0;      // initialize token for first call only
len = 4096;     // reset to actual length prior to each call
ret_value = api.GetNextPacket( "PdssPayload.RT.PL.7", token, buf, len );
 
if( ret_value == SUCCESS || ret_value == TLM_API_MISSING_DATA || ret_value == TLM_API_MORE_DATA_AVAILABLE )
{
    // Can process data with Packet class.
    // pkt.Extract( buf, len );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
tlm_api_cpp_next/cpp_next_main.cpp

Examples: tlm_api_cpp_next/cpp_next_main.cpp.

◆ GetPacketDefinition()

int32_t trek::TelemetryApi::GetPacketDefinition	(	const char *	pkt_key,
		Packet &	pkt
	)

Retrieve the Packet definition for the specified key.

The returned packet definition has all of the parameters available for this packet.

Parameters

[in]	pkt_key	The packet key.
[out]	pkt	Holds the complete packet definition if SUCCESS is returned.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_DATA_STORE_WAIT_ERR; DATA_STORE_PACKET_DOES_NOT_EXIST; TLM_API_COULD_NOT_LOAD_FILE

Example:

TelemetryApi api;
int32_t ret_value;
Packet pkt;
 
ret_value = api.Connect();          // assumes success.
 
ret_value = api.GetPacketDefinition( "PdssPayload.RT.PL.7", pkt );
 
if( ret_value == SUCCESS )
{
    // The variable pkt as a complete Packet definition.
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
tlm_api_cpp_newest/cpp_newest_main.cpp tlm_api_cpp_next/cpp_next_main.cpp

Examples: tlm_api_cpp_newest/cpp_newest_main.cpp, and tlm_api_cpp_next/cpp_next_main.cpp.

◆ GetSourceList()

int32_t trek::TelemetryApi::GetSourceList ( StringArray & pkt_key_list )

Gets the list of packet keys currently being processed.

This method returns an array of the active packets in the corresponding TReK Data application.

Parameters

[out] pkt_key_list Array of packet keys.

Returns: SUCCESS; TCA_API_NOT_CONNECTED; TCA_WAIT_TIMEOUT; TLM_API_DATA_STORE_WAIT_ERR; TLM_API_FILE_OPEN_ERR

Example:

TelemetryApi api;
int32_t ret_value;
StringArray pkt_list;
 
// assume API is already connected.
ret_value = api.GetSourceList( pkt_list );
 
if( ret_value == SUCCESS )
{
    printf("List of all packets being processed:\n");
    for( uint32_t ii = 0; ii < pkt_list.Size(); ii++ )
        printf( "%s\n", pkt_list.GetAt(ii) );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
tlm_api_cpp_newest/cpp_newest_main.cpp

Examples: tlm_api_cpp_newest/cpp_newest_main.cpp.

◆ GetThisPacket()

int32_t trek::TelemetryApi::GetThisPacket	(	const char *	pkt_key,
		uint32_t &	token,
		uint8_t *	buf,
		uint32_t &	len
	)

Gets a copy of the specified packet from the data store.

If a packet still exists in the buffer with a matching token, it is returned.

The returned packet can be processed with a Packet instance.

Parameters

[in]	pkt_key	The packet key.
[in]	token	A token value used to determine the packet to return.
[out]	buf	An already allocated buffer to hold the copy of the packet data.
[in,out]	len	The length of the allocated buffer. Reset to the actual returned length upon SUCCESS. Reset to the number needed if return code is TLM_API_LENGTH_ERR.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_DATA_STORE_WAIT_ERR; TLM_API_LENGTH_ERR

Example:

TelemetryApi api;
int32_t ret_value;
uint8_t buf[4096];
uint32_t token;
uint32_t len;
 
ret_value = api.Connect();          // assumes success.
 
token = 1560;   // find packet with this token
len = 4096;     // reset to actual length prior to each call
ret_value = api.GetThisPacket( "PdssPayload.RT.PL.7", token, buf, len );
 
if( ret_value == SUCCESS )
{
    // Can process data with Packet class.
    // pkt.Extract( buf, len );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

◆ RegisterPacketSemaphore()

int32_t trek::TelemetryApi::RegisterPacketSemaphore ( const char * pkt_key )

Registers a semaphore to be signaled when a packet arrives.

If SUCCESS is returned, WaitForPacket can be called to be notified of the arrival of the next packet.

Parameters

[in] pkt_key The packet key to register for.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_ALREADY_EXISTS; TLM_API_DATA_STORE_WAIT_ERR

Example:

TelemetryApi api;
int32_t ret_value;
 
ret_value = api.Connect();          // assumes success.
 
ret_value = api.RegisterPacketSemaphore( "PdssPayload.RT.PL.7" );
 
if( ret_value == SUCCESS )
{
    // can call WaitForPacket
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
tlm_api_cpp_next/cpp_next_main.cpp

Examples: tlm_api_cpp_next/cpp_next_main.cpp.

◆ SetMonitorLogFile()

int32_t trek::TelemetryApi::SetMonitorLogFile ( const char * filename )

Sets the filename used for writing monitor messages if monitor logging is on.

The filename should be the complete path to the file. The file is not created until trek::TelemetryApi::StartMonitorLogging() is called. When the file is created a timestamp is appended to the name and a ".log" extension is added after the timestamp.

Parameters

[in] filename The full path to a file for logging.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_FILE_LEN_ERR; TCA_WAIT_TIMEOUT

Example:

TelemetryApi api;
int32_t ret_value;
 
ret_value = api.Connect();          // assumes success.
 
ret_value = api.SetMonitorLogFile( "/home/me/monitor_file" );       // API adds time and ".log"
 
if( ret_value == SUCCESS )
    printf("Success\n");
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

◆ StartMonitorLogging()

int32_t trek::TelemetryApi::StartMonitorLogging ( )

Starts the logging of monitor messages.

The filename is set via SetMonitorLogFile() or the Data GUI.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TCA_WAIT_TIMEOUT

Example:

TelemetryApi api;
int32_t ret_value;
 
ret_value = api.Connect();          // assumes success.
 
ret_value = api.StartMonitorLogging();
 
if( ret_value == SUCCESS )
    printf("Success\n");
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

◆ StopMonitorLogging()

int32_t trek::TelemetryApi::StopMonitorLogging ( )

Stops the logging of monitor messages.

Closes the file for monitor messages. Starting logging again will create a new file.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TCA_WAIT_TIMEOUT

Example:

TelemetryApi api;
int32_t ret_value;
 
ret_value = api.Connect();          // assumes success.
 
ret_value = api.StopMonitorLogging();
 
if( ret_value == SUCCESS )
    printf("Success\n");
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

◆ UnregisterPacketSemaphore()

int32_t trek::TelemetryApi::UnregisterPacketSemaphore ( const char * pkt_key )

Unregisters the packet arrival semaphore.

Removes the semaphore from the list of semaphores to be signalled when the specified packet arrives.

Parameters

[in] pkt_key The packet key.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_ALREADY_EXISTS; TLM_API_DATA_STORE_WAIT_ERR

Example:

TelemetryApi api;
int32_t ret_value;
 
ret_value = api.Connect();          // assumes success.
 
ret_value = api.RegisterPacketSemaphore( "PdssPayload.RT.PL.7" );       // assumes success
 
// more code...and when you are finished...
 
ret_value = api.UnregisterPacketSemaphore( "PdssPayload.RT.PL.7" );
 
if( ret_value == SUCCESS )
    printf("Success\n");
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

Examples: tlm_api_cpp_next/cpp_next_main.cpp.

◆ WaitForPacket()

int32_t trek::TelemetryApi::WaitForPacket	(	const char *	pkt_key,
		uint32_t	timeout = `0`
	)

Waits for the specified packet to arrive.

Will wait the specified time for a signal that a new packet has arrived. If the method returns SUCCESS, other API calls can be made to retrieve new data.

Note: If a packet arrives when the code has not blocked with a WaitForPacket call, the WaitForPacket method will release immediately when called the next time to allow the program to retrieve data.

Parameters

[in]	pkt_key	The packet key to wait for.
[in]	timeout	The number of milliseconds to wait. Use a value of 0 for an infinite wait.

Returns: SUCCESS; TLM_API_NULL_POINTER; TCA_API_NOT_CONNECTED; TLM_API_PKT_NAME_LEN_ERR; TCA_WAIT_TIMEOUT; TLM_API_DOES_NOT_EXIST

Example:

TelemetryApi api;
int32_t ret_value;
 
ret_value = api.Connect();          // assumes success.
 
ret_value = api.RegisterPacketSemaphore( "PdssPayload.RT.PL.7" );       // assumes success
 
if( ret_value == SUCCESS )
{
    ret_value = api.WaitForPacket( "PdssPayload.RT.PL.7", 5000 );       // wait for 5 seconds
 
    if( ret_value == SUCCESS )
    {
        // make other API calls to get data
    }
    else
        printf("Error %d while waiting for packet\n", ret_value);
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
tlm_api_cpp_next/cpp_next_main.cpp

Examples: tlm_api_cpp_next/cpp_next_main.cpp.

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TelemetryApi()

◆ ~TelemetryApi()

Member Function Documentation

◆ FindSourcePacket()

◆ GetNewestPacket()

◆ GetNewestParameterValueAsString() [1/2]

◆ GetNewestParameterValueAsString() [2/2]

◆ GetNextPacket()

◆ GetPacketDefinition()

◆ GetSourceList()

◆ GetThisPacket()

◆ RegisterPacketSemaphore()

◆ SetMonitorLogFile()

◆ StartMonitorLogging()

◆ StopMonitorLogging()

◆ UnregisterPacketSemaphore()

◆ WaitForPacket()