MEATER Cloud API for FHEM

Reproduzierbare FHEM-Integration eines einzelnen MEATER Pro über die öffentliche MEATER Cloud REST API. HTTPMOD übernimmt Login und Polling, drei Funktionen in 99_myUtils.pm bereiten die Daten auf und ein kompaktes DOIF erkennt Ereignisse.

Der Stand v0.1.0 ist für erfahrene FHEM-Anwender und Maker gedacht. Es gibt keinen Installer und kein eigenes FHEM-Modul. Die mitgelieferten Dateien werden bewusst manuell geprüft, angepasst und in die lokale Installation übernommen.

Eigenschaften

• JWT-Login über HTTPMOD mit lokalem FHEM-Key-Value-Speicher
• direkter Abruf eines einzelnen Geräts im 60-Sekunden-Intervall
• explizite JSON-Pfade statt dauerhaftem extractAllJSON
• kompakte mehrzeilige Anzeige über stateFormat
• sichere Kennzeichnung veralteter Cloud-Daten
• neutrale Anzeige ohne alte Temperaturen bei getrenntem, inaktivem Fühler
• einmalige Logereignisse pro Cook-ID
• vollständiger Ausschluss aus DbLog
• keine Steuerung des MEATER, Grills oder Ofens
• keine externen Bridges, MQTT-Dienste oder blockierenden HTTP-Aufrufe

Status und Grenzen

Die öffentliche MEATER-API ist als Beta gekennzeichnet. API-Zustände und Cook-Lebenszyklus können von der App-Darstellung abweichen. Im Live-Test blieb ein gestarteter Cook beispielsweise im API-State Configured; die laufende Zeit in elapsedSeconds war deshalb das belastbare Startsignal.

v0.1.0 unterstützt genau einen MEATER Pro. Mehrere Fühler, historische Cooks, Plots, TTS, Alexa und Pushover gehören nicht zum Umfang dieses Releases.

Enthaltene Dateien

Datei	Zweck
fhem/MeaterCloud.fhem	HTTPMOD-Gerät, JSON-Readings, userReadings und Anzeige
fhem/99_myUtils-MeaterCloud-snippet.pm	Perl-Import und drei Funktionen für die bestehende 99_myUtils.pm
fhem/doif_MeaterCloud.fhem	Minütliche Ereignisprüfung und Wiederholungssperren
tools/build-release.ps1	Erstellt ein hochladbares Release-ZIP unter dist/

Die Dateien unter fhem/ sind die maßgebliche Referenzimplementierung. Die README beschreibt Installation, Verhalten und Validierungsgrenzen, dupliziert aber nicht den gesamten Code.

Voraussetzungen

• FHEM mit HTTPMOD und DOIF
• ein MEATER-Cloud-Konto
• ein in der Cloud sichtbarer MEATER Pro
• die Geräte-ID aus GET /v1/devices
• eine vorhandene 99_myUtils.pm

Installation

1. Dateien beziehen

Repository klonen oder das ZIP eines Releases herunterladen. Vor der Übernahme alle Dateien lokal prüfen.

git clone https://github.com/TeeVau/fhem-MeaterCloudAPI.git

2. Zugangsdaten lokal speichern

Die Befehle ausschließlich in der eigenen FHEM-Instanz ausführen. Ausgefüllte Befehle, JWTs, Geräte-IDs und Cook-IDs gehören weder in Git noch in Support-Ausgaben.

{storeKeyValue("meater_email","MEATER_EMAIL")}
{storeKeyValue("meater_password","MEATER_PASSWORD")}

Die Geräte-ID wird direkt in der HTTPMOD-URL eingesetzt und absichtlich nicht über storeKeyValue verwaltet.

3. Funktionen in 99_myUtils.pm übernehmen

Aus fhem/99_myUtils-MeaterCloud-snippet.pm

1. use POSIX qw(strftime); bei den Importen ergänzen, sofern noch nicht vorhanden,
2. die drei Funktionen vor das abschließende 1; der vorhandenen 99_myUtils.pm kopieren und
3. danach in FHEM ausführen:

reload 99_myUtils.pm

Die Snippet-Datei ist kein eigenständiges FHEM-Modul und darf nicht einfach als solches in das Modulverzeichnis kopiert werden.

4. HTTPMOD-Konfiguration übernehmen

In fhem/MeaterCloud.fhem zuerst DEVICE_ID durch die eigene Geräte-ID ersetzen. Anschließend die Befehle kontrolliert in FHEM ausführen. room, alias und andere Darstellungsattribute bleiben installationsspezifisch.

Das Intervall von 60 Sekunden bleibt unter der offiziellen Empfehlung von höchstens zwei Anfragen pro 60 Sekunden. Cook-Readings werden entfernt, sobald die API keinen Cook-Block mehr liefert; extractAllJSON wird nicht benötigt.

5. Ereignisprüfung übernehmen

Die Befehle aus fhem/doif_MeaterCloud.fhem in FHEM ausführen. Der ausgerichtete Minutentimer erkennt ausbleibende Cloud-Updates auch dann, wenn kein neues HTTPMOD-Event eintrifft. Jede Meldungsart wird über die aktuelle Cook-ID gegen Wiederholungen gesperrt.

Erst nach erfolgreicher Prüfung speichern:

save

Reading-Modell

Gruppe	Readings
Gerät	deviceId, internalTemperature, ambientTemperature, updatedAt
Cook	cookId, cookName, cookState, targetTemperature, peakTemperature, elapsedSeconds, remainingSeconds
API	apiStatus, apiStatusCode
Abgeleitet	cookActive, cookStateDE, cloudState, dataAge, targetDelta, remainingTime, estimatedFinish, cookStartedAt

Zustands- und Ereignislogik

Situation	Anzeige / Verhalten
verbunden, kein Cook	aktuelle Temperaturen und Cloud: online
gestartet, API-State Configured, elapsedSeconds > 0	cookActive = 1, Anzeige läuft
aktiver Cook, Daten älter als 180 s	rote Stale-Warnbox und einmalige Logmeldung
Wiederverbindung	automatische Rückkehr zu Cloud: online
Cook-Block verschwindet nach aktivem Cook	einmalige Abschlussmeldung
getrennt, kein aktiver Cook	neutrale Meldung ohne veraltete Temperaturen

Pro Cook-ID werden höchstens folgende Ereignisse protokolliert:

• höchstens 5 °C bis zur Zieltemperatur
• Ready For Resting
• Finished oder das bestätigte Verschwinden des aktiven Cook-Blocks
• OVERCOOK!
• Messwerte länger als 180 Sekunden veraltet

Release-Paket erstellen

Das Build-Skript bündelt README, Lizenz, Changelog, Titelbild und die drei FHEM-Dateien. Die Ausgabe unter dist/ ist absichtlich nicht Teil des Git-Repositories.

powershell -ExecutionPolicy Bypass -File .\tools\build-release.ps1 -Version 0.1.1

Das Skript gibt den Pfad und den SHA-256-Hash des ZIPs aus. Dieses ZIP kann bei einem GitHub-Release als Asset hochgeladen werden; GitHub zählt dessen Downloads separat. Vor einer Veröffentlichung muss die Version zum Release-Tag passen.

Validierungsstand

Live mit einem MEATER Pro und HTTPMOD 4.2.0 geprüft:

• Login, JWT-Erneuerung und 60-Sekunden-Polling
• Cook-Start trotz API-State Configured
• Active-Cook-Merker und Wiederholungssperren
• aktive Verbindung → stale → Wiederverbindung
• genau eine Stale-Meldung während des Test-Cooks
• genau eine Abschlussmeldung nach dem Test-Cook
• neutraler Offline-Zustand ohne alte Temperaturen
• keine Einträge für MeaterCloud in DbLog

Noch nicht gezielt live beobachtet wurden die Ereignisse bei 5 °C Restdifferenz, Ready For Resting und OVERCOOK!. Sie sollten während eines normalen Garvorgangs validiert und nicht künstlich provoziert werden.

Fehlerdiagnose

Symptom	Prüfpunkte
HTTP 401 / auth_error	lokale Keys, Login-Antwort, sid1IdJSON, erneute Anmeldung
HTTP 429 / rate_limited	Pollingintervall und weitere Clients desselben Kontos
HTTP 5xx / cloud_error	MEATER-Cloud; alte Daten nicht als aktuell interpretieren
Gerät fehlt	Bluetooth- und Cloud-Verbindung der App, Konto, einmalig abgeschlossener Cloud-Cook
stale bei aktivem Cook	App-/Block-Verbindung und Fortschritt von updatedAt
kein Cook vor App-Start	erwartetes Verhalten; die API liefert noch keinen Cook-Block

Sicherheit und Datenschutz

• Das Repository enthält keine E-Mail-Adresse, kein Passwort, kein JWT, keine reale Geräte-ID und keine Cook-ID.
• storeKeyValue wird nur für E-Mail-Adresse und Passwort verwendet.
• Die Geräte-ID steht lokal in der HTTPMOD-URL und darf nicht veröffentlicht werden.
• DbLogExclude .* ist für HTTPMOD und DOIF gesetzt.
• Das Projekt ist rein lesend und darf nicht zur sicherheitskritischen Grill-/Ofensteuerung erweitert werden.

Lizenz

Veröffentlicht unter der MIT-Lizenz. MEATER und MEATER Pro sind Marken ihrer jeweiligen Rechteinhaber. Dieses Projekt ist nicht mit Apption Labs verbunden oder von Apption Labs unterstützt.

Quellen

• MEATER Cloud REST API
• FHEM HTTPMOD
• FHEM DOIF