Aller au contenu

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

  1. Appeler JSONRPC.Hello. La réponse dit si la box exige une authentification (authenticationRequired) et si elle n'a encore aucun compte (initialSetupRequired).
  2. Appeler JSONRPC.Authenticate avec username, password et deviceName (un nom qui permet de reconnaître ce client, et de révoquer son jeton) → la box répond avec un token.
  3. Mettre ce token dans chaque requête suivante, à côté de id et method. Un autre jeton, ou aucun, ferme la connexion ; pour changer de compte, refaites JSONRPC.Hello.
  4. Pour recevoir des notifications, appeler JSONRPC.SetNotificationStatus avec 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.