WebSocket API

Authentication

Local access

Connect directly to your SolarAssistant device on your local network using your device password. A password must be configured on the device before the API can be used - see the local password guide for instructions.

Cloud access

When accessing a SolarAssistant unit via the cloud, requests go through two layers of security. See the sacli authorize section for details.

Connecting

The WebSocket API streams live metrics as they update. The examples below assume your device's IP address is 192.168.0.100. You can find your device's IP address in the access overview.

Connect to:

ws://192.168.0.100/api/socket/websocket?password=<password>

Then join the metrics channel. The ref is a client-chosen identifier that is echoed back in the server's reply, allowing you to match responses to requests:

{"topic": "metrics", "event": "join", "payload": {}, "ref": "1"}

Using "event": "phx_join" is also accepted for full compatibility with Phoenix Channels. Client libraries are available in C#, Python, JavaScript (docs, npm), Java/Kotlin and Swift.

By default a curated set of common metrics is streamed. To subscribe to specific topics, pass a topics filter on join:

{
  "topic": "metrics",
  "event": "join",
  "payload": {"topics": [{"topic": "total/*"}, {"topic": "battery_1/*"}]},
  "ref": "1"
}

To change the topic filter after joining, send a topics event:

{
  "topic": "metrics",
  "event": "topics",
  "payload": {"topics": [{"topic": "*"}]},
  "ref": "2"
}

The server sends two types of messages. A definition message is sent once per topic with its metadata:

{
  "event": "definition",
  "payload": {"definitions": [
    {"topic": "total/pv_power", "device": "Totals", "group": "Status", "name": "PV power", "unit": "W"}
  ]}
}

A data message is sent each time metric values update:

{
  "event": "data",
  "payload": {"metrics": [
    {"topic": "total/pv_power", "value": 1240},
    {"topic": "total/load_power", "value": 940}
  ]}
}

You can also limit update frequency per topic with max_frequency_s to avoid being overwhelmed with updates:

{"topics": [{"topic": "total/*", "max_frequency_s": 5}]}

Topic structure

Topics follow the same structure as MQTT. Metrics are grouped under total/, inverter_1/, inverter_2/, battery_1/, etc. Some common topics:

  • total/pv_power - combined PV power across all inverters (W)
  • total/load_power - total load power (W)
  • total/grid_power - grid power, negative = export (W)
  • total/battery_power - battery power, negative = charging (W)
  • total/battery_state_of_charge - battery state of charge (%)
  • inverter_1/device_mode - current inverter mode
  • battery_1/voltage - battery voltage (V)