# Migration Guide (v4.0+)

Version 4.0 introduces a significant change to how Entity Unique IDs are generated, transitioning from a **Host/Port** based system to a **Serial Number** based system. This ensures that your entities (sensors) remain consistent even if your inverter's IP address changes or if you move your database to a new Home Assistant instance.

## Why the change?
Previously, unique IDs were generated using the Inverter's IP address (e.g., `solis_modbus_192.168.1.10_active_power`). If you changed your router or used DHCP, a new IP would cause Home Assistant to see all your sensors as "New" devices, breaking your history and dashboards.

By using the **Serial Number** (e.g., `solis_modbus_SN123ABC_active_power`), the ID remains tied to the physical device.

## The Migration Process
When you upgrade to v4.0+, the integration performs the following checks on startup:

1.  **Serial Number Check**: It checks if your configuration entry has a valid "Inverter Serial".
2.  **Auto-Migration**:
    *   If a Serial is present, it calculates what your *Old* Entity IDs were (based on your Host or the old "Identification" setting).
    *   It safely renames the *Old* Entity ID to the *New* Serial-based ID in the Home Assistant Entity Registry.
    *   **Result**: Your entity names (e.g., `sensor.solis_active_power`) stay the same, and your history is preserved.
3.  **Deferred Migration**:
    *   If your configuration is *missing* the Serial Number, the migration cannot happen.
    *   The integration will continue to work, but will generate a **Persistent Notification** asking you to "Reconfigure".
    *   Once you add the Serial Number, the migration will trigger automatically.

## Troubleshooting
If you see duplicate entities (e.g., `sensor.solis_active_power` and `sensor.solis_active_power_2`), it means the migration might have been interrupted or a conflict occurred.

*   **Solution**: Delete the "New" (duplicate) entities and restart Home Assistant. The migration logic will try to rename the "Old" (original) entities again.
*   **Logs**: Check your Home Assistant logs for messages starting with `Migration collision` or `Migrating sensor ...`.

### Restoring Sensor History
If a sensor's entity ID changes and you want to keep the old history:

1. Navigate to **Developer Tools** -> **Statistics**.
2. Search for the sensor name (e.g., "Today Battery Charge Energy").
3. You will likely see multiple entries with similar names. Identify which is the **current** sensor and which is the **historic** one.
4. Click on the **current** sensor, click the gear icon, and now rename the "Entity ID" to the old one

## "Identification" Field
The old "Identification" field (used to manually override the unique ID base) is now **deprecated**.
*   It is no longer available in the Setup/Config flow.
*   If you had it set previously, the migration logic *will* honor it to find your old entities and migrate them to the Serial Number format.
*   After migration, this field is effectively unused.