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. On the Devices page choose System → Devices → Add Device 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. It should come up Connected (the server log shows sonnen battery connected). If the log instead shows 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. Create a zone for the battery yourself — the driver does not auto-create one. Add it under Zones, bound to this sonnenBatterie device:
   • Subsystem — leave it on Power. The driver files under power, a default-seeded subsystem, so the zone editor pre-selects Power for you. (Its secondary hint, energy, is not a stock subsystem; add one under Subsystems only if you want to keep battery zones separate.)
   • Address — use battery. The address is just a label here: the battery is a single system, so the driver publishes the same live readings to every zone bound to it, regardless of address. One zone is all a typical single-stack install needs (see the multi-stack note under Known limitations below).

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, in milliseconds. Default 10000; range 2000–600000.

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.

Only the state attribute is cataloged in GEM's attribute registry; the power-flow and SOC attributes above are written live by the polling loop, so they will not show up in the Attribute editor's name picker. Type the exact name (e.g. state_of_charge or battery_power_w) when you build a trigger, dashboard tile, or report on one of them.

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.
• The sonnenBatterie does not feed GEM's generic energy dashboards — the Power Flow and battery-backup widgets (see Power Management). Those widgets light up automatically only for integrations whose readings have been tagged for them, and this driver has not been tagged. The readings still land on the zone, so you can put them on zone tiles or a custom widget, chart them under History, and use them in triggers and reports.

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).
Zone shows no readings	The zone must be bound to this sonnenBatterie device, and the device must be Connected. The driver only publishes onto zones you create — it never adds them.

Related documentation

• Devices — add and configure the sonnenBatterie device.
• Zones — create the battery zone and bind it to the device.
• Subsystems — the Power subsystem the zone files under.
• Commands — run set_mode / set_charge and the read commands.
• Power Management — GEM's energy dashboards and widgets.