Matter Pir unoccupied to occupied delay

[lboue]

Proposed change

Adds support in the Matter integration for configuring PIR occupancy “unoccupied → occupied” timing/threshold attributes via number entities, with accompanying fixtures and test coverage.

Matter Specs

• PIRUnoccupiedToOccupiedDelay attribute
  • This attribute SHALL specify the time delay, in seconds, before the PIR sensor changes to its occupied state after the first detection of occupancy in the sensed area.
• PIRUnoccupiedToOccupiedThreshold attribute
  • This attribute SHALL specify the number of occupancy detection events that must occur in the period PIRUnoccupiedToOccupiedDelay, before the PIR sensor changes to its occupied state.

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:
• This PR fixes or closes discussion: fixes Add PIRUnoccupiedToOccupiedThreshold and PIRUnoccupiedToOccupiedDelay to matter integration
• 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 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 in this repository.

[home-assistant]

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, problem in config, problem in device, feature-request) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) on the pull request.

[Copilot]

Pull request overview

Adds support in the Matter integration for configuring PIR occupancy “unoccupied → occupied” timing/threshold attributes via number entities, with accompanying fixtures and test coverage.

Changes:

• Add Matter number entities for PIRUnoccupiedToOccupiedDelay and PIRUnoccupiedToOccupiedThreshold (gated by the PIR feature bit).
• Add a new PIR occupancy sensor node fixture and extend snapshot coverage for the new fixture’s entities.
• Add explicit tests validating state updates and write_attribute calls for the new numbers.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
homeassistant/components/matter/number.py	Adds discovery schemas mapping the PIR delay/threshold attributes to number entities.
homeassistant/components/matter/strings.json	Adds translation keys for the two new number entity names.
tests/components/matter/test_number.py	Adds tests for the two new PIR occupancy sensing number entities (read/update/write).
tests/components/matter/conftest.py	Registers the new node fixture so it participates in parameterized Matter snapshot tests.
tests/components/matter/fixtures/nodes/mock_occupancy_sensor_pir.json	Adds a PIR occupancy sensing fixture exposing the new attributes for testing.
tests/components/matter/snapshots/test_number.ambr	Updates snapshots to include the two new number entities for the new fixture.
tests/components/matter/snapshots/test_button.ambr	Updates snapshots for entities produced by the new fixture (identify button).
tests/components/matter/snapshots/test_binary_sensor.ambr	Updates snapshots for entities produced by the new fixture (occupancy binary sensor).

[NoRi2909]

Do we have to stick to the convoluted naming from the Matter specs?

Or could we use terms like

• Detection delay
• Detection threshold

instead that are more in line with what Home Assistant uses otherwise?

For the opposite direction the PIROccupiedToUnoccupiedDelay has the translation key "Hold time" so that's nice and short, too.

[lboue]

Do we have to stick to the convoluted naming from the Matter specs?

We can simplify if we find a simpler term for the user.

Or could we use a term like "(Occupancy) detection delay / threshold" instead that is more in line with what Home Assistant uses otherwise?

Good idea

For the opposite direction the PIROccupiedToUnoccupiedDelay has the translation key "hold_time".

Yes, in latest cluster revision, a new attribute has been introduced.

[NoRi2909]

You already answered while I further edited my above comment. 😃

As these will only show up in the Configuration section of occupancy sensors we could leave that word out and just go with

• Detection delay
• Detection threshold
• Hold time

for those three related settings. As all three will have an entry field next to them, the shorter the label the better.

[lboue]

As these will only show up in the Configuration section of occupancy sensors we could leave that word out and just go with

* Detection delay

* Detection threshold

* Hold time

for those three related settings. As all three will have an entry field next to them, the shorter the label the better.

I corrected the naming.

[NoRi2909]

Strings are much better! - Thanks for addressing.
Regarding the code I'm not qualified for a full review.