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¶
JSONRPC.Helloaufrufen. Die Antwort sagt, ob die Box eine Authentifizierung verlangt (authenticationRequired) und ob sie noch kein Konto hat (initialSetupRequired).JSONRPC.Authenticatemitusername,passwordunddeviceNameaufrufen (ein Name, an dem man diesen Client erkennt und sein Token widerrufen kann) → die Box antwortet mit einemtoken.- Dieses
tokenin jede weitere Anfrage setzen, nebenidundmethod. Ein anderes Token oder keines schließt die Verbindung; für einen KontowechselJSONRPC.Helloerneut aufrufen. - Für Benachrichtigungen
JSONRPC.SetNotificationStatusmit 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.