Read from the real-time API on sonnenBatterie to manage Backup Reserve use.
Use sonnenBatterie web portal or mobile app to set Backup Reserve percent.
- System state On Grid, Off Grid or Critical Error.
- Real time power, current and voltage.
- Battery levels, Charge/Discharge rate, time to fully charged.
- Backup reserve, time to reserve, time to fully discharge.
- MicroGrid status when Offgrid & Blackstart settings.
- Temperature and batterie health.
This Home Assistant component helps manage sonnenBatterie backup reserve, particularly whilst batterie is 'OffGrid'.
The official Sonnen mobile app normally used to monitor the batterie relies on the cloud service the batterie reports to. When grid power is off, it is likely Internet may also be out either due to the same event or eventually power is out long enough to deplete ISP equipment emergency power.
Without Internet access, Home Assistant server requires only the local home network to continue functioning using the sonnenBatterie backup reserve charge.
It is recommended to have an independent (small) UPS running off sonnenBatterie power for the LAN & Home Assistant server. There is a momentary power drop when sonnenBatterie switches to MicroGrid mode when grid power drops. A small UPS will prevent Home Assistant server from rebooting at the very moment it needs to alert you to batterie system_status changed to "OffGrid".
The excellent Weltmeyer/ha_sonnenbatterie package uses API v1 with user/password authentication. If you can't use a user account with API v1, this API v2 package can also be used to configure HASS Energy dashboard.
Install sonnenbackup custom integration.
Uses sonnen_api_v2 driver package which requires a readonly API Token created in the sonnenBatterie management portal.
Configuration will require the IP address of the battery device and the readonly API token.
If the Batterie portal uses a non-standard port, other than 80, that can be configured too.
The API package does not support https (port 443) using a self-signed certificate.
Install sonnenbackup with hacs.
Open HACS -> Home Assistant Community Store page
From Overflow Menu: 3 vertical dots upper right, choose custom repositories.
Enter github URL: https://github.com/MarkusBiggus/SonnenBackup
The component is added to HACS and the form redisplayed - click cancel to return to HACS.
Search HACS for the component just added, SonnenBackup.
Click the Integration to see its details page.
On the component details page click the download button lower right.
Return to HACS (upper left arrow) where "Pending Restart" is displayed.
Restart HASS from Settings/System restart button, upper far right.
From Settings/Devices & Services, click Add Integration button, lower right.
HASS Sensor is the name used by Home Assistant from the sonnen_api_v2 package property.
| HASS Sensor | Package Property | Type | When Valid |
|---|---|---|---|
| activity_state | battery_activity_state | string | always |
| blackstart_time1 | configuration_blackstart_time1 | string | when configured |
| blackstart_time2 | configuration_blackstart_time2 | string | when configured |
| blackstart_time3 | configuration_blackstart_time3 | string | when configured |
| firmware_version | configuration_de_software | string | always |
| interval_since_full | time_since_full | string | always |
| interval_to_fully_charged | time_to_fully_charged | string | charging is true |
| interval_until_fully_discharged | time_until_fully_discharged | string | discharging is true |
| interval_to_reserve | time_to_reserve | string | see notes below |
| led_state | led_state | string | always |
| led_state_text | led_state_text | string | always |
| led_status | led_status | string | always |
| operating_mode | configuration_em_operatingmode | string | always |
| package_version | response.version | string | always |
| package_build | response.package_build | string | always |
| seconds_to_reserve | seconds_to_reserve | integer | charging or discharging is true |
| seconds_to_fully_charged | seconds_to_fully_charged | integer | charging is true |
| seconds_until_fully_discharged | seconds_until_fully_discharged | integer | discharging is true |
| state_bms | state_bms | string | always |
| state_inverter | state_inverter | string | always |
| system_status | system_status | string | always |
| cycle_count | battery_cycle_count | integer | always |
| average_current | battery_average_current | Amps | always |
| unusable_capacity | battery_unusable_capacity_wh | Wh | always |
| capacity_to_reserve | capacity_to_reserve | Wh | usable_capacity <= reserve_capacity |
| capacity_until_reserve | capacity_until_reserve | Wh | usable_capacity => reserve_capacity |
| full_charge_capacity | battery_full_charge_capacity_wh | Wh | always |
| remaining_capacity | remaining_capacity_wh | Wh | always |
| reserve_capacity | backup_buffer_capacity_wh | Wh | always |
| usable_capacity | usable_remaining_capacity_wh | Wh | always |
| used_capacity | used_capacity | Wh | always |
| frequency | status_frequency | hertz | always |
| kwh_consumed | kwh_consumed | kWh | always |
| kwh_produced | kwh_produced | kWh | always |
| depth_of_discharge_limit | battery_dod_limit | percent | always |
| relative_charge | r_soc | percent | always |
| usable_charge | u_soc | percent | always |
| reserve_charge | status_backup_buffer | percent | always |
| charge_power | charging | watts | charging is true |
| consumption_average | consumption_average | watts | always |
| consumption_now | consumption | watts | always |
| discharge_power | discharging | watts | discharging is true |
| grid_export | status_grid_export | watts | always |
| grid_import | status_grid_import | watts | always |
| offgrid_power | inverter_pac_microgrid | watts | system_status is 'OffGrid' |
| ongrid_power | inverter_pac_total | watts | system_status is 'OnGrid' |
| production_now | production | watts | always |
| max_battery_temp | battery_max_cell_temp | celsius | always |
| min_battery_temp | battery_min_cell_temp | celsius | always |
| fully_charged_at | fully_charged_at | timestamp | charging is true or activity_state=='charged' |
| fully_discharged_at | fully_discharged_at | timestamp | discharging is true |
| last_time_full | last_time_full | timestamp | always |
| last_updated | last_updated | timestamp | always |
| reserve_at | backup_reserve_at | timestamp | see notes below |
| status_timestamp | system_status_timestamp | timestamp | always |
| time_since_full | time_since_full | deltatime | always |
| time_to_fully_charged | time_to_fully_charged | deltatime | charging is true |
| time_until_fully_discharged | time_until_fully_discharged | deltatime | discharging is true |
| time_to_reserve | time_to_reserve | deltatime | see notes below |
| blackstart_enabled | configuration_em_reenable_microgrid | bool | when configured |
| microgrid_enabled | microgrid_enabled | bool | system_status is 'OffGrid' |
| charging | status_battery_charging | bool | always |
| discharging | status_battery_discharging | bool | always |
| dc_minimum_rsoc | dc_minimum_rsoc_reached | bool | microgrid_enabled is true |
| microgrid_minimum_soc | mg_minimum_soc_reached | bool | microgrid_enabled is true |
Some sensors have enumerated values:
system_status: ["Config", "OnGrid", "OffGrid", "Critical Error"]
activity_state: ["standby", "charging", "discharging", "discharging reserve", "charged", "discharged"]
operating_mode: {1: "Manual", 2: "Automatic", 6: "Extension module", 10: "Time of Use"}
Sensors time_to_reserve & interval_to_reserve are the same measurement with different datatypes. Both are calculated from seconds_to_reserve.
Calculations to Reserve capacity are only valid when:
*usable_charge* is above *reserve_charge* whilst *discharging* is true
*usable_charge* is below *reserve_charge* whilst *charging* is true
in both cases, *time_to_reserve* is estimated using current *charge_power* or *discharge_power* values.
"standby" indicates the battery is neither charging nor discharging.
The battery could be fully charged, fully discharged or idle at backup reserve charge.
Must be read in conjuction with usable_charge to determine the reason for "standby".
Activity "discharging reserve" & "discharged" can only happen when system_status is "OffGrid".
Timestamps are datetime.datetime objects.
Sensors fully_charged_at, fully_discharged_at & backup_reserve_at are calculated on current charge_power or discharge_power values.
When battery activity_state is 'standby', these timestamp values are undefined.
Times are calculated relative to sonnenBatterie system time system_status_timestamp.
A slight discrepency will be apparent if HASS server time and batterie system time are different.
Deltatimes are datetime.deltatime objects.
Sensors prefixed with 'time_' are delatime objects.
Sensors prefixed with 'interval_' are deltatimes as string format "D HH:MM:SS".
HASS has problems with delatime object sensors, so use the string format in things like LogBooks and anywhere deltatime object sensors don't work as expected, like template variables.
Sensors with 'seconds_' prefix are the values used to create the deltatime objects.
As a rule, 'time_to' is valid when charging & 'time_until' is valid when discharging. 'time_to_reserve' is valid when charging below reserve or discharging above reserve.
Sensor indicates the state of the status LED on the side of the battery.
Only one element may be True, that element, with brightness, is returned as a string.
e.g 'Pulsing White 100%'
"Eclipse Led": {
"Blinking Green":true, # undocumented - see "Eclipse Status"
"Blinking Red":true, # Error - call installer!
"Brightness":100,
"Eclipse Status":"0x01 - ONGRID_READY",
"Pulsing Green":true, # Off Grid.
"Pulsing Orange":true, # No Internet connection!
"Pulsing White":true, # Normal Operation.
"Solid Red":true # Critical Error - call installer!
}
All values False indicates Off Grid operation, the string "Off Grid." is returned.
The meaning of the current LED state as defined in the user manual, including "Eclipse Status" text.
Comments in example are text string returned.
eg. "Normal Operation. [0x01 - ONGRID_READY]" is returned for LED state 'Pulsing White 100%'
led_status returns "Eclipse Status" text.
sonnenBatterie reports two State of Charge values, Relative and Usable. The difference between these two values is reported by sensor depth_of_discharge_limit (DoD). Depth of Discharge reserve is included in relative_charge (RSoC) overall values, like full_charge_capacity. Specific usable values are based on usable_charge (USoC), like usable_capacity, which do not include the DoD limit reported by sensor unusable_capacity.
Importantly, the reserve_charge percent for backup buffer is based on USoC. eg. when sensor activity_state is 'standby' USoC equals Backup Reserve Charge, a little less than RSoC.
Sensors capacity_to_reserve & capacity_until_reserve are both zero when battery is in standby at reserve_capacity. Otherwise, only one has a value depending on USoC being above or below reserve_charge.
Two sensors are extracted from the sonnen_api_v2 API response:
package_version is the version of the installed package being used.
package_build is build number of the installed package being used.
Use developer tools to examine these sensors to confirm which package verion/build is currently running in HASS.
Some sensor values do not change, some only change when configuration changes, some are of little value when not current. These sensors will waste space if recorded.
Suggested recording exclusions in configuration.yaml:
# Recorder filter to exclude specified entities, change placeholder names
# your actual sensor names.
# eg. "sonnenbackup_nnnnnn_full_charge_capacity"
# where 'nnnnnn' is the battery serial number entered on the config form.
recorder:
exclude:
entities:
- sensor.sonnenbackup_nnnnnn_backup_reserve_at
- sensor.sonnenbackup_nnnnnn_backup_reserve_percent
- sensor.sonnenbackup_nnnnnn_blackstart_enabled
- sensor.sonnenbackup_nnnnnn_blackstart_time1
- sensor.sonnenbackup_nnnnnn_blackstart_time2
- sensor.sonnenbackup_nnnnnn_blackstart_time3
- sensor.sonnenbackup_nnnnnn_depth_of_discharge_limit
- sensor.sonnenbackup_nnnnnn_full_charge_capacity
- sensor.sonnenbackup_nnnnnn_fully_charged_at
- sensor.sonnenbackup_nnnnnn_fully_discharged_at
- sensor.sonnenbackup_nnnnnn_interval_to_fully_charged
- sensor.sonnenbackup_nnnnnn_interval_until_fully_discharged
- sensor.sonnenbackup_nnnnnn_interval_to_reserve
- sensor.sonnenbackup_nnnnnn_interval_since_full
- sensor.sonnenbackup_nnnnnn_led_state
- sensor.sonnenbackup_nnnnnn_last_time_full
- sensor.sonnenbackup_nnnnnn_last_updated
- sensor.sonnenbackup_nnnnnn_operating_mode
- sensor.sonnenbackup_nnnnnn_package_version
- sensor.sonnenbackup_nnnnnn_package_build
- sensor.sonnenbackup_nnnnnn_reserve_charge
- sensor.sonnenbackup_nnnnnn_seconds_since_full
- sensor.sonnenbackup_nnnnnn_state_bms
- sensor.sonnenbackup_nnnnnn_state_inverter
- sensor.sonnenbackup_nnnnnn_status_frequency
- sensor.sonnenbackup_nnnnnn_system_status_timestamp
- sensor.sonnenbackup_nnnnnn_time_to_fully_charged
- sensor.sonnenbackup_nnnnnn_time_until_fully_discharged
- sensor.sonnenbackup_nnnnnn_time_to_reserve
- sensor.sonnenbackup_nnnnnn_time_since_full
- sensor.sonnenbackup_nnnnnn_unusable_capacity
Go to Settings then Devices & Services then select Helpers from the top menu. Create each of the 6 integrals by clicking “+ CREATE HELPER”, lower right.
Choose Integral Sensor -> Add Riemann sum integral sensor: use Left rule for conservative values, Trapezoidal rule for more realistic values over longer periods.
| Helper Name | SonnenBackup Input Sensor | Rule | Precision | Interval |
|---|---|---|---|---|
| PowerConsumption | sensor.sonnenbackup_nnnnnn_consumption_now | Trapezoidal | 1 | 10s |
| PowerProduction | sensor.sonnenbackup_nnnnnn_production_now | Trapezoidal | 1 | 10s |
| GridImport | sensor.sonnenbackup_nnnnnn_grid_import | Trapezoidal | 1 | 10s |
| GridExport | sensor.sonnenbackup_nnnnnn_grid_export | Trapezoidal | 1 | 10s |
| BatteryInput | sensor.sonnenbackup_nnnnnn_charge_power | Trapezoidal | 1 | 10s |
| BatteryOutput | sensor.sonnenbackup_nnnnnn_discharge_power | Trapezoidal | 1 | 10s |
XXXXX will be the Batterie serial number entered on the configuration form.
Metric prefix is blank, all package sensor integer values are single units.
Use default time unit Hours for all integrals.
| Energy Dashboard Metric | Helper Sensor |
|---|---|
| Grid Consumption | GridImport |
| Grid Production | GridExport |
| Battery In | BatteryInput |
| Battery Out | BatteryOutput |
| Solar Production | PowerProduction |
Solar production may also be provided by a sensor from the solar inverter component. Given sonnenBatterie is AC coupled, the Sonnen production value will be slightly less and so a more realistic value to use.
The sonnenBatterie EVO model has a Black Start feature that will attempt to restart the batterie after depletion. A small reserve is kept to enable solar production at set times in the morning. Check configuration AC Microgrid is enabled with reenabling times also set to times solar production is usually available.
A weather event that will cause no sunshine for several days, such as a cyclone/hurricane, will exhaust Black Start retries before solar production is available to charge the battery, leaving the battery off until grid power is restored.
Have a generator option installed to the household powerboard to run the house from generator in absence of grid power for an extended period. Like, days after a severe weather event. For both strategies below, rely on generator for household power whilst battery is unavailable.
sonnenBatterie must be configured for Recharge Strategy "Green charging" to only charge from solar production.
Isolate the battery from load before it turns itself off when USoC is low, under 15% or so. When solar production is available, enable the battery circuit and allow it to "green charge" normally.
Let Batterie deplete and rely on Black Start feature.
Should Black Start feature not work after solar production can resume, use generator power to restart the battery. "Green charging" recharge strategy will not charge the battery from generator power.
Do NOT use generator power to recharge the batterie without assurance from manufacturer that you have a supported configuration for your sonnenBatterie with your model generator.
These batteries have been tested and confirmed to be working. If your batterie is not listed below, this library may still work provided your battery admin portal can generate an API read token and responds to Sonnen API v2 endpoints. Newer Sonnen Batteries are not provisoned with user accounts for API v1 access. Whilst the installer account could be used, that is not a wise cybersecurity choice to use those credentials for this purpose.
- Power unit Evo IP56
API token will return status 401 if used with API v1. Use Weltmeyer/ha_sonnenbatterie package if user/password authentication is required.