Alarm panel: Add changes to support enhanced features (#5671)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

CODEOWNERS

@@ -25,7 +25,7 @@ esphome/components/airthings_ble/* @jeromelaban
 esphome/components/airthings_wave_base/* @jeromelaban @kpfleming @ncareau
 esphome/components/airthings_wave_mini/* @ncareau
 esphome/components/airthings_wave_plus/* @jeromelaban
-esphome/components/alarm_control_panel/* @grahambrown11
+esphome/components/alarm_control_panel/* @grahambrown11 @hwstar
 esphome/components/alpha3/* @jan-hofmeier
 esphome/components/am43/* @buxtronix
 esphome/components/am43/cover/* @buxtronix
@@ -327,7 +327,7 @@ esphome/components/tca9548a/* @andreashergert1984
 esphome/components/tcl112/* @glmnet
 esphome/components/tee501/* @Stock-M
 esphome/components/teleinfo/* @0hax
-esphome/components/template/alarm_control_panel/* @grahambrown11
+esphome/components/template/alarm_control_panel/* @grahambrown11 @hwstar
 esphome/components/text/* @mauritskorse
 esphome/components/thermostat/* @kbx81
 esphome/components/time/* @OttoWinter

esphome/components/alarm_control_panel/__init__.py

@@ -11,7 +11,7 @@ from esphome.const import (
 )
 from esphome.cpp_helpers import setup_entity
 
-CODEOWNERS = ["@grahambrown11"]
+CODEOWNERS = ["@grahambrown11", "@hwstar"]
 IS_PLATFORM_COMPONENT = True
 
 CONF_ON_TRIGGERED = "on_triggered"
@@ -22,6 +22,8 @@ CONF_ON_ARMED_HOME = "on_armed_home"
 CONF_ON_ARMED_NIGHT = "on_armed_night"
 CONF_ON_ARMED_AWAY = "on_armed_away"
 CONF_ON_DISARMED = "on_disarmed"
+CONF_ON_CHIME = "on_chime"
+CONF_ON_READY = "on_ready"
 
 alarm_control_panel_ns = cg.esphome_ns.namespace("alarm_control_panel")
 AlarmControlPanel = alarm_control_panel_ns.class_("AlarmControlPanel", cg.EntityBase)
@@ -53,12 +55,22 @@ ArmedAwayTrigger = alarm_control_panel_ns.class_(
 DisarmedTrigger = alarm_control_panel_ns.class_(
     "DisarmedTrigger", automation.Trigger.template()
 )
+ChimeTrigger = alarm_control_panel_ns.class_(
+    "ChimeTrigger", automation.Trigger.template()
+)
+ReadyTrigger = alarm_control_panel_ns.class_(
+    "ReadyTrigger", automation.Trigger.template()
+)
+
 ArmAwayAction = alarm_control_panel_ns.class_("ArmAwayAction", automation.Action)
 ArmHomeAction = alarm_control_panel_ns.class_("ArmHomeAction", automation.Action)
 ArmNightAction = alarm_control_panel_ns.class_("ArmNightAction", automation.Action)
 DisarmAction = alarm_control_panel_ns.class_("DisarmAction", automation.Action)
 PendingAction = alarm_control_panel_ns.class_("PendingAction", automation.Action)
 TriggeredAction = alarm_control_panel_ns.class_("TriggeredAction", automation.Action)
+ChimeAction = alarm_control_panel_ns.class_("ChimeAction", automation.Action)
+ReadyAction = alarm_control_panel_ns.class_("ReadyAction", automation.Action)
+
 AlarmControlPanelCondition = alarm_control_panel_ns.class_(
     "AlarmControlPanelCondition", automation.Condition
 )
@@ -111,6 +123,16 @@ ALARM_CONTROL_PANEL_SCHEMA = cv.ENTITY_BASE_SCHEMA.extend(
                 cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(ClearedTrigger),
             }
         ),
+        cv.Optional(CONF_ON_CHIME): automation.validate_automation(
+            {
+                cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(ChimeTrigger),
+            }
+        ),
+        cv.Optional(CONF_ON_READY): automation.validate_automation(
+            {
+                cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(ReadyTrigger),
+            }
+        ),
     }
 )
 
@@ -157,6 +179,12 @@ async def setup_alarm_control_panel_core_(var, config):
     for conf in config.get(CONF_ON_CLEARED, []):
         trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
         await automation.build_automation(trigger, [], conf)
+    for conf in config.get(CONF_ON_CHIME, []):
+        trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
+        await automation.build_automation(trigger, [], conf)
+    for conf in config.get(CONF_ON_READY, []):
+        trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
+        await automation.build_automation(trigger, [], conf)
 
 
 async def register_alarm_control_panel(var, config):
@@ -232,6 +260,29 @@ async def alarm_action_trigger_to_code(config, action_id, template_arg, args):
     return var
 
 
+@automation.register_action(
+    "alarm_control_panel.chime", ChimeAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+)
+async def alarm_action_chime_to_code(config, action_id, template_arg, args):
+    paren = await cg.get_variable(config[CONF_ID])
+    var = cg.new_Pvariable(action_id, template_arg, paren)
+    return var
+
+
+@automation.register_action(
+    "alarm_control_panel.ready", ReadyAction, ALARM_CONTROL_PANEL_ACTION_SCHEMA
+)
+@automation.register_condition(
+    "alarm_control_panel.ready",
+    AlarmControlPanelCondition,
+    ALARM_CONTROL_PANEL_CONDITION_SCHEMA,
+)
+async def alarm_action_ready_to_code(config, action_id, template_arg, args):
+    paren = await cg.get_variable(config[CONF_ID])
+    var = cg.new_Pvariable(action_id, template_arg, paren)
+    return var
+
+
 @automation.register_condition(
     "alarm_control_panel.is_armed",
     AlarmControlPanelCondition,

esphome/components/alarm_control_panel/alarm_control_panel.cpp

@@ -96,6 +96,14 @@ void AlarmControlPanel::add_on_cleared_callback(std::function<void()> &&callback
   this->cleared_callback_.add(std::move(callback));
 }
 
+void AlarmControlPanel::add_on_chime_callback(std::function<void()> &&callback) {
+  this->chime_callback_.add(std::move(callback));
+}
+
+void AlarmControlPanel::add_on_ready_callback(std::function<void()> &&callback) {
+  this->ready_callback_.add(std::move(callback));
+}
+
 void AlarmControlPanel::arm_away(optional<std::string> code) {
   auto call = this->make_call();
   call.arm_away();

esphome/components/alarm_control_panel/alarm_control_panel.h

@@ -89,6 +89,18 @@ class AlarmControlPanel : public EntityBase {
    */
   void add_on_cleared_callback(std::function<void()> &&callback);
 
+  /** Add a callback for when a chime zone goes from closed to open
+   *
+   * @param callback The callback function
+   */
+  void add_on_chime_callback(std::function<void()> &&callback);
+
+  /** Add a callback for when a ready state changes
+   *
+   * @param callback The callback function
+   */
+  void add_on_ready_callback(std::function<void()> &&callback);
+
   /** A numeric representation of the supported features as per HomeAssistant
    *
    */
@@ -178,6 +190,10 @@ class AlarmControlPanel : public EntityBase {
   CallbackManager<void()> disarmed_callback_{};
   // clear callback
   CallbackManager<void()> cleared_callback_{};
+  // chime callback
+  CallbackManager<void()> chime_callback_{};
+  // ready callback
+  CallbackManager<void()> ready_callback_{};
 };
 
 }  // namespace alarm_control_panel

esphome/components/alarm_control_panel/automation.h

@@ -69,6 +69,20 @@ class ClearedTrigger : public Trigger<> {
   }
 };
 
+class ChimeTrigger : public Trigger<> {
+ public:
+  explicit ChimeTrigger(AlarmControlPanel *alarm_control_panel) {
+    alarm_control_panel->add_on_chime_callback([this]() { this->trigger(); });
+  }
+};
+
+class ReadyTrigger : public Trigger<> {
+ public:
+  explicit ReadyTrigger(AlarmControlPanel *alarm_control_panel) {
+    alarm_control_panel->add_on_ready_callback([this]() { this->trigger(); });
+  }
+};
+
 template<typename... Ts> class ArmAwayAction : public Action<Ts...> {
  public:
   explicit ArmAwayAction(AlarmControlPanel *alarm_control_panel) : alarm_control_panel_(alarm_control_panel) {}

esphome/components/template/alarm_control_panel/__init__.py

@@ -12,11 +12,13 @@ from esphome.const import (
 )
 from .. import template_ns
 
-CODEOWNERS = ["@grahambrown11"]
+CODEOWNERS = ["@grahambrown11", "@hwstar"]
 
 CONF_CODES = "codes"
 CONF_BYPASS_ARMED_HOME = "bypass_armed_home"
 CONF_BYPASS_ARMED_NIGHT = "bypass_armed_night"
+CONF_CHIME = "chime"
+CONF_TRIGGER_MODE = "trigger_mode"
 CONF_REQUIRES_CODE_TO_ARM = "requires_code_to_arm"
 CONF_ARMING_HOME_TIME = "arming_home_time"
 CONF_ARMING_NIGHT_TIME = "arming_night_time"
@@ -24,16 +26,20 @@ CONF_ARMING_AWAY_TIME = "arming_away_time"
 CONF_PENDING_TIME = "pending_time"
 CONF_TRIGGER_TIME = "trigger_time"
 
+
 FLAG_NORMAL = "normal"
 FLAG_BYPASS_ARMED_HOME = "bypass_armed_home"
 FLAG_BYPASS_ARMED_NIGHT = "bypass_armed_night"
+FLAG_CHIME = "chime"
 
 BinarySensorFlags = {
     FLAG_NORMAL: 1 << 0,
     FLAG_BYPASS_ARMED_HOME: 1 << 1,
     FLAG_BYPASS_ARMED_NIGHT: 1 << 2,
+    FLAG_CHIME: 1 << 3,
 }
 
+
 TemplateAlarmControlPanel = template_ns.class_(
     "TemplateAlarmControlPanel", alarm_control_panel.AlarmControlPanel, cg.Component
 )
@@ -46,6 +52,14 @@ RESTORE_MODES = {
     "RESTORE_DEFAULT_DISARMED": TemplateAlarmControlPanelRestoreMode.ALARM_CONTROL_PANEL_RESTORE_DEFAULT_DISARMED,
 }
 
+AlarmSensorType = template_ns.enum("AlarmSensorType")
+
+ALARM_SENSOR_TYPES = {
+    "DELAYED": AlarmSensorType.ALARM_SENSOR_TYPE_DELAYED,
+    "INSTANT": AlarmSensorType.ALARM_SENSOR_TYPE_INSTANT,
+    "DELAYED_FOLLOWER": AlarmSensorType.ALARM_SENSOR_TYPE_DELAYED_FOLLOWER,
+}
+
 
 def validate_config(config):
     if config.get(CONF_REQUIRES_CODE_TO_ARM, False) and not config.get(CONF_CODES, []):
@@ -60,6 +74,10 @@ TEMPLATE_ALARM_CONTROL_PANEL_BINARY_SENSOR_SCHEMA = cv.maybe_simple_value(
         cv.Required(CONF_INPUT): cv.use_id(binary_sensor.BinarySensor),
         cv.Optional(CONF_BYPASS_ARMED_HOME, default=False): cv.boolean,
         cv.Optional(CONF_BYPASS_ARMED_NIGHT, default=False): cv.boolean,
+        cv.Optional(CONF_CHIME, default=False): cv.boolean,
+        cv.Optional(CONF_TRIGGER_MODE, default="DELAYED"): cv.enum(
+            ALARM_SENSOR_TYPES, upper=True, space="_"
+        ),
     },
     key=CONF_INPUT,
 )
@@ -123,6 +141,7 @@ async def to_code(config):
 
     for sensor in config.get(CONF_BINARY_SENSORS, []):
         bs = await cg.get_variable(sensor[CONF_INPUT])
+
         flags = BinarySensorFlags[FLAG_NORMAL]
         if sensor[CONF_BYPASS_ARMED_HOME]:
             flags |= BinarySensorFlags[FLAG_BYPASS_ARMED_HOME]
@@ -130,7 +149,9 @@ async def to_code(config):
         if sensor[CONF_BYPASS_ARMED_NIGHT]:
             flags |= BinarySensorFlags[FLAG_BYPASS_ARMED_NIGHT]
             supports_arm_night = True
-        cg.add(var.add_sensor(bs, flags))
+        if sensor[CONF_CHIME]:
+            flags |= BinarySensorFlags[FLAG_CHIME]
+        cg.add(var.add_sensor(bs, flags, sensor[CONF_TRIGGER_MODE]))
 
     cg.add(var.set_supports_arm_home(supports_arm_home))
     cg.add(var.set_supports_arm_night(supports_arm_night))

esphome/components/template/alarm_control_panel/template_alarm_control_panel.cpp

@@ -1,3 +1,4 @@
+
 #include "template_alarm_control_panel.h"
 #include <utility>
 #include "esphome/components/alarm_control_panel/alarm_control_panel.h"
@@ -15,8 +16,14 @@ static const char *const TAG = "template.alarm_control_panel";
 TemplateAlarmControlPanel::TemplateAlarmControlPanel(){};
 
 #ifdef USE_BINARY_SENSOR
-void TemplateAlarmControlPanel::add_sensor(binary_sensor::BinarySensor *sensor, uint16_t flags) {
+void TemplateAlarmControlPanel::add_sensor(binary_sensor::BinarySensor *sensor, uint16_t flags, AlarmSensorType type) {
-  this->sensor_map_[sensor] = flags;
+  // Save the flags and type. Assign a store index for the per sensor data type.
+  SensorDataStore sd;
+  sd.last_chime_state = false;
+  this->sensor_map_[sensor].flags = flags;
+  this->sensor_map_[sensor].type = type;
+  this->sensor_data_.push_back(sd);
+  this->sensor_map_[sensor].store_index = this->next_store_index_++;
 };
 #endif
 
@@ -35,13 +42,27 @@ void TemplateAlarmControlPanel::dump_config() {
   ESP_LOGCONFIG(TAG, "  Trigger Time: %" PRIu32 "s", (this->trigger_time_ / 1000));
   ESP_LOGCONFIG(TAG, "  Supported Features: %" PRIu32, this->get_supported_features());
 #ifdef USE_BINARY_SENSOR
-  for (auto sensor_pair : this->sensor_map_) {
+  for (auto sensor_info : this->sensor_map_) {
-    ESP_LOGCONFIG(TAG, "  Binary Sesnsor:");
+    ESP_LOGCONFIG(TAG, "  Binary Sensor:");
-    ESP_LOGCONFIG(TAG, "    Name: %s", sensor_pair.first->get_name().c_str());
+    ESP_LOGCONFIG(TAG, "    Name: %s", sensor_info.first->get_name().c_str());
     ESP_LOGCONFIG(TAG, "    Armed home bypass: %s",
-                  TRUEFALSE(sensor_pair.second & BINARY_SENSOR_MODE_BYPASS_ARMED_HOME));
+                  TRUEFALSE(sensor_info.second.flags & BINARY_SENSOR_MODE_BYPASS_ARMED_HOME));
     ESP_LOGCONFIG(TAG, "    Armed night bypass: %s",
-                  TRUEFALSE(sensor_pair.second & BINARY_SENSOR_MODE_BYPASS_ARMED_NIGHT));
+                  TRUEFALSE(sensor_info.second.flags & BINARY_SENSOR_MODE_BYPASS_ARMED_NIGHT));
+    ESP_LOGCONFIG(TAG, "    Chime mode: %s", TRUEFALSE(sensor_info.second.flags & BINARY_SENSOR_MODE_CHIME));
+    const char *sensor_type;
+    switch (sensor_info.second.type) {
+      case ALARM_SENSOR_TYPE_INSTANT:
+        sensor_type = "instant";
+        break;
+      case ALARM_SENSOR_TYPE_DELAYED_FOLLOWER:
+        sensor_type = "delayed_follower";
+        break;
+      case ALARM_SENSOR_TYPE_DELAYED:
+      default:
+        sensor_type = "delayed";
+    }
+    ESP_LOGCONFIG(TAG, "    Sensor type: %s", sensor_type);
   }
 #endif
 }
@@ -92,31 +113,80 @@ void TemplateAlarmControlPanel::loop() {
       (millis() - this->last_update_) > this->trigger_time_) {
     future_state = this->desired_state_;
   }
-  bool trigger = false;
+
+  bool delayed_sensor_not_ready = false;
+  bool instant_sensor_not_ready = false;
+
 #ifdef USE_BINARY_SENSOR
-  if (this->is_state_armed(future_state)) {
+  // Test all of the sensors in the list regardless of the alarm panel state
-    // TODO might be better to register change for each sensor in setup...
+  for (auto sensor_info : this->sensor_map_) {
-    for (auto sensor_pair : this->sensor_map_) {
+    // Check for chime zones
-      if (sensor_pair.first->state) {
+    if ((sensor_info.second.flags & BINARY_SENSOR_MODE_CHIME)) {
-        if (this->current_state_ == ACP_STATE_ARMED_HOME &&
+      // Look for the transition from closed to open
-            (sensor_pair.second & BINARY_SENSOR_MODE_BYPASS_ARMED_HOME)) {
+      if ((!this->sensor_data_[sensor_info.second.store_index].last_chime_state) && (sensor_info.first->state)) {
-          continue;
+        // Must be disarmed to chime
+        if (this->current_state_ == ACP_STATE_DISARMED) {
+          this->chime_callback_.call();
         }
-        if (this->current_state_ == ACP_STATE_ARMED_NIGHT &&
+      }
-            (sensor_pair.second & BINARY_SENSOR_MODE_BYPASS_ARMED_NIGHT)) {
+      // Record the sensor state change
-          continue;
+      this->sensor_data_[sensor_info.second.store_index].last_chime_state = sensor_info.first->state;
+    }
+    // Check for triggered sensors
+    if (sensor_info.first->state) {  // Sensor triggered?
+      // Skip if bypass armed home
+      if (this->current_state_ == ACP_STATE_ARMED_HOME &&
+          (sensor_info.second.flags & BINARY_SENSOR_MODE_BYPASS_ARMED_HOME)) {
+        continue;
+      }
+      // Skip if bypass armed night
+      if (this->current_state_ == ACP_STATE_ARMED_NIGHT &&
+          (sensor_info.second.flags & BINARY_SENSOR_MODE_BYPASS_ARMED_NIGHT)) {
+        continue;
+      }
+
+      // If sensor type is of type instant
+      if (sensor_info.second.type == ALARM_SENSOR_TYPE_INSTANT) {
+        instant_sensor_not_ready = true;
+        break;
+      }
+      // If sensor type is of type interior follower
+      if (sensor_info.second.type == ALARM_SENSOR_TYPE_DELAYED_FOLLOWER) {
+        // Look to see if we are in the pending state
+        if (this->current_state_ == ACP_STATE_PENDING) {
+          delayed_sensor_not_ready = true;
+        } else {
+          instant_sensor_not_ready = true;
         }
-        trigger = true;
+      }
+      // If sensor type is of type delayed
+      if (sensor_info.second.type == ALARM_SENSOR_TYPE_DELAYED) {
+        delayed_sensor_not_ready = true;
         break;
       }
     }
   }
+  // Update all sensors not ready flag
+  this->sensors_ready_ = ((!instant_sensor_not_ready) && (!delayed_sensor_not_ready));
+
+  // Call the ready state change callback if there was a change
+  if (this->sensors_ready_ != this->sensors_ready_last_) {
+    this->ready_callback_.call();
+    this->sensors_ready_last_ = this->sensors_ready_;
+  }
+
 #endif
-  if (trigger) {
+  if (this->is_state_armed(future_state) && (!this->sensors_ready_)) {
-    if (this->pending_time_ > 0 && this->current_state_ != ACP_STATE_TRIGGERED) {
+    // Instant sensors
-      this->publish_state(ACP_STATE_PENDING);
+    if (instant_sensor_not_ready) {
-    } else {
       this->publish_state(ACP_STATE_TRIGGERED);
+    } else if (delayed_sensor_not_ready) {
+      // Delayed sensors
+      if ((this->pending_time_ > 0) && (this->current_state_ != ACP_STATE_TRIGGERED)) {
+        this->publish_state(ACP_STATE_PENDING);
+      } else {
+        this->publish_state(ACP_STATE_TRIGGERED);
+      }
     }
   } else if (future_state != this->current_state_) {
     this->publish_state(future_state);

esphome/components/template/alarm_control_panel/template_alarm_control_panel.h

@@ -21,7 +21,15 @@ enum BinarySensorFlags : uint16_t {
   BINARY_SENSOR_MODE_NORMAL = 1 << 0,
   BINARY_SENSOR_MODE_BYPASS_ARMED_HOME = 1 << 1,
   BINARY_SENSOR_MODE_BYPASS_ARMED_NIGHT = 1 << 2,
+  BINARY_SENSOR_MODE_CHIME = 1 << 3,
 };
+
+enum AlarmSensorType : uint16_t {
+  ALARM_SENSOR_TYPE_DELAYED = 0,
+  ALARM_SENSOR_TYPE_INSTANT,
+  ALARM_SENSOR_TYPE_DELAYED_FOLLOWER
+};
+
 #endif
 
 enum TemplateAlarmControlPanelRestoreMode {
@@ -29,6 +37,16 @@ enum TemplateAlarmControlPanelRestoreMode {
   ALARM_CONTROL_PANEL_RESTORE_DEFAULT_DISARMED,
 };
 
+struct SensorDataStore {
+  bool last_chime_state;
+};
+
+struct SensorInfo {
+  uint16_t flags;
+  AlarmSensorType type;
+  uint8_t store_index;
+};
+
 class TemplateAlarmControlPanel : public alarm_control_panel::AlarmControlPanel, public Component {
  public:
   TemplateAlarmControlPanel();
@@ -38,6 +56,7 @@ class TemplateAlarmControlPanel : public alarm_control_panel::AlarmControlPanel,
   uint32_t get_supported_features() const override;
   bool get_requires_code() const override;
   bool get_requires_code_to_arm() const override { return this->requires_code_to_arm_; }
+  bool get_all_sensors_ready() { return this->sensors_ready_; };
   void set_restore_mode(TemplateAlarmControlPanelRestoreMode restore_mode) { this->restore_mode_ = restore_mode; }
 
 #ifdef USE_BINARY_SENSOR
@@ -46,7 +65,8 @@ class TemplateAlarmControlPanel : public alarm_control_panel::AlarmControlPanel,
    * @param sensor The BinarySensor instance.
    * @param ignore_when_home if this should be ignored when armed_home mode
    */
-  void add_sensor(binary_sensor::BinarySensor *sensor, uint16_t flags = 0);
+  void add_sensor(binary_sensor::BinarySensor *sensor, uint16_t flags = 0,
+                  AlarmSensorType type = ALARM_SENSOR_TYPE_DELAYED);
 #endif
 
   /** add a code
@@ -98,8 +118,9 @@ class TemplateAlarmControlPanel : public alarm_control_panel::AlarmControlPanel,
  protected:
   void control(const alarm_control_panel::AlarmControlPanelCall &call) override;
 #ifdef USE_BINARY_SENSOR
-  // the map of binary sensors that the alarm_panel monitors with their modes
+  // This maps a binary sensor to its type and attribute bits
-  std::map<binary_sensor::BinarySensor *, uint16_t> sensor_map_;
+  std::map<binary_sensor::BinarySensor *, SensorInfo> sensor_map_;
+
 #endif
   TemplateAlarmControlPanelRestoreMode restore_mode_{};
 
@@ -115,10 +136,15 @@ class TemplateAlarmControlPanel : public alarm_control_panel::AlarmControlPanel,
   uint32_t trigger_time_;
   // a list of codes
   std::vector<std::string> codes_;
+  // Per sensor data store
+  std::vector<SensorDataStore> sensor_data_;
   // requires a code to arm
   bool requires_code_to_arm_ = false;
   bool supports_arm_home_ = false;
   bool supports_arm_night_ = false;
+  bool sensors_ready_ = false;
+  bool sensors_ready_last_ = false;
+  uint8_t next_store_index_ = 0;
   // check if the code is valid
   bool is_code_valid_(optional<std::string> code);