Telemetry API

The Telemetry API is used to send live runtime data from a module to the ArmorLink App.

Telemetry is only transmitted when requested by the ArmorLink App. This keeps ESP-NOW traffic low and avoids unnecessary broadcasts.

For the conceptual overview, see Telemetry.

Basic Example

float batteryVoltage = 4.12f;

ArmorLink.sendTelemetry(
    "battery",
    "main",
    batteryVoltage,
    "V"
);

This sends a telemetry value with:

• Group: battery
• Name: main
• Value: 4.12
• Unit: V

On-Demand Behavior

Telemetry is not always active.

A module only sends telemetry when telemetry has been enabled by the ArmorLink App.

If telemetry is not enabled, telemetry calls return without sending data.

tip

You can call telemetry functions regularly from your application logic.

ArmorLink decides internally whether telemetry should actually be transmitted.

sendTelemetry(...)

Sends a single telemetry value.

ArmorLink.sendTelemetry(
    "battery",
    "main",
    4.12f,
    "V"
);

Parameters:

Parameter	Description
group	Logical telemetry group
name	Telemetry value name
value	Numeric value
unit	Optional display unit

Example:

void loop()
{
    ArmorLink.loop();

    float voltage = readBatteryVoltage();

    ArmorLink.sendTelemetry(
        "battery",
        "voltage",
        voltage,
        "V"
    );
}

telemetry(...)

telemetry(...) is the lower-level function used to send a single telemetry value.

ArmorLink.telemetry(
    "battery",
    "voltage",
    4.12f,
    "V"
);

sendTelemetry(...) is available as a convenience wrapper around this behavior.

telemetryGroup(...)

telemetryGroup(...) creates a telemetry message containing multiple values.

Example:

ArmorLink.telemetryGroup("battery", "main")
    .value("voltage", 4.12f)
    .value("percent", 87.0f)
    .unit("V")
    .send();

This is useful when related values should be sent together.

value(...)

Adds a value to a telemetry group.

.value("voltage", 4.12f)

Telemetry values are numeric.

Use separate keys for separate values.

Example:

ArmorLink.telemetryGroup("imu", "motion")
    .value("x", accelX)
    .value("y", accelY)
    .value("z", accelZ)
    .send();

unit(...)

Sets the display unit for a telemetry value or group.

.unit("V")

Common units include:

• V
• %
• C
• ms
• deg

The ArmorLink App uses the unit when displaying telemetry data.

send()

Sends a telemetry group.

ArmorLink.telemetryGroup("battery", "main")
    .value("voltage", voltage)
    .value("percent", percent)
    .unit("V")
    .send();

If telemetry is currently disabled, the call returns without transmitting data.

Gateway Behavior

If the module is the Gateway, telemetry is sent directly to the ArmorLink App over BLE.

If the module is a regular module, telemetry is sent to the Gateway and forwarded to the App.

Module
   |
   v
Gateway
   |
   v
ArmorLink App

For more information, see Gateway.

Traffic Control

ArmorLink includes internal rate limiting for telemetry traffic.

This helps avoid excessive ESP-NOW traffic when telemetry functions are called frequently.

The default minimum telemetry interval is handled internally by the runtime.

Example: Battery Telemetry

void sendBatteryTelemetry()
{
    float voltage = readBatteryVoltage();
    float percent = calculateBatteryPercent(voltage);

    ArmorLink.telemetryGroup("battery", "main")
        .value("voltage", voltage)
        .value("percent", percent)
        .unit("V")
        .send();
}

Example: Temperature Telemetry

void sendTemperatureTelemetry()
{
    float temperature = readTemperature();

    ArmorLink.sendTelemetry(
        "environment",
        "temperature",
        temperature,
        "C"
    );
}

Telemetry vs Configuration

Telemetry describes the current runtime state of a module.

Configuration defines how a module should behave.

For more information, see Configuration.

Telemetry vs Remote Logging

Telemetry is structured runtime data.

Remote Logging is developer-focused diagnostic output.

For more information, see Remote Logging.

Summary

The Telemetry API sends live runtime data to the ArmorLink App.

Common methods include:

• sendTelemetry(...)
• telemetry(...)
• telemetryGroup(...)
• value(...)
• unit(...)
• send()

Telemetry is only transmitted when requested by the ArmorLink App.