diff --git a/components/alarm_control_panel/index.rst b/components/alarm_control_panel/index.rst new file mode 100644 index 000000000..686fc57dc --- /dev/null +++ b/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 ` set for your device and + you want the switch to use that name, you can set ``name: None``. + +- **on_state** (*Optional*, :ref:`Action `): An automation to perform + when the alarm changes state. See :ref:`alarm_control_panel_on_state_trigger`. +- **on_triggered** (*Optional*, :ref:`Action `): An automation to perform + when the alarm triggers. See :ref:`alarm_control_panel_on_triggered_trigger`. +- **on_cleared** (*Optional*, :ref:`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 ` 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 `, 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` diff --git a/components/alarm_control_panel/template.rst b/components/alarm_control_panel/template.rst new file mode 100644 index 000000000..efcd3318d --- /dev/null +++ b/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 ` + +.. 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` diff --git a/components/index.rst b/components/index.rst index 48a4c1ca8..d26885a1a 100644 --- a/components/index.rst +++ b/components/index.rst @@ -26,4 +26,5 @@ Components microphone/index speaker/index time/index + alarm_control_panel/index * diff --git a/images/alarm-panel.svg b/images/alarm-panel.svg new file mode 100644 index 000000000..cf033c712 --- /dev/null +++ b/images/alarm-panel.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 89053e224..6ae7b8168 100644 --- a/index.rst +++ b/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 ------------------------