bdraco
April 14, 2025, 6:09am
22
If you delete a config entry that was created before the current friendly naming system was introduced (or before you set a friendly name in the ESPHome config)—and it used the legacy naming scheme—those names won’t be preserved when you re-add the device. The new config entry will follow the updated naming rules.
Backwards compatibility for entity names and IDs only applies for the lifetime of the existing config entry. Once a new entry is created, the updated rules take effect.
The naming behavior is documented here:Entity Naming and IDs Documentation
And the relevant code can be found here:
assert entry_data.device_info is not None
device_info = entry_data.device_info
self._device_info = device_info
self._on_entry_data_changed()
self._key = entity_info.key
self._state_type = state_type
self._on_static_info_update(entity_info)
self._attr_device_info = DeviceInfo(
connections={(dr.CONNECTION_NETWORK_MAC, device_info.mac_address)}
)
#
# If `friendly_name` is set, we use the Friendly naming rules, if
# `friendly_name` is not set we make an exception to the naming rules for
# backwards compatibility and use the Legacy naming rules.
#
# Friendly naming
# - Friendly name is prepended to entity names
# - Device Name is prepended to entity ids
# - Entity id is constructed from device name and object id
#
# Legacy naming
Also, device name conflicts aren’t currently handled automatically. When a conflict occurs, an error is logged, and manual resolution is required.
This pull request aims to improve that behavior:
dev ← esphome_conflict_repair
opened 11:26PM - 07 Apr 25 UTC
## Proposed change
Add a repair for ESPHome device conflicts
Sometimes, tw… o ESPHome devices might end up with the same name but different hardware (MAC address). Previously, this would show an error in the logs, and you had to figure out why your device stopped working.
This process is now more user-friendly.
If this situation comes up, you’ll see a **guided repair option**. It will ask whether:
- You meant to **replace** the old device with new hardware, or
- You **accidentally flashed** the same firmware to multiple devices.
### If you choose to replace the device:
- The system will update the configuration automatically.
- The new device will take over with your existing settings.
- No configuration will be lost.
### If you accidentally flashed the firmware to multiple devices:
- The system will tell you how to resolve the conflict
- When the flow completes, the system will try again to set up the entry.
This makes it easier to swap out devices when needed.
additional discussion https://community.home-assistant.io/t/better-handling-of-mac-address-mismatch-with-esphome-devices/876873/22?u=bdraco
<img width="610" alt="Screenshot 2025-04-07 at 12 51 08 PM" src="https://github.com/user-attachments/assets/d38a42f8-3071-4103-9161-bca30f47b246" />
Migration Path
<img width="565" alt="Screenshot 2025-04-07 at 5 38 12 PM" src="https://github.com/user-attachments/assets/a67c7e99-a527-466d-bc15-10e14e731d34" />
<img width="580" alt="Screenshot 2025-04-07 at 5 33 57 PM" src="https://github.com/user-attachments/assets/168b6acb-1c74-403e-976b-a784f7e11b54" />
<img width="394" alt="Screenshot 2025-04-07 at 5 34 00 PM" src="https://github.com/user-attachments/assets/1d7c6ec8-8ac4-4408-ba85-472965d856c3" />
At this point the migration happens, the config entry reloads, and the new device is ready to use.
Rename / Remove Path
<img width="587" alt="Screenshot 2025-04-07 at 5 38 16 PM" src="https://github.com/user-attachments/assets/d4ed536f-0f1f-4f01-ae29-eb283ae96142" />
<img width="588" alt="Screenshot 2025-04-07 at 5 33 42 PM" src="https://github.com/user-attachments/assets/40f99c96-28d0-49c7-80a1-4b5a6f7122ca" />
<img width="378" alt="Screenshot 2025-04-07 at 5 33 46 PM" src="https://github.com/user-attachments/assets/15ceac18-5c4d-46e4-85d6-cee16cf45928" />
At this point, the config entry reloads, and the conflict is resolved. If they didn't actually remove the device from the network or change the name, the repair will get triggered again.
## Type of change
- [ ] Dependency upgrade
- [ ] Bugfix (non-breaking change which fixes an issue)
- [ ] New integration (thank you!)
- [x] New feature (which adds functionality to an existing integration)
- [ ] Deprecation (breaking change to happen in the future)
- [ ] Breaking change (fix/feature causing existing functionality to break)
- [ ] Code quality improvements to existing code or addition of tests
## Additional information
- This PR fixes or closes issue: fixes #
- This PR is related to issue: https://github.com/home-assistant/core/issues/100369
- Link to documentation pull request:
- Link to developer documentation pull request:
- Link to frontend pull request:
## Checklist
- [x] The code change is tested and works locally.
- [ ] Local tests pass. **Your PR cannot be merged unless tests pass**
- [ ] There is no commented out code in this PR.
- [ ] I have followed the [development checklist][dev-checklist]
- [ ] I have followed the [perfect PR recommendations][perfect-pr]
- [ ] The code has been formatted using Ruff (`ruff format homeassistant tests`)
- [x] Tests have been added to verify that the new code works.
If user exposed functionality or configuration variables are added/changed:
- [ ] Documentation added/updated for [www.home-assistant.io][docs-repository]
If the code communicates with devices, web services, or third-party tools:
- [ ] The [manifest file][manifest-docs] has all fields filled out correctly.
Updated and included derived files by running: `python3 -m script.hassfest`.
- [ ] New or updated dependencies have been added to `requirements_all.txt`.
Updated by running `python3 -m script.gen_requirements_all`.
- [ ] For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.
To help with the load of incoming pull requests:
- [ ] I have reviewed two other [open pull requests][prs] in this repository.
[prs]: https://github.com/home-assistant/core/pulls?q=is%3Aopen+is%3Apr+-author%3A%40me+-draft%3Atrue+-label%3Awaiting-for-upstream+sort%3Acreated-desc+review%3Anone+-status%3Afailure
[dev-checklist]: https://developers.home-assistant.io/docs/development_checklist/
[manifest-docs]: https://developers.home-assistant.io/docs/creating_integration_manifest/
[quality-scale]: https://developers.home-assistant.io/docs/integration_quality_scale_index/
[docs-repository]: https://github.com/home-assistant/home-assistant.io
[perfect-pr]: https://developers.home-assistant.io/docs/review-process/#creating-the-perfect-pr
1 Like
tom_l
April 14, 2025, 6:26am
23
The PR was introduced more than 26 months ago. They first installed their device 8 months ago.
But then added the friendly name 6 months ago (without deleting the device) and it did not change the entity ids.
Only when deleting and re-adding the device were the entity ids changed.
bdraco
April 14, 2025, 6:29am
24
I adjusted the post to clarify:
If you delete a config entry that was created before the current friendly naming system was introduced (or before you set a friendly name in the ESPHome config)
1 Like
Well, the plot thickens a little. It turns out that the presence or not of a friendly name does affect the constructed entity names for a device - but it’s not the friendly name that gets used!
So if I add a device with this config:
esphome:
name: esp-testing
Then for the “Uptime” sensor I get an entity named sensor.uptime. So the device name has been ignored.
But if I change the config to:
esphome:
name: esp-testing
friendly_name: ESP Test
Then delete and re-add the device, now the same sensor is called sensor.esp_testing_uptime.
So while the presence of the friendly name has an effect, its value is not used for this purpose, the name is. Now it makes sense to me that the name should be used, but it makes no sense that it is only used if the friendly name is set.