SolarAssistant WebSocket API

WebSocket API

This article covers the device WebSocket API for local network access. For remote access via the cloud, see the Cloud API. Client libraries are available for Python and Go.

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 site authorize API or sacli authorize 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.

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

After connecting, use the events below. The ref field is a client-chosen identifier echoed back in the server's reply, allowing you to match responses to requests. Using "phx_join" instead of "join" is also accepted for full compatibility with Phoenix Channels. Client libraries are available in C#, Python, JavaScript (docs, npm), Java/Kotlin and Swift.

SENDjoinStart receiving metrics

Joins the metrics channel. By default a curated set of common metrics is streamed. Pass a topics filter to subscribe to specific topics only.

Payload fields

topics

array

List of topic filters, e.g. [{"topic": "total/*"}, {"topic": "battery_1/*"}]. Omit to receive the default set.

Example

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

With topic filter

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

SENDtopicsSet which metrics to receive

Changes the topic subscription after joining, without rejoining the channel.

Payload fields

topics

arrayrequired

List of topic filters. Use [{"topic": "*"}] to receive all topics.

Example

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

Add max_frequency_s to any filter to throttle update frequency for that topic:

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

RECVdefinitionReceive metric metadata from server

Sent once per topic after joining with metadata describing the metric.

Example

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

RECVdataReceive metric values from server

Sent each time metric values update.

Example

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

SENDsetWrite a setting

Sends a new value to the inverter. The topic format matches the metrics topics.

Payload fields

topic	stringrequired	The metric topic to write, e.g. inverter_1/output_source_priority.
value	stringrequired	The new value to set.

Example

{
  "topic": "metrics",
  "event": "set",
  "payload": {"topic": "inverter_1/output_source_priority", "value": "Utility first"},
  "ref": "3"
}

RECVset_resultReceive result of set command

Sent in response to a set event. On failure the payload includes a result of "error" and a message describing the problem.

Example

{
"event": "set_result",
"payload": {"topic": "inverter_1/output_source_priority", "result": "ok"}
}

Topic structure

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

Topic	Description
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 = discharging (W)
total/battery_state_of_charge	Battery state of charge (%)
total/pv_energy	PV energy generated this period (kWh)
total/load_energy	Load energy consumed this period (kWh)
total/battery_energy_in	Energy charged into the battery this period (kWh)
total/battery_energy_out	Energy discharged from the battery this period (kWh)
total/grid_energy_in	Energy imported from the grid this period (kWh)
total/grid_energy_out	Energy exported to the grid this period (kWh)
inverter_1/device_mode	Current inverter mode
battery_1/voltage	Battery voltage (V)

The kWh topics are period-to-date totals, not lifetime counters. Each one is the energy measured since the start of the current period in the device's local time, and it starts again from zero when the next period begins. Set the period under Configuration › System › Reset energy totals: Daily counts from midnight, Weekly from Monday midnight (the default) and Monthly from the 1st of the month.

If you derive energy deltas by subtracting consecutive readings, expect a large negative step at each reset and treat the first reading of a new period as the energy used since that period started.