### Zigbee2MQTT ControllerX Basic Mapping Example

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This configuration demonstrates a basic setup for a Zigbee2MQTT integration, mapping device actions like toggling and brightness adjustments to media player controls.

```yaml
name: z2m
listen_to: mqtt
media_player: group.sonos_all
mapping:
  toggle: play_pause
  brightness_up_click: click_volume_up
  brightness_down_click: click_volume_down
  brightness_up_hold: hold_volume_up
  brightness_down_hold: hold_volume_down
  brightness_up_release: release
  brightness_up_release: release
  arrow_right_click: next_source
  arrow_left_click: previous_source
  arrow_right_hold: next_track
  arrow_left_hold: previous_track
```

--------------------------------

### Run ControllerX with AppDaemon using Docker (Shell)

Source: https://github.com/xaviml/controllerx/blob/main/CONTRIBUTING.md

Launch AppDaemon with ControllerX configurations using Docker. Requires an 'apps.yaml' file and HA Long-Lived Access Token. This example is for basic setup without MQTT.

```shell
docker run --pull=always --rm \
-v $PWD/apps/controllerx:/usr/src/app/conf/apps/controllerx \
-v $PWD/apps.yaml:/usr/src/app/conf/apps/apps.yaml \
-e DASH_URL=http://127.0.0.1:5050 \
-e HA_URL="http://YOUR_HA_IP:8123" \
-e TOKEN="YOUR_HA_TOKEN" \
acockburn/appdaemon:latest
```

--------------------------------

### Render Integration Examples with YAML Configuration in Jinja2

Source: https://github.com/xaviml/controllerx/blob/main/docs/device_template.md

Generates tabbed integration examples with YAML configuration for each supported integration. Handles both simple integrations and complex ones with additional attributes, dynamically building valid ControllerX YAML configuration blocks.

```jinja2
{% for integration in controller.integrations_examples %}

=== "{{ integration["title"] }}"

    ```yaml
    example_app:
      module: controllerx
      class: {{ controller.cls }}{% if "attrs" not in integration %}
      integration: {{ integration["name"] }}{% else %}
      integration:
        name: {{ integration["name"] }}
      {% for attr_key, attr_value in integration["attrs"].items() %}  {{ attr_key }}: {{ attr_value }}{% endfor %}{% endif %}
      controller: {{ integration["controller"] }}
      {{ controller.entity_arg }}: {{ controller.entity_name }}
    ```

{% endfor %}
```

--------------------------------

### ControllerX Predefined Actions Examples

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/advanced/predefined-actions.md

Examples demonstrating how to pass parameters to ControllerX predefined actions using the 'action' keyword in YAML configuration. This allows customization of actions like 'sync' and 'toggle'.

```yaml
example_app:
  module: controllerx
  class: E1810Controller
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.my_light
  merge_mapping:
    toggle_hold:
      action: sync
      brightness: 128
      color_temp: 153

example_app:
  module: controllerx
  class: E1810Controller
  controller: controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.my_light
  merge_mapping:
    toggle:
      action: toggle
      attributes:
        brightness: 128
        xy_color: [0.323, 0.329]
```

--------------------------------

### Configure AppDaemon YAML

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/installation.md

This YAML configuration is for the AppDaemon addon, specifying secrets, latitude, longitude, timezone, excluded directories, app directory, and plugin settings. Ensure paths and secrets are correctly set for your Home Assistant environment.

```yaml
---
secrets: /homeassistant/secrets.yaml # (1)
appdaemon:
  latitude: X.XXXXXXX # (2)
  longitude: X.XXXXXXX
  elevation: XXXX
  time_zone: XXXXXXXX
  exclude_dirs:
    - cx_core # (3)
  app_dir: /homeassistant/appdaemon/apps # (4)
  plugins:
    HASS:
      type: hass
http:
  url: http://127.0.0.1:5050
admin:
api:
hadashboard:

```

--------------------------------

### Lutron Caseta Pro Pico Light Controller with Transition

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure Lutron Caseta Pro Pico controller with state integration to control a light with a custom 800ms transition time for smoother dimming effects.

```yaml
example_app:
  module: controllerx
  class: LutronCasetaProPicoLightController
  integration: state
  controller: sensor.controller_action
  light: light.example_light
  transition: 800
```

--------------------------------

### E1810 Controller with Z2M Event Integration

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure E1524/E1810 IKEA controller with Zigbee2MQTT using event entities to control a group of living room lights. This setup listens to z2m events directly for controller actions.

```yaml
livingroom_controller:
  module: controllerx
  class: E1810Controller
  controller: livingroom_controller_action
  integration:
    name: z2m
    listen_to: event
  light: group.livingroom_lights
```

--------------------------------

### ControllerX E1810 Multiple Click and Merge Mapping YAML

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This example showcases how to handle multiple clicks on a button and merge mappings for an E1810 controller. It configures two separate applications to control different lights based on single and double toggle clicks.

```yaml
example_app_1:
  module: controllerx
  class: E1810Controller
  controller: my_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.light1
  merge_mapping:
    toggle$1: toggle

example_app_2:
  module: controllerx
  class: E1810Controller
  controller: my_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.light2
  mapping:
    toggle$2: toggle
```

--------------------------------

### ControllerX E1810 with Templated Actions YAML

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This example demonstrates using templating with ControllerX for an E1810 controller. It configures the 'toggle' action to dynamically select the next option from an input_select entity, allowing for different predefined actions to be executed.

```yaml
example_app:
  module: controllerx
  class: E1810Controller
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.my_light
  mapping:
    toggle:
      - service: input_select.select_next
        data:

```

--------------------------------

### Install Dependencies and Pre-commit Hooks (Shell)

Source: https://github.com/xaviml/controllerx/blob/main/CONTRIBUTING.md

Commands to install project dependencies using poetry and set up pre-commit hooks for code quality checks. Assumes Python 3.10+.

```shell
poetry install
poetry shell
pre-commit install
```

--------------------------------

### Light Controller Actions: Brightness, Color Temperature, and Color

Source: https://context7.com/xaviml/controllerx/llms.txt

Utilize the E1810LightController class for comprehensive light control, including brightness stepping, color temperature adjustments, and xy color cycling. This example showcases a full-featured setup with manual and automatic step configurations, brightness limits, color temperature ranges, and transition effects.

```yaml
# Full-featured light controller with all action types
advanced_light:
  module: controllerx
  class: E1810LightController
  controller: adv_remote
  integration:
    name: z2m
    listen_to: mqtt
  light: light.rgb_strip
  manual_steps: 10  # steps for click brightness changes
  automatic_steps: 10  # steps for smooth hold transitions
  min_brightness: 1
  max_brightness: 255
  min_color_temp: 153  # warm white
  max_color_temp: 500  # cool white
  transition: 300  # milliseconds
  color_wheel: default_color_wheel  # color sequence for xy_color
  mapping:
    toggle: toggle
    toggle$2: on_full_brightness
    toggle$3: on_min_brightness
    brightness_up_click: click_brightness_up
    brightness_down_click: click_brightness_down
    brightness_up_hold: hold_brightness_up
    brightness_down_hold: hold_brightness_down
    brightness_up_release: release
    brightness_down_release: release
    arrow_left_click: click_color_temp_down
    arrow_right_click: click_color_temp_up
    arrow_left_hold: hold_color_temp_down
    arrow_right_hold: hold_color_temp_up
```

--------------------------------

### E1810 Controller with Z2M MQTT Integration

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure E1524/E1810 IKEA controller integrated with Zigbee2MQTT using direct MQTT listening instead of the z2m integration wrapper. Allows more granular MQTT control.

```yaml
office_light:
  module: controllerx
  class: E1810Controller
  controller: office_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.office
```

--------------------------------

### Customize Aqara WXKG01LM with Z2M for Light Toggling

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This configuration customizes the Aqara WXKG01LM controller with Z2M integration to toggle a light to a specific brightness. It merges the default controller behavior with a custom mapping for the 'single' action, setting the brightness to 20.

```yaml
mando_aqara_salon:
  module: controllerx
  class: WXKG01LMLightController
  controller: "0x00158d00027b6d79"
  integration:
    name: z2m
    listen_to: mqtt
  light: light.0x000d6ffffec2620d_light
  merge_mapping:
    single: # Give an action to the `single` event
      service: light.toggle
      data:
        entity_id: light.0x000d6ffffec2620d_light
        brightness: 20
```

--------------------------------

### Control Different Lights with E1810Controller and deCONZ

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This configuration uses the E1810Controller with the deCONZ integration to control different lights based on the 'input_select.where_am_i' state. It allows for distinct light controls in the living room, bedroom, and bathroom.

```yaml
livingroom_controller:
  module: controllerx
  class: E1810Controller
  controller: controller_id
  integration: deconz
  light: light.light1
  constrain_input_select: input_select.where_am_i,livingroom

controller_bedroom:
  module: controllerx
  class: E1810Controller
  controller: controller_id
  integration: deconz
  light: light.light2
  constrain_input_select: input_select.where_am_i,bedroom

controller_bathroom:
  module: controllerx
  class: E1810Controller
  controller: controller_id
  integration: deconz
  light: light.light3
  constrain_input_select: input_select.where_am_i,bathroom
```

--------------------------------

### Customize Aqara Magic Cube with Scenes and Z2M

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This configuration customizes the Aqara magic cube with Z2M integration, using the `mapping` attribute to trigger different Home Assistant scenes. It maps gestures like 'flip90', 'flip180', and 'tap' to specific scene activations.

```yaml
cube_bedroom:
  module: controllerx
  class: Controller
  controller: cube_bedroom
  integration:
    name: z2m
    listen_to: mqtt
  mapping:
    flip90:
      service: scene.turn_on
      data:
        entity_id: scene.bedroom1
    flip180:
      service: scene.turn_on
      data:
        entity_id: scene.bedroom2
    tap:
      service: scene.turn_on
      data:
        entity_id: scene.bedroom3
```

--------------------------------

### Basic Controller Configuration with YAML

Source: https://context7.com/xaviml/controllerx/llms.txt

This snippet demonstrates the basic setup for different controller types (light, media player, cover) using YAML. It specifies the module, class, controller, integration type, and target entity. The framework automatically maps button events to predefined actions for the specified device.

```yaml
# Basic IKEA E1810 (5-button remote) controlling a living room light via Zigbee2MQTT
livingroom_controller:
  module: controllerx
  class: E1810LightController
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.livingroom

# IKEA E1743 (2-button remote) controlling media player via ZHA
bedroom_media_controller:
  module: controllerx
  class: E1743MediaPlayerController
  controller: sensor.ikea_remote_bedroom
  integration: zha
  media_player: media_player.bedroom_speaker

# IKEA E2002 (4-button remote) controlling cover via deCONZ
office_blinds_controller:
  module: controllerx
  class: E1743CoverController
  controller: office_switch
  integration: deconz
  cover: cover.office_blinds

```

--------------------------------

### ControllerX Tasmota Integration Configuration (YAML)

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/integrations/tasmota.md

Provides an example YAML configuration for the ControllerX Tasmota integration. This demonstrates how to map Tasmota device events to control specific lights or other entities within your system.

```yaml
example_app:
  module: controllerx
  class: TasmotaButtonLightController
  controller: stat/tasmota_device/RESULT
  integration:
    name: tasmota
    component: Button1
  light: light.example_light
```

--------------------------------

### E1743 Light Controller with ZHA Integration

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure IKEA E1743 on/off switch to control a simple light with ZHA integration. Uses specific actions (on/off) for basic on-off light control without dimming support.

```yaml
bedroom_light:
  module: controllerx
  class: E1743Controller
  controller: 00:67:88:56:06:78:9b:3f
  integration: zha
  light: light.simple_light
  actions:
    - "on"
    - "off"
```

--------------------------------

### ControllerX E1744 Example for Media Player

Source: https://github.com/xaviml/controllerx/wiki/Home

This YAML configuration demonstrates how to use the E1744 controller to control a media player. It links a sensor to a media player entity.

```yaml
bedroom_speaker:
  module: controllerx
  class: E1744MediaPlayerController
  sensor: sensor.symfonisk_controller_action
  media_player: media_player.bedroom_speaker
```

--------------------------------

### E1810 with Hue Bridge Light Group - Color and Brightness Only

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure E1810 with Hue Bridge integration using Home Assistant groups for color/brightness sync and exclude toggle actions to maintain smooth operation with Hue light groups. Includes smooth power-on and multiple action definitions.

```yaml
hallway_light_group_no_toggle:
  module: controllerx
  class: E1810Controller
  controller: "x90fd9ffffe17d796"
  integration:
    name: z2m
    listen_to: mqtt
  smooth_power_on: true
  light: group.hallway
  actions:
    - arrow_left_hold
    - arrow_left_release
    - arrow_right_hold
    - arrow_right_release
    - arrow_right_click
    - arrow_left_click
    - brightness_up_click
    - brightness_down_click
    - brightness_up_release
    - brightness_down_release
    - brightness_up_hold
    - brightness_down_hold
```

--------------------------------

### E1744 Media Player Controller with deCONZ

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure IKEA Symfonisk controller (E1744) to control a bedroom media player using deCONZ integration. Enables music playback control from the wireless speaker controller.

```yaml
bedroom_speaker:
  module: controllerx
  class: E1744MediaPlayerController
  controller: symfonisk_controller
  integration: deconz
  media_player: media_player.bedroom_speaker
```

--------------------------------

### ControllerX E1810 Example for Living Room Lights

Source: https://github.com/xaviml/controllerx/wiki/Home

A concrete YAML configuration for the E1810 controller to manage all lights in the living room. It maps a specific sensor entity to a group of lights.

```yaml
livingroom_controller:
  module: controllerx
  class: E1810Controller
  sensor: sensor.livingroom_controller_action
  light: group.livingroom_lights
```

--------------------------------

### ControllerX E1744 Light Controller with Conditional Behavior YAML

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This configuration demonstrates advanced control for an E1744 Symfonisk controller using deCONZ. It includes mappings for brightness, color temperature, and toggling behavior, controlled by input booleans for different modes.

```yaml
example_app:
  module: controllerx
  class: E1744LightController
  controller: symfonisk_controller
  integration: deconz
  light: light.livingroom_lamp
  automatic_steps: 15
  delay: 150
  mapping:
    2001: hold_brightness_up # Right turn
    3001: hold_brightness_down # Left turn
    2003: release # Stop right turn
    3003: release # Stop left turn
  constrain_input_boolean: input_boolean.light_mode,on

example_app2:
  module: controllerx
  class: E1744LightController
  controller: symfonisk_controller
  integration: deconz
  light: light.livingroom_lamp
  automatic_steps: 15
  delay: 150
  mapping:
    2001: hold_color_up # Right turn
    3001: hold_color_down # Left turn
    2003: release # Stop right turn
    3003: release # Stop left turn
  constrain_input_boolean: input_boolean.light_mode,off

example_app3:
  module: controllerx
  class: E1744LightController
  controller: symfonisk_controller
  integration: deconz
  light: light.livingroom_lamp
  min_color_temp: 200
  mapping:
    1004: on_min_color_temp # 2 clicks
  constrain_input_boolean: input_boolean.light_colortemp_mode,on

example_app4:
  module: controllerx
  class: E1744LightController
  controller: symfonisk_controller
  integration: deconz
  light: light.livingroom_lamp
  max_color_temp: 400
  mapping:
    1004: on_full_color_temp # 2 clicks
  constrain_input_boolean: input_boolean.light_colortemp_mode,off

example_app5:
  module: controllerx
  class: E1744LightController
  controller: symfonisk_controller
  integration: deconz
  light: light.livingroom_lamp
  mapping:
    1002: toggle # 1 clicks
    1004: # 2 clicks
      service: input_boolean.toggle
      data:
        entity_id: input_boolean.light_colortemp_mode
    1005: # 3 clicks
      service: input_boolean.toggle
      data:
        entity_id: input_boolean.light_mode
```

--------------------------------

### Basic E1810 Controller Configuration

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/others/zigbee2mqtt-light-controller.md

This YAML configuration demonstrates the standard setup for an E1810 controller using ControllerX's Light Controller functionality with a Home Assistant light entity.

```yaml
livingroom_controller:
  module: controllerx
  class: E1810Controller # (1)
  controller: sensor.livingroom_controller_action
  integration: z2m
  light: light.livingroom
```

--------------------------------

### E1810 Color Control Only with Z2M

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure E1810 controller to manage only color/color temperature while toggle and brightness are handled by Zigbee groups. Filters actions to color-related controls only.

```yaml
example_app:
  module: controllerx
  class: E1810Controller
  controller: controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.light1
  actions:
    - arrow_left_hold
    - arrow_left_release
    - arrow_right_hold
    - arrow_right_release
    - arrow_right_click
    - arrow_left_click
```

--------------------------------

### E1743 Controller with Delayed Off Action

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure E1743 on/off switch with action_delay to delay the off action by 10 seconds. Useful for corridor lights where immediate off is undesired to prevent lights from turning off too quickly.

```yaml
corridor_controller:
  module: controllerx
  class: E1743Controller
  controller: corridor_controller
  integration: deconz
  light: light.corridor
  action_delay:
    2002: 10
```

--------------------------------

### Aqara Double Key Wireless Switch Dual Light Control

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure two instances of DoubleKeyWirelessAqaraController to independently control left and right lights using a single Aqara double switch with z2m MQTT integration. Separate configurations handle left and right button groups.

```yaml
controller_left_switch:
  module: controllerx
  class: DoubleKeyWirelessAqaraController
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.light1
  manual_steps: 7
  actions:
    - left
    - left_double
    - left_long

controller_right_switch:
  module: controllerx
  class: DoubleKeyWirelessAqaraController
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.light2
  manual_steps: 7
  actions:
    - right
    - right_double
    - right_long
```

--------------------------------

### Control Multiple Lights with LightController and deCONZ

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This configuration utilizes the LightController with the deCONZ integration to manage three distinct lights (light1, light2, and a group of all lights). It maps specific button codes to actions like 'on', 'off', and brightness adjustments.

```yaml
light1_controller:
  module: controllerx
  class: LightController
  controller: e1810_controller
  integration: deconz
  light: light.light1
  mapping:
    2002: "on"
    3002: "off"
    2001: hold_brightness_up
    2003: release
    3001: hold_brightness_down
    3003: release

light2_controller:
  module: controllerx
  class: LightController
  controller: e1810_controller
  integration: deconz
  light: light.light2
  mapping:
    4002: "on"
    5002: "off"
    4001: hold_brightness_down
    4003: release
    5001: hold_brightness_up
    5003: release

all_lights_controller:
  module: controllerx
  class: LightController
  controller: e1810_controller
  integration: deconz
  light: group.all_lights
  mapping:
    1002: "off"
```

--------------------------------

### Smooth Power On/Off with E1810Controller and Z2M

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This advanced configuration for the E1810Controller with Z2M integration enhances the 'smooth power on' functionality. It allows buttons to set lights to minimum or maximum brightness/color temperature when the light is off, based on button clicks or holds.

```yaml
livingroom_light_on:
  module: controllerx
  class: E1810Controller
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.livingroom
  constrain_input_boolean: light.livingroom,on

livingroom_light_off:
  module: controllerx
  class: LightController
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.livingroom
  mapping:
    toggle: toggle
    brightness_up_click: on_full_brightness
    brightness_down_click: on_min_brightness
    brightness_up_hold: on_full_brightness
    brightness_down_hold: on_min_brightness
    arrow_right_click: on_full_color_temp
    arrow_left_click: on_min_color_temp
    arrow_right_hold: on_full_color_temp
    arrow_left_hold: on_min_color_temp
  constrain_input_boolean: light.livingroom,off
```

--------------------------------

### State Integration Configuration Example

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/integrations/state.md

This YAML configuration demonstrates how to use the 'state' integration to listen for attribute changes ('click') on a custom button sensor ('sensor.my_custom_button') and map these changes to light actions ('on', 'off').

```yaml
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"
```

--------------------------------

### ESPHome I2C Configuration and Display Setup

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/sonos-display.md

Configures I2C communication with specified SDA, SCL pins, and frequency. Sets up an SSD1306 I2C display with a specific model, reset pin, address, and brightness. Includes an update interval and defines a lambda function for dynamic page content.

```yaml
i2c:
  sda: D1
  scl: D2
  frequency: 100khz

display:
  - platform: ssd1306_i2c
    model: "SSD1306 128x64"
    reset_pin: D0
    address: 0x3C
    brightness: 100%
    update_interval: 1s
    id: sonos
    pages:
      lambda: |-
        // Lambda function code here
```

--------------------------------

### Customize Aqara Magic Cube with MediaPlayerController and deCONZ

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This configuration demonstrates customising the Aqara magic cube using the MediaPlayerController with the deCONZ integration (gesture type). It maps cube gestures like shake and rotate to media player actions such as play/pause and volume control.

```yaml
example_app:
  module: controllerx
  class: MediaPlayerController
  controller: my_magic_cube_id
  integration:
    name: deconz
    type: gesture
  media_player: media_player.livingroom_speaker
  mapping:
    1: play_pause # Shake
    8: click_volume_down # Rotate left
    7: click_volume_up # Rotate right
    3: next_track # Flip90
    4: previous_track # Flip180
```

--------------------------------

### Zigbee2MQTT Controller Configuration (MQTT Topic) - YAML

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/integrations/zigbee2mqtt.md

Example of a ControllerX configuration using the 'z2m' integration to listen directly to MQTT topics. This requires enabling the MQTT plugin in ControllerX and specifies the controller's friendly name as the MQTT topic.

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

--------------------------------

### Define Entity and Action in ControllerX

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This snippet demonstrates how to specify an entity ID and define an action in ControllerX using XaViml. The action can be a predefined special value, allowing for dynamic behavior based on the system's state. This configuration is fundamental for setting up device control routines.

```yaml
entity_id: input_select.light_state
- action: "{{ special }}"
```

--------------------------------

### Control Sonos Devices with E1810Controller and Z2M

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

This configuration uses the E1810Controller with Z2M integration to control a group of Sonos devices. It customizes the default behavior by inverting click and hold actions, allowing pressing to skip source instead of tracks.

```yaml
sonos_speaker:
  module: controllerx
  class: MediaPlayerController
  controller: "0x90fd9ffffe0cbd69"
  integration:
```

--------------------------------

### ZHA Integration Configuration with ControllerX

Source: https://github.com/xaviml/controllerx/blob/main/docs/start/integrations/zha.md

YAML configuration for the ControllerX ZHA integration. This example shows how to specify the controller, integration type (zha), and the target light entity. It demonstrates customizing the 'type' attribute to listen for 'gesture' events instead of the default 'command'.

```yaml
example_app:
  module: controllerx
  class: MFKZQ01LMLightController
  controller: magic_cube
  integration:
    name: zha
    type: gesture # defaults to `command`
  light: light.example_light
```

--------------------------------

### E1810 XY Color Light as Color Temperature Light

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure E1810 controller with XY color bulb to operate as a color temperature light when the bulb supports color temperature mode. Set color_mode to color_temp to override default XY behavior.

```yaml
office:
  module: controllerx
  class: E1810Controller
  controller: office_controller
  integration:
    name: z2m
    listen_to: mqtt
  light:
    name: light.office
    color_mode: color_temp
```

--------------------------------

### Configure MQTT Plugin in appdaemon.yaml

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/others/enable-mqtt-plugin.md

This YAML snippet shows the necessary configuration to enable the MQTT plugin within the AppDaemon setup. It includes essential parameters like plugin type, namespace, host, username, and password. Ensure these details are correctly set for your MQTT broker.

```yaml
appdaemon:
  plugins:
    MQTT:
      type: mqtt
      namespace: mqtt
      client_host: host
      client_user: XXXXX
      client_password: XXXXX
```

--------------------------------

### ControllerX Event Integration Configuration

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/advanced/event-integration.md

Example ControllerX YAML configuration for the Event integration. This setup allows ControllerX to listen to a custom event, identify the controller, and map event-driven actions using a template.

```yaml
example_app:
  module: controllerx
  class: LightController
  controller: my_device
  light: light.my_light
  integration:
    name: event
    event_type: my_custom_event
    controller_key: device_name
    action_template: "action_{command}_{args[direction]}"
  mapping:
    action_step_up: click_brightness_up
    action_step_down: click_brightness_down
```

--------------------------------

### Serve Documentation Locally (Shell)

Source: https://github.com/xaviml/controllerx/blob/main/CONTRIBUTING.md

Build and serve the project's documentation locally using MkDocs. This allows for previewing changes to the documentation before deployment.

```shell
cd docs
poetry run mkdocs serve
```

--------------------------------

### Custom Event Payload Example

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/advanced/event-integration.md

An example payload structure for a custom event. This JSON object contains details about the device, the command issued, and any associated arguments, which ControllerX can use to trigger actions.

```json
{
  "device_ieee": "00:67:88:56:06:78:9b:3f",
  "device_name": "my_device",
  "command": "step",
  "args": { "direction": "up" }
}
```

--------------------------------

### ControllerX YAML Configuration Example

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/configuration.md

This YAML snippet demonstrates the core configuration for a ControllerX application. It specifies the module, controller class, integration type, and various options for action handling, timing, and mapping. Dependencies include the ControllerX module itself and the specified smart home integration (e.g., Z2M, Deconz). Inputs are controller identifiers and action names, with outputs being configured controller behaviors.

```yaml
example_app: # It can be anything
  module: controllerx

  # `class` value depends on the controller you want to use
  # Check the classes for each controller on the supported controllers page
  # Supported controller page: https://xaviml.github.io/controllerx/controllers/
  class: Controller # or E1810Controller, LightController, HueDimmerController, etc.

  # `controller` value depends on the integration used (z2m, deconz, zha).
  # Check https://xaviml.github.io/controllerx/others/extract-controller-id for more info
  controller: sensor.my_controller_action # or my_controller_id or 00:67:88:56:06:78:9b:3f

  # `integration` is the integration used for your controller
  # It can be used as object like:
  # integration:
  #   name: z2m
  #   listen_to: mqtt
  # Check https://xaviml.github.io/controllerx/start/integrations for more info
  integration: z2m # or deconz, mqtt, zha, state, etc.

  # `actions` and `excluded_actions` can be used to indicate which actions from the default mapping
  # will be used or not. These 2 attributes cannot be used at the same time.
  actions: # or excluded_actions. This is optional.
    - toggle
    - brightness_up_click

  # `action_delta` is the threshold to avoid firing the same action twice
  action_delta: 300 # default. This is optional.

  # `multiple_click_delay` is used for the multiclick functionality
  # Check https://xaviml.github.io/controllerx/advanced/multiple-clicks for more info
  multiple_click_delay: 500 # default. This is optional.

  # `action_delay` lets you configure delays to existing actions
  action_delay: # This is optional.
    toggle: 10 # This will fire `toggle` action in 10 seconds after pressed.

  # `mode` allows you to define the strategy when an action is already executing
  # Possible values are `single`, `restart`, `queued` and `parallel`
  mode: single # default. This is optional.

  # `mapping` and `merge_mapping` let you override the default behaviour of your controller.
  # `merge_mapping` updates the default mapping, and `mapping` overrides it completely.
  # Check https://xaviml.github.io/controllerx/advanced/custom-controllers for more info
  merge_mapping: # or `mapping`. This is optional.
    brightness_up_click: toggle_full_brightness # use predefined actions
    toggle: # or HA service calls
      service: scene.turn_on
      data:
        entity_id: scene.my_scene
    toggle$2: # This scripts will be called when toggle is fired twice within 500ms (multiple_click_delay)
      - service: script.my_script
      - service: script.my_script_with_arguments
        data:
          my_attr: test

  # From here on, we can include specific attribute from type controllers like
  # Light, MediaPlayer, Switch or Cover controller for example
  # Check https://xaviml.github.io/controllerx/start/type-configuration for more info
  light: light.my_light # or media_player, switch, cover

```

--------------------------------

### YAML Custom Mapping Example

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/advanced/index.md

Demonstrates how to use 'merge_mapping' in YAML to define custom actions for controller events. This example shows how to trigger a scene and send a Telegram notification when the 'off' event occurs on an E1743 controller.

```yaml
example_app:
  module: controllerx
  class: E1743Controller
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.livingroom
  merge_mapping:
    "off":
      - scene: scene.night
      - service: notify.telegram
        data:
          message: "off" clicked
```

--------------------------------

### Zigbee2MQTT Integration Configuration (YAML)

Source: https://github.com/xaviml/controllerx/blob/main/docs/start/integrations/z2m.md

Example configuration for the ControllerX integration with Zigbee2MQTT. It shows how to specify the controller ID, the integration name, and the event type to listen to.

```yaml
example_app:
  module: controllerx
  class: MFKZQ01LMLightController
  controller: magic_cube
  integration:
    name: z2m
    type: gesture # defaults to `action`
  light: light.example_light
```

--------------------------------

### Commit Changes using Commitizen (Shell)

Source: https://github.com/xaviml/controllerx/blob/main/CONTRIBUTING.md

Initiate a commit using the commitizen tool, which guides the user through creating a commit message following a standard format. This assumes the virtual environment is activated.

```shell
cz commit
```

--------------------------------

### Run ControllerX with AppDaemon using Docker and MQTT (Shell)

Source: https://github.com/xaviml/controllerx/blob/main/CONTRIBUTING.md

Launch AppDaemon with ControllerX configurations using Docker, including MQTT support. Requires 'apps.yaml', 'appdaemon.yaml', HA token, and MQTT credentials.

```shell
docker run --pull=always --rm \
-v $PWD/apps/controllerx:/usr/src/app/conf/apps/controllerx \
-v $PWD/apps.yaml:/usr/src/app/conf/apps/apps.yaml \
-v $PWD/appdaemon.yaml:/usr/src/app/conf/appdaemon.yaml.example \
-e DASH_URL=http://127.0.0.1:5050 \
-e HA_URL="http://YOUR_HA_IP:8123" \
-e TOKEN="YOUR_HA_TOKEN" \
-e MQTT_NAMESPACE=mqtt \
-e MQTT_CLIENT_HOST=192.168.X.XXX \
-e MQTT_CLIENT_USER="YOUR_USER" \
-e MQTT_CLIENT_PASSWORD="YOUR_PASSWORD" \
acockburn/appdaemon:latest
```

--------------------------------

### Zigbee2MQTT Controller Configuration (HA State) - YAML

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/integrations/zigbee2mqtt.md

Example of a ControllerX configuration using the 'z2m' integration to listen to HA states. This method is deprecated and requires enabling legacy action sensors in Zigbee2MQTT.

```yaml
livingroom_controller:
  module: controllerx
  class: E1810Controller
  controller: sensor.livingroom_controller_action
  integration:
    name: z2m
    listen_to: ha
  light: light.bedroom
```

--------------------------------

### Tasmota Payload Example

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/integrations/tasmota.md

Illustrates the expected JSON payload format from a Tasmota device when using the ControllerX integration. This payload typically contains device-specific information like button presses or switch states.

```json
{
  "Button1": {
    "Action": "TOGGLE"
  }
}
```

--------------------------------

### deCONZ Integration Configuration (YAML)

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/integrations/deconz.md

Example YAML configuration for ControllerX's deCONZ integration. This snippet shows how to specify the controller, integration name, and customize listening parameters like `listen_to` and `type`.

```yaml
example_app:
  module: controllerx
  class: MFKZQ01LMLightController
  controller: magic_cube
  integration:
    name: deconz
    listen_to: unique_id # defaults to `id`
    type: gesture # defaults to `event`
  light: light.example_light
```

--------------------------------

### Create Beta Release Version

Source: https://github.com/xaviml/controllerx/blob/main/CONTRIBUTING.md

Creates a beta pre-release version using Commitizen. Ensure all release changes are documented in RELEASE_NOTES.md before proceeding. The `--dry-run` flag can be used to preview the version bump. Pushes the new tag to the remote repository.

```shell
cz bump --prerelease beta
git push origin HEAD --tags
```

--------------------------------

### Configure MQTT Integration for ControllerX

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/start/integrations/mqtt.md

This configuration snippet demonstrates how to set up the MQTT integration within ControllerX. It specifies the controller topics to listen to, the target light entity, and the MQTT integration details including the key to extract data from JSON payloads. The mapping translates specific MQTT payload values to light actions. This requires the MQTT plugin to be enabled.

```yaml
example_app:
  module: controllerx
  class: LightController
  controller:
    - zigbee2mqtt/stairway_sensor01_occupancy
    - zigbee2mqtt/stairway_sensor02_occupancy
  light: light.stairway
  integration:
    name: mqtt
    key: occupancy
  mapping:
    "true": "on"
    "false": "off"
```

--------------------------------

### E1810 with Hue Bridge Direct Light Group - Toggle Control

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/examples/index.md

Configure E1810 to control a Hue Bridge light group directly using toggle and toggle_hold actions for synchronized on/off control via Zigbee group commands.

```yaml
hallway_light_group_toggle:
  module: controllerx
  class: E1810Controller
  controller: "x90fd9ffffe17d796"
  integration:
    name: z2m
    listen_to: mqtt
  light: light.hallway
  actions:
    - toggle
    - toggle_hold
```

--------------------------------

### E2002 Light Controller Configuration (YAML)

Source: https://github.com/xaviml/controllerx/blob/main/README.md

This YAML configuration demonstrates how to set up the E2002 controller from IKEA to control a light. It specifies the module, class, controller name, integration details (Z2M via MQTT), and the target light entity. This allows for brightness and color temperature adjustments.

```yaml
livingroom_controller:
  module: controllerx
  class: E2002LightController
  controller: livingroom_controller
  integration:
    name: z2m
    listen_to: mqtt
  light: light.livingroom
```

--------------------------------

### Basic Hold Action Configuration in ControllerX (YAML)

Source: https://github.com/xaviml/controllerx/blob/main/docs/docs/advanced/hold-click-modes.md

This YAML configuration illustrates a basic setup for a 'hold' action on the 'brightness' attribute using ControllerX. It highlights the core parameters required for a simple hold functionality, with the default 'stop' mode being applied.

```yaml
example_app:
  module: controllerx
  class: E1810Controller
  integration: deconz
  controller: my_controller
  light: light.my_light
  merge_mapping:
    2001:
      action: hold
      attribute: brightness
      direction: up
```