Intégration MCU

Présentation

VBatPower accepte les données de télémétrie de tout appareil capable d'effectuer des requêtes HTTP POST. Le format des données est volontairement simple — un CSV plat qui peut être généré avec printf sur n'importe quel MCU 8 bits.

Le flux typique :

  1. Créez un projet dans l'application VBatPower
  2. Générez une clé d'API dans Paramètres > API
  3. Envoyez la télémétrie depuis votre MCU vers POST /api/v1/telemetry
  4. Consultez les graphiques et l'analyse dans l'application

Arduino / ESP32

Utilisation du client HTTP WiFi pour envoyer des données de télémétrie :

// Global state
uint32_t nonce = 0;
uint32_t runid = 1;

// Read sensors and send data
void sendTelemetry() {
    float batteryV = analogRead(VBAT_PIN) * 3.3 / 4095.0 * 2.0;
    float currentMA = readINA219();
    uint32_t elapsed = millis();
    nonce++;

    String json = "{\"records\":[";
    // Battery voltage (type: v = value measurement)
    json += "{\"id\":\"0\",\"type\":\"v\",\"value\":";
    json += String(batteryV, 3);
    json += ",\"unit\":\"V\",\"nonce\":";
    json += String(nonce);
    json += ",\"runid\":";
    json += String(runid);
    json += "},";
    // State execution duration (type: t = telemetry timing)
    json += "{\"id\":\"0.0.0\",\"type\":\"t\",\"value\":";
    json += String(500);  // execution duration in ms
    json += ",\"unit\":\"ms\",\"nonce\":";
    json += String(nonce);
    json += ",\"runid\":";
    json += String(runid);
    json += "},";
    // Current draw (type: v = value measurement)
    json += "{\"id\":\"0.0.0\",\"type\":\"v\",\"value\":";
    json += String(currentMA, 2);
    json += ",\"unit\":\"mA\",\"nonce\":";
    json += String(nonce);
    json += ",\"runid\":";
    json += String(runid);
    json += "},";
    // Elapsed time from boot (type: n = elapsed-time measurement)
    json += "{\"id\":\"0.0.0\",\"type\":\"n\",\"value\":";
    json += String(elapsed);
    json += ",\"unit\":\"ms\",\"nonce\":";
    json += String(nonce);
    json += ",\"runid\":";
    json += String(runid);
    json += "}]}";

    HTTPClient http;
    http.begin("https://api.vbatpower.com/api/v1/telemetry");
    http.addHeader("Content-Type", "application/json");
    http.addHeader("Authorization", "Bearer " + String(API_KEY));
    int code = http.POST(json);
    http.end();
}

STM32 (bare metal / HAL)

Pour un STM32 avec un module UART-vers-WiFi (commandes AT ESP8266) ou Ethernet, formatez la charge utile JSON avec snprintf :

char buf[512];
int len = snprintf(buf, sizeof(buf),
    "{\"records\":["
    "{\"id\":\"0.0.0\",\"type\":\"t\","
    "\"value\":%lu,\"unit\":\"ms\","
    "\"nonce\":%lu,\"runid\":%lu},"
    "{\"id\":\"0.0.0\",\"type\":\"v\","
    "\"value\":%.2f,\"unit\":\"mA\","
    "\"nonce\":%lu,\"runid\":%lu},"
    "{\"id\":\"0.0.0\",\"type\":\"n\","
    "\"value\":%lu,\"unit\":\"ms\","
    "\"nonce\":%lu,\"runid\":%lu}"
    "]}",
    exec_duration_ms, nonce, runid,
    current_ma, nonce, runid,
    HAL_GetTick(), nonce, runid
);

Envoyez buf comme corps de la requête HTTP POST vers /api/v1/telemetry avec les en-têtes Content-Type: application/json et Authorization: Bearer your-key.

Collecte hors ligne

Si votre MCU n'a pas de connectivité réseau, enregistrez les données sur carte SD ou en série au format CSV :

// Print CSV to Serial or SD file
void logSample(uint32_t nonce, uint32_t runid) {
    float vbat = readBattery();
    float current = readCurrent();
    uint32_t elapsed = millis();

    Serial.printf("0,v,%.3f,V,%lu,%lu\n", vbat, nonce, runid);
    Serial.printf("0.0.0,t,500,ms,%lu,%lu\n", nonce, runid);
    Serial.printf("0.0.0,v,%.2f,mA,%lu,%lu\n", current, nonce, runid);
    Serial.printf("0.0.0,n,%lu,ms,%lu,%lu\n", elapsed, nonce, runid);
}

Capturez la sortie série dans un fichier .csv et importez-le dans la page Données.

Stratégie de nonce

Le nonce est un compteur croissant de façon monotone qui regroupe les mesures prises au même instant. Règles :

  • Incrémentez une fois par cycle de mesure (et non par enregistrement)
  • Tous les enregistrements d'un même cycle partagent le même nonce
  • Ne réinitialisez jamais au cours d'une exécution — utilisez runid pour séparer les expériences
  • Utilisez un entier non signé 32 bits — à 1 échantillon/seconde, il déborde après 136 ans

Conseils

  • Téléversements groupés — tamponnez plusieurs nonces et envoyez-les dans un seul POST pour réduire les réveils WiFi et économiser de l'énergie.
  • MCU 8 bits — le format CSV ne nécessite aucune analyse JSON côté appareil. Utilisez printf pour formater les lignes et téléverser le tout en fichier plus tard.
  • États multiples — mesurez différents modes de fonctionnement (veille, actif, TX) en attribuant chacun à un ID d'état différent (p. ex. 0.0.0 pour la veille, 0.0.1 pour l'actif).
  • Surveillance de la batterie — incluez une mesure de tension à la profondeur 1 (p. ex. 0,v,3.28,V,...) pour suivre la décharge au fil du temps.