feat(z2m): add event entity listener

related to #1090

Author: xaviml

RELEASE_NOTES.md

@@ -6,9 +6,10 @@ _This minor change does not contain any breaking changes._
 
 **_Note: Remember to restart the AppDaemon addon/server after updating to a new version._**
 
-<!--
 ## :pencil2: Features
--->
+
+- Add [`event` sensor listener](https://BASE_URL/controllerx/start/integrations/zigbee2mqtt/#event-state-listen_to-event) to Zigbee2MQTT integration. [ #1090 ]
+- Deprecate [HA sensor action listener](https://BASE_URL/controllerx/start/integrations/zigbee2mqtt/#ha-states-listen_to-ha) from Zigbee2MQTT integration. [ #1090 ]
 
 <!--
 ## :video_game: New devices
@@ -20,9 +21,9 @@ _This minor change does not contain any breaking changes._
 ## :hammer: Fixes
 -->
 
-<!--
 ## :scroll: Docs
--->
+
+- Refactor [Integration page](https://BASE_URL/controllerx/start/integrations).
 
 <!--
 ## :clock2: Performance

apps/controllerx/cx_core/controller.py

@@ -228,7 +228,9 @@ def get_default_actions_mapping(
     ) -> DefaultActionsMapping:
         actions_mapping = integration.get_default_actions_mapping()
         if actions_mapping is None:
-            raise ValueError(f"This controller does not support {integration.name}.")
+            raise ValueError(
+                f"This controller does not support {integration.name}. Use `mapping` to define the actions."
+            )
         return actions_mapping
 
     @overload

apps/controllerx/cx_core/integration/tasmota.py

@@ -17,7 +17,7 @@ async def listen_changes(self, controller_id: str) -> None:
         if component_key is None:
             raise ValueError(
                 "`component` attribute is mandatory. "
-                "Check example from https://xaviml.github.io/controllerx/start/integrations/#tasmota"
+                "Check example from https://xaviml.github.io/controllerx/start/integrations/tasmota"
             )
         await Mqtt.listen_event(
             self.controller, self.event_callback, topic=controller_id, namespace="mqtt"

apps/controllerx/cx_core/integration/z2m.py

@@ -8,6 +8,7 @@
 
 LISTENS_TO_HA = "ha"
 LISTENS_TO_MQTT = "mqtt"
+LISTENS_TO_EVENT = "event"
 
 
 class Z2MIntegration(Integration):
@@ -19,6 +20,12 @@ def get_default_actions_mapping(self) -> Optional[DefaultActionsMapping]:
     async def listen_changes(self, controller_id: str) -> None:
         listens_to = self.kwargs.get("listen_to", LISTENS_TO_HA)
         if listens_to == LISTENS_TO_HA:
+            self.controller.log(
+                "⚠️ Listening to HA sensor actions is now deprecated and will be removed in the future. Use `listen_to: mqtt` or `listen_to: event` instead."
+                " Read more about it here: https://xaviml.github.io/controllerx/others/z2m-ha-sensor-deprecated",
+                level="WARNING",
+                ascii_encode=False,
+            )
             await Hass.listen_state(self.controller, self.state_callback, controller_id)
         elif listens_to == LISTENS_TO_MQTT:
             topic_prefix = self.kwargs.get("topic_prefix", "zigbee2mqtt")
@@ -28,9 +35,16 @@ async def listen_changes(self, controller_id: str) -> None:
                 topic=f"{topic_prefix}/{controller_id}",
                 namespace="mqtt",
             )
+        elif listens_to == LISTENS_TO_EVENT:
+            await Hass.listen_state(
+                self.controller,
+                self.state_callback,
+                f"event.{controller_id}",
+                attribute="event_type",
+            )
         else:
             raise ValueError(
-                "`listen_to` has to be either `ha` or `mqtt`. Default is `ha`."
+                "`listen_to` has to be either `ha`, `mqtt` or `event`. Default is `ha`."
             )
 
     async def event_callback(

docs/docs/advanced/entity-groups.md

@@ -3,7 +3,7 @@ title: Entity groups
 layout: page
 ---
 
-_This is supported from ControllerX v4.14.0_
+_This is supported since ControllerX v4.14.0_
 
 ControllerX allow for Entity Controllers (LightController, MediaPlayerController, CoverController, etc) to work with grouped entities.
 

docs/docs/advanced/event-integration.md

@@ -3,9 +3,9 @@ title: Event integration
 layout: page
 ---
 
-_This is supported from ControllerX v4.23.0_
+_This is supported since ControllerX v4.23.0_
 
-Most of the integrations supported by ControllerX are defined for an specific use case (zigbee2mqtt, deCONZ, ZHA), but we also have the [`State` integration](/controllerx/start/integrations#state), which is a more generic integration and allows us to listen to any Home Assistant entity state and build a mapping from it. From ControllerX v4.23.0, we can also use the [`Event` integration](/controllerx/start/integrations#event) which allows us define the event we want to listen to, and which actions build from it.
+Most of the integrations supported by ControllerX are defined for an specific use case (zigbee2mqtt, deCONZ, ZHA), but we also have the [`State` integration](/controllerx/start/integrations/state), which is a more generic integration and allows us to listen to any Home Assistant entity state and build a mapping from it. From ControllerX v4.23.0, we can also use the [`Event` integration](/controllerx/start/integrations/event) which allows us define the event we want to listen to, and which actions build from it.
 
 Each event has its own payload that could look like:
 

docs/docs/faq.md

@@ -46,7 +46,7 @@ This is probably happenning to you sometimes and is because the stop/release act
 However, these are some actions you can take to overcome this problem and reduce the number of times that this happens:
 
 - If `release` action is sent at a similar time than a `hold` one, you could use [`release_delay` attribute](/controllerx/start/type-configuration/?h=release_delay#light-controller) to execute `release` actions some amount of time defined after they have been fired. For example: `release_delay: 0.01` (time in seconds).
-- If using z2m, change the integration to listen MQTT directly, this way it will avoid the HA state machine layer. Read more about in [here](/controllerx/start/integrations#zigbee2mqtt).
+- If using z2m, change the integration to listen MQTT directly, this way it will avoid the HA state machine layer. Read more about in [here](/controllerx/start/integrations/zigbee2mqtt).
 - If using deCONZ and you just want to dim your lights smoothly, then you can consider using [this AppDaemon app](https://github.com/Burningstone91/Hue_Dimmer_Deconz) from [_@Burningstone91_](https://github.com/Burningstone91). It brightens/dims your lights with a deCONZ calls instead of calling HA periodically, this means that deCONZ would handle the dimming for you.
 - Play around with delay (default is 350ms) and automatic_steps (default is 10) attributes. You can read more about them in [here](/controllerx/start/type-configuration#light-controller). The lower the delay is, the more requests will go to HA. The more automatic_steps, the more steps it will take to get from min to max, and vice versa.
 - Add more Zigbee routers to the network.

docs/docs/others/enable-mqtt-plugin.md

@@ -5,7 +5,7 @@ layout: page
 
 If we want to use the `mqtt` integration or the `listen_to: mqtt` from `z2m` integration as well as the `Z2MLightController`, we will need to activate the MQTT Plugin on the AppDaemon configuration (normally located in `/addon_configs/a0d7b954_appdaemon/appdaemon.yaml`). We will need the add the following highlighted section in that file:
 
-```yaml hl_lines="12 13 14 15 16 17"
+```yaml hl_lines="13-18"
 ---
 secrets: /homeassistant/secrets.yaml
 appdaemon:

docs/docs/others/extract-controller-id.md

@@ -0,0 +1,63 @@
+---
+title: Zigbee2MQTT - HA sensor is deprecated
+layout: page
+---
+
+_Zigbee2MQTT HA sensor deprecated since ControllerX v4.29.0_
+
+Zigbee2MQTT 2.0.0 brought [some breaking changes](https://github.com/Koenkk/zigbee2mqtt/discussions/24198), and one of them was to deprecate the [Home Assistant action sensors](https://www.zigbee2mqtt.io/guide/usage/integrations/home_assistant.html#via-home-assistant-action-sensor-deprecated), which is the default option for [Zigbee2MQTT integration](/controllerx/start/integrations/zigbee2mqtt) in ControllerX.
+
+You might be here because of a warning in AppDaemon logs that look like the following:
+
+!!! quote
+
+    ⚠️ Listening to HA sensor actions is now deprecated and will be removed in the future. Use `listen_to: mqtt` or `listen_to: event` instead. Read more about it here: https://xaviml.github.io/controllerx/others/z2m-ha-sensor-deprecated
+
+This might be because your controller configuration looks like:
+
+```yaml hl_lines="4-5"
+livingroom_controller:
+  module: controllerx
+  class: E1810Controller
+  controller: sensor.livingroom_controller_action
+  integration: z2m
+  light: light.livingroom
+```
+
+The issue is within the `integration: z2m` which is defaulted to read a HA `sensor`. You need to switch to either [`mqtt`](/controllerx/start/integrations/zigbee2mqtt/#mqtt-topics-listen_to-mqtt) (recommended) or HA [`event`](/controllerx/start/integrations/zigbee2mqtt/#event-state-listen_to-event) (experimental).
+
+## Switch to MQTT listener (recommended)
+
+In case of switching to MQTT (as [recommneded by Zigbee2MQTT](https://www.zigbee2mqtt.io/guide/usage/integrations/home_assistant.html#via-mqtt-device-trigger-recommended)), you would need to first [enable MQTT plugin](/controllerx/others/enable-mqtt-plugin). Then, change your configuration to something like the following:
+
+```yaml hl_lines="4-7"
+livingroom_controller:
+  module: controllerx
+  class: E1810Controller
+  controller: livingroom_controller # (1)
+  integration:
+    name: z2m
+    listen_to: mqtt # (2)
+  light: light.livingroom
+```
+
+1. This is the device friendly_name in Zigbee2MQTT. Check [here](/controllerx/start/integrations/zigbee2mqtt/#mqtt-topics-listen_to-mqtt) how to get this value.
+2. By indicating `mqtt` here, ControllerX will listen to MQTT controller topic.
+
+## Switching to HA Event sensor listener (experimental)
+
+Another option is to listen the newly (and experimental) event entity from Zigbee2MQTT 2.0.0. First, we will need to enable the experimental feature in Zigbee2MQTT as explained [here](/controllerx/start/integrations/zigbee2mqtt/#event-state-listen_to-event). Then, you would need to switch configuration to something like:
+
+```yaml hl_lines="4-7"
+livingroom_controller:
+  module: controllerx
+  class: E1810Controller
+  controller: office_controller_action # (1)
+  integration:
+    name: z2m
+    listen_to: event # (2)
+  light: light.livingroom
+```
+
+1. This is the event entity without the `event.` prefix. Check [here](/controllerx/start/integrations/zigbee2mqtt/#event-state-listen_to-event) how to get this value.
+2. By indicating `event` here, ControllerX will listen to the event entity changes.

docs/docs/others/z2m-ha-sensor-deprecated.md

@@ -3,7 +3,7 @@ title: Zigbee2MQTT Light Controller
 layout: page
 ---
 
-_This is supported from ControllerX v4.21.0_
+_This is supported since ControllerX v4.21.0_
 
 ControllerX has always given support for [Light Controller](/controllerx/start/type-configuration#light-controller) which allows amongst other features to smoothly change attributes (brightness, color temperature) values by requesting the changes periodically to Home Assistant. This has allowed to work with lights integrated with many integrations (e.g.: Zigbee2MQTT, deCONZ, WLED, Hue). However, this generalization has penalized Zigbee2MQTT which has its own mechanism to change brightness and color temp over time which works much smoother than the Light Controller.