Add cluster_revision filtering to Matter discovery schema - #175693
Open
lboue wants to merge 1 commit into
Open
Conversation
Allows discovery schemas to filter by the Matter ClusterRevision attribute, so entity behavior can differ across cluster spec revisions. Applied to the Thermostat TemperatureOffset number entity, whose LocalTemperatureCalibration constraint changed between Matter 1.3 (±2.5°C) and 1.4 (no explicit spec constraint).
home-assistant
Bot
added
cla-signed
has-tests
integration: matter
new-feature
Top 100
Contributor
|
Hey there @home-assistant/matter, mind taking a look at this pull request as it has been labeled with an integration ( Code owner commandsCode owners of
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds optional cluster_revision_min/cluster_revision_max filtering to MatterDiscoverySchema, letting Matter discovery pick a different entity schema based on a cluster's ClusterRevision attribute (0xFFFD). It applies this to fix the Thermostat TemperatureOffset number entity, whose LocalTemperatureCalibration constraint changed between Matter 1.3 (rev ≤6, ±2.5 °C) and Matter 1.4 (rev ≥7, no spec constraint → int8 range). It also corrects a pre-existing bug where the entity's native_min/max_value were expressed in raw Matter units (±25) instead of the entity's native °C unit after the /10 conversion.
Changes:
- Add
CLUSTER_REVISION_ATTRIBUTE_IDconstant andcluster_revision_min/maxschema fields plus acluster_revisionfield onMatterEntityInfo. - Add
_resolve_cluster_revisionin discovery and split theTemperatureOffsetschema into rev ≤6 (±2.5 °C) and rev ≥7 (±12.7 °C) variants with corrected units. - Add a parametrized discovery test overriding
ClusterRevision, and update snapshots.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| homeassistant/components/matter/const.py | Adds CLUSTER_REVISION_ATTRIBUTE_ID = 65533. |
| homeassistant/components/matter/models.py | Adds cluster_revision to MatterEntityInfo and cluster_revision_min/max to MatterDiscoverySchema. |
| homeassistant/components/matter/discovery.py | Adds _resolve_cluster_revision helper and wires revision filtering into discovery. |
| homeassistant/components/matter/number.py | Splits TemperatureOffset into rev ≤6/≥7 schemas and fixes native min/max units. |
| tests/components/matter/test_number.py | Adds parametrized test asserting bounds per ClusterRevision. |
| tests/components/matter/snapshots/test_number.ambr | Updates snapshots to °C bounds (±2.5 / ±12.7). |
Comment on lines
+64
to
+65
| # [optional] cluster revision value if required by discovery schema | ||
| cluster_revision: int | None = None |
Comment on lines
+361
to
+362
| # Matter 1.4 dropped the ±2.5°C constraint; fall back to the | ||
| # int8 storage range of the raw attribute (-128..127 in 0.1°C units) |
Comment on lines
+518
to
+525
| @pytest.mark.parametrize("node_fixture", ["mock_thermostat"]) | ||
| async def test_temperature_offset_cluster_revision( | ||
| hass: HomeAssistant, | ||
| matter_client: MagicMock, | ||
| matter_node: MatterNode, | ||
| expected_min: float, | ||
| expected_max: float, | ||
| ) -> None: |
Contributor
Author
|
Is it OK? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed change
Adds optional
cluster_revision_min/cluster_revision_maxattributes toMatterDiscoverySchema, so discovery can select a different entity schema based on the Matter cluster'sClusterRevisionattribute (0xFFFD).This is used to fix the Thermostat
TemperatureOffsetnumber entity: theLocalTemperatureCalibrationattribute's constraint changed between Matter cluster revisions:int8storage range (±12.7°C).This also fixes a pre-existing bug in the
TemperatureOffsetschema wherenative_max_value/native_min_valuewere set in raw Matter units (±25) instead of the entity's native unit (°C, after the/10conversion), letting the UI/service calls send values 10x larger than the device actually accepts.This is a redo of #161793 (closed due to inactivity), addressing the review from @TheJulianJES and Copilot on that PR:
ClusterRevisionattribute ID magic number intoconst.py(next toFEATUREMAP_ATTRIBUTE_ID), instead of hardcoding it in the discovery loop.NullValue/unreadableClusterRevisionbefore comparing, to avoid a runtime crash.native_max_value/native_min_valueunits for both the revision ≤6 and revision ≥7 schemas.ClusterRevisionattribute value, as suggested in review.Type of change
Additional information
cluster_revisionattribute to MatterDiscoverySchema #161793Checklist
ruff format homeassistant tests)If user exposed functionality or configuration variables are added/changed:
If the code communicates with devices, web services, or third-party tools:
Updated and included derived files by running:
python3 -m script.hassfest.requirements_all.txt.Updated by running
python3 -m script.gen_requirements_all.To help with the load of incoming pull requests: