Integrations
Integrations is a way to abstract the logic from the event extraction in ControllerX. Each integration is resposible for listening the state or event and decoding the events in a way that ControllerX understands. Here you can see which value the controller
should have for each of this integrations:
Zigbee2MQTT
This integration(z2m
) is meant to be used for zigbee2mqtt. It listens the states from the HA sensor entities. You can add listen_to
attribute to indicate if it listens for HA states (ha
) or MQTT topics (mqtt
). Default is ha
. If you want to use the mqtt
, then you will need to change the appdaemon.yaml
as it is stated in the MQTT
integration section. Imagine we have the following configuration already created for a z2m
controller listening to HA state:
livingroom_controller:
module: controllerx
class: E1810Controller
controller: sensor.livingroom_controller_action
integration: z2m
light: light.bedroom
Then, if we want to listen to the MQTT topic directly (skipping the HA state machine), we will need to change to:
livingroom_controller:
module: controllerx
class: E1810Controller
controller: livingroom_controller
integration:
name: z2m
listen_to: mqtt
action_key: action # By default is `action` already
light: light.bedroom
Three things to clarify when using the z2m
integration listening to MQTT:
appdaemon.yaml
needs to be changed by adding the MQTT plugin (seeMQTT
section below).- The Zigbee2MQTT friendly name from the z2m needs to be specified in the
controller
attribute. action_key
is the key inside the topic payload that contains the fired action from the controller. It is normallyaction
orclick
. By default will beaction
.action_group
is a list of allowed action groups for the controller configuration. Read more about it here.
deCONZ
This integration(deconz
) listens to events and actions gets fired by default with the event
attribute from the data
object. However, you can change the attribute to listen to by adding a type
attribute. This is an example
example_app:
module: controllerx
class: MFKZQ01LMLightController
controller: magic_cube
integration:
name: deconz
type: gesture
light: light.example_light
ZHA
This integration(zha
) listens to events and concatenates the command with the argument for the action string. It does not have any additional arguments.
MQTT
This integration(mqtt
) listens for the topic sent from the controller
attribute. Although this integration makes sense to use together with custom controllers, it works with the actions from zigbee2mqtt. This means that if you have a configuration like the following:
livingroom_controller:
module: controllerx
class: E1810Controller
controller: sensor.livingroom_controller_action
integration: z2m
light: light.bedroom
You can remove the layer of HA state and therefore gain some speed by changing it for:
livingroom_controller:
module: controllerx
class: E1810Controller
# This is the action topic from z2m
controller: zigbee2mqtt/livingroom_controller/action
integration: mqtt
light: light.bedroom
By doing this, ControllerX will be listening directly from MQTT rather than Home Assistant (which listens from MQTT). Not only can you use this with zigbee2mqtt, but also with any other MQTT integration. However, it comes with the limitation that it expects the payload from the topic to be the action and not a JSON, this is why the example above we use zigbee2mqtt/livingroom_controller/action
and not zigbee2mqtt/livingroom_controller
. Last but not least, MQTT needs to be configured on appdaemon.yaml
by adding the MQTT
plugin, apart from the HASS
plugin. The whole file should look like the following:
---
secrets: /config/secrets.yaml
appdaemon:
latitude: X.XXXXXXX
longitude: X.XXXXXXX
elevation: XXXX
time_zone: XXXXXXXX
# You can add `missing_app_warnings` if you don't want any
# warning spam from ControllerX when starting AppDaemon
missing_app_warnings: 1
plugins:
HASS:
type: hass
MQTT:
type: mqtt
namespace: mqtt # This is important
client_host: <Host without indicating the port (e.g. 192.168.1.10)>
client_user: XXXXX
client_password: XXXXX
http:
url: http://127.0.0.1:5050
admin:
api:
hadashboard:
State
This integration (state
) listens for the state of a sensor and the action is fired with the changed event. You can add attribute
parameter if you want to listen to state change on the state attribute level. Read more about the options in here. An example could be:
example_app:
module: controllerx
class: LightController
controller: sensor.my_custom_button
integration:
name: state
attribute: click
light: light.example_light
mapping:
1_click: "on"
2_click: "off"