Migration

Migration

Coming from 0.3.x

The integration uses the same fronius_modbus domain. Install it over the earlier integration (see Installation and Setup) and restart; existing entries are migrated on the first start. What changes is checked against 0.3.3 and 0.3.4. Breaking changes are listed in the CHANGELOG.

What stays

• Entity IDs, unique IDs, history and statistics, and existing options.
• A title you gave the entry.
• Port and inverter address of an entry set up with 0.2.x.
• The role you chose, for an entry from 0.3.2 or later. An older entry, or one without a stored role, takes the technician role when a technician token is stored, otherwise the customer role.
• Both entities where two of them shared a unique id, and the sensors of MPPT strings that are dark at the update.
• The module temperatures of 0.3.3 and later (AC Module Temperature, DC Module Temperature, Battery Module Temperature); they continue as AC module 1 temperature, DC module temperature (3) and DC or battery module temperature.
• The entities whose unique ids the 0.3.4-rc2 pre-release wrote in lowercase. Where that version left the earlier entity beside its own, the earlier one is kept with its history; the other goes.

Coming straight from 0.2.7 or older, the MPPT and storage module sensors (mppt1_power, mppt1_lfte and the like) come back under new entity IDs, as they did with 0.2.8.

Enum states are keys now

Select options and sensor states are lowercase keys, shown translated in the interface: Auto became auto, Charge from Grid became charge_from_grid, On grid operating became on_grid_operating, Enabled/Disabled became enabled/disabled. The rule is lowercase with every run of other characters replaced by _. Update automations and templates that compare against the old texts (is_state(..., "Auto"), option: "Charge from Grid").

Connection and data

• Minimum Home Assistant version 2026.9.0.
• No Modbus connection of its own: the integration asks Home Assistant's built-in modbus integration for a unit on a shared connection, so it can run beside other integrations that talk to the same inverter.
• Registers are decoded from the SunSpec model definitions, including sentinel values and scale factors.
• The Web API is polled on its own interval (default 60 s) instead of once per Modbus poll.
• An energy total still ignores a drop and an implausible jump, but accepts a genuine counter reset after three readings that agree; the earlier integration refuses every lower value for good.
• A control set to the value the inverter already holds writes nothing.
• Load can be negative: with other generation behind the grid meter that the inverter does not see, it is the household's consumption minus that generation. Up to 0.3.3 it stopped at 0 W.

Setup and security

• The checkbox "Restrict Modbus to this IP" became the option Modbus IP restriction with three choices (see Installation and Setup); the default keeps the inverter's setting. The earlier integration lifted the restriction whenever the box was unchecked, and a checked box replaced the allowed hosts with Home Assistant's address; allowing Home Assistant now adds its address to the hosts already allowed while the restriction is on. While it is off, Home Assistant's address becomes the only allowed host. Migrated entries keep their choice: checked becomes "restrict and allow this Home Assistant", unchecked becomes "keep".
• Enabling Modbus TCP keeps the RS485 ports' roles and Modbus RTU served alongside TCP. The earlier integration wrote a fixed block that moved both RS485 ports to master and turned RTU served alongside TCP into TCP alone.
• The stored Web API token is readable by Home Assistant only, and deleted once no entry uses its host and role.
• The Web API login is optional (see Web API).
• The inverter is discovered over mDNS, and an entry set up by IPv4 address follows it to a new address.

Battery

• The SoC window follows the inverter's own switch: SoC Maximum and the new SoC Minimum (Web API) are writable while the new Web API SoC mode is Manual. The earlier integration tied them to Self-consumption optimisation.
• Grid charge power and Grid discharge power scale by their own rate maximum; the earlier integration wrote each against the opposite one. If the two maximums differ, check the values your automations set.
• PV charge limit and Discharge limit convert watts with WChaMax, the reference Fronius documents, instead of the battery's nameplate rating. If the two differ, check the values your automations set.

New names

These entities show a new name; their entity IDs stay, so automations keep working:

0.3.3	Now
Battery API mode	Self-consumption optimisation
Core storage control mode (inverter)	Control mode
Events	Event severity
Max charging power	Charge/discharge reference power
SoC Minimum	Modbus storage reserve
Temperature	Internal temperature
AC Module Temperature	AC module 1 temperature
DC Module Temperature	DC module temperature (3)
Battery Module Temperature	DC or battery module temperature

New entities

• Component sensors from the inverter's web interface: module temperatures, fans, per-phase AC power, output power limit, grid validity, battery state of health and more.
• Throttle reason, Web API SoC mode, SoC Minimum (Web API), and the inverter's events (see Events and Throttling).
• A diagnostics download with the raw SunSpec register map.

Coming from redpomodoro/fronius_modbus

The last release of redpomodoro/fronius_modbus is 0.1.9. The domain is the same, so the entry is taken over and its entities move along: they keep their entity ids and history, and the devices keep their area, name and automations.

• The four MPPT sensors get new entity ids (mppt_module_0_dc_power, mppt_module_0_lifetime_energy and the same for module 1). Their statistics move with them, but automations and dashboards that use the old ids need updating.
• storage_power has no successor and is removed. Use the separate charging and discharging power sensors instead.
• An entry from 0.1.9 has no web login. Home Assistant asks for one after the update; the entities that need it appear once you have logged in.
• Update straight to this version. Going through 0.3.x removes most of the old entities, and that cannot be repaired afterwards.

Do not uninstall the old repository. The Marketplace removes the integration's configuration with it, and the update then has nothing to carry over. Instead, take a backup, replace the folder config/custom_components/fronius_modbus with the one from this release by hand, and restart. The Marketplace has no way yet to switch repositories, so it will not offer updates for this one (discussion). If you still run HACS, removing the repository there keeps the entry.

Entries without a valid login

Entries created with older Modbus-only versions are migrated with safe defaults and keep working. If an entry has no valid stored Web API token for its host and role, Home Assistant asks for a new login on the integration (Reauthentication required): choose the role and enter its password, or choose Without the web API. Host, intervals and the Modbus IP restriction stay as they are; change them with Reconfigure. Logging in again with a role also writes the inverter's Modbus settings, as the setup does (see Web API), including the Modbus IP restriction the entry has.

Until then such an entry does not poll the inverter's web interface at all: the component sensors and events are missing too, and only the first smart meter is read.