API JSON-RPC — guide Supporté¶
ETM PowerSync expose en local l'API JSON-RPC de nymea, avec les namespaces des modules
installés sur la box (Energy, NymeaEnergy pour le moteur, AirConditioning). Cette page
explique comment s'y connecter ; chaque méthode est décrite dans la
référence.
Connexion¶
| Mode | Adresse | Notes |
|---|---|---|
| TCP | <ip>:2222 |
chiffré (TLS) dans la configuration par défaut |
| WebSocket | wss://<ip>:4444 |
chiffré (TLS) dans la configuration par défaut |
Le certificat est auto-signé : la box l'a créé elle-même (voir Première connexion). Votre client doit l'accepter, idéalement en vérifiant son empreinte.
Le client parle en premier : il envoie JSONRPC.Hello dans les 10 secondes, sinon la
box ferme la connexion. Tout autre message envoyé avant Hello ferme aussi la connexion.
Chaque message est un objet JSON ; séparez deux messages par un saut de ligne. Une requête
porte un id (entier), repris dans sa réponse, et "status" y vaut success, error ou
unauthorized. Une notification porte un champ notification (son nom, par exemple
Energy.PowerBalanceChanged) et son propre id.
Authentification¶
- Appeler
JSONRPC.Hello. La réponse dit si la box exige une authentification (authenticationRequired) et si elle n'a encore aucun compte (initialSetupRequired). - Appeler
JSONRPC.Authenticateavecusername,passwordetdeviceName(un nom qui permet de reconnaître ce client, et de révoquer son jeton) → la box répond avec untoken. - Mettre ce
tokendans chaque requête suivante, à côté deidetmethod. Un autre jeton, ou aucun, ferme la connexion ; pour changer de compte, refaitesJSONRPC.Hello. - Pour recevoir des notifications, appeler
JSONRPC.SetNotificationStatusavec la liste des namespaces voulus.
Exemple¶
Une session minimale, message par message (→ envoyé par le client, ← reçu) :
→ {"id": 1, "method": "JSONRPC.Hello", "params": {}}
← {"id": 1, "status": "success", "params": {"authenticationRequired": true, "initialSetupRequired": false, …}}
→ {"id": 2, "method": "JSONRPC.Authenticate",
"params": {"username": "<compte>", "password": "<mot de passe>", "deviceName": "mon-script"}}
← {"id": 2, "status": "success", "params": {"success": true, "token": "<jeton>", …}}
→ {"id": 3, "token": "<jeton>", "method": "JSONRPC.SetNotificationStatus",
"params": {"namespaces": ["Energy"]}}
← {"id": 3, "status": "success", "params": {"namespaces": ["Energy"], …}}
→ {"id": 4, "token": "<jeton>", "method": "Energy.GetPowerBalance", "params": {}}
← {"id": 4, "status": "success", "params": {"currentPowerAcquisition": …, …}}
Gardez le jeton : il reste valable aux connexions suivantes, où JSONRPC.Hello peut le
porter directement.
Conventions énergie¶
| Grandeur | Convention |
|---|---|
| Production PV | valeur négative (convention producteur) |
currentPowerAcquisition |
réseau — positif = import, 0 si export |
currentPowerStorage |
batterie — positif = charge, négatif = décharge |
| Totaux d'énergie | en kWh |
| Timestamps | en secondes (Unix epoch) |
Référence complète¶
→ Référence API JSON-RPC : chaque méthode, notification et type, avec le droit qu'elle exige.