Type Configuration

Each device supports a type of controller and this is what gives them the functionality over an entity.

Here you can check the specific parameters that each type of controller needs. Check the configuration page for the generic parameters.

Light controller

This controller allows the devices to control light or group of lights. This allows you to:

• Turn on/off light(s)
• Toggle light(s)
• Manual increase/decrease of brightness and color
• Smooth increase/decrease (holding button) of brightness and color
• Color loop changing if the light supports xy color.

key	type	value	description
light*	string | dictionary	group.livingroom_lights or light.kitchen	The light (or group of lights) you want to control
manual_steps	int	10	Number of steps to go from min to max when clicking. If the value is 2 with one click you will set the light to 50% and with another one to 100%.
automatic_steps	int	10	Number of steps to go from min to max when smoothing. If the value is 2 with one click you will set the light to 50% and with another one to 100%.
min_brightness	int	1	The minimum brightness to set to the light.
max_brightness	int	255	The maximum brightness to set to the light.
min_white_value	int	1	The minimum white value to set to the light.
max_white_value	int	255	The maximum white value to set to the light.
min_color_temp	int	153	The minimum color temperature to set to the light.
max_color_temp	int	500	The maximum color temperature to set to the light.
smooth_power_on	boolean	False	If True the associated light will be set to minimum brightness when brightness up is clicked or hold ad light is off.
delay	int	Controller specific	Delay in milliseconds that takes between sending the instructions to the light (for the smooth functionality). Note that if leaving to 0, you might get uncommon behavior.
max_loops	int	50	Maximum number of loops when holding. The loop will stop either with a release action or reaching the max_loops value.
hold_release_toggle	boolean	False	If true, a hold action will work as a release when another hold is running. This is useful when you have a button with just one action event and you want to use the hold-release feature, then you just need to map that event to a hold action.
release_delay	float	0	release actions will be delayed this amount of time (in seconds). This is to avoid cases where release is send almost at the same time as hold actions.
transition	int	300	Time in milliseconds that takes the light to transition from one state to another one.
add_transition	boolean	True	If true adds transition if supported, otherwise it does not adds the transition attribute.
add_transition_turn_toggle	boolean	True	If false does not add transition when turning on/off or toggling, otherwise it adds the transition attribute to the call. See FAQ #6 for a further explanation on the use of this parameter.
color_wheel	string | list	default_color_wheel	It defines the color wheel used when changing the xy color either when click or hold actions are used. Check down to know more about the options.
supported_features	int	0b101100 or 44	See below for the explanation.
supported_color_modes	list	["xy", "rgb"]	It overrides the supported_color_modes that can be found in light attributes. Values can be color_temp, hs, xy, rgb, rgbw and rgbww.
update_supported_features	boolean	False	If true, it will check the supported features field everytime before calling any call service action. Useful in case the supported features of the device entity changes over the time.
hold_toggle_direction_init	string	up	It indicates the first direction of the hold toggle actions (up or down).

* Required fields

Light dictionary for the light attribute:

key	type	value	description
name*	string	light.kitchen	The light (or group of lights) you want to control
color_mode	string	auto	This attribute can take auto, xy_color or color_temp as value. auto will check first if the light supports xy_color and then color_temp. xy_color will cicle through different colors infinitely. color_temp will change the color temperature attribute of the light. If a light supports both, user can pick which action wants for the light(s).

* Required fields

Information about color_wheel attribute:

This attribute can be either an string or a list. These are the possible string values:

value	description
default_color_wheel	These are the 24 colors that appear in the circle color of home assistant.
color_temp_wheel	These are the xy colors translated from color temperature (2000K to 6488K). They were extracted from here.

Otherwise, a custom xy color list can be defined like the following:

example_app:
  module: controllerx
  class: < device class or LightController >
  controller: < your controller id >
  integration: < your integration >
  light: light.your_light
  color_wheel:
    - [0.525, 0.411]
    - [0.167, 0.338]
    - [0.324, 0.329]

Zigbee2MQTT Light controller

This controller (Z2MLightController) allows the devices to control Zigbee2MQTT lights. It allows you to:

• Turn on/off light
• Toggle light
• Manual increase/decrease of brightness and color
• Smooth increase/decrease (holding button) of brightness and color

You can read more about this specific controller here.

key	type	value	description
light*	string | dictionary	my_light	The light you want to control. This is the friendly name light from Zigbee2MQTT.
click_steps	float	70	Number of steps that are passed to Zigbee2MQTT for click actions.
hold_steps	float	70	Number of steps that are passed to Zigbee2MQTT for hold actions.
transition	float	0.5	Transition sent to Zigbee2MQTT when changing brightness or color temp.
use_onoff	bool	false	This allows click and hold actions to turn on/off the light when off or minimum brightness is reached.

* Required fields

Light dictionary for the light attribute:

key	type	value	description
name*	string	light.kitchen	The light you want to control. This is the friendly name light from Zigbee2MQTT.
mode	string	ha	This attribute can take ha, mqtt. On the one hand, ha will send the mqtt messages through Home Assistant with mqtt.publish service. On the other hand, mqtt will send the MQTT messages through MQTT plugin from AppDaemon (hence skipping HA).
topic_prefix	string	zigbee2mqtt	MQTT base topic for Zigbee2MQTT MQTT messages. The topic sent will be <topic_prefix>/<friendly_name>/set.

* Required fields

Media player controller

This allows you to control media players. It supports volume, play/pause and skipping forward/backward the track and the source.

key	type	value	description
media_player*	string	group.livingroom_speakers or media_player.bedroom_speaker	The media player (or group of media players) you want to control
volume_steps	int	10	Number of steps to go from min to max when clicking or holding. If the value is 2 with one click you will set the volume to 50% and with another one to 100%.
delay	int	Controller specific	Delay in milliseconds that takes between sending the volume up/down instructions. Note that the maximum value is 1000 and if leaving to 0, you might get uncommon behavior.
max_loops	int	50	Maximum number of loops when holding. The loop will stop either with a release action or reaching the max_loops value.
hold_release_toggle	boolean	False	If true, a hold action will work as a release when another hold is running. This is useful when you have a button with just one action event and you want to use the hold-release feature, then you just need to map that event to a hold action.
release_delay	float	0	release actions will be delayed this amount of time. This is to avoid cases where release is send almost at the same time as hold actions.
supported_features	int	0b10111111 or 191	See below for the explanation.
update_supported_features	boolean	False	If true, it will check the supported features field everytime before calling any call service action. Useful in case the supported features of the device entity changes over the time.

* Required fields

Switch controller

This allows you to control switch entities as well as input_boolean and binary_sensor. It supports turning on/off and toggling.

key	type	value	description
switch*	string	group.switches or switch.dishwasher	The switch (or group of switches) you want to control

* Required fields

Cover controller

This allows you to control covers. It supports opening/closing and stop covers.

key	type	value	description
cover*	string	group.all_covers or cover.kitchen	The cover (or group of covers) you want to control
open_position	number	100	The open position (between 0 and 100)
close_position	number	0	The close position (between 0 and 100)
cover_duration	number	-	Duration of the cover to open and/or close in seconds, so toggle_open and toggle_close can stop the cover if the cover is still moving. This is recommended to be used when the cover does not report opening and closing states, otherwise, it is not necessary.
supported_features	int	0b10111111 or 191	See below for the explanation.
update_supported_features	boolean	False	If true, it will check the supported features field everytime before calling any call service action. Useful in case the supported features of the device entity changes over the time.

* Required fields

"supported_features" field

This field will override the supported_features attribute from the entity (light, media player, etc). By default, ControllerX will check this value from Home Assistant, however, there are times that this attribute does not reflect properly the features that the entity supports. ControllerX automatically will select one action or another depending on this value, this is why it's important that reflects the supported features. This is defined as a bit field in Home Assistant, so its binary representation of the number will defined which features it supports. You can see the values for each entity below.

Light

feature	value
EFFECT	4
FLASH	8
TRANSITION	32

If you want to express support for everything, the value is 0b101100 or 44.

Media player

feature	value
PAUSE	1
SEEK	2
VOLUME_SET	4
VOLUME_MUTE	8
PREVIOUS_TRACK	16
NEXT_TRACK	32
TURN_ON	128
TURN_OFF	256
PLAY_MEDIA	512
VOLUME_STEP	1024
SELECT_SOURCE	2048
STOP	4096
CLEAR_PLAYLIST	8192
PLAY	16384
SHUFFLE_SET	32768
SELECT_SOUND_MODE	65536
SUPPORT_BROWSE_MEDIA	131072
SUPPORT_REPEAT_SET	262144
SUPPORT_GROUPING	524288

If you want to express support for everything, the value is 0b1111111111110111111 or 524223.

Cover

feature	value
OPEN	1
CLOSE	2
SET_COVER_POSITION	4
STOP	8
OPEN_TILT	16
CLOSE_TILT	32
STOP_TILT	64
SET_TILT_POSITION	128

If you want to express support for everything, the value is 0b11111111 or 255.