Skip to content

Matter Dead front behavior #150113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 4 commits into
base: dev
Choose a base branch
from
Draft

Matter Dead front behavior #150113

wants to merge 4 commits into from
+104 −68

Conversation

lboue
Copy link
Contributor

@lboue lboue commented Aug 6, 2025 •
edited
Loading

Proposed change

Add support for Matter Dead front behavior:
On household appliances, there is a button that turns the appliance's control panel on or off.
The Matter specifications allow this to be replicated. They call this “dead front” behavior.
This switch is defined in the specifications and allows this behavior to be enabled or disabled:

  • Off command of the On/Off cluster SHALL move the device into the "dead front" state
  • On command of the On/Off cluster SHALL bring the device out of the "dead front" state

If this behavior is enabled, the device will not respond to start/stop/pause requests.

image

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:

Matter specs

13.1.5.1. On/Off Cluster (Server) Clarifications
 As indicated in the Element Requirements section below, the DF (Dead Front) feature is required for
 the On/Off cluster in this device type. See the "DeadFrontBehavior feature" section in the On/Off
 cluster description for detailed requirements. The "dead front" state is linked to the OnOff attribute
 in the On/Off cluster having the value False. Thus, the Off command of the On/Off cluster SHALL
 move the device into the "dead front" state, the On command of the On/Off cluster SHALL bring the
 device out of the "dead front" state, and the device SHALL adhere with the associated requirements
 on subscription handling and event reporting.

Checklist

  • 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.

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

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:

@home-assistant
Copy link

home-assistant bot commented Aug 6, 2025

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

Code owner commands

Code owners of matter 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 matter 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.

@lboue lboue marked this pull request as ready for review August 6, 2025 13:27
@lboue lboue requested a review from a team as a code owner August 6, 2025 13:27
MartinHjelmare
MartinHjelmare reviewed Aug 6, 2025
View reviewed changes
homeassistant/components/matter/switch.py
entity_description=MatterNumericSwitchEntityDescription(
key="MatterDeadFrontToggle",
device_class=SwitchDeviceClass.SWITCH,
translation_key="dead_front",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "dead front" mean and why should we add a switch entity for it? The PR description doesn't explain this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On household appliances, there is a button that turns the appliance's control panel on or off.
The Matter specifications allow this to be replicated. They call this “dead front” behavior.
This switch is defined in the specifications and allows this behavior to be enabled or disabled:

  • Off command of the On/Off cluster SHALL move the device into the "dead front" state
  • On command of the On/Off cluster SHALL bring the device out of the "dead front" state

If this behavior is enabled, the device will not respond to start/stop/pause requests.

Copy link
Contributor Author

@lboue lboue Aug 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mabe I can rename it to 'Lock control panel'

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's a better name.

It should have entity category CONFIG, I think.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed by last commit

@MartinHjelmare MartinHjelmare marked this pull request as draft August 6, 2025 13:30
@lboue
Copy link
Contributor Author

lboue commented Aug 6, 2025

Here are some additional explanations about this feature:

 1.5.4.2. DeadFrontBehavior Feature
 When this feature is supported, the device exposing this server cluster exhibits "dead front" behav
 ior when the "OnOff" attribute is FALSE (Off). This "dead front" behavior includes:
 • clusters other than this OnOff cluster that are also exposed MAY respond with failures to Invoke and
 Write interactions. Such failure responses when in a "dead front" SHALL be with an
 INVALID_IN_STATE status code.
 • clusters other than this cluster MAY change the values of their attributes to best-effort values,
 due to the actual values not being defined or available in this state. Device type specifications
 that require support for the DF feature SHOULD define what these best-effort values are.
 • Report Transactions SHALL continue to be generated. Such transactions MAY include best-effort
 values as noted above.
 • Event generation logic for clusters other than this cluster is unchanged (noting possible use of
 best-effort attribute values as in the preceding bullets).
 When this feature is supported and the OnOff attribute changes from TRUE to FALSE (e.g. when
 receiving an Off Command, or due to a manual interaction on the device), it SHALL start executing
 this "dead front" behavior.
 When this feature is supported and the OnOff attribute changes from FALSE to TRUE (e.g. when
 receiving an On Command, or due to a manual interaction on the device), it SHALL stop executing
 this "dead front" behavior.
 When this feature is supported, and any change of the "dead front" state leads to changes in attrib
 utes of other clusters due to the "dead front" feature, these attribute changes SHALL NOT be
 skipped or omitted from the usual processing associated with attribute changes. For example, if an
 attribute changes from value 4 to null on "dead front" behavior due to an Off command being
 received, this change SHALL be processed for reporting and subscriptions.

@lboue lboue marked this pull request as ready for review August 6, 2025 13:59
@MartinHjelmare
Copy link
Member

My fear with this entity is that's a bit vague what exactly is locked and what isn't locked on the device, reading the specification. I think it may be hard for users to understand how and when they can use the entity. I'm not completely convinced that we should add it.

@MartinHjelmare MartinHjelmare marked this pull request as draft August 6, 2025 18:46
@MartinHjelmare
Copy link
Member

I suggest we take this topic up for discussion in an appropriate place. We're about to move issue trackers etc for Matter. I'll check with Marcel where he thinks we should hold the discussion.

@lboue
Copy link
Contributor Author

lboue commented Aug 6, 2025 •
edited
Loading

My fear with this entity is that's a bit vague what exactly is locked and what isn't locked on the device, reading the specification. I think it may be hard for users to understand how and when they can use the entity. I'm not completely convinced that we should add it.

The problem is that the switch is already displayed in the interface, but as a PowerSwitch.
The aim is to display the control correctly to the user.

@MartinHjelmare
Copy link
Member

I think we should first decide if we want to expose this at all.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@MartinHjelmare MartinHjelmare MartinHjelmare left review comments

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
cla-signed has-tests integration: matter new-feature Quality Scale: No score
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@lboue @MartinHjelmare