Modèle de données et format de payload MQTT

Cette page technique décrit l'API MQTT exacte de la fonctionnalité d'export MQTT. Utilisez ce format lorsque vous construisez un subscriber, un parser ou une pipeline de données qui consomme des messages EnergieID.

Prêt à relier votre broker à EnergieID ? Pour les étapes de configuration, les droits et les messages d'erreur, consultez Export MQTT.

Concepts de base

• Workspace : l'environnement d'une organisation dans EnergieID.
• Record : un dossier dans un Workspace, le plus souvent un bâtiment ou une installation.
• Meter : une série temporelle dans un dossier, par exemple la consommation de gaz, la production solaire ou le stockage batterie.
• Device (twin) : un appareil ou point de données connecté qui peut fournir des messages en temps réel.
• Channel : un canal de mesure dans les données d'appareil (key-value), par exemple la puissance, la tension, le courant ou la température.

Quels flux de données existent ?

• Données de compteur : lectures de compteur traitées provenant du dossier. Ces données ne sont pas en temps réel et sont publiées périodiquement. La fréquence dépend de l'intégration et du type de compteur.
• Données d'appareil : données d'appareil en temps réel par connexion/intégration. Toutes les intégrations ne fournissent pas de données en temps réel ; certaines ne publient que des données de compteur.

Toutes les données d'appareil sont également publiées comme données de compteur, éventuellement agrégées après traitement, mais toutes les données de compteur ne sont pas publiées comme données d'appareil, car toutes les intégrations ne fournissent pas de données en temps réel. Pour les analyses, il vaut donc mieux utiliser les données de compteur, car elles sont plus complètes. Si vous voulez construire un tableau de bord en temps réel, utilisez plutôt les données d'appareil.

Données de compteur

Topic par défaut : energyid/workspace/{{workspaceId}}/record/{{recordNumber}}/meter/{{meterId}}

Les données de compteur sont publiées sous la forme d'un objet JSON contenant des métadonnées et un tableau data.

{
  "workspaceId": "7e8f2f7e-2c9f-4e90-bf2e-8e1c6b6f5f6c",
  "recordNumber": "EA-1234567",
  "meterId": "3c2a6b8f-7f0a-45b4-9d4a-6f73b30e30aa",
  "metric": "electricityImport",
  "unit": "kWh",
  "readingType": "PostmarkedInterval",
  "interval": "PT15M",
  "data": [
    {
      "timestamp": "2026-08-06 10:15:00+02:00",
      "value": 1.42,
      "min": 1.21,
      "max": 1.55,
      "mean": 1.39
    }
  ]
}

Champs

• workspaceId : GUID du Workspace.
• recordNumber : numéro du dossier.
• meterId : GUID du compteur.
• metric : code de métrique indiquant ce qui est mesuré.
• unit : unité associée à cette métrique.
• readingType : type de mesure, qui précise comment interpréter une valeur, par exemple Counter ou Gauge.
• interval : périodicité de mesure ISO-8601, par exemple PT5M, PT15M, PT1H, P1D, ou manual pour les mesures non périodiques.
• data[].timestamp : timestamp avec offset.
• data[].value : valeur principale de la mesure.
• data[].min / max / mean : uniquement pertinent pour des données de type gauge ; peut manquer ou être null pour d'autres types.

Important : Les champs metric, unit et readingType sont des Enums, il existe donc un ensemble fixe de valeurs possibles. Pour une vue à jour de toutes les valeurs possibles, consultez la documentation API des ressources meter : EnergyID API reference - Meters.

Données d'appareil

Topic par défaut : energyid/workspace/{{workspaceId}}/record/{{recordNumber}}/device/{{twinId}}

Les données d'appareil sont publiées événement par événement au format JSON.

{
  "recordNumber": "EA-1234567",
  "twinId": "f2a13f6d-1d7a-4f14-b5e8-a53c9f638f1c",
  "timestamp": 1754477700,
  "channels": {
    "pwr": 430.2,
    "el": 230.1
  }
}

Champs

• recordNumber : numéro du dossier.
• twinId : GUID de l'appareil/digital twin.
• timestamp : timestamp Unix (secondes).
• channels : map key-value avec les canaux de mesure et des valeurs numériques.

Détail des channels

Les clés exactes dans channels dépendent du type d'appareil et de l'intégration connectée. EnergieID traite les channels comme un ensemble de mesures flexible, de sorte que l'ensemble des clés peut varier selon le message ou le type d'appareil.

Caractéristiques typiques des channels :

• Chaque clé est un nom de mesure, par exemple el, pwr, bat ou heat.
• Chaque valeur est numérique (floating point).
• Toutes les clés ne sont pas toujours présentes ; les subscribers doivent gérer défensivement les clés manquantes ou supplémentaires.
• La signification et l'unité d'une clé de channel dépendent de l'intégration et du type d'appareil.

Ci-dessous, vous trouverez une liste des channels standards et la manière dont nous les mappons dans nos systèmes :

QoS et comportement retain

• Les messages sont publiés avec la QoS AtLeastOnce (QoS 1).
• Pour les données de compteur, le publisher utilise un flag retain afin que le dernier payload connu puisse être conservé sur le topic par le broker.
• Pour les données d'appareil en temps réel, les messages sont publiés sans retain.

Erreurs et robustesse

• En cas d'échec de connexion ou de publication, EnergieID journalise un échec de livraison spécifique au broker dans les paramètres du Workspace.
• Après un échec, le publisher réessaie avec une nouvelle connexion.
• Lors du premier échec, un administrateur du Workspace reçoit un message dans le centre de messages.