Skip to content
PLANOVI Docs

Telemetry Pipeline & Cloud Ingestion

The Telemetry Pipeline packages readings acquired by the Modbus engine, adds hardware timestamps and system diagnostic metadata, and delivers packets to the Planovi Cloud using MQTT over Mutual TLS (mTLS).

1. Telemetry Schema v3 Specification

All telemetry data emitted by the converter adheres strictly to Schema v3:

{
  "schema_version": 3,
  "converter_id": "conv-aslandi-001a4f",
  "timestamp": "2026-09-21T10:45:00.124Z",
  "trusted_time": true,
  "system": {
    "uptime_seconds": 345820,
    "free_heap_bytes": 184320,
    "temperature_celsius": 42.6,
    "wifi_rssi": -64,
    "littlefs_queue_depth": 14,
    "active_alarms": []
  },
  "readings": [
    {
      "meter_address": 1,
      "meter_type": "ZAMEL_LEM60",
      "status": "OK",
      "metrics": {
        "active_energy_import_kwh": 1452.34,
        "active_energy_export_kwh": 312.80,
        "voltage_v": 231.4,
        "current_a": 4.12,
        "active_power_w": 948,
        "frequency_hz": 50.0
      }
    },
    {
      "meter_address": 2,
      "meter_type": "CHINT_DTSU666",
      "status": "OK",
      "metrics": {
        "active_energy_import_kwh": 8940.15,
        "reactive_energy_kvarh": 124.50,
        "voltage_l1_v": 230.8,
        "voltage_l2_v": 231.2,
        "voltage_l3_v": 230.1,
        "current_l1_a": 12.4,
        "current_l2_a": 11.8,
        "current_l3_a": 14.1,
        "active_power_kw": 8.74,
        "power_factor": 0.98
      }
    }
  ]
}

2. Cloud Transport: MQTT QoS 1 over mTLS

sequenceDiagram
    autonumber
    participant Converter as Aslandi Converter
    participant Broker as "Secure MQTT Broker (Port 8883)"
    participant Backend as "Planovi Backend (FastAPI / Deno)"
    participant DB as Supabase PostgreSQL

    Note over Converter,Broker: mTLS Handshake (Client Cert + Planovi CA)
    Converter->>Broker: CONNECT (ClientID: conv-aslandi-001a4f, KeepAlive: 60s)
    Broker-->>Converter: CONNACK (Accepted)
    
    loop Every Telemetry Interval
        Converter->>Broker: PUBLISH (Topic: planovi/telemetry/conv-aslandi-001a4f, QoS: 1, PacketID: 412)
        Broker->>Backend: Forward Telemetry Packet
        Backend->>Backend: Validate Schema v3 & Compute Unique Hash
        Backend->>DB: INSERT INTO telemetry ... ON CONFLICT DO NOTHING
        DB-->>Backend: Insert Confirmed
        Broker-->>Converter: PUBACK (PacketID: 412)
        Converter->>Converter: Retire Record from LittleFS FIFO Buffer
    end

Protocol Invariants

  • Topic Structure: planovi/telemetry/{converter_id}
  • QoS 1 Guarantee: The converter guarantees At-Least-Once delivery. Messages remain in flash memory until the broker returns PUBACK.
  • Deduplication Engine: The backend computes a composite unique constraint (converter_id, meter_address, timestamp) on PostgreSQL ingest, safely discarding duplicate packets generated during sudden connection dropouts.
  • Failover to HTTP: If the MQTT broker port is blocked by enterprise firewalls, the converter supports an authenticated HTTPS fallback endpoint (POST /api/v1/telemetry/ingest).