JSON-RPC API — guide Supported¶
ETM PowerSync exposes nymea's JSON-RPC API locally, with the namespaces of the modules
installed on the box (Energy, NymeaEnergy for the engine, AirConditioning). This page
explains how to connect; every method is described in the
reference.
Connection¶
| Mode | Address | Notes |
|---|---|---|
| TCP | <ip>:2222 |
encrypted (TLS) in the default configuration |
| WebSocket | wss://<ip>:4444 |
encrypted (TLS) in the default configuration |
The certificate is self-signed: the box created it itself (see First connection). Your client has to accept it, ideally after checking its fingerprint.
The client speaks first: it sends JSONRPC.Hello within 10 seconds, otherwise the box
closes the connection. Any other message sent before Hello closes it too.
Every message is a JSON object; separate two messages with a newline. A request carries an
id (integer), echoed in its reply, where "status" is success, error or
unauthorized. A notification carries a notification field (its name, for example
Energy.PowerBalanceChanged) and its own id.
Authentication¶
- Call
JSONRPC.Hello. The reply says whether the box requires authentication (authenticationRequired) and whether it has no account yet (initialSetupRequired). - Call
JSONRPC.Authenticatewithusername,passwordanddeviceName(a name to recognise this client by, and to revoke its token) → the box answers with atoken. - Put this
tokenin every subsequent request, next toidandmethod. Another token, or none, closes the connection; to switch accounts, callJSONRPC.Helloagain. - To receive notifications, call
JSONRPC.SetNotificationStatuswith the list of namespaces you want.
Example¶
A minimal session, message by message (→ sent by the client, ← received):
→ {"id": 1, "method": "JSONRPC.Hello", "params": {}}
← {"id": 1, "status": "success", "params": {"authenticationRequired": true, "initialSetupRequired": false, …}}
→ {"id": 2, "method": "JSONRPC.Authenticate",
"params": {"username": "<account>", "password": "<password>", "deviceName": "my-script"}}
← {"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": …, …}}
Keep the token: it stays valid on later connections, where JSONRPC.Hello can carry it
directly.
Energy conventions¶
| Quantity | Convention |
|---|---|
| PV output | negative value (producer convention) |
currentPowerAcquisition |
grid — positive = import, 0 when exporting |
currentPowerStorage |
battery — positive = charging, negative = discharging |
| Energy totals | in kWh |
| Timestamps | in seconds (Unix epoch) |
Full reference¶
→ JSON-RPC API reference: every method, notification and type, with the permission it requires.