Battery Control

Battery Control

The battery can be controlled two ways, and the integration offers both:

• Over Modbus (SunSpec storage model 124): Storage Control Mode and the limits and grid powers that go with it, and the Modbus storage reserve. Every entry with a battery has them, also one without the web API.
• Over the Web API: the settings of the inverter's own battery management, as its web interface shows them. They need a login (see Web API).

The inverter's own controls - AC limit, power factor, grid connection, export soft limit - are at the end of the page, under Inverter controls.

Scheduled (time-dependent) charging and discharging in the inverter's web interface and the Modbus storage modes get in each other's way; turn the schedule off when using the modes.

Storage control modes

Storage Control Mode selects how the battery is controlled over Modbus. Change the mode first, then set the controls active in that mode: a mode change resets its rates.

Mode	Key	What it does
Auto	auto	The inverter runs its own battery management; the Modbus storage reserve is not applied in this mode.
PV Charge Limit	pv_charge_limit	The battery charges from PV at a limited rate. The limit is set to the maximum after the change.
Discharge Limit	discharge_limit	The battery charges from PV and discharges at a limited rate. The limit is set to the maximum after the change.
PV Charge and Discharge Limit	pv_charge_and_discharge_limit	Both limits. They are set to the maximum after the change.
Charge from Grid	charge_from_grid	The battery charges from the grid at Grid charge power, which is set to 0 W after the change. See Charging from the grid.
Discharge to Grid	discharge_to_grid	The battery discharges to the grid at Grid discharge power, which is set to 0 W after the change.
Block Discharging	block_discharging	The battery only charges, from PV. The charge limit is set to the maximum.
Block Charging	block_charging	The battery only discharges and does not charge from PV. The discharge limit is set to the maximum.

The entity state and the select.select_option value are the keys; the mode names are the display texts.

Selecting a grid mode again keeps its grid power while the inverter still holds the mode; otherwise it starts at 0 W again.

Which control each mode uses

Mode	PV charge limit	Discharge limit	Grid charge power	Grid discharge power	Modbus storage reserve
Auto	Ignored (100 %)	Ignored (100 %)	Ignored (0 %)	Ignored (0 %)	Ignored
PV Charge Limit	Used	Ignored (100 %)	Ignored (0 %)	Ignored (0 %)	Used
Discharge Limit	Ignored (100 %)	Used	Ignored (0 %)	Ignored (0 %)	Used
PV Charge and Discharge Limit	Used	Used	Ignored (0 %)	Ignored (0 %)	Used
Charge from Grid	Ignored	Ignored	Used	Ignored (0 %)	Used
Discharge to Grid	Ignored	Ignored	Ignored (0 %)	Used	Used
Block Discharging	Used	Ignored (0 %)	Ignored (0 %)	Ignored (0 %)	Used
Block Charging	Ignored (0 %)	Used	Ignored (0 %)	Ignored (0 %)	Used

A limit or grid power the current mode does not use is unavailable; select a mode that uses it first. Modbus storage reserve is the exception: it stays writable in every mode, and in Auto the inverter ignores it (see Two minimum SoC values).

How the modes relate to the inverter's web interface

The time-dependent battery control of the inverter's web interface corresponds to these controls (observed, not documented by Fronius):

Web interface	Integration control	Integration mode
Max. charging power	PV charge limit	PV Charge Limit
Min. charging power	Grid charge power	Charge from Grid
Max. discharging power	Discharge limit	Discharge Limit
Min. discharging power	Grid discharge power	Discharge to Grid

What the inverter refuses, and the integration refuses first

This section and With evcc describe 1.4.0b3 and later. In 1.4.0b2 the integration still judges both rates, so with another controller it can show another mode than described here.

The limits and grid powers are percentages of WChaMax, the battery's charge/discharge reference power (model 124), and the number's range follows it. A value is checked against the registers the inverter holds right now, read before the write, and refused with a message instead of a bare Modbus error where the inverter would refuse it:

• 0 W in both directions. Where both limits are on (Charge and Discharge Limit, Block Discharging, Block Charging), 0 W (or a value that rounds to it) with the other side at 0 W is refused: the inverter does not take both directions blocked. In PV Charge Limit and Discharge Limit the other side is off, so 0 W is taken.
• The mode was left. A limit or grid power is refused while the inverter's registers no longer hold the selected mode, for example after a schedule or another controller changed it, also when only a rate went to 0 W and the next poll has not shown it yet. Select the mode again.
• A combined window another controller left. A grid power beyond a combined charge and discharge limit another controller left in place is refused. Select the mode again to set the power freely.

The mode the select shows is checked against the inverter's registers on every poll. Only the rates StorCtl_Mod switches on count: in its charge mode (1) the inverter applies the charge rate alone, in its discharge mode (2) the discharge rate alone, and ignores the other. Another controller such as evcc leaves that other rate as it was, so its hold after discharging shows as Block Discharging, its hold charge after charging as Block Charging, and a limit or grid power that is off shows as no limit. A limit set in Home Assistant in such a mode also switches its rate on, or it would have no effect. See With evcc.

A mode another controller sets replaces the one chosen in Home Assistant; the select's history shows each change, and the log has it at info level. Some register images are two modes at once, because a rate at 0 W reads like a block mode: PV Charge Limit at 0 W and Block Charging, Discharge to Grid at 0 W and Block Charging, Discharge Limit or Charge from Grid at 0 W and Block Discharging. Such an image keeps the chosen mode while it holds what Home Assistant wrote; when another controller sets the rate to 0 W (evcc's hold charge after a PV charge limit), the select follows the registers. After a restart Home Assistant has written nothing yet, so such an image shows as the block mode. A mode written from Home Assistant that the inverter does not take is shown as written for a few polls, then the inverter's mode wins, with a warning in the log.

With evcc

evcc controls a GEN24's battery over Modbus with its fronius-gen24 template. Each of its battery modes writes a fixed sequence of model 124 registers; the integration shows them as these storage modes:

evcc battery mode	What evcc writes	Storage Control Mode shows
normal	StorCtl_Mod 0, OutWRte 100 %, InWRte 100 %	Auto
hold	StorCtl_Mod 2, OutWRte 0 %	Block Discharging
charge	ChaGriSet 1, StorCtl_Mod 2, OutWRte minus evcc's maximum charge rate	Charge from Grid
holdcharge	StorCtl_Mod 1, InWRte 0 %	Block Charging
discharge	StorCtl_Mod 0, InWRte −100 %, OutWRte 100 %, StorCtl_Mod 3	Discharge to Grid

• Each evcc switch is shown within one update, whatever mode came before. The select's history keeps every switch; the log has it at info level ("Storage mode changed outside Home Assistant"), not as a warning, since it is normal operation with evcc. Right after you changed a storage setting in Home Assistant it takes up to three updates, while the integration waits for the inverter to confirm that change. evcc writes only one rate in hold, charge and holdcharge and leaves the other as it was; the inverter ignores that other rate, and so does the integration.
• An update in the middle of evcc's sequence can show the mode between two of its writes for one update; the next one shows evcc's mode.
• The last writer wins. A mode you select in Home Assistant replaces evcc's until evcc writes again, and the other way round.
• Home Assistant's own 0 W stays. PV Charge Limit or Discharge to Grid at 0 W write the same registers as evcc's holdcharge; set from Home Assistant, the mode stays. When evcc sets the rate to 0 after a limit you set, the select follows evcc (Block Charging or Block Discharging).
• A limit while evcc holds the battery. In Block Charging and Block Discharging the other direction stays free to set. Under evcc's hold or holdcharge that direction is switched off; setting a limit in Home Assistant also switches it on (StorCtl_Mod 3), so the limit applies.
• A limit right after evcc switched is refused with "The inverter is no longer in the selected storage mode, for example after a schedule or another controller changed it. Select the mode again." while the next update has not shown evcc's change yet, instead of overwriting evcc's setting.
• Grid charging stays allowed. evcc's charge sets ChaGriSet (Modbus grid charging) to 1 and never back; the Grid charging sensor shows it.
• Curtailment. evcc's curtail writes the inverter's AC limit (WMaxLimPct, WMaxLim_Ena); AC limit rate and AC limit enable show what evcc set, and a value set there replaces evcc's until it writes again.
• After a restart Home Assistant has written nothing yet, so the mode comes from the registers alone: evcc's holdcharge and your own PV Charge Limit at 0 W then both show as Block Charging.
• evcc sets no timeout. The inverter keeps evcc's last mode when evcc stops, until another writer changes it.

Let one controller own the storage mode and use the other to watch; two that both write keep replacing each other's mode.

Modbus controls

Entity	What it sets
Storage Control Mode	The mode, see above.
PV charge limit	The maximum PV charging power in watts.
Discharge limit	The maximum discharging power in watts.
Grid charge power	The charging power in watts while the battery charges from the grid. Grid charging has been reported to reach only about 50 % of the set power.
Grid discharge power	The discharging power in watts while the battery discharges to the grid.
Modbus storage reserve	Model 124 MinRsvPct, the reserve the inverter applies under Modbus storage control. A whole percent from 5 to 100; a fractional value is rounded. See Two minimum SoC values.

The diagnostic sensor Core storage control mode shows StorCtl_Mod as the direction the battery is driven: in Charge from Grid it shows Charge, in Discharge to Grid Discharge. From 1.4.0b3, only the rates StorCtl_Mod switches on count, as for the storage mode. Charging power and Discharging power show the rates InWRte and OutWRte in percent of WChaMax as the registers hold them; a negative rate is a grid mode's power, and a rate StorCtl_Mod keeps off is ignored by the inverter.

Web API controls

The inverter keeps two independent switches, and the entities follow them:

• Self-consumption optimisation is HYB_EM_MODE, the inverter's automatic/manual energy management. Target feed in belongs to it.
• Web API SoC mode is BAT_M0_SOC_MODE, the automatic/manual switch of the SoC window. SoC Minimum (Web API) and SoC Maximum belong to it; switching self-consumption optimisation does not touch the window.
• Backup reserve is independent of both switches.

Entity	What it sets
Self-consumption optimisation	HYB_EM_MODE: Automatic or Manual. Does not change the SoC window.
Target feed in	The manual target feed-in in watts. Positive values target feed-in, negative values target grid consumption, which the inverter then targets even when PV power is available. Reported, not documented by Fronius: the inverter ignores it while battery charging is unavailable. Only available while Self-consumption optimisation is Manual.
Web API SoC mode	BAT_M0_SOC_MODE: Automatic or Manual. The SoC window is only writable while it is Manual.
SoC Maximum	BAT_M0_SOC_MAX. Only available while Web API SoC mode is Manual; not below SoC Minimum (Web API).
SoC Minimum (Web API)	BAT_M0_SOC_MIN, the minimum the inverter's web interface shows. Only available while Web API SoC mode is Manual.
Backup reserve	HYB_BACKUP_RESERVED: the share of the battery kept for backup power, 5 to 100 %.
Charge from grid	HYB_EVU_CHARGEFROMGRID. Turning it on also turns on Charge from AC; turning it off only turns off the grid flag.
Charge from AC	HYB_BM_CHARGEFROMAC. Turning it off turns off both charge-source flags.

Two minimum SoC values

The inverter has two minimum-SoC settings, read by two different regulators, and the integration shows both:

Entity	Register	Who applies it
Modbus storage reserve	model 124 MinRsvPct	The SunSpec storage control, only while a Modbus storage mode other than Auto is active (StorCtl_Mod not 0). In Auto the inverter ignores it.
SoC Minimum (Web API)	BAT_M0_SOC_MIN	The inverter's own battery management, the value its web interface shows, whenever Web API SoC mode is Manual. In Auto this is the only minimum that counts.

Synchronisation goes one way: writing Modbus storage reserve also writes SoC Minimum (Web API) while the SoC mode is Manual, because a web value under an automatic window would be ignored by the inverter. A change of the web minimum, in Home Assistant or in the inverter's web interface, is not written into the Modbus register: that register only means something under an active Modbus mode, and the integration does not write registers whose effect depends on a mode you did not choose.

While the SoC mode is Manual, a new Modbus storage reserve is first checked against the SoC window the inverter holds; it must not exceed SoC Maximum. If that window cannot be read, nothing is written, so the reserve cannot be changed while the Web API does not answer. If the Web API refuses the minimum after Modbus took it, the error says so: the two minimums then differ until one of them is set again.

In practice: if you only use the inverter's own battery management (storage mode Auto), set Web API SoC mode to Manual and use SoC Minimum (Web API) and SoC Maximum; leave the Modbus reserve alone. If you use the Modbus storage modes, set Modbus storage reserve; it is mirrored to the web window while that is Manual.

Charging from the grid

• Turn off scheduled charging and discharging in the inverter's web interface to avoid unexpected behaviour.
• Set Grid charge power to a multiple of 10 W. Other values do not work and lead to odd behaviour such as charging at about 500 W; if you need to press "increment" to get the battery to charge, this is the likely cause. You do not need to touch the Modbus storage reserve.
• Grid charging also stops at around 500 W while the inverter's own battery configuration does not allow charging from the grid, whatever charge power is written over Modbus. PV charging reaches full power in the same state, which makes this look like a Modbus fault.

Selecting Charge from Grid therefore turns on the Charge from grid and Charge from AC toggles over the Web API, so an entry with a login clears this on its own; without one, allow both in the inverter's web interface. If the Web API refuses the toggles, or the entry has lost its web login and waits for a new one, Home Assistant reports an error: the storage mode is then set, but grid charging is not allowed.

Inverter controls

Entity	What it sets
AC limit enable	Switches the AC limit on or off (WMaxLim_Ena). Set AC limit rate first and then enable it, so the limit the inverter still holds does not apply for a moment.
AC limit rate	The AC limit in watts, written as SunSpec WMaxLimPct (percent of WMax) with the inverter's scale factor. It limits everything the inverter puts out, not only the feed-in.
Power factor control	Switches the fixed power factor control on or off (OutPFSet_Ena).
Power factor	The fixed power factor (OutPFSet), -1.0 to 1.0. Negative values are over-excited, positive values are under-excited.
Inverter connection	Connects the inverter to the grid or disconnects it over Modbus (Conn).
Export soft limit	The soft export limit in watts, over the Web API; a number to set it and a sensor that shows it. Needs the technician role. Setting a value also switches the inverter's soft limit on; switch it off in the inverter's web interface. While it is off, both show unknown.
Solar API	Switches the inverter's Solar API v1 on or off over the Web API; diagnostic. Switching it off also clears the inverter's option to switch the Solar API on for devices it discovers, and switching it on leaves that option off.
Reset Modbus Control	Sends the inverter's Modbus reset command over the Web API; diagnostic.

A new value for an active AC limit or power factor is applied by switching the control off and on around the write, as the inverter requires; if the write fails, the control is switched back on. The inverter keeps all of these with no timeout, also after Home Assistant stops (see Installation and Setup).