# JSON-RPC API <span class="badge ok">Supported</span>

ETM PowerSync exposes **nymea's JSON-RPC API** locally, extended with the ETM
namespaces (`Energy`, `AirConditioning`, `EvDash`).

---

## Connection

| Mode | Address | Notes |
| --- | --- | --- |
| **Raw TCP** | `<ip>:2222` | The server sends a JSON welcome message (`\n`-delimited) on connect |
| **WebSocket** | `ws://<ip>:4444` | The client sends `JSONRPC.Hello` first |

Every message is a JSON object terminated by `\n`. Requests carry an `id` field
(integer) to match the reply. Notifications have no `id`.

---

## Authentication

1. Call [`JSONRPC.Authenticate`](../api/metier/jsonrpc.md#jsonrpcauthenticate)
   with `username`, `password` and `deviceName` → the server answers with a
   `token`.
2. Include the `token` in every subsequent request.
3. To receive notifications: call `JSONRPC.SetNotificationStatus` with
   `{ "namespaces": ["Energy", "Integrations", ...] }`.

---

## 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) |

---

## Permission badges

| Badge | Scope | Description |
| --- | --- | --- |
| <span class="badge perm-none">AUTH</span> | `PermissionScopeNone` | Any authenticated account (token required whenever the transport requires authentication; only `JSONRPC.Hello`, `Authenticate` and `RequestPushButtonAuth` work without one) |
| <span class="badge perm-control">CONTROL</span> | `PermissionScopeControlThings` / `ExecuteRules` | Control of things and rules |
| <span class="badge perm-configure">CONFIGURE</span> | `PermissionScopeConfigureThings` / `ConfigureRules` | Configuration of integrations and rules |
| <span class="badge perm-admin">ADMIN</span> | `PermissionScopeAdmin` | System administration |

---

## Full reference

→ [JSON-RPC API reference](../api/index.md)