From ee248f20e6684b6b0d70436115fcdb64b0691157 Mon Sep 17 00:00:00 2001
From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Date: Wed, 11 Sep 2024 13:39:18 +0200
Subject: [PATCH] Alarm control panel: add state (#34680)

* Alarm control panel: add state

* Fix formatting

* Fix typo

* Add related topics
---
 .../alarm_control_panel.markdown              | 41 ++++++++++++++-----
 1 file changed, 30 insertions(+), 11 deletions(-)

diff --git a/source/_integrations/alarm_control_panel.markdown b/source/_integrations/alarm_control_panel.markdown
index ac002248f01..1f60c3503a1 100644
--- a/source/_integrations/alarm_control_panel.markdown
+++ b/source/_integrations/alarm_control_panel.markdown
@@ -9,24 +9,43 @@ ha_domain: alarm_control_panel
 ha_codeowners:
   - '@home-assistant/core'
 ha_integration_type: entity
+related:
+  - docs: /integrations/manual/
+    title: Manual alarm
+  - docs: /integrations/alarm_control_panel.template/
+    title: Template alarm
 ---
 
 Home Assistant can give you an interface which is similar to a classic alarm system.
 Please see [manual alarm](/integrations/manual) or [template alarm](/integrations/alarm_control_panel.template) for alarm configuration.
 
-
 {% include integrations/building_block_integration.md %}
 
-### Actions
+## The state of an alarm panel entity
+
+An alarm panel entity can have the following states. Not all integrations implement all the different states.
+
+- **Disarmed**: The alarm is disarmed (off).
+- **Armed home**: The alarm is armed in home mode.
+- **Armed away**: The alarm is armed in away mode.
+- **Armed night**: The alarm is armed in night mode.
+- **Armed vacation**: The alarm is armed in vacation mode.
+- **Armed custom bypass**: The alarm is armed in bypass mode.
+- **Pending**: The alarm is pending (towards triggered).
+- **Arming**: The alarm is in the process of being armed.
+- **Disarming**: The alarm is in the process of being disarmed.
+- **Triggered**: The alarm has been triggered.
+
+## Actions
 
 Depending on features supported by a specific integration alarm may expose the following actions:
 
-| Action | Data | Description |
-| ------- | ---- | ----------- |
-| `alarm_arm_home` | `entity_id` <br> `code` (optional) | Arm the alarm in the home mode.
-| `alarm_arm_away` | `entity_id` <br> `code` (optional) | Arm the alarm in the away mode.
-| `alarm_arm_night` | `entity_id` <br> `code` (optional) | Arm the alarm in the night mode.
-| `alarm_arm_vacation` | `entity_id` <br> `code` (optional) | Arm the alarm in the vacation mode.
-| `alarm_disarm` | `entity_id` <br> `code` (optional) | Disarm the alarm.
-| `alarm_trigger` | `entity_id` <br> `code` (optional) | Trigger the alarm manually.
-| `alarm_arm_custom_bypass` | `entity_id` <br> `code` (optional) | Send arm custom bypass command.
+| Action                    | Data                               | Description                         |
+| ------------------------- | ---------------------------------- | ----------------------------------- |
+| `alarm_arm_home`          | `entity_id` <br> `code` (optional) | Arm the alarm in the home mode.     |
+| `alarm_arm_away`          | `entity_id` <br> `code` (optional) | Arm the alarm in the away mode.     |
+| `alarm_arm_night`         | `entity_id` <br> `code` (optional) | Arm the alarm in the night mode.    |
+| `alarm_arm_vacation`      | `entity_id` <br> `code` (optional) | Arm the alarm in the vacation mode. |
+| `alarm_disarm`            | `entity_id` <br> `code` (optional) | Disarm the alarm.                   |
+| `alarm_trigger`           | `entity_id` <br> `code` (optional) | Trigger the alarm manually.         |
+| `alarm_arm_custom_bypass` | `entity_id` <br> `code` (optional) | Send arm custom bypass command.     |