Update zum PERGOLUX Matter Controller / RGB-Lichtproblem
Ich bin inzwischen ebenfalls über das hier beschriebene Problem mit dem PERGOLUX Matter Controller gestolpert und habe es etwas genauer untersucht.
Bei mir handelt es sich um eine PERGOLUX Control Box RGB PX293-02 EU , Matter Vendor ID 0x15B8, Product ID 0xFB24, HW V1.0, FW 1.
Die Ursache lässt sich ziemlich eindeutig auf die Matter-Implementierung des Controllers eingrenzen: Der Controller kann einen ColorMode XY melden, obwohl ColorCapabilities XY nicht als unterstützten Farbmodus ausweist . Passende CurrentX-/CurrentY-Attribute sind ebenfalls nicht vorhanden. Home Assistant akzeptiert diesen Zustand folgerichtig nicht und läuft dann in:
set to unsupported color mode xy, expected one of {hs, color_temp}
Das kann dazu führen, dass die komplette Licht-Entität in Home Assistant nicht mehr korrekt funktioniert.
Ich habe dazu inzwischen einen offiziellen Home-Assistant-Core-Issue angelegt:
offen 04:58AM - 20 Sep 26 UTC
integration: matter
### The problem
The problem
A PERGOLUX Matter pergola controller exposes an R… GB light endpoint with inconsistent Matter ColorControl information.
Device information:
* Manufacturer: PERGOLUX
* Product model: PX293-02 EU
* Matter Vendor ID: 5560 (0x15B8)
* Matter Product ID: 64292 (0xFB24)
* Hardware version: V1.0
* Software version: 1
* Matter version: 1.2
The light endpoint exposes Hue/Saturation attributes and its ColorCapabilities indicate Hue/Saturation support. However, the device can report its current ColorMode as XY.
Home Assistant then maps the reported mode to ColorMode.XY, although XY is not included in the supported color modes derived from the device capabilities.
This causes the Matter light entity to become unusable after switching the light on.
The resulting error is:
set to unsupported color mode xy, expected one of {hs, color_temp}
The physical device itself continues to work and can still be controlled using the manufacturer’s remote and Bluetooth application.
Relevant Matter observations
For the light endpoint:
* OnOff cluster is present
* LevelControl cluster is present
* ColorControl cluster is present
* CurrentHue is present
* CurrentSaturation is present
* CurrentX / CurrentY are not present
* ColorCapabilities = 17
* the device can nevertheless report the current ColorMode as XY
Therefore the runtime ColorMode reported by the device is inconsistent with its advertised capabilities and available attributes.
Reproduction
1. Commission the PERGOLUX controller through Matter.
2. The Matter light entity is created successfully.
3. Switch the light on.
4. The device reports XY as its current color mode.
5. Home Assistant rejects this because XY is not part of the entity’s supported color modes.
6. The light entity becomes unavailable/unusable.
Tested workaround
I tested a very small device-specific workaround in:
homeassistant/components/matter/light.py
After:
ha_color_mode = COLOR_MODE_MAP[color_mode]
I normalize the reported color mode for this exact device:
if (
ha_color_mode == ColorMode.XY
and device_info.vendorID == 5560
and device_info.productID == 64292
and device_info.hardwareVersionString == "V1.0"
and device_info.softwareVersionString == "1"
):
ha_color_mode = ColorMode.HS
With this workaround:
* On/off works
* Brightness works
* Color selection works
* The unsupported color mode xy exception disappears
I have also reported the inconsistent Matter implementation to PERGOLUX, since the root cause appears to be device firmware.
Possible Home Assistant improvement
Although the device appears to be non-conformant, it might be useful for the Matter integration to handle this situation gracefully instead of making the complete light entity unusable.
Rather than implementing a generic unconditional XY -> HS conversion, Home Assistant could potentially detect a situation where:
* the reported current ColorMode is not contained in the advertised/supported modes,
* attributes required for that reported mode are unavailable,
* another advertised color mode has the corresponding attributes available.
In this case HA could either:
1. fall back to the supported mode whose attributes are actually available, or
2. retain the last valid color mode and log a warning.
For this particular device, Hue/Saturation is advertised and the Hue/Saturation attributes are available, while XY is not advertised and CurrentX/CurrentY are absent.
Environment
* Home Assistant Core: 2026.9.3
* Home Assistant OS: 18.2
* Matter Server: 1.4.0
* matter.js: 0.17.9
* matter-python-client: 1.4.0
I can provide the complete Matter diagnostics for the device if required.
### What version of Home Assistant Core has the issue?
2026.9.3
### What was the last working version of Home Assistant Core?
_No response_
### What type of installation are you running?
Home Assistant Core
### Integration causing the issue
Matter
### Link to integration documentation on our website
_No response_
### Diagnostics information
[matter-01M14R1HFF2MEARC991GM30ZEW-Pergola Controller-b8b1e85e5f0159402de8e6941a4336e0.json](https://github.com/user-attachments/files/32459282/matter-01M14R1HFF2MEARC991GM30ZEW-Pergola.Controller-b8b1e85e5f0159402de8e6941a4336e0.json)
### Example YAML snippet
```yaml
Suggested Fix:
ha_color_mode = COLOR_MODE_MAP[color_mode]
supported_color_modes = self._attr_supported_color_modes or set()
if ha_color_mode not in supported_color_modes:
LOGGER.warning(
"Matter device %s reported unsupported color mode %s; "
"supported modes are %s",
self.entity_id,
ha_color_mode,
supported_color_modes,
)
# Some non-conformant Matter devices report a ColorMode that does not
# match their advertised ColorCapabilities. Fall back to a supported
# color mode only if the required runtime attributes are available.
if (
ColorMode.HS in supported_color_modes
and self._entity_info.endpoint.has_attribute(
None, clusters.ColorControl.Attributes.CurrentHue
)
and self._entity_info.endpoint.has_attribute(
None, clusters.ColorControl.Attributes.CurrentSaturation
)
and self.get_matter_attribute_value(
clusters.ColorControl.Attributes.CurrentHue
)
is not None
and self.get_matter_attribute_value(
clusters.ColorControl.Attributes.CurrentSaturation
)
is not None
):
ha_color_mode = ColorMode.HS
elif (
ColorMode.XY in supported_color_modes
and self._entity_info.endpoint.has_attribute(
None, clusters.ColorControl.Attributes.CurrentX
)
and self._entity_info.endpoint.has_attribute(
None, clusters.ColorControl.Attributes.CurrentY
)
and self.get_matter_attribute_value(
clusters.ColorControl.Attributes.CurrentX
)
is not None
and self.get_matter_attribute_value(
clusters.ColorControl.Attributes.CurrentY
)
is not None
):
ha_color_mode = ColorMode.XY
elif (
ColorMode.COLOR_TEMP in supported_color_modes
and self._entity_info.endpoint.has_attribute(
None, clusters.ColorControl.Attributes.ColorTemperatureMireds
)
and self.get_matter_attribute_value(
clusters.ColorControl.Attributes.ColorTemperatureMireds
)
is not None
):
ha_color_mode = ColorMode.COLOR_TEMP
LOGGER.debug(
"Got color mode (%s) for %s",
ha_color_mode,
self.entity_id,
)
return ha_color_mode
```
### Anything in the logs that might be useful for us?
```txt
```
### Additional information
_No response_
Außerdem gibt es einen Core-PR mit einem generischen Fallback , der nicht speziell auf PERGOLUX zugeschnitten ist:
dev ← danielwatter:fix-matter-invalid-color-mode
offen 08:09AM - 21 Sep 26 UTC
## Proposed change
Handle Matter lights that report a current color mode wh… ich is not included
in their advertised supported color modes.
Some Matter devices expose inconsistent ColorControl data. For example, a
device may advertise Hue/Saturation and Color Temperature support while
reporting XY as its current ColorMode.
Home Assistant currently maps the reported ColorMode directly. This can
result in an unsupported color mode being assigned to the light entity,
causing state updates to fail.
This change adds a generic fallback:
- If the reported color mode is supported, behavior is unchanged.
- If it is not supported, Home Assistant checks which advertised color modes
have the required current-value attributes available.
- If exactly one usable supported color mode can be determined, that mode is
used as the fallback.
- If the fallback is ambiguous, existing behavior is preserved.
The fallback uses debug logging to avoid repeated warning messages during
normal Matter attribute updates.
The change was also tested with a physical Matter device exhibiting this
inconsistent ColorControl behavior. On/off, brightness and color control work
correctly with the fallback applied.
## Type of change
- [ ] Dependency upgrade
- [x] 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 #182740
- This PR is related to issue:
- Link to documentation pull request:
- Link to developer documentation pull request:
- Link to frontend pull request:
Regression coverage was added for:
- fallback to Hue/Saturation
- fallback to XY
- fallback to Color Temperature
- ambiguous fallback conditions where no unique mode can be selected
The original regression case fails without the fix and passes with the fix.
Local verification:
- 21 Matter light tests passed
- 26 snapshots passed
- Ruff passed
- mypy passed
- pylint passed
- codespell passed
- prettier passed
## Checklist
- [x] I understand the code I am submitting and can explain how it works.
- [x] The code change is tested and works locally.
- [x] Local tests pass. **Your PR cannot be merged unless tests pass**
- [x] There is no commented out code in this PR.
- [x] I have followed the [development checklist][dev-checklist]
- [x] I have followed the [perfect PR recommendations][perfect-pr]
- [x] The code has been formatted using Ruff (`ruff format homeassistant tests`)
- [x] Tests have been added to verify that the new code works.
- [x] 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][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 diff between library versions and ideally a link to the changelog/release notes 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
Der Ansatz prüft bei einem widersprüchlichen gemeldeten ColorMode die tatsächlich vom Gerät angekündigten Farbmodi und deren verfügbaren aktuellen Attribute. Nur wenn sich daraus eindeutig genau ein gültiger Farbmodus bestimmen lässt, wird dieser verwendet. Bei einem mehrdeutigen Zustand bleibt das bisherige Verhalten bestehen.
Die Regressionstests laufen durch und die GitHub-CI des PR ist ebenfalls vollständig grün. Der PR wartet aktuell auf das Review durch einen Home-Assistant-Maintainer.
PERGOLUX habe ich den Fehler ebenfalls direkt gemeldet. Dort wurde die technische Fehlerbeschreibung inzwischen an die Produkt- und Entwicklungsabteilung weitergeleitet. PERGOLUX prüft jetzt die Matter-/Firmware-Seite und will sich melden, sobald eine Rückmeldung der Entwicklung vorliegt.
Das ist wichtig, weil der eigentliche Widerspruch natürlich idealerweise in der Firmware des Controllers behoben werden sollte. Der HA-PR soll zusätzlich verhindern, dass ein einzelner inkonsistenter Matter-ColorMode gleich die komplette Licht-Entität unbrauchbar macht.
Sobald es eine Rückmeldung von PERGOLUX oder zum Home-Assistant-PR gibt, kann ich hier ein Update posten.
Und danke an tchristian1103 für die vorherige Analyse und den Patch – das war ein ziemlich guter Hinweis darauf, dass das Problem nicht nur bei meinem Controller auftritt.
