Skip to content

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

  1. Call JSONRPC.Hello. The reply says whether the box requires authentication (authenticationRequired) and whether it has no account yet (initialSetupRequired).
  2. Call JSONRPC.Authenticate with username, password and deviceName (a name to recognise this client by, and to revoke its token) → the box answers with a token.
  3. Put this token in every subsequent request, next to id and method. Another token, or none, closes the connection; to switch accounts, call JSONRPC.Hello again.
  4. To receive notifications, call JSONRPC.SetNotificationStatus with 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.