Telemetry System

Overview

The telemetry system acts as the interface between temeletry data producers and data consumers. It consists of the following core components:

  • Data: Data is a collection of address-value pairs, where each of them represnets one piece of data that is being monitored such as battery voltage of segment 1 or IMU acceleration in the x-axis. The address is an integer that uniquely identifies the data which does not need to be contiguously defined.

  • Group: A group is a collection of data that are logically related to each other. For example, a group can be a collection of data that are related to the IMU sensor. And only after all data in a group is updated by the producer side will the data be updated on the consumer side or published by the backend if the group is associated with one. Each group also has a unique ID to identify it which also does not need to be contiguously defined.

  • Backend: A backend is used to transmit data to the consumers such as through UART to the host or to another thread when a group associated with it is updated. Backends must be defined by the user to implement the actual transmission of data.

Usage

Design

Architecture

API Reference

group Telemetry

Defines

TM_DATA_DECLARE(name, type)

Declare a telemetry data, useful for header files.

Parameters:

  • name – [in] Name of the data.

  • type – [in] Type of the data.

TM_DATA_DEFINE(_name, _type, _addr)

Define a telemetry data.

Parameters:

  • _name – [in] Name of the data.

  • _type – [in] Type of the data.

  • _addr – [in] Address of the data.

TM_ALIAS_DECLARE(name, alias)

Declare a telemetry data alias, useful for header files.

Parameters:

  • name – [in] Name of the alias.

  • alias – [in] Telemetry data that this alias refers to.

TM_ALIAS_DEFINE(_name, _alias, _addr)

Define a telemetry data alias.

Parameters:

  • _name – [in] Name of the alias.

  • _alias – [in] Telemetry data that this alias refers to.

  • _addr – [in] Address of the alias.

TM_GROUP_DATA(data, ...)

Specify a telemetry data to be aggregated and published by a telemetry group.

Parameters:

  • data – [in] Telemetry data to be aggregated and published.

  • ... – [in] Optional flags of the data, the same ones and rules as AGG_MEMBER.

TM_GROUP_DEFINE(_name, _period, _min_separation, _watermark, _publish, _user_data, ...)

Define a telemetry group to aggregrate and publish telementry data.

Parameters:

  • _name – [in] Name of the telemetry group.

  • _period – [in] Period of data publishing.

  • _min_separation – [in] Minimum separation time between two data publishing.

  • _watermark – [in] Watermark to wait for late-arriving members.

  • _publish – [in] Function to publish the data, must be of type tm_publish_t.

  • _user_data – [in] Pointer to custom data for the callback.

  • ... – [in] Data to be aggregated and published, must be specified by TM_GROUP_DATA.

TM_DATA_GET(name)

Get the value of telemetry data using its name.

Parameters:

  • name – [in] Name of the telemetry data.

Returns:

Value of the telemetry data.

TM_DATA_UPDATE(name, value)

Update telemetry data using its name and value.

Parameters:

  • name – [in] Name of the telemetry data.

  • value – [in] New value of the telemetry data.

Typedefs

typedef void (*tm_publish_t)(uint32_t addr, const void *data, size_t size, void *user_data)

Function to publish the data.

Param addr:

[in] Address of the data.

Param data:

[in] Pointer to the data to be published.

Param size:

[in] Size of the data to be published.

Param user_data:

[in] Pointer to custom data for callback functions.

Enums

enum tm_data_type

Telemetry data type.

Values:

enumerator TM_DATA_TYPE_NORMAL = 0
enumerator TM_DATA_TYPE_ALIAS

Functions

int tm_data_get(uint32_t addr, void *value)

Get telemetry data using its address and pointer to value.

Parameters:

  • addr – [in] Address of the telemetry data.

  • value – [out] Pointer to store the retrieved value.

Return values:

  • 0 – For success.

  • -ENOENT – If the data does not exist.

int tm_data_update(uint32_t addr, const void *value)

Update telemetry data using its address and pointer to value.

Parameters:

  • addr – [in] Address of the telemetry data.

  • value – [in] Pointer to the new value of the telemetry data.

Return values:

  • 0 – For success.

  • -ENOENT – If the data does not exist.

void tm_data_notify_lock(const struct tm_data *data)

Notify the telemetry groups that this data has been updated. Must be called while holding the lock.

Warning

Internal use only.

Parameters:

  • data – [in] Pointer to tm_data.

void tm_group_copy(struct tm_group *group)

Copy the data in the telemetry data to the group’s publishing buffer.

Warning

Internal use only.

Parameters:
struct tm_group_data
#include <nturt/telemetry.h>

Telemetry group data.

Public Functions

STAILQ_ENTRY (tm_group_data) next

List entry of the element.

Public Members

struct tm_group *const group

Pointer to the telemetry group.

struct tm_data *const data

Pointer to the telemetry data.

void *const pub_data

Pointer to the buffer for publishing.

struct tm_data
#include <nturt/telemetry.h>

Telemetry data.

Public Members

enum tm_data_type type

Type of the telemetry data.

const uint32_t addr

Address of the telemetry data.

const char *name

Name of the telementry data.

const size_t size

Size of the telemetry data.

struct tm_group_list groups

List of groups that publish the telemetry data.

struct k_spinlock lock

Spinlock to protect the following members.

void *const data

Pointer to the buffer of the telementry data.

struct tm_data *const alias

Pointer to the telemetry data that this alias refers to.

struct tm_group
#include <nturt/telemetry.h>

Telemetry publishing group.

Public Members

const tm_publish_t publish

Function to publish the data.

const size_t num_data

Number of data in the group.

struct k_spinlock lock

Spinlock to protect the following members.

struct agg agg

Aggregation of the data in the group.

struct tm_group_data *const datas

Array of data in the group.