API locale d'historique énergétique pour les relevés en kWh

Introduction

Pour les utilisateurs qui créent leurs propres tableaux de bord, automatisations ou outils d'analyse hors ligne, les données énergétiques réelles sont plus utiles lorsqu'elles sont disponibles à intervalle régulier. Une simple mesure de puissance en temps réel montre ce qui se passe à l'instant présent, mais un historique kWh par demi-heure aide à comprendre comment les importations et les exportations d'électricité évoluent dans le temps.

À partir de la version de firmware i.91.063TS8.bin, publiée le 2 juin 2026, IAMMETER prend en charge une nouvelle API locale : GET /api/energyhistory. Cette API renvoie des relevés kWh mis en cache localement, échantillonnés autour des limites de demi-heure UTC, ce qui facilite l'analyse de la consommation récente sans dépendre uniquement de l'historique côté cloud.

C'est particulièrement utile pour la surveillance solaire, la surveillance énergétique domestique et les workflows de gestion d'énergie personnalisés, dans lesquels les utilisateurs souhaitent comparer l'importation, l'exportation et les données énergétiques par phase. IAMMETER n'est pas seulement un appareil de mesure : l'objectif de la collecte de ces données est d'aider les utilisateurs à optimiser leur consommation, à améliorer l'autoconsommation solaire et à réduire leurs factures d'électricité.

Ce que fournit l'API Energy History

Le nouvel endpoint est :

GET /api/energyhistory

Il renvoie des relevés d'énergie en kWh, échantillonnés autour de ces limites de demi-heure UTC :

• 00:00
• 00:30
• 01:00
• 01:30
• etc.

Le firmware conserve jusqu'à 96 enregistrements, soit 48 heures d'historique à intervalles de 30 minutes. Les enregistrements sont stockés dans la RAM du module Wi-Fi : ils sont donc perdus après un redémarrage de l'appareil.

Une réponse typique comprend :

• utc : l'horodatage UTC actuel du module
• timeSynced : indique si le module dispose d'une heure UTC valide
• interval : l'intervalle d'échantillonnage, actuellement 1800 secondes
• count : le nombre d'enregistrements d'historique disponibles
• order : actuellement newest_first
• unit : actuellement kWh
• channels : les noms de canaux correspondant à chaque valeur
• Datas : les enregistrements d'historique par demi-heure

Chaque élément de Datas contient un horodatage UTC et un tableau de valeurs en kWh. Les valeurs suivent le même ordre que le tableau channels.

Pourquoi l'historique kWh par demi-heure est important

Les données énergétiques par demi-heure sont pratiques car elles offrent une vue compacte mais pertinente du comportement énergétique. Au lieu d'enregistrer chaque point en temps réel, les utilisateurs peuvent analyser les valeurs cumulées d'importation et d'exportation sur des créneaux fixes.

Par exemple, un utilisateur peut se servir des données locales pour :

• Consulter l'énergie importée et exportée récente sans attendre les rapports cloud.
• Exporter les 48 dernières heures de relevés kWh vers une base de données locale ou un fichier CSV.
• Comparer les profils d'exportation solaire avec la consommation du foyer.
• Vérifier si une stratégie d'automatisation modifie la consommation d'électricité sur certaines périodes.
• Créer un tableau de bord local pour l'historique énergétique récent.

Pour des scénarios de surveillance solaire plus larges, consultez la solution de surveillance solaire IAMMETER. Pour la surveillance de l'électricité résidentielle, consultez la solution de surveillance énergétique domestique IAMMETER.

Configurations de canaux prises en charge

Le champ channels indique au client comment interpréter les valeurs de chaque enregistrement d'historique. Différentes configurations de compteur renvoient différentes dispositions de canaux.

Monophasé

["imp", "exp"]

Biphasé (split phase)

["a_imp", "a_exp", "b_imp", "b_exp"]

Triphasé

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"]

Triphasé avec compensation nette activée

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp", "nem_imp", "nem_exp"]

Les noms de canaux étant renvoyés dans la réponse, un logiciel personnalisé doit d'abord lire le tableau channels, puis associer chaque valeur de Datas[].values en conséquence.

Exemples de réponses d'origine de l'API

Les deux exemples suivants présentent les valeurs d'origine renvoyées par l'API pour une réponse vide et pour une réponse contenant des données.

Exemple de réponse vide

Après le démarrage de l'appareil, le tableau d'historique peut rester vide tant qu'une heure UTC valide et des trames de compteur valides ne sont pas disponibles. Dans ce cas, l'API peut renvoyer count: 0 et un tableau Datas vide.

{
  "utc": 1780023600,
  "timeSynced": 1,
  "interval": 1800,
  "count": 0,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": []
}

Cette réponse est normale après le démarrage. Un tableau de bord ou un script local doit gérer cet état et attendre de nouveaux échantillons par demi-heure.

Exemple de réponse avec données

L'exemple suivant montre deux enregistrements par demi-heure provenant d'un compteur triphasé. La réponse est ordonnée du plus récent au plus ancien.

{
  "utc": 1780023700,
  "timeSynced": 1,
  "interval": 1800,
  "count": 2,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": [
    {
      "utc": 1780023600,
      "values": [11.337, 11.201, 11.039, 10.908, 10.975, 10.846]
    },
    {
      "utc": 1780021800,
      "values": [11.330, 11.198, 11.030, 10.900, 10.970, 10.840]
    }
  ]
}

Dans l'enregistrement le plus récent, a_imp vaut 11.337 kWh, a_exp vaut 11.201 kWh, et ainsi de suite. La signification de chaque valeur est définie par le tableau channels.

Utiliser les valeurs renvoyées dans un logiciel

Les exemples de réponses d'origine ci-dessus suffisent pour construire une logique d'analyse locale simple. L'essentiel est de lire d'abord channels, puis d'appliquer cet ordre à chaque élément de Datas.

Associer channels à values

Lorsque vous développez un logiciel autour de cette API, évitez de coder en dur les positions, sauf si la configuration du compteur est fixe. Une approche plus sûre consiste à convertir la liste des canaux et le tableau de valeurs en un objet nommé.

const response = await fetch("http://<meter-ip>/api/energyhistory").then((res) => res.json());
const latest = response.Datas[0];

const latestByChannel = Object.fromEntries(
  response.channels.map((name, index) => [name, latest.values[index]])
);

console.log(latest.utc, latestByChannel);

Pour l'exemple de réponse triphasée ci-dessus, latestByChannel contiendrait :

{
  "a_imp": 11.337,
  "a_exp": 11.201,
  "b_imp": 11.039,
  "b_exp": 10.908,
  "c_imp": 10.975,
  "c_exp": 10.846
}

Les données sont ainsi plus faciles à stocker, à afficher ou à exporter vers un outil d'analyse local.

Calculer une variation de kWh sur une demi-heure

Si vous utilisez les valeurs kWh renvoyées comme des relevés d'énergie cumulés, la variation entre deux enregistrements adjacents peut être calculée en soustrayant la valeur la plus ancienne de la plus récente pour un même canal.

En reprenant l'exemple triphasé ci-dessus :

variation a_imp = 11.337 - 11.330 = 0.007 kWh
variation a_exp = 11.201 - 11.198 = 0.003 kWh
variation b_imp = 11.039 - 11.030 = 0.009 kWh
variation b_exp = 10.908 - 10.900 = 0.008 kWh

Ce type de calcul aide les utilisateurs à construire un rapport récent d'importation/exportation, à comparer les variations d'énergie par phase ou à vérifier la quantité d'énergie importée ou exportée pendant un créneau de demi-heure donné.

Comportement d'échantillonnage important

L'historique énergétique est généré localement par le module Wi-Fi. Ce comportement d'échantillonnage est important lors de la création d'intégrations ou d'outils d'analyse :

• L'échantillonnage est piloté par des trames de compteur UART valides.
• Le module stocke l'échantillon le plus proche de chaque limite de demi-heure UTC.
• L'heure UTC doit être valide avant que les enregistrements d'historique ne soient stockés.
• Si timeSynced vaut 0, aucun nouvel échantillon d'historique n'est enregistré.
• Après le démarrage, Datas peut être vide jusqu'à ce qu'un nombre suffisant d'échantillons valides ait été capturé.
• Le stockage actuel se fait en RAM : l'API est donc destinée à l'historique local récent, et non au stockage à long terme.

L'API convient ainsi à l'interrogation locale, à l'analyse à court terme et aux tests d'intégration. Pour les rapports énergétiques à long terme, les utilisateurs doivent conserver une source de données persistante, comme les données cloud IAMMETER ou leur propre base de données.

Idées d'intégration

Les développeurs et les utilisateurs avancés peuvent utiliser /api/energyhistory comme source de données locale simple pour l'historique kWh récent.

Une approche courante consiste à interroger périodiquement l'endpoint, à lire la liste channels et à enregistrer tout nouvel enregistrement Datas dans une base de données locale. Cela permet d'alimenter des tableaux de bord locaux, des rapports personnalisés ou des scripts d'analyse hors ligne.

Un autre scénario utile est l'analyse de l'autoconsommation solaire. En comparant les valeurs kWh importées et exportées sur des créneaux de demi-heure, les utilisateurs comprennent mieux quand les charges domestiques consomment localement la production solaire et quand l'énergie excédentaire est exportée. Cela permet de meilleures décisions d'automatisation, comme le décalage des charges flexibles vers les périodes de production solaire plus élevée.

Si vous développez des intégrations locales, consultez également API locale, Modbus/TCP et MQTT et l'explorateur d'API locale IAMMETER.

Comment cela s'intègre à la gestion de l'énergie

La valeur d'une API d'historique énergétique ne réside pas seulement dans le fait qu'elle expose davantage de données. L'essentiel est ce que les utilisateurs peuvent faire de ces données.

Avec un historique kWh par demi-heure, les utilisateurs peuvent analyser l'importation et l'exportation récentes d'électricité, identifier des habitudes de consommation et évaluer si les stratégies solaires ou de pilotage des charges apportent réellement un bénéfice. Cela sert l'objectif global d'IAMMETER : transformer les données de surveillance énergétique en décisions concrètes qui améliorent l'efficacité énergétique et réduisent les factures d'électricité.

Pour les utilisateurs qui associent IAMMETER à des plateformes d'automatisation, l'historique énergétique local peut aussi fournir une couche de données pratique pour tester et valider la logique de contrôle. Par exemple, les utilisateurs de Home Assistant qui optimisent l'utilisation du surplus solaire peuvent examiner les variations kWh récentes en parallèle du comportement de leurs automatisations. Voir automatisation solaire Home Assistant avec IAMMETER pour un cas d'usage connexe.

FAQ

Cette API peut-elle remplacer l'historique énergétique à long terme ?

Non. L'API stocke jusqu'à 96 enregistrements, soit 48 heures de données par demi-heure, en RAM. Elle est conçue pour l'historique local récent. Les données sont perdues après un redémarrage.

Pourquoi Datas est-il vide après le démarrage ?

Après le démarrage, le module a besoin d'une heure UTC valide et de trames de compteur valides avant de pouvoir enregistrer des échantillons d'historique. Tant qu'un nombre suffisant d'échantillons valides n'a pas été capturé, l'API peut renvoyer un tableau Datas vide.

Les horodatages sont-ils basés sur l'heure locale ?

Non. Les créneaux d'échantillonnage sont alignés sur les limites de demi-heure UTC.

Comment un logiciel doit-il interpréter le tableau de valeurs ?

Lisez toujours d'abord le champ channels. Les valeurs de chaque tableau Datas[].values suivent le même ordre que les noms de canaux.