Lokale Energieverlaufs-API für kWh-Werte

title: Lokale Energieverlaufs-API für kWh-Werte

abstract: Halbstündliche kWh-Historie lokal für Offline-Analysen auslesen.

language: de

author: Jessica

Einleitung

Für Nutzer, die eigene Dashboards, Automatisierungen oder Offline-Analysewerkzeuge erstellen, sind echte Energiedaten dann besonders nützlich, wenn sie in einem stabilen Intervall verfügbar sind. Ein einzelner Echtzeit-Leistungswert zeigt, was gerade passiert, doch eine halbstündliche kWh-Historie hilft Nutzern zu verstehen, wie sich Strombezug und Einspeisung im Laufe der Zeit verändern.

Ab der Firmware-Version i.91.063TS8.bin, veröffentlicht am 2. Juni 2026, unterstützt IAMMETER eine neue lokale API: GET /api/energyhistory. Diese API liefert lokal zwischengespeicherte kWh-Werte, die um UTC-Halbstundengrenzen herum abgetastet werden. Dadurch lässt sich der aktuelle Energieverbrauch leichter analysieren, ohne ausschließlich auf die Historie in der Cloud angewiesen zu sein.

Das ist besonders nützlich für die Solarüberwachung, die Überwachung des Haushaltsstroms und individuelle Energiemanagement-Workflows, bei denen Nutzer Bezug, Einspeisung und Energie auf Phasenebene vergleichen möchten. IAMMETER ist nicht nur ein Messgerät; der Zweck der Datenerfassung besteht darin, Nutzern zu helfen, ihren Energieverbrauch zu optimieren, den Eigenverbrauch von Solarstrom zu erhöhen und Stromkosten zu senken.

Was die Energy-History-API bereitstellt

Der neue Endpunkt lautet:

GET /api/energyhistory

Er liefert Energiewerte in kWh, abgetastet um diese UTC-Halbstundengrenzen:

00:00
00:30
01:00
01:30
und so weiter

Die Firmware speichert bis zu 96 Datensätze, was 48 Stunden Historie im 30-Minuten-Intervall entspricht. Die Datensätze liegen im RAM des Wi-Fi-Moduls und gehen daher bei einem Neustart des Geräts verloren.

Eine typische Antwort enthält:

utc: der aktuelle UTC-Zeitstempel des Moduls
timeSynced: ob das Modul über eine gültige UTC-Zeit verfügt
interval: das Abtastintervall, derzeit 1800 Sekunden
count: die Anzahl der verfügbaren Verlaufsdatensätze
order: derzeit newest_first
unit: derzeit kWh
channels: die Kanalnamen, die zu den jeweiligen Werten passen
Datas: die halbstündlichen Verlaufsdatensätze

Jeder Eintrag in Datas enthält einen UTC-Zeitstempel und ein Array mit kWh-Werten. Die Werte folgen derselben Reihenfolge wie das Array channels.

Warum eine halbstündliche kWh-Historie wichtig ist

Halbstündliche Energiedaten sind praxisnah, weil sie Nutzern eine kompakte, aber aussagekräftige Sicht auf das Energieverhalten bieten. Statt jeden Echtzeitpunkt zu speichern, können Nutzer kumulierte Bezugs- und Einspeisewerte über feste Zeitfenster analysieren.

Zum Beispiel kann ein Nutzer die lokalen Daten verwenden, um:

den kürzlich bezogenen und eingespeisten Strom zu prüfen, ohne auf Cloud-Berichte zu warten.
die letzten 48 Stunden an kWh-Werten in eine lokale Datenbank oder CSV-Datei zu exportieren.
Einspeisemuster der Solaranlage mit dem Verbrauch des Haushalts zu vergleichen.
zu prüfen, ob eine Automatisierungsstrategie den Stromverbrauch in bestimmten Zeiträumen verändert.
ein lokales Dashboard für den aktuellen Energieverlauf zu erstellen.

Für umfassendere Solarüberwachungsszenarien siehe die IAMMETER Solar Energy Monitoring Solution. Für die Überwachung des Haushaltsstroms siehe die IAMMETER Home Energy Monitoring Solution.

Unterstützte Kanal-Layouts

Das Feld channels sagt dem Client, wie die Werte in jedem Verlaufsdatensatz zu interpretieren sind. Unterschiedliche Zählerkonfigurationen liefern unterschiedliche Kanal-Layouts.

Einphasig

["imp", "exp"]

Split Phase

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

Dreiphasig

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

Dreiphasig mit aktiviertem Net Metering

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

Da die Kanalnamen in der Antwort zurückgegeben werden, sollte individuelle Software zuerst das Array channels lesen und dann jeden Wert in Datas[].values entsprechend zuordnen.

Beispiele der ursprünglichen API-Rückgabe

Die folgenden zwei Beispiele zeigen die ursprünglichen Rückgabewerte der API für eine leere Antwort und eine Antwort mit Daten.

Beispiel einer leeren Antwort

Nach dem Start des Geräts kann das Verlaufs-Array leer sein, bis eine gültige UTC-Zeit und gültige Zähler-Telegramme vorliegen. In diesem Fall kann die API count: 0 und ein leeres Datas-Array zurückgeben.

{
  "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": []
}

Diese Antwort ist nach dem Start normal. Ein lokales Dashboard oder Skript sollte diesen Zustand behandeln und auf neue Halbstundenwerte warten.

Beispiel einer Datenantwort

Das folgende Beispiel zeigt zwei halbstündliche Datensätze eines dreiphasigen Zählers. Die Antwort ist vom neuesten zum ältesten Datensatz geordnet.

{
  "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]
    }
  ]
}

Im neuesten Datensatz ist a_imp gleich 11.337 kWh, a_exp gleich 11.201 kWh und so weiter. Die Bedeutung jedes Wertes wird durch das Array channels festgelegt.

Verwendung der Rückgabewerte in Software

Die oben gezeigten ursprünglichen Rückgabebeispiele reichen aus, um eine einfache lokale Analyselogik aufzubauen. Entscheidend ist, zuerst channels zu lesen und diese Reihenfolge dann auf jeden Eintrag in Datas anzuwenden.

Zuordnung von `channels` zu `values`

Beim Aufbau von Software rund um diese API sollten fest codierte Positionen vermieden werden, sofern die Zählerkonfiguration nicht feststeht. Ein sicherer Ansatz besteht darin, die Kanalliste und das Werte-Array in ein benanntes Objekt umzuwandeln.

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

Für die oben gezeigte dreiphasige Beispielantwort würde latestByChannel Folgendes enthalten:

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

So lassen sich die Daten leichter speichern, anzeigen oder in ein lokales Analysewerkzeug exportieren.

Berechnung der kWh-Änderung über eine halbe Stunde

Wenn Sie die zurückgegebenen kWh-Werte als kumulierte Energiewerte verwenden, lässt sich die Änderung zwischen zwei benachbarten Datensätzen berechnen, indem der ältere Wert vom neueren Wert desselben Kanals subtrahiert wird.

Unter Verwendung des obigen dreiphasigen Beispiels:

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

Diese Art der Berechnung kann Nutzern helfen, einen aktuellen Bezugs-/Einspeisebericht zu erstellen, Energieänderungen auf Phasenebene zu vergleichen oder zu prüfen, wie viel Energie in einem bestimmten Halbstundenfenster bezogen oder eingespeist wurde.

Wichtiges Abtastverhalten

Der Energieverlauf wird lokal vom Wi-Fi-Modul erzeugt. Das Abtastverhalten ist wichtig, wenn Integrationen oder Analysewerkzeuge erstellt werden:

Die Abtastung wird durch gültige UART-Zähler-Telegramme ausgelöst.
Das Modul speichert den Wert, der jeder UTC-Halbstundengrenze am nächsten liegt.
Die UTC-Zeit muss gültig sein, bevor Verlaufsdatensätze gespeichert werden.
Wenn timeSynced gleich 0 ist, werden keine neuen Verlaufswerte aufgezeichnet.
Nach dem Start kann Datas leer sein, bis genügend gültige Werte erfasst wurden.
Der aktuelle Speicher ist RAM-basiert, daher ist die API für den aktuellen lokalen Verlauf gedacht, nicht für die Langzeitspeicherung.

Damit eignet sich die API für lokales Polling, kurzfristige Analysen und Integrationstests. Für langfristige Energieberichte sollten Nutzer weiterhin eine persistente Datenquelle nutzen, etwa die Daten der IAMMETER-Cloud oder eine eigene Datenbank.

Beispiele für Integrationsideen

Entwickler und fortgeschrittene Nutzer können /api/energyhistory als einfache lokale Datenquelle für den aktuellen kWh-Verlauf verwenden.

Ein gängiger Ansatz besteht darin, den Endpunkt regelmäßig abzufragen, die Liste channels zu lesen und alle neuen Datas-Datensätze in einer lokalen Datenbank zu speichern. Dies kann lokale Dashboards, individuelle Berichte oder Offline-Analyseskripte unterstützen.

Ein weiteres nützliches Szenario ist die Analyse des Solar-Eigenverbrauchs. Durch den Vergleich von bezogenen und eingespeisten kWh-Werten über Halbstundenfenster können Nutzer besser verstehen, wann Haushaltslasten die Solarerzeugung lokal verbrauchen und wann überschüssige Energie eingespeist wird. Das kann bessere Automatisierungsentscheidungen unterstützen, etwa das Verschieben flexibler Lasten in Zeiträume mit höherer Solarleistung.

Wenn Sie lokale Integrationen erstellen, siehe auch Local API, Modbus/TCP and MQTT und den IAMMETER Local API Explorer.

Wie das ins Energiemanagement passt

Der Wert einer Energieverlaufs-API liegt nicht nur darin, dass sie mehr Daten bereitstellt. Entscheidend ist, was Nutzer mit diesen Daten tun können.

Mit einer halbstündlichen kWh-Historie können Nutzer den aktuellen Strombezug und die Einspeisung analysieren, Verbrauchsmuster erkennen und bewerten, ob Solar- oder Laststeuerungsstrategien tatsächlich helfen. Das unterstützt das übergeordnete Ziel von IAMMETER: Energiemonitoring-Daten in praktische Entscheidungen umzuwandeln, die die Energieeffizienz verbessern und die Stromkosten senken.

Für Nutzer, die IAMMETER mit Automatisierungsplattformen kombinieren, kann der lokale Energieverlauf zudem eine praktische Datenschicht zum Testen und Validieren von Steuerungslogik bieten. Beispielsweise können Home-Assistant-Nutzer, die die Nutzung von Solarüberschuss optimieren, die aktuellen kWh-Änderungen zusammen mit dem Automatisierungsverhalten prüfen. Siehe Home Assistant Solar Energy Automation with IAMMETER für einen verwandten Anwendungsfall.

FAQ

Kann diese API die langfristige Energiehistorie ersetzen?

Nein. Die API speichert bis zu 96 Datensätze, also 48 Stunden halbstündlicher Daten, im RAM. Sie ist für den aktuellen lokalen Verlauf ausgelegt. Nach einem Neustart gehen die Daten verloren.

Warum ist `Datas` nach dem Start leer?

Nach dem Start benötigt das Modul eine gültige UTC-Zeit und gültige Zähler-Telegramme, bevor Verlaufswerte aufgezeichnet werden können. Bis genügend gültige Werte erfasst wurden, kann die API ein leeres Datas-Array zurückgeben.

Basieren die Zeitstempel auf der lokalen Zeit?

Nein. Die Abtastfenster sind an UTC-Halbstundengrenzen ausgerichtet.

Wie sollte Software das Werte-Array interpretieren?

Lesen Sie immer zuerst das Feld channels. Die Werte in jedem Array Datas[].values folgen derselben Reihenfolge wie die Kanalnamen.