sonnenBatterie

GEM driver for sonnen residential and light-commercial battery storage systems (sonnenBatterie eco, 8, 10, and evo) using the local v2 REST API. Reads live power flow, state-of-charge, and operating mode; writes operating mode and manual charge/discharge setpoints when the battery is in manual mode.

The driver talks to the battery directly on the LAN — no cloud account or internet connectivity is required. Telemetry remains on-site.

Prerequisites

• A sonnenBatterie on the same LAN as the GEM host with firmware that exposes the v2 REST API. This is universal on eco 10 and evo and is available on eco 8 firmware ≥ 1.10.

• An Auth-Token generated from the sonnen User UI. Open the battery's web interface at http://<battery-ip>/, sign in as the system owner, navigate to Software-Integration, and either copy the existing token or generate a new one. Keep this token private — anyone with it can charge, discharge, or reconfigure the battery.

• Confirm the GEM host can reach the API. From the GEM host:

  curl -H "Auth-Token: <your-token>" http://192.168.1.x/api/v2/status

  A JSON response (not an empty object) confirms the token is correct.

Setup steps

1. Add the device under Devices → Add and pick sonnenBatterie (Local API) as the driver.
2. Fill in the battery's LAN IP for ip and paste the Auth-Token into token. Leave port at 80 (the sonnen API is not exposed on TLS).
3. Save and reload the device. Watch the server log for sonnen battery connected. If you see initial read failed, double-check the token — older firmware silently returns an empty object instead of 401 when the token is wrong.
4. Run the get_system command to confirm the battery model and serial.
5. Add a zone for the battery. Use battery as the zone address; most sonnen installs are single-stack, so one zone is all you need. Multi-stack sonnen systems may add additional logical addresses in the future.

Attribute reference

Device

Attribute	Required	Description
ip	yes	LAN IP of the sonnen battery.
token	yes	Auth-Token from Software-Integration (secure).
port	no	HTTP port. Default 80.
status_interval	no	How often the driver polls /api/v2/status for live power flow and SOC (ms). Default 10000.

Zone

Attribute	Description
address	battery for the primary system.
state	charging, discharging, or idle — derived from the live power flow.
state_of_charge	User-visible state of charge (USOC, %).
production_w	Solar / DC production in watts.
consumption_w	Site load in watts.
grid_feed_w	Grid feed-in in watts (positive = exporting, negative = importing).
battery_power_w	Net battery power (positive = discharging, negative = charging) per Pac_total_W.
operating_mode	Numeric EM_OperatingMode (1 = manual, 2 = self-consumption, 6 = backup, 10 = time-of-use).
charging / discharging	Boolean flow flags from the API.

Commands

Command	Description
get_system	Read battery_system info (capacity, model, serial).
get_status	Read /api/v2/status — same data the driver polls automatically.
get_latestdata	Read /api/v2/latestdata for the most granular live measurements.
get_inverter	Read inverter telemetry.
get_io	Read IO states.
set_mode	Set EM_OperatingMode. Argument mode accepts manual, self_consumption, backup, or time_of_use.
set_charge	Set a manual charge setpoint in watts. Only honored when the battery is in manual mode.
set_discharge	Set a manual discharge setpoint in watts. Only honored in manual mode.
stop_charging	Clear the manual setpoint (set_charge to 0).

Known limitations

• Setpoint commands (set_charge, set_discharge, stop_charging) are silently ignored unless the battery is in manual mode. Most production installs run in self_consumption or time_of_use; a macro that wants short-term direct control needs to flip the mode first and restore it after.
• The driver currently exposes a single logical zone. Multi-stack sonnen systems do report per-module data through latestdata; surfacing those as separate zones is a follow-up.
• No write paths for EM_USOC_* (USOC reserve floor) or charge/discharge rate-limit settings yet. Read them from get_status if needed.

Troubleshooting

Symptom	Likely cause
Reads return {} with status 200	Auth-Token typo. Older firmware does not return 401; it returns success with no data.
Setpoint commands have no effect	Battery is not in manual mode. Call set_mode with mode=manual first.
connection refused on port 443	sonnen only exposes HTTP on port 80 on the LAN interface. Do not change protocol to https.
Status poll never updates	Confirm status_interval is not absurdly large and that the device is reachable from the GEM host (check ping).