Add Alarm Control Panel (#2891)

Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/alarm_control_panel/index.rst

@@ -0,0 +1,203 @@
+Alarm Control Panel Component
+=============================
+
+.. seo::
+    :description: Instructions for setting up generic Alarm Control Panels in ESPHome.
+    :image: alarm-panel.svg
+
+.. _config-alarm_control_panel:
+
+Base Alarm COntrol Panel Configuration
+--------------------------------------
+
+.. code-block:: yaml
+
+    alarm_control_panel:
+      - platform: ...
+        name: Alarm Panel
+
+
+Configuration variables:
+
+- **name** (**Required**, string): The name of the alarm control panel.
+
+  .. note::
+
+      If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
+      you want the switch to use that name, you can set ``name: None``.
+
+- **on_state** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when the alarm changes state. See :ref:`alarm_control_panel_on_state_trigger`.
+- **on_triggered** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when the alarm triggers. See :ref:`alarm_control_panel_on_triggered_trigger`.
+- **on_cleared** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when the alarm clears. See :ref:`alarm_control_panel_on_cleared_trigger`.
+
+
+Automation:
+-----------
+
+.. _alarm_control_panel_on_state_trigger:
+
+``on_state`` Trigger
+********************
+
+This trigger is activated each time the alarm changes state.
+
+.. code-block:: yaml
+
+    alarm_control_panel:
+      # ...
+      on_state:
+        then:
+          - logger.log: "Alarm Panel State Changed!"
+
+.. _alarm_control_panel_on_triggered_trigger:
+
+``on_triggered`` Trigger
+************************
+
+This trigger is activated when the alarm changes to triggered state.
+
+.. code-block:: yaml
+
+    alarm_control_panel:
+      # ...
+      on_triggered:
+        then:
+          - logger.log: "Alarm Triggered!"
+
+.. _alarm_control_panel_on_cleared_trigger:
+
+``on_cleared`` Trigger
+**********************
+
+This trigger is activated when the alarm changes from triggered back to either the previous armed state or disarmed.
+
+.. code-block:: yaml
+
+    alarm_control_panel:
+      # ...
+      on_cleared:
+        then:
+          - logger.log: "Alarm Cleared!"
+
+.. _alarm_control_panel_arm_away_action:
+
+``arm_away`` Action
+*******************
+
+This action arms the alarm in away mode. The ``code`` is required when *requires_code_to_arm* is *true*.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - alarm_control_panel.arm_away:
+            id: alarm
+            code: "1234"
+
+.. _alarm_control_panel_arm_home_action:
+
+``arm_home`` Action
+*******************
+
+This action arms the alarm in home mode. The ``code`` is required when *requires_code_to_arm* is *true*.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - alarm_control_panel.arm_home:
+            id: alarm
+            code: "1234"
+
+.. _alarm_control_panel_disarm_action:
+
+``disarm`` Action
+*****************
+
+This action disarms the alarm. The ``code`` is required when *codes* is not empty.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - alarm_control_panel.disarm:
+            id: alarm
+            code: "1234"
+
+.. _alarm_control_panel_pending_action:
+
+``pending`` Action
+******************
+
+This action puts the alarm in pending state (the state before triggered after *pending_time*).
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - alarm_control_panel.pending: alarm
+
+.. _alarm_control_panel_triggered_action:
+
+``triggered`` Action
+********************
+
+This action puts the alarm in triggered state.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - alarm_control_panel.triggered: alarm
+
+.. _alarm_control_panel_is_armed_condition:
+
+``is_armed`` Condition
+**********************
+
+This :ref:`Condition <config-condition>` checks if the alarm control panel is armed.
+
+.. code-block:: yaml
+
+    on_...:
+      if:
+        condition:
+          alarm_control_panel.is_armed: alarm
+
+
+.. _alarm_control_panel_lambda_calls:
+
+lambda calls
+************
+
+From :ref:`lambdas <config-lambda>`, you can call the following methods:
+
+- ``arm_away(code)``
+- ``arm_home(code)``
+- ``disarm(code)``
+
+.. code-block:: cpp
+
+    id(alarm).arm_away();
+    id(alarm).arm_home();
+    id(alarm).disarm("1234");
+
+
+Platforms
+---------
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
+
+See Also
+--------
+
+- :doc:`/components/binary_sensor/index`
+- :apiref:`alarm_control_panel/alarm_control_panel.h`
+- :ghedit:`Edit`

components/alarm_control_panel/template.rst

@@ -0,0 +1,135 @@
+Template Alarm Control Panel
+============================
+
+.. seo::
+    :description: Instructions for setting up template Alarm Control Panels in ESPHome.
+    :image: description.svg
+
+The ``template`` alarm control panel platform allows you to turn your binary sensors into a state machine
+managed alarm control panel.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    alarm_control_panel:
+      - platform: template
+        name: Alarm Panel
+        codes:
+          - "1234"
+        binary_sensors:
+          - input: zone_1
+          - input: zone_2
+            bypass_armed_home: true
+
+Configuration variables:
+------------------------
+
+- **codes** (*Optional*, list of string): A list of codes for disarming the alarm, if *requires_code_to_arm* set to true then for arming the alarm too.
+- **requires_code_to_arm** (*Optional*, boolean): Code required for arming the alarm, *code* must be provided.
+- **arming_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed.
+- **pending_time** (*Optional*, :ref:`config-time`): The entry delay before the alarm is triggered.
+- **trigger_time** (*Optional*, :ref:`config-time`): The time after a triggered alarm before resetting to previous state if the sensors are cleared/off.
+- **binary_sensors** (*Optional*, *list*): A list of binary sensors the panel should use. Each consists of:
+
+  - **input** (**Required**, string): The id of the binary sensor component
+  - **bypass_armed_home** (*Optional*, boolean): This binary sensor will not trigger the alarm when in ``armed_home`` state.
+
+- **restore_mode** (*Optional*, enum):
+
+  - **ALWAYS_DISARMED** (Default): Always start in ``disarmed`` state.
+  - **RESTORE_DEFAULT_DISARMED**: Restore state or default to ``disarmed`` state if no saved state was found.
+
+- All other options from :ref:`Alarm Control Panel <config-alarm_control_panel>`
+
+.. note::
+
+    If ``binary_sensors`` is ommited then you're expected to trigger the alarm using
+    :ref:`alarm_control_panel_pending_action` or :ref:`alarm_control_panel_triggered_action`.
+
+
+.. _template_alarm_control_panel-state_flow:
+
+State Flow:
+-----------
+
+1. The alarm starts in ``DISARMED`` state
+2. When the ``arm_...`` method is invoked
+
+  a. ``arming_time`` greater than 0 the state is ``ARMING``
+  b. ``arming_time`` is 0 or after the ``arming_time`` delay the state is ``ARM_AWAY`` or ``ARM_HOME``
+
+3. When the alarm is tripped by a sensor state changing to ``on``
+
+  a. ``pending_time`` greater than 0 the state is ``PENDING``
+  b. ``pending_time`` is 0 or after the ``pending_time`` delay the state is ``TRIGGERED``
+
+4. If ``trigger_time`` greater than 0 and no sensors are ``on`` after ``trigger_time`` delay
+   the state returns to ``ARM_AWAY`` or ``ARM_HOME``
+
+Example:
+--------
+
+.. code-block:: yaml
+
+    alarm_control_panel:
+      platform: template
+      name: Alarm Panel
+      codes:
+        - "1234"
+      requires_code_to_arm: true
+      arming_time: 10s
+      pending_time: 15s
+      trigger_time: 5min
+      binary_sensors:
+        - input: zone_1
+        - input: zone_2
+          bypass_armed_home: true
+        - input: ha_test
+      on_state:
+        then:
+          - lambda: !lambda |-
+              ESP_LOGD("TEST", "State change %s", alarm_control_panel_state_to_string(id(acp1)->get_state()));
+      on_triggered:
+        then:
+          - switch.turn_on: siren
+      on_cleared:
+        then:
+          - switch.turn_off: siren
+
+    binary_sensor:
+      - platform: gpio
+        id: zone_1
+        name: Zone 1
+        device_class: door
+        pin:
+          number: D1
+          mode: INPUT_PULLUP
+          inverted: True
+      - platform: gpio
+        id: zone_2
+        name: Zone 2
+        device_class: motion
+        pin:
+          number: D2
+          mode: INPUT_PULLUP
+          inverted: True
+      - platform: homeassistant
+        id: ha_test
+        name: Zone 3
+        entity_id: input_boolean.test_switch
+
+    switch:
+      - platform: gpio
+        id: siren
+        name: Siren
+        icon: mdi:alarm-bell
+        pin: D7
+
+
+See Also
+--------
+
+- :doc:`index`
+- :doc:`/components/binary_sensor/index`
+- :apiref:`template/alarm_control_panel/template_alarm_control_panel.h`
+- :ghedit:`Edit`

components/index.rst

@@ -26,4 +26,5 @@ Components
     microphone/index
     speaker/index
     time/index
+    alarm_control_panel/index
     *

images/alarm-panel.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M20 3H4c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h16c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2M8 19H5v-2h3v2m0-3H5v-2h3v2m0-3H5v-2h3v2m5.5 6h-3v-2h3v2m0-3h-3v-2h3v2m0-3h-3v-2h3v2m5.5 6h-3v-2h3v2m0-3h-3v-2h3v2m0-3h-3v-2h3v2m0-4H5V5h14v4Z"/></svg>

index.rst

@@ -750,6 +750,14 @@ Home Assistant Companion Components
     Text Sensor, components/text_sensor/homeassistant, home-assistant.svg
     Binary Sensor, components/binary_sensor/homeassistant, home-assistant.svg
 
+Alarm Control Panel Components
+------------------------------
+
+.. imgtable::
+
+    Alarm Control Panel Core, components/alarm_control_panel/index, alarm-panel.svg
+    Template Alarm Control Panel, components/alarm_control_panel/template, description.svg
+
 Miscellaneous Components
 ------------------------