From f35be6b5ccae002e1b839cbc7d1bf386fe24dada Mon Sep 17 00:00:00 2001
From: Clyde Stubbs <2366188+clydebarrow@users.noreply.github.com>
Date: Wed, 25 Jun 2025 22:09:43 +1000
Subject: [PATCH] [binary_sensor] Add timeout filter (#9198)

---
 esphome/components/binary_sensor/__init__.py | 14 +++++++++++
 esphome/components/binary_sensor/filter.cpp  |  6 +++++
 esphome/components/binary_sensor/filter.h    | 12 +++++++++-
 tests/components/binary_sensor/common.yaml   | 25 ++++++++++++++++++++
 4 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/esphome/components/binary_sensor/__init__.py b/esphome/components/binary_sensor/__init__.py
index fd9551b850..c97de6d5e5 100644
--- a/esphome/components/binary_sensor/__init__.py
+++ b/esphome/components/binary_sensor/__init__.py
@@ -148,6 +148,7 @@ BinarySensorCondition = binary_sensor_ns.class_("BinarySensorCondition", Conditi
 
 # Filters
 Filter = binary_sensor_ns.class_("Filter")
+TimeoutFilter = binary_sensor_ns.class_("TimeoutFilter", Filter, cg.Component)
 DelayedOnOffFilter = binary_sensor_ns.class_("DelayedOnOffFilter", Filter, cg.Component)
 DelayedOnFilter = binary_sensor_ns.class_("DelayedOnFilter", Filter, cg.Component)
 DelayedOffFilter = binary_sensor_ns.class_("DelayedOffFilter", Filter, cg.Component)
@@ -171,6 +172,19 @@ async def invert_filter_to_code(config, filter_id):
     return cg.new_Pvariable(filter_id)
 
 
+@register_filter(
+    "timeout",
+    TimeoutFilter,
+    cv.templatable(cv.positive_time_period_milliseconds),
+)
+async def timeout_filter_to_code(config, filter_id):
+    var = cg.new_Pvariable(filter_id)
+    await cg.register_component(var, {})
+    template_ = await cg.templatable(config, [], cg.uint32)
+    cg.add(var.set_timeout_value(template_))
+    return var
+
+
 @register_filter(
     "delayed_on_off",
     DelayedOnOffFilter,
diff --git a/esphome/components/binary_sensor/filter.cpp b/esphome/components/binary_sensor/filter.cpp
index 41d0553b35..3567e9c72b 100644
--- a/esphome/components/binary_sensor/filter.cpp
+++ b/esphome/components/binary_sensor/filter.cpp
@@ -25,6 +25,12 @@ void Filter::input(bool value) {
   }
 }
 
+void TimeoutFilter::input(bool value) {
+  this->set_timeout("timeout", this->timeout_delay_.value(), [this]() { this->parent_->invalidate_state(); });
+  // we do not de-dup here otherwise changes from invalid to valid state will not be output
+  this->output(value);
+}
+
 optional<bool> DelayedOnOffFilter::new_value(bool value) {
   if (value) {
     this->set_timeout("ON_OFF", this->on_delay_.value(), [this]() { this->output(true); });
diff --git a/esphome/components/binary_sensor/filter.h b/esphome/components/binary_sensor/filter.h
index 65838da49d..16f44aa5fe 100644
--- a/esphome/components/binary_sensor/filter.h
+++ b/esphome/components/binary_sensor/filter.h
@@ -16,7 +16,7 @@ class Filter {
  public:
   virtual optional<bool> new_value(bool value) = 0;
 
-  void input(bool value);
+  virtual void input(bool value);
 
   void output(bool value);
 
@@ -28,6 +28,16 @@ class Filter {
   Deduplicator<bool> dedup_;
 };
 
+class TimeoutFilter : public Filter, public Component {
+ public:
+  optional<bool> new_value(bool value) override { return value; }
+  void input(bool value) override;
+  template<typename T> void set_timeout_value(T timeout) { this->timeout_delay_ = timeout; }
+
+ protected:
+  TemplatableValue<uint32_t> timeout_delay_{};
+};
+
 class DelayedOnOffFilter : public Filter, public Component {
  public:
   optional<bool> new_value(bool value) override;
diff --git a/tests/components/binary_sensor/common.yaml b/tests/components/binary_sensor/common.yaml
index 148b7d2405..2b4a006352 100644
--- a/tests/components/binary_sensor/common.yaml
+++ b/tests/components/binary_sensor/common.yaml
@@ -4,6 +4,31 @@ binary_sensor:
     id: some_binary_sensor
     name: "Random binary"
     lambda: return (random_uint32() & 1) == 0;
+    filters:
+      - invert:
+      - delayed_on: 100ms
+      - delayed_off: 100ms
+      # Templated, delays for 1s (1000ms) only if a reed switch is active
+      - delayed_on_off: !lambda "return 1000;"
+      - delayed_on_off:
+          time_on: 10s
+          time_off: !lambda "return 1000;"
+      - autorepeat:
+          - delay: 1s
+            time_off: 100ms
+            time_on: 900ms
+          - delay: 5s
+            time_off: 100ms
+            time_on: 400ms
+      - lambda: |-
+          if (id(some_binary_sensor).state) {
+            return x;
+          } else {
+            return {};
+          }
+      - settle: 100ms
+      - timeout: 10s
+
     on_state_change:
       then:
         - logger.log: