Add occupancy binary sensor triggers #157631

emontnemery · 2025-12-01T14:33:07Z

Proposed change

Add occupancy binary sensor triggers

Tagged for 2025.12.0 to have a binary sensor show case in the December 2025 release

Note: Language is aligned with the changes in #157643

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 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:

I have reviewed two other open pull requests in this repository.

home-assistant · 2025-12-01T14:33:17Z

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

Code owner commands

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

home-assistant · 2025-12-01T14:33:17Z

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

Code owner commands

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

emontnemery · 2025-12-01T14:36:33Z

homeassistant/components/binary_sensor/strings.json

@jlpouffier Please check the text and also the trigger keys (binary_sensor.started_detecting_presence, binary_sensor.stopped_detecting_presence) are as you expect

For the cover one, we used that convention: cover.shutter_opened
So let's try to use the same... meaning binary_sensor.presence_something_something

When it comes to the something something 😅 we can either be generic or find something that suits each device class best.
I would vote for the latter, and in that case, I would do

binary_sensor.presence_detected

binary_sensor.presence_cleared

It's both past tense, so it fits our model, and it's simpler to understand.

When it comes to the strings, I would align all of them to this.

Title: Presence Detected
Description: Triggers after one or several presence sensors start detecting presence

Title: Presence Cleared
Description: Triggers after one or several presence sensors stop detecting presence

(I struggled a bit to write something with the word "Cleared".
I think it's fine to have a different wording in the description than the title).

@jlpouffier can you check again please?

Copilot

Pull request overview

This PR adds experimental presence detection triggers for binary sensors, enabling automations to fire when presence sensors start or stop detecting presence. The feature is gated behind the "New triggers and conditions" experimental flag.

Key changes:

Adds two new binary sensor triggers: started_detecting_presence and stopped_detecting_presence
Implements trigger filtering by presence device class
Provides comprehensive test coverage for trigger behaviors (any, first, last)

Reviewed changes

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

Show a summary per file

File	Description
homeassistant/components/binary_sensor/trigger.py	Implements the presence binary sensor triggers with state change detection (has bugs: missing entity_filter override and incorrect docstrings)
homeassistant/components/binary_sensor/triggers.yaml	Defines trigger configuration with behavior field and device_class filtering
homeassistant/components/binary_sensor/strings.json	Adds user-facing translations for trigger names, descriptions, and behavior options
homeassistant/components/binary_sensor/icons.json	Defines icons for the triggers (icons appear to be reversed)
homeassistant/components/automation/init.py	Registers binary_sensor as an experimental trigger platform
tests/components/binary_sensor/test_trigger.py	Provides comprehensive test coverage for trigger behaviors (missing device class filtering tests)

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

homeassistant/components/binary_sensor/trigger.py

homeassistant/components/binary_sensor/icons.json

tests/components/binary_sensor/test_trigger.py

homeassistant/components/binary_sensor/trigger.py

NoRi2909 · 2025-12-01T19:27:27Z

homeassistant/components/binary_sensor/strings.json

+  "title": "Binary sensor",
+  "triggers": {
+    "started_detecting_presence": {
+      "description": "Triggers after one ore more presence sensors start detecting presence.",


Is the change from "Triggers when …" to "Triggers after …" intentional here?

It's making these inconsistent with all existing triggers and the "When" headline in the automation editor.

We currently use "Occupancy" for these sensors, for example in the Activity.

"Presence" is for people or device trackers with regard to zones.

We currently use "Occupancy" for these sensors, for example in the Activity.

Can you clarify what activity you refer to?
Anyhow, I think you're right that the trigger should be for device class BinarySensorDeviceClass.OCCUPANCY instead.

Yes, for the so-called "presence sensors" the device class in HA is BinarySensorDeviceClass.OCCUPANCY

emontnemery · 2025-12-02T07:02:12Z

@NoRi2909 the language in this PR is aligned with the changes in #157643

MartinHjelmare

Code looks good. There are some open conversations above.

NoRi2909

We need to change those two from "Presence" to "Occupancy" as well.

Otherwise this is highly inconsistent and will be indistinguishable from "Presence detected / cleared" for that other device class.

If we want to keep "presence sensors" in the wording, then this could be in the description using:
"Triggers after one ore more presence sensors start detecting occupancy."

homeassistant/components/binary_sensor/strings.json

homeassistant/components/binary_sensor/triggers.yaml

MartinHjelmare · 2025-12-02T14:51:37Z

tests/components/__init__.py

+            },
+            "excluded": {
+                "state": state[0],
+                "attributes": state[1],


There doesn't seem to be much difference between included and excluded states. It's not clear to me why we need the separation here.

The excluded state in the binary_sensor case don't have the wanted device class. For other domains it will be states without some capability attribute etc. The purpose is to check the filtering of entities which are not supported by the trigger is working.

NoRi2909 · 2025-12-02T18:20:56Z

homeassistant/components/binary_sensor/strings.json

+      "name": "Occupancy cleared"
+    },
+    "occupancy_detected": {
+      "description": "Triggers after one ore more occupancy sensors start detecting occupancy.",


We missed the typo "ore" instead of "or".

Fixing that in #157791

Add presence binary sensor triggers

932480b

emontnemery added this to the 2025.12.0 milestone Dec 1, 2025

Copilot AI review requested due to automatic review settings December 1, 2025 14:33

emontnemery requested a review from a team as a code owner December 1, 2025 14:33

home-assistant bot added cla-signed core has-tests integration: automation integration: binary_sensor new-feature by-code-owner Quality Scale: internal labels Dec 1, 2025

Copilot started reviewing on behalf of emontnemery December 1, 2025 14:33 View session

emontnemery commented Dec 1, 2025

View reviewed changes

Copilot finished reviewing on behalf of emontnemery December 1, 2025 14:36

Copilot AI reviewed Dec 1, 2025

View reviewed changes

emontnemery added 2 commits December 1, 2025 15:57

Address comments

25179b7

Adjust language

492bc7f

NoRi2909 reviewed Dec 1, 2025

View reviewed changes

Fix tests

a0db660

AlexC mentioned this pull request Dec 2, 2025

Implement Device Tracker for surepetcare Pets #157537

Draft

21 tasks

emontnemery added 2 commits December 2, 2025 10:38

Merge branch 'dev' into add_presence_binary_sensor_trigger

ba71105

Adjust tests

4213736

MartinHjelmare approved these changes Dec 2, 2025

View reviewed changes

emontnemery added 2 commits December 2, 2025 13:11

Improve test

2bb71ec

Change device class to occupancy, adjust language

297be0b

emontnemery requested a review from synesthesiam as a code owner December 2, 2025 12:20

emontnemery requested a review from arturpragacz as a code owner December 2, 2025 12:20

NoRi2909 suggested changes Dec 2, 2025

View reviewed changes

homeassistant/components/binary_sensor/strings.json Outdated Show resolved Hide resolved

homeassistant/components/binary_sensor/strings.json Outdated Show resolved Hide resolved

emontnemery added 2 commits December 2, 2025 14:00

Adjust

81cbea2

Update light condition tests

8c015d7

emontnemery changed the title ~~Add presence binary sensor triggers~~ Add occupancy binary sensor triggers Dec 2, 2025

MartinHjelmare reviewed Dec 2, 2025

View reviewed changes

NoRi2909 approved these changes Dec 2, 2025

View reviewed changes

Sort triggers.yaml

b689310

MartinHjelmare approved these changes Dec 2, 2025

View reviewed changes

emontnemery merged commit e63242e into dev Dec 2, 2025
60 checks passed

emontnemery deleted the add_presence_binary_sensor_trigger branch December 2, 2025 15:37

frenck added the cherry-picked label Dec 2, 2025

frenck pushed a commit that referenced this pull request Dec 2, 2025

Add occupancy binary sensor triggers (#157631)

bbcc2a9

NoRi2909 reviewed Dec 2, 2025

View reviewed changes

github-actions bot locked and limited conversation to collaborators Dec 4, 2025

Uh oh!

Add occupancy binary sensor triggers #157631

Add occupancy binary sensor triggers #157631

Uh oh!

Conversation

emontnemery commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Type of change

Additional information

Checklist

Uh oh!

home-assistant bot commented Dec 1, 2025

Uh oh!

home-assistant bot commented Dec 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlpouffier Dec 1, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emontnemery commented Dec 2, 2025

Uh oh!

MartinHjelmare left a comment

Choose a reason for hiding this comment

Uh oh!

NoRi2909 left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

MartinHjelmare Dec 2, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

emontnemery commented Dec 1, 2025 •

edited

Loading

jlpouffier Dec 1, 2025 •

edited

Loading

NoRi2909 left a comment •

edited

Loading

MartinHjelmare Dec 2, 2025 •

edited

Loading