Fix MAC address mix-ups between WLED devices

[mik-laj]

Breaking change

Proposed change

Fix MAC address mix-ups between WLED devices

This PR fixes an issue where Home Assistant could accidentally associate a WLED config entry with the wrong physical device when host/IP information changes (e.g. after DHCP reassignment or moving controllers between locations).
WLED does not guarantee stable hostnames, and the integration previously did not validate the MAC address returned at runtime, so a stale IP or reused hostname could cause HA to load data from an unintended device. This manifested as:

• entities from one controller appearing under another controller’s entry,
• unexpected merging of devices,
• devices “switching places” after network changes,
• setup succeeding even when the device behind the host had changed.

Here is discussion about this problem: https://discord.com/channels/330944238910963714/1431013499466809364/1431013499466809364

Runtime MAC-address validation

The coordinator now validates that the device we connect to at runtime matches the MAC stored in the config entry.
If the MAC does not match:

• config entry setup fails with a clear error,
• existing entities become unavailable instead of showing incorrect data,
• accidental config corruption is prevented.

This ensures that each WLED entry always represents exactly one physical controller.

Reconfigure flow

To give users a way to fix the mismatch error, this PR adds a reconfigure flow for WLED.
This allows the user to:

• update the host/IP of an existing WLED entry,
• retry the connection,
• resolve a mismatch cleanly if the device genuinely changed address.

If the MAC matches, the entry is updated and the flow aborts with reconfigure_successful.
If the MAC does not match, the flow aborts with unique_id_mismatch to prevent linking to the wrong device.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• 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:
• Link to documentation pull request:
• Link to developer documentation pull request:
• Link to frontend pull request:

Checklist

• I understand the code I am submitting and can explain how it works.
• 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
• I have followed the perfect PR recommendations
• The code has been formatted using Ruff (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.
• Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file 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 in this repository.

[home-assistant]

Hey there @frenck, mind taking a look at this pull request as it has been labeled with an integration (wled) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of wled can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign wled Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

[Copilot]

Pull Request Overview

This pull request adds reconfiguration support for the WLED integration, allowing users to change the host address without removing and re-adding the device. Additionally, it implements MAC address verification to ensure devices aren't swapped during reconfiguration or polling.

Key changes:

• Added reconfiguration flow to update host addresses
• Implemented MAC address mismatch detection in the coordinator
• Added test coverage for the new reconfiguration scenarios

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
homeassistant/components/wled/config_flow.py	Added async_step_reconfigure method and unique ID validation during reconfiguration
homeassistant/components/wled/coordinator.py	Introduced WLEDConfigEntry type alias and MAC address mismatch detection in data updates
homeassistant/components/wled/__init__.py	Updated to import and use WLEDConfigEntry from coordinator module
homeassistant/components/wled/strings.json	Added user-facing messages for reconfiguration success and unique ID mismatch
tests/components/wled/test_config_flow.py	Added tests for successful reconfiguration and unique ID mismatch scenarios
tests/components/wled/test_sensor.py	Added test to verify entity unavailability when MAC address mismatches

[erwindouna]

In circumstances it can fail at reconfigure right? Since it uses the user_step, but that has a try-except that can fail. Normally it's good practice to write a test that initially fails and then demonstrates the flow can recover and successfully reconfigure. That would be a good additional test. :)

[mik-laj]

I added a new test case: test_full_reconfigure_flow_connection_error_and_success . I think this is what you need.

[mik-laj]

frenck added this to the 2025.12.0 milestone 18 minutes ago

🎉