Document ESPHome reconfig and name conflict resolution #38680
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe documentation for the ESPHome integration in Home Assistant has been expanded with a new section detailing the "Reconfiguration and Device Replacement" process. This addition explains support for reconfiguring devices after initial setup, introduces a "Name Conflict Resolution" feature for handling devices with duplicate configuration names, and describes two resolution options: "Migrate" and "Overwrite." The requirements for triggering this feature and various methods to initiate the process are also outlined. No changes were made to code or public APIs. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant HomeAssistant
participant ESPHomeDevice (Old)
participant ESPHomeDevice (New)
User->>HomeAssistant: Initiate device replacement (e.g., via UI or discovery)
HomeAssistant->>ESPHomeDevice (New): Detect device with same config name as old device
HomeAssistant->>ESPHomeDevice (Old): Check if old device is offline
alt Name Conflict Detected
HomeAssistant->>User: Prompt for resolution (Migrate or Overwrite)
User->>HomeAssistant: Select resolution option
alt Migrate
HomeAssistant->>ESPHomeDevice (New): Transfer configuration, preserve settings/history
else Overwrite
HomeAssistant->>ESPHomeDevice (New): Replace old configuration, erase previous settings/history
end
end
HomeAssistant->>User: Complete replacement process
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
source/_integrations/esphome.markdown (2)
112-117: Enhance clarity and grammar in the “Overwrite” descriptionThe current caution sentence is lengthy and missing a comma before “including.” Consider rephrasing for readability and consistency:
-**Caution:** This will **erase all existing settings** for the old device including entity names, customizations, and history will be lost. +**Caution:** This will **erase all existing settings** for the old device, including entity names, customizations, and history. Use this only if the new device is entirely different and you don’t need any previous data.
- Added a comma before “including.”
- Split into two sentences to avoid a run‑on.
- Swapped “completely” for “entirely” to vary word choice.
🧰 Tools
🪛 LanguageTool
[style] ~116-~116: Consider using a different adverb to strengthen your wording.
Context: ...ost. Use this only if the new device is completely different and you don’t need anything f...(COMPLETELY_ENTIRELY)
[uncategorized] ~116-~116: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...f the new device is completely different and you don’t need anything from the previo...(COMMA_COMPOUND_SENTENCE)
124-132: Refine bullet introduction for concisenessTo tighten phrasing, remove “of” from the heading’s lead‑in:
-To trigger Name Conflict Resolution, all of the following must be true: +To trigger Name Conflict Resolution, the following must all be true:🧰 Tools
🪛 LanguageTool
[style] ~126-~126: Consider removing “of” to be more concise
Context: ...n To trigger Name Conflict Resolution, all of the following must be true: - The new devi...(ALL_OF_THE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/esphome.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/esphome.markdown
[style] ~116-~116: Consider using a different adverb to strengthen your wording.
Context: ...ost. Use this only if the new device is completely different and you don’t need anything f...
(COMPLETELY_ENTIRELY)
[uncategorized] ~116-~116: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...f the new device is completely different and you don’t need anything from the previo...
(COMMA_COMPOUND_SENTENCE)
[style] ~126-~126: Consider removing “of” to be more concise
Context: ...n To trigger Name Conflict Resolution, all of the following must be true: - The new devi...
(ALL_OF_THE)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (3)
source/_integrations/esphome.markdown (3)
104-111: Well-structured introduction to reconfiguration processThe new Reconfiguration and Device Replacement section clearly explains how ESPHome devices can be updated post‑setup and succinctly introduces Name Conflict Resolution. This provides valuable guidance for users replacing or reconfiguring devices.
118-120: Approve tip block phrasingThe tip succinctly advises when to choose Migrate vs. Overwrite, matching Home Assistant’s style for actionable guidance.
134-142: Comprehensive trigger methods listThe enumeration of how to initiate Name Conflict Resolution is thorough and clearly formatted, covering UI, discovery, and manual flows. Nice work!
|
thanks |
Proposed change
After thinking about this a bit, reconfiguration deserves some docs that explain the name conflict resolution process.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit