Devices and Groups

Zigbee2MQTT also stores the definitions of devices and groups in the configuration.yml.

Most options are optional, only the IEEE address (or MAC) as the key and a friendly_name are required.

devices:
    # First device
    '0x00158d0001d82999':
        friendly_name: 'my_occupancy_sensor'
        retain: true
        disabled: false
        qos: 1
        debounce: 0.5
        debounce_ignore:
            - action
            - brightness
        # Set `homeassistant: null` to skip discovery for this device
        homeassistant:
            # Applied to all discovered entities.
            expire_after: 30
            # Only applied to discovered temperature sensor.
            temperature:
                icon: mdi:oil-temperature
                # Omit values by setting them to null, e.g. don't send device_class
                device_class: null
        # Device type specific examples
        occupancy_timeout: 120
        no_occupancy_since: [10, 600]
    # Another device
    '0x000d6ffffee405eb':
        friendly_name: 'Kitchen bulb'

Generic device options

Every Zigbee Device supports the following list of options.

friendly_name
Used in the MQTT topic of a device. By default, this is the device ID (e.g. 0x00128d0001d9e1d2).

description
Description of this device, e.g. This device is in the kitchen, will be shown in the frontend.

retain
Retain MQTT messages of this device (default false).

disabled
Disables the device. This does not prevent the device from communicating in the Zigbee network. E.g. when messages are received from this device, Zigbee2MQTT will still publish them. This feature is useful for devices which will be disconnected from the Zigbee network for a longer time (like Christmas lights). Disabling a device does the following:

• The availability feature will not try to ping it
• The device is always marked as unavailable in Home Assistant
• It will not be configured on Zigbee2MQTT startup (required for some devices in order to start working)
• It will be excluded from network scans (network map)
• It will be excluded from optimistic group state updates

retention
Sets the MQTT Message Expiry in seconds e.g. retention: 900 = 15 minutes (default: not enabled). Make sure to set mqtt.version to 5 (see mqtt configuration above)

qos
QoS level for MQTT messages of this device. What is QoS?

homeassistant
Allows overriding the values of the Home Assistant discovery payload. See example above.

debounce
Debounces messages of this device. When setting e.g. debounce: 1 and a message from a device is received, Zigbee2MQTT will not immediately publish this message. But it will combine it with other messages that are received max 1 seconds apart from each other. So there needs to be "N second of silence" from the device before the combined message is sent out.

For example debounce: 5 means that there needs to be "5 seconds of silence" from the device, before combined messages is sent out.

This is handy for e.g. the WSDCGQ11LM which publishes humidity, temperature and pressure at the same time but as 3 different messages.

Don't configure debounce to be higher that sensors update interval as that would cause all the messages to be debouncer and messages won't be sent out at all.

debounce_ignore
Protects unique payload values of specified payload properties from overriding within debounce time. When setting e.g. debounce: 1 and debounce_ignore: - action every payload with unique action value will be published. This is handy for e.g. the E1744 which publishes multiple messages in short time period after one turn and debounce option without debounce_ignore publishes only last payload with action rotate_stop. On the other hand debounce: 1 with debounce_ignore: - action will publish all unique action messages, at least two ( e.g. action: rotate_left and action: rotate_stop)

throttle
Throttle processing of messages from this device. When setting e.g. throttle: 10 the first message from the device is processed but all other messages within the next 10 seconds are ignored. Be careful when using this option, unlike debounce that can ignore some attributes, this will drop the entire message.

debounce option has priority over throttle; if both are present for one device, only debounce will have any effect.

Setting this option reduces the number of MQTT messages sent for a particular device. This is directly linked to how high the option is set. When used on misbehaving devices with proper values, it can drastically reduce the size of external databases that store history (like Home Assistant), and yet have little to no impact on the quality of said history.

Some ambient sensors like TS0601_air_quality_sensor and some water level sensors, among others, are known to benefit from this option

filtered_attributes
Allows preventing certain attributes from being published. When a device would e.g. publish {"temperature": 10, "battery": 20} and you set filtered_attributes: ["battery"] it will publish {"temperature": 10}.

filtered_cache
Allows preventing certain attributes from ending up in the cache. This prevents attributes from being published when the value did not change.

optimistic
The optimistic mode is a feature that influences how the state of a device is handled in the absence of updates. When optimistic mode is enabled for a device and the last sent command was successful, it updates the device state accordingly, even before receiving confirmation from the device itself (default true).

Enabled: If you send a command to turn on a light and the command was successful, for example, Zigbee2MQTT will immediately update its internal state to reflect that the light is on. If the command fails, the state is not updated.

Disabled: Zigbee2MQTT will only update its internal state after the device reports the new state, regardless of whether the command was successful or not.

filtered_optimistic
Same as the filtered_attributes option but only applies to the optimistic published attributes. Has no effect when optimistic: false is set. Example: filtered_optimistic: ["color_mode", "color"].

icon
Allows to override the device icon (image) shown on the frontend, should be one of:

• A path to an image e.g. device_icons/my-device.png, note that the image must be inside the device_icons directory next to the Zigbee2MQTT configuration.yaml. Other directories are not allowed.
• A full URL link to an image, e.g. https://SOME.SITE/MODEL123.jpg.

Specific device options

Some Zigbee devices like the RTCGQ11LM supports some special attributes. To see if your device has device type specific configuration, visit the device page by going to Supported devices and clicking on the model number.

In the above example occupancy_timeout and no_occupancy_since are device specific options.

Default values

You can set default values which are applied to all devices if the devices does not explicitly set the value in the device block. You can also set defaults for device-specific options.

device_options:
    retain: true
    occupancy_timeout: 120
    no_occupancy_since: [10, 600]

Groups

Groups can be defined in the configuration.yaml, devices can be added to the group via the frontend or MQTT. See the groups guide for more information.

groups:
    '1':
        friendly_name: Kitchen lights
        # Optional: Retain messages (true/false) (default: false)
        retain: false
        # Optional: Default transition to be used when e.g. changing brightness (in seconds) (default: 0)
        transition: 2
        # Optional: Change group state when one of the devices in it changes state, see 'State changes' below (default: true)
        optimistic: true

Extract config to separate files

Usually devices and groups are specified as objects within the configuration.yaml but it is also possible to extract the configuration into separate files.

# Define the files which contains the configs
devices: devices.yaml
groups: groups.yaml

# devices.yaml
'0x00158d0001d82999':
    friendly_name: 'my_occupancy_sensor'

# groups.yaml
'1':
    friendly_name: group_1
    devices:
        - 0x00158d0001d82999