Telemetry System

Overview

The telemetry system provides a type-safe interface for defining, updating, and aggregating telemetry data to be consumed by various backends. It can be added to any application by enabling the CONFIG_NTURT_TM Kconfig option.

Core concepts

  • Data Address: Since most of the embedded protocols uses an address to identify data such as I2C, Modbus, or CAN Open, the telemetry system uses the same concept. Each piece of data is defined by TM_DATA_DEFINE using its name, type, and address.

  • Data Aliases: To support multiple protocols with different addresses for the same data, data aliases can be defined using TM_ALIAS_DEFINE. This allows the same data to be accessed using different addresses and when either the data or any of its aliases is updated, all aliases as well as the original data are updated.

  • Publishing Groups: To support the situation where multiple pieces of data need to be published together such as different sensor data within a single CAN frame, data and aliases can be grouped via TM_GROUP_DEFINE to be aggregated into a single frame.

  • Data Retrieval: Aside from actively publishing data to a backend, data also can be queried by passive protocols such as I2C or Modbus using tm_data_get().

All data operations are reentrant and thread-safe.

Usage

Defining Telemetry Data

Use TM_DATA_DEFINE to define one piece of data. If that data would be accessed across multiple files, use TM_DATA_DECLARE to declare it in a header file.

To define a data named foo of type int with address 0x01 and bar of type float with address 0x02:

// in a header file
TM_DATA_DECLARE(foo, int);
TM_DATA_DECLARE(bar, float);

// in a source file
TM_DATA_DEFINE(foo, int, 0x01);
TM_DATA_DEFINE(bar, float, 0x02);

Data aliases are defined and declared in similar way using TM_ALIAS_DEFINE and TM_ALIAS_DECLARE. To define an alias for the data bar with the name baz and alias address 0x100:

// in a header file
TM_ALIAS_DECLARE(baz, bar);

// in a source file
TM_ALIAS_DEFINE(baz, bar, 0x100);

Updating and Retrieving Data

Data and aliases can be accessed either by their names via TM_DATA_GET, TM_DATA_UPDATE macros, or by their addresses via tm_data_get(), tm_data_update() functions.

Since the type of the data is known at compile time, accessing by their names is internally done via assignment operator =. For example, to update the data foo that is an integer with a float value or retrieve it as a boolean:

TM_DATA_UPDATE(foo, 3.14F);

bool is_non_zero = TM_DATA_GET(foo);

However, since accessing data by their addresses is internally done via memcpy(), the argument must be of the same type as the data. For example, to update the data foo of address 0x01 with a float value:

float new_foo = 3.14F;
int new_foo_int = new_foo;
tm_data_update(0x01, &new_foo_int);

Grouping Data

Telemetry system uses Data Aggregation to aggregate data into groups for publishing. For example:

TM_GROUP_DEFINE(my_group,
    period, min_separation, watermark, flag, publish, user_data
    TM_DATA(foo),
    TM_DATA(baz, AGG_MEMBER_FLAG_OPTIONAL)
);

defines a group named my_group that aggregates the data foo and baz. Where period, min_separation, watermark, and flag are parameters for aggregation.

After the data is aggregated, publish of type tm_publish_t is called for every data in the group.

API Reference

group Telemetry

Telemetry support.

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. Used in TM_GROUP_DEFINE.

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, _flag, _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.

  • _flag – [in] Flag of the aggregation. The same ones and rules as flag in AGG_DEFINE.

  • _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.