Integração de MCU

Visão geral

O VBatPower aceita dados de telemetria de qualquer dispositivo capaz de fazer pedidos HTTP POST. O formato dos dados é intencionalmente simples — um CSV plano que pode ser gerado com printf em qualquer MCU de 8 bits.

O fluxo típico:

  1. Crie um projeto na aplicação VBatPower
  2. Gere uma chave de API em Definições > API
  3. Envie telemetria do seu MCU para POST /api/v1/telemetry
  4. Veja gráficos e análises na aplicação

Arduino / ESP32

A usar o cliente HTTP WiFi para enviar dados de telemetria:

// 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)

Para STM32 com um módulo UART-para-WiFi (comandos AT do ESP8266) ou Ethernet, formate o payload JSON com 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
);

Envie buf como corpo do pedido HTTP POST para /api/v1/telemetry com os cabeçalhos Content-Type: application/json e Authorization: Bearer your-key.

Recolha Offline

Se o seu MCU não tiver conectividade de rede, registe os dados num cartão SD ou na porta série em formato 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);
}

Capture a saída série para um ficheiro .csv e importe-o na página Dados.

Estratégia de Nonce

O nonce é um contador monotonicamente crescente que agrupa medições efetuadas no mesmo instante. Regras:

  • Incremente uma vez por ciclo de medição (não por registo)
  • Todos os registos de um ciclo partilham o mesmo nonce
  • Nunca reinicie dentro de uma execução — use runid para separar experiências
  • Use um inteiro sem sinal de 32 bits — a 1 amostra/segundo, transborda ao fim de 136 anos

Dicas

  • Carregamentos em lote — armazene em buffer vários nonces e envie-os num único POST para reduzir os despertares do WiFi e poupar energia.
  • MCUs de 8 bits — o formato CSV não exige análise de JSON no lado do dispositivo. Use printf para formatar as linhas e carregue-as como ficheiro mais tarde.
  • Múltiplos estados — meça diferentes modos de funcionamento (suspensão, ativo, TX) atribuindo cada um a um ID de estado diferente (p. ex. 0.0.0 para suspensão, 0.0.1 para ativo).
  • Monitorização da bateria — inclua uma medição de tensão na profundidade 1 (p. ex. 0,v,3.28,V,...) para acompanhar a descarga ao longo do tempo.