jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-24 09:46:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document ESPHome reconfig and name conflict resolution (#38680)

Browse Source
This commit is contained in:
J. Nick Koston 2025-04-22 10:03:16 -10:00 committed by GitHub
parent 0e49dcf63b
commit 21861d7af8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 39 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
source/_integrations/esphome.markdown
View File

@ -100,3 +100,42 @@ The entity will be named `livingroomdesk Temperature` and will default to having
data:
homeassistant.components.esphome: debug
```
## Reconfiguration and Device Replacement
This integration supports reconfiguration, allowing you to make changes—such as updating the IP address—even after a device has already been set up.
### Name Conflict Resolution
If Home Assistant detects multiple devices with the same [**name**](https://esphome.io/components/esphome.html#configuration-variables), it will automatically initiate **Name Conflict Resolution**. This process is designed to help you seamlessly replace a failed or retired device with new hardware, while preserving your existing configuration if desired.
This process gives you two options:
- **Migrate**: Transfers the existing entity configuration to the new device. This preserves all your settings, entity names, and history. Use this when you're replacing the hardware but keeping the same YAML configuration.
- **Overwrite**: Replaces the existing configuration with the new device.
**Caution:** This will **erase all existing settings** for the old device including entity names, customizations, and history will be lost. Use this only if the new device is completely different and you don’t need anything from the previous setup.
{% tip %}
If you’re using the same YAML file on the new device, choose **Migrate**. If it’s a totally different device (even if it shares the same name), **Overwrite** is the safer option.
{% endtip %}
---
### Requirements for Name Conflict Resolution
To trigger Name Conflict Resolution, all of the following must be true:
- The new device must be running **ESPHome 2025.4.0 or later**.
- The new device must use the same [**name**](https://esphome.io/components/esphome.html#configuration-variables) (not just the friendly name).
- The original (old) device must be **offline**.
---
### How to Trigger Name Conflict Resolution
You can trigger Name Conflict Resolution in several ways:
- Connecting a new device with the same name and a **static IP address** will automatically launch a repair flow.
- Using the **Reconfigure** option in the UI to point to a different IP that hosts a device with the same name.
- Configuring a **newly discovered device** that uses the same name.
- **Manually adding** a device with the same name via the integration setup.