Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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>
This commit is contained in:
Graham Brown 2023-06-15 02:34:42 +02:00 committed by GitHub
parent 4448acbe5d
commit e7047e6fe0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 348 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
components/alarm_control_panel/index.rst Normal file
View File

@ -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`

135
components/alarm_control_panel/template.rst Normal file
View File

@ -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`

1
components/index.rst
View File

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

1
images/alarm-panel.svg Normal file
View File

@ -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>
Side by Side

After

Width:  |  Height:  |  Size: 340 B

8
index.rst
View File

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