Add a dynamic sensitivity slider for Matter sensors by wardmatter · Pull Request #167710 · home-assistant/core

wardmatter · 2026-04-08T17:51:17Z

Breaking change

Manufacturer-specific sensitivity select entities have been deprecated and will be removed in the future. A new number entity is added to all supporting Matter devices. This affects the following devices:

Aqara P2 contact sensor
Aqara P2 motion sensor
Aqara FP300 presence sensor
Heiman motion sensor

Proposed change

The PR deprecates previous PID/VID filtered select config entities for sensitivity levels to better support more sensors with more than 3 sensitivity levels, like the newly released Aqara P100 multi-propose sensor that has 10 sensitivity levels. Old select entities are disabled by default.

Screenshot showing the newly added entity (do note that the old select entity is now available again as well, though disabled by default):

Screenshot showing the new number config entity

Changes

Add new discovery entry in number.py and remove filters for the Matter sensors mentioned above. To align with Aqara app and other real life using experience. The added slider would start from 1 instead of 0 defined in Matter spec.

Here's a comparison between HA and the Aqara app:

Home Assistant	Aqara app

Manufacturer-specific sensitivity select entities have been deprecated and will be removed in six months.

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 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 · 2026-04-08T17:51:26Z

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

This PR replaces the previous vendor-specific sensitivity level select entities with a dynamic, generic number entity (slider) that works with any device having the BooleanStateConfiguration cluster with the SensitivityLevel feature. The new implementation converts device sensitivity levels (0-indexed) to user-friendly values (1-indexed) and supports an arbitrary number of sensitivity levels rather than being limited to 3.

Changes:

Removed vendor-specific (Aqara and Heiman) select entity discovery schemas for sensitivity levels from select.py
Added a generic number entity discovery schema in number.py that works with any device having BooleanStateConfiguration cluster with SensitivityLevel feature
Updated tests to validate the new number entity behavior and removed obsolete select entity tests
User experience shifts from dropdown select ("10 mm", "20 mm", "30 mm") to a slider with numeric values (1, 2, 3)

Reviewed changes

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

Show a summary per file

File	Description
homeassistant/components/matter/select.py	Removed 3 vendor-specific select discovery schemas for Aqara contact sensor (P2), Aqara motion sensor (P2), and Heiman motion sensor
homeassistant/components/matter/number.py	Added 1 generic number discovery schema supporting any device with BooleanStateConfiguration cluster and SensitivityLevel feature
tests/components/matter/test_select.py	Removed test for Aqara door/window P2 select entity
tests/components/matter/test_number.py	Added test for the new generic sensitivity level number entity
tests/components/matter/snapshots/test_select.ambr	Removed snapshots for old select entities
tests/components/matter/snapshots/test_number.ambr	Added snapshots for new number entities on affected devices

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

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

lboue · 2026-04-08T18:58:32Z

Shouldn't we first announce the withdrawal and then, in a second step, eliminate the old entities?

wardmatter · 2026-04-08T19:08:10Z

Shouldn't we first announce the withdrawal and then, in a second step, eliminate the old entities?

Thanks for the comments. If we use both filters and the new generic slider, will there be unexpected behavior?

TheJulianJES · 2026-04-10T11:04:56Z

    ),
-    MatterDiscoverySchema(
-        platform=Platform.SELECT,
-        entity_description=MatterSelectEntityDescription(


Yeah, let's deprecate the old select entities first by making them disabled by default.
If you add entity_registry_enabled_default=False to the MatterSelectEntityDescription, the old entities are disabled for newly paired devices, but still enabled on existing devices, since they might be used in automations there.

It should not cause any weird behavior. Both entities should update at the same time (if enabled). Though you need to add allow_multi=True to the number entity, so it doesn't "reserve" the CurrentSensitivityLevel attribute for itself, causing the old SELECT entities to not be discovered.

(I think due to how discovery works (first going through NUMBER, then SELECT schemas), it's enough to only add allow_multi=True to the number schemas, but let's also add it to the SELECT schemas as well to be a bit more consistent, and not depend on how the discovery order works.)

Hi,

Thanks for the help!

The test won't pass with the entity_registry_enabled_default=False added, even the device aqara_door_window_p2 works in real life with this PR. Should I touch the test_select as well?

It looks like you got everything figured out now, with tests passing.
It's fine to add entity_registry_enabled_by_default to the test_select test, so the old entities are enabled by default for that test.

TheJulianJES · 2026-04-13T11:20:32Z

+            name="Sensitivity",
+            entity_category=EntityCategory.CONFIG,
+            translation_key="sensitivity_level",


We'll also need to add a translation for the sensitivity_level key to the number section of Matter strings here: https://github.com/home-assistant/core/blob/dev/homeassistant/components/matter/strings.json

The existing translation is just for the SELECT platform, so it won't be used by this new NUMBER entity.
If that's done, we can also drop the name here:

Suggested change

name="Sensitivity",

entity_category=EntityCategory.CONFIG,

translation_key="sensitivity_level",

entity_category=EntityCategory.CONFIG,

translation_key="sensitivity_level",

(Do note you may need to run python3 -m script.translations develop locally after adding a new string to strings.json, before it's used by HA.)

You'll also need to regenerate test snapshots after having added the sensitivity_level to strings.json (`pytest tests/components/matter --snapshot-update).

Hi, thanks for the suggested edits. I have made extra commits based on your suggestions.

TheJulianJES · 2026-04-13T11:25:46Z

Everything is looking good already. One more small thing:
We likely also want one basic test in test_number.py, where it's tested that the newly added sensitivity entity writes the correct value to the right attribute, and that an incoming report also updates the entity state.

(If you need help with that, I can also help with that. It should be pretty similar to existing tests in test_number though.)

Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>

TheJulianJES

Looks good. Thanks!

abmantis · 2026-04-24T17:52:48Z

Should we update the description to "Manufacturer-specific sensitivity select entities have been deprecated and will be removed in the future."? Otherwise users may thing they are gone already.

wardmatter · 2026-04-24T18:05:12Z

Should we update the description to "Manufacturer-specific sensitivity select entities have been deprecated and will be removed in the future."? Otherwise users may thing they are gone already.

Hi thanks for the inputs. I have added a line for clarification.

abmantis · 2026-04-24T18:56:31Z

Should we update the description to "Manufacturer-specific sensitivity select entities have been deprecated and will be removed in the future."? Otherwise users may thing they are gone already.

Hi thanks for the inputs. I have added a line for clarification.

I've added it to the "Breaking change" section too.

wardmatter added 2 commits April 9, 2026 01:35

Add dynamic Matter sensitivity slider discovery

75468a1

Make Matter sensitivity slider one-based

fb120a7

Copilot AI review requested due to automatic review settings April 8, 2026 17:51

Copilot started reviewing on behalf of wardmatter April 8, 2026 17:52 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

wardmatter added 2 commits April 9, 2026 01:56

Format Matter select test

1075942

Regenerate Matter snapshots

f53ce2b

Copilot AI review requested due to automatic review settings April 8, 2026 18:20

Copilot started reviewing on behalf of wardmatter April 8, 2026 18:21 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

regenerate test files manually

c158202

wardmatter marked this pull request as ready for review April 8, 2026 18:40

Merge branch 'dev' into codex/matter-sensitivity-slider

5227e80

wardmatter requested a review from a team as a code owner April 8, 2026 18:40

Copilot AI review requested due to automatic review settings April 8, 2026 18:40

Copilot started reviewing on behalf of wardmatter April 8, 2026 18:42 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

TheJulianJES reviewed Apr 10, 2026

View reviewed changes

Remove Matter custom component version

4d09d6c

wardmatter marked this pull request as ready for review April 10, 2026 22:02

wardmatter marked this pull request as draft April 10, 2026 22:08

wardmatter and others added 3 commits April 11, 2026 06:22

Disable Matter legacy sensitivity selects by default

b5f1814

enable select entity for aqara_door_window_p2 for testing

0cf7b22

Merge branch 'dev' into codex/matter-sensitivity-slider

375c7ca

wardmatter marked this pull request as ready for review April 10, 2026 23:03

TheJulianJES reviewed Apr 13, 2026

View reviewed changes

Comment thread homeassistant/components/matter/select.py Outdated

TheJulianJES reviewed Apr 13, 2026

View reviewed changes

TheJulianJES marked this pull request as draft April 13, 2026 11:25

TheJulianJES added deprecation Indicates a breaking change to happen in the future and removed breaking-change labels Apr 13, 2026

wardmatter and others added 2 commits April 13, 2026 19:32

Merge branch 'dev' into codex/matter-sensitivity-slider

a998a29

Update homeassistant/components/matter/number.py

f7f0bd3

Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>

TheJulianJES added the new-feature label Apr 13, 2026

wardmatter added 3 commits April 13, 2026 20:17

Refine Matter sensitivity migration coverage

4c17644

edit for cleaner diff of select.py

e86f9f7

Format Matter P100 node fixture

4bfa267

wardmatter marked this pull request as ready for review April 13, 2026 13:42

TheJulianJES reviewed Apr 21, 2026

View reviewed changes

Comment thread homeassistant/components/matter/select.py Outdated

wardmatter and others added 2 commits April 22, 2026 09:11

Update select.py comment

82e545f

Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>

Merge branch 'dev' into codex/matter-sensitivity-slider

ae41ef1

TheJulianJES approved these changes Apr 24, 2026

View reviewed changes

abmantis approved these changes Apr 24, 2026

View reviewed changes

abmantis merged commit 8b2afb4 into home-assistant:dev Apr 24, 2026
33 checks passed

github-actions Bot locked and limited conversation to collaborators Apr 25, 2026

Uh oh!

Conversation

wardmatter commented Apr 8, 2026 • edited by abmantis Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Breaking change

Proposed change

Changes

Type of change

Additional information

Checklist

Uh oh!

home-assistant Bot commented Apr 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

lboue commented Apr 8, 2026

Uh oh!

wardmatter commented Apr 8, 2026

Uh oh!

TheJulianJES Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wardmatter Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

TheJulianJES Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TheJulianJES Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wardmatter Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

TheJulianJES commented Apr 13, 2026

Uh oh!

Uh oh!

TheJulianJES left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

abmantis commented Apr 24, 2026

Uh oh!

wardmatter commented Apr 24, 2026

Uh oh!

abmantis commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

wardmatter commented Apr 8, 2026 •

edited by abmantis

Loading

TheJulianJES Apr 10, 2026 •

edited

Loading

TheJulianJES Apr 13, 2026 •

edited

Loading