Zum Inhalt

JSON-RPC-API — Leitfaden Unterstützt

ETM PowerSync stellt lokal die JSON-RPC-API von nymea bereit, mit den Namensräumen der auf der Box installierten Module (Energy, NymeaEnergy für die Engine, AirConditioning). Diese Seite erklärt die Verbindung; jede Methode steht in der Referenz.


Verbindung

Modus Adresse Hinweise
TCP <ip>:2222 in der Standardkonfiguration verschlüsselt (TLS)
WebSocket wss://<ip>:4444 in der Standardkonfiguration verschlüsselt (TLS)

Das Zertifikat ist selbstsigniert: Die Box hat es selbst erzeugt (siehe Erste Verbindung). Ihr Client muss es akzeptieren, am besten nach Prüfung seines Fingerabdrucks.

Der Client spricht zuerst: Er sendet JSONRPC.Hello innerhalb von 10 Sekunden, sonst schließt die Box die Verbindung. Jede andere Nachricht vor Hello schließt sie ebenfalls.

Jede Nachricht ist ein JSON-Objekt; trennen Sie zwei Nachrichten durch einen Zeilenumbruch. Eine Anfrage trägt eine id (Ganzzahl), die in ihrer Antwort wiederkehrt; "status" ist dort success, error oder unauthorized. Eine Benachrichtigung trägt ein Feld notification (ihren Namen, z. B. Energy.PowerBalanceChanged) und eine eigene id.


Authentifizierung

  1. JSONRPC.Hello aufrufen. Die Antwort sagt, ob die Box eine Authentifizierung verlangt (authenticationRequired) und ob sie noch kein Konto hat (initialSetupRequired).
  2. JSONRPC.Authenticate mit username, password und deviceName aufrufen (ein Name, an dem man diesen Client erkennt und sein Token widerrufen kann) → die Box antwortet mit einem token.
  3. Dieses token in jede weitere Anfrage setzen, neben id und method. Ein anderes Token oder keines schließt die Verbindung; für einen Kontowechsel JSONRPC.Hello erneut aufrufen.
  4. Für Benachrichtigungen JSONRPC.SetNotificationStatus mit der Liste der gewünschten Namensräume aufrufen.

Beispiel

Eine minimale Sitzung, Nachricht für Nachricht (→ vom Client gesendet, ← empfangen):

→ {"id": 1, "method": "JSONRPC.Hello", "params": {}}
← {"id": 1, "status": "success", "params": {"authenticationRequired": true, "initialSetupRequired": false, …}}

→ {"id": 2, "method": "JSONRPC.Authenticate",
   "params": {"username": "<Konto>", "password": "<Passwort>", "deviceName": "mein-skript"}}
← {"id": 2, "status": "success", "params": {"success": true, "token": "<Token>", …}}

→ {"id": 3, "token": "<Token>", "method": "JSONRPC.SetNotificationStatus",
   "params": {"namespaces": ["Energy"]}}
← {"id": 3, "status": "success", "params": {"namespaces": ["Energy"], …}}

→ {"id": 4, "token": "<Token>", "method": "Energy.GetPowerBalance", "params": {}}
← {"id": 4, "status": "success", "params": {"currentPowerAcquisition": …, …}}

Bewahren Sie das Token auf: Es bleibt bei späteren Verbindungen gültig, wo JSONRPC.Hello es direkt mitgeben kann.


Energie-Konventionen

Größe Konvention
PV-Erzeugung negativer Wert (Erzeugerkonvention)
currentPowerAcquisition Netz — positiv = Bezug, 0 bei Einspeisung
currentPowerStorage Speicher — positiv = Laden, negativ = Entladen
Energiesummen in kWh
Zeitstempel in Sekunden (Unix-Epoch)

Vollständige Referenz

→ JSON-RPC-API-Referenz: jede Methode, Benachrichtigung und jeder Typ, mit dem Recht, das sie verlangt.