From ab02bc1e01dce2baa6d145e4bc016d8247595dbe Mon Sep 17 00:00:00 2001 From: G Johansson Date: Tue, 22 Oct 2024 21:43:51 +0200 Subject: [PATCH] Add new alarm state property and enum (#2361) * Add new alarm state property and enum * Mod date * Change name of enum * Fix * Fixes * Mod --- blog/2024-10-22-new-alarm-state-property.md | 33 +++++++++++++++++++++ docs/core/entity/alarm-control-panel.md | 25 ++++++++-------- 2 files changed, 46 insertions(+), 12 deletions(-) create mode 100644 blog/2024-10-22-new-alarm-state-property.md diff --git a/blog/2024-10-22-new-alarm-state-property.md b/blog/2024-10-22-new-alarm-state-property.md new file mode 100644 index 00000000..69958b4d --- /dev/null +++ b/blog/2024-10-22-new-alarm-state-property.md @@ -0,0 +1,33 @@ +--- +author: G Johansson +authorURL: https://github.com/gjohansson-ST +authorImageURL: https://avatars.githubusercontent.com/u/62932417?v=4 +authorTwitter: GJohansson +title: "New alarm control panel state property and state enum" +--- + +As of Home Assistant Core 2024.11, we have introduced the `alarm_state` property in the `AlarmControlPanelEntity`. This newly added property should be used instead of directly setting the `state` property. + +The new `alarm_state` property should return its state using the new `AlarmControlPanelState` enum instead of as previously, setting the state using the `STATE_ALARM_*` constants. + +There is a one-year deprecation period, and the constants will stop working from 2025.11 to ensure all custom integration authors have time to adjust. + +### Example + +```python + +from homeassistant.components.alarm_control_panel import AlarmControlPanelEntity, AlarmControlPanelState + +class MyAlarm(AlarmControlPanelEntity): + """My alarm.""" + + @property + def alarm_state(self) -> AlarmControlPanelState | None: + """Return the state of the alarm.""" + if self.device.is_on(): + return AlarmControlPanelState.ARMED_AWAY + return AlarmControlPanelState.DISARMED + +``` + +More details can be found in the [alarm control panel documentation](/docs/core/entity/alarm-control-panel#states). diff --git a/docs/core/entity/alarm-control-panel.md b/docs/core/entity/alarm-control-panel.md index 33f45ea4..3a85bc12 100644 --- a/docs/core/entity/alarm-control-panel.md +++ b/docs/core/entity/alarm-control-panel.md @@ -13,26 +13,27 @@ Properties should always only return information from memory and not do I/O (lik | Name | Type | Default | Description | ---- | ---- | ------- | ----------- -| state | str | None | **Required** | One of the states listed in the **states**. +| alarm_state | AlarmControlPanelState | None | **Required** | One of the alarm values listed in the **states**. | code_arm_required | bool | `True` | Whether the code is required for arm actions. | code_format | CodeFormat | None | `None` | One of the states listed in the **code formats** section. | changed_by | str | None | `None` | Last change triggered by. ### States +Setting the state should return an enum from `AlarmControlPanelState` in the `alarm_state` property. + | Value | Description | ----- | ----------- -| `None` | Unknown state. -| `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 arming. -| `disarming` | The alarm is disarming. -| `triggered` | The alarm is triggered. +| `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 arming. +| `DISARMING` | The alarm is disarming. +| `TRIGGERED` | The alarm is triggered. ## Supported features