Telemetry API

Die Telemetry API wird verwendet, um Live-Laufzeitdaten eines Modules an die ArmorLink App zu senden.

Telemetry wird nur übertragen, wenn sie von der ArmorLink App angefordert wird. Dadurch bleibt der ESP-NOW-Verkehr gering und unnötige Übertragungen werden vermieden.

Für den konzeptionellen Überblick siehe Telemetry.

Basisbeispiel

float batteryVoltage = 4.12f;

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

Dies sendet einen Telemetry-Wert mit:

• Gruppe: battery
• Name: main
• Wert: 4.12
• Einheit: V

Verhalten auf Abruf

Telemetry ist nicht dauerhaft aktiv.

Ein Module sendet Telemetry nur dann, wenn diese zuvor durch die ArmorLink App aktiviert wurde.

Wenn Telemetry nicht aktiviert ist, werden die Aufrufe ohne Datenübertragung beendet.

tipp

Du kannst Telemetry-Funktionen regelmäßig aus deiner Anwendungslogik aufrufen.

ArmorLink entscheidet intern, ob die Daten tatsächlich übertragen werden müssen.

sendTelemetry(...)

Sendet einen einzelnen Telemetry-Wert.

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

Parameter:

Parameter	Beschreibung
group	Logische Telemetry-Gruppe
name	Name des Telemetry-Werts
value	Numerischer Wert
unit	Optionale Anzeigeeinheit

Beispiel:

void loop()
{
    ArmorLink.loop();

    float voltage = readBatteryVoltage();

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

telemetry(...)

telemetry(...) ist die Low-Level-Funktion zum Senden eines einzelnen Telemetry-Werts.

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

sendTelemetry(...) dient als komfortabler Wrapper um dieses Verhalten.

telemetryGroup(...)

telemetryGroup(...) erstellt eine Telemetry-Nachricht mit mehreren Werten.

Beispiel:

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

Dies ist sinnvoll, wenn mehrere zusammengehörige Werte gemeinsam übertragen werden sollen.

value(...)

Fügt einer Telemetry-Gruppe einen Wert hinzu.

.value("voltage", 4.12f)

Telemetry-Werte sind numerisch.

Verwende unterschiedliche Schlüssel für unterschiedliche Werte.

Beispiel:

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

unit(...)

Legt die Anzeigeeinheit für einen Telemetry-Wert oder eine Gruppe fest.

.unit("V")

Typische Einheiten:

• V
• %
• C
• ms
• deg

Die ArmorLink App verwendet diese Einheit bei der Darstellung.

send()

Sendet eine Telemetry-Gruppe.

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

Wenn Telemetry aktuell deaktiviert ist, erfolgt keine Übertragung.

Gateway-Verhalten

Wenn das Module selbst das Gateway ist, wird die Telemetry direkt per BLE an die ArmorLink App gesendet.

Wenn es sich um ein normales Module handelt, werden die Daten zunächst an das Gateway und anschließend an die App weitergeleitet.

Module
   |
   v
Gateway
   |
   v
ArmorLink App

Weitere Informationen findest du unter Gateway.

Traffic-Kontrolle

ArmorLink besitzt internes Rate-Limiting für Telemetry-Daten.

Dadurch wird übermäßiger ESP-NOW-Verkehr vermieden, wenn Telemetry-Funktionen häufig aufgerufen werden.

Das minimale Telemetry-Intervall wird intern von der Runtime verwaltet.

Beispiel: Batterie-Telemetry

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

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

Beispiel: Temperatur-Telemetry

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

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

Telemetry vs. Configuration

Telemetry beschreibt den aktuellen Laufzeitzustand eines Modules.

Configuration definiert, wie sich ein Module verhalten soll.

Weitere Informationen findest du unter Configuration.

Telemetry vs. Remote Logging

Telemetry sind strukturierte Laufzeitdaten.

Remote Logging dient der Diagnose und Fehlersuche.

Weitere Informationen findest du unter Remote Logging.

Zusammenfassung

Die Telemetry API sendet Live-Laufzeitdaten an die ArmorLink App.

Häufig verwendete Methoden:

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

Telemetry wird nur übertragen, wenn sie von der ArmorLink App angefordert wurde.