How to support new devices #

Zigbee2MQTT uses zigbee-herdsman-converters to parse messages to and from devices.

This page will guide you through the process of adding support for new devices to zigbee-herdsman-converters.

In case you require any help feel free to create an issue.

Before starting, first check if you devices is not already supported in the Zigbee2MQTT dev branch! This can be done by searching on your Zigbee model (see step 1 below) in any of the files here.

Instructions #

1. Pairing the device with Zigbee2MQTT #

The first step is to pair the device with Zigbee2MQTT. It should be possible to pair your unsupported device out of the box because Zigbee2MQTT can pair with any zigbee device. You need to find out how to bring your device into pairing mode, most of the time via a factory reset.

Once you successfully paired the device you will see something like:

Zigbee2MQTT:info  2019-11-09T12:19:56: Successfully interviewed '0x00158d0001dc126a', device has successfully been paired
Zigbee2MQTT:warn  2019-11-09T12:19:56: Device '0x00158d0001dc126a' with Zigbee model 'lumi.sens' and manufacturer name 'some_name' is NOT supported, please follow https://www.zigbee2mqtt.io/how_tos/how_to_support_new_devices.html

NOTE: Make sure that permit_join: true is set in configuration.yaml otherwise new devices cannot join the network.

2. Adding your device #

The next step is to create an external converter file. This file has to be created next to the configuration.yaml, in this example we will call it WSDCGQ01LM.js (make sure it ends with .js). In order to provide support for e.g. the lumi.sens from step 1 we would add the following to this file:

const fz = require('zigbee-herdsman-converters/converters/fromZigbee');
const tz = require('zigbee-herdsman-converters/converters/toZigbee');
const exposes = require('zigbee-herdsman-converters/lib/exposes');
const reporting = require('zigbee-herdsman-converters/lib/reporting');
const extend = require('zigbee-herdsman-converters/lib/extend');
const e = exposes.presets;
const ea = exposes.access;

const definition = {
    zigbeeModel: ['lumi.sens'], // The model ID from: Device with modelID 'lumi.sens' is not supported.
    model: 'WSDCGQ01LM', // Vendor model number, look on the device for a model number
    vendor: 'Xiaomi', // Vendor of the device (only used for documentation and startup logging)
    description: 'MiJia temperature & humidity sensor', // Description of the device, copy from vendor site. (only used for documentation and startup logging)
    fromZigbee: [], // We will add this later
    toZigbee: [], // Should be empty, unless device can be controlled (e.g. lights, switches).
    exposes: [e.battery(), e.temperature(), e.humidity()], // Defines what this device exposes, used for e.g. Home Assistant discovery and in the frontend
};

module.exports = definition;

If your device is advertised as “Tuya compatible” and/or requires Tuya gateway/app to operate look here for additional info

Now set the Zigbee2MQTT log_level to debug and enable the external converter by adding the following to your Zigbee2MQTT configuration.yaml.

advanced:
  log_level: debug
external_converters:
  - WSDCGQ01LM.js

Once finished, restart Zigbee2MQTT and trigger some actions on the device. You will see messages like:

Zigbee2MQTT:debug  2019-11-09T12:24:22: No converter available for 'WSDCGQ01LM' with cluster 'msTemperatureMeasurement' and type 'attributeReport' and data '{"measuredValue":2512}'

In case your device is not reporting anything, it could be that this device requires additional configuration. This can be done by adding a configure: section. It may help to look at similar devices.

If your device reports anything with ‘manuSpecificTuya’ then it’s a “Tuya compatible” device and additional instructions for adding those are here.

Some basic external converter examples:

3. Adding converter(s) for your device #

In order to parse the messages of your Zigbee device we need to add converter(s). Probably existing converters can be reused, those can be found here.

For E.G. the following message we could use the already existing fz.temperature converter:

Zigbee2MQTT:debug  2019-11-09T12:24:22: No converter available for 'WSDCGQ01LM' with cluster 'msTemperatureMeasurement' and type 'attributeReport' and data '{"measuredValue":2512}'

Now update your external converter.

const fz = require('zigbee-herdsman-converters/converters/fromZigbee');
const tz = require('zigbee-herdsman-converters/converters/toZigbee');
const exposes = require('zigbee-herdsman-converters/lib/exposes');
const reporting = require('zigbee-herdsman-converters/lib/reporting');
const extend = require('zigbee-herdsman-converters/lib/extend');
const e = exposes.presets;
const ea = exposes.access;

const definition = {
    zigbeeModel: ['lumi.sens'],
    model: 'WSDCGQ01LM',
    vendor: 'Xiaomi',
    description: 'MiJia temperature & humidity sensor',
    fromZigbee: [fz.temperature], // <-- added here
    toZigbee: [],
    exposes: [e.battery(), e.temperature(), e.humidity()],
};

module.exports = definition;

Repeat until your device does not produce any more log messages like: 2018-5-1 18:19:41 WARN No converter available for 'WSDCGQ01LM' with....

In case you need to add custom converters you can find an external converter example here.

3.1 Retrieving color temperature range (only required for lights which support color temperature) #

If your device is a light and supports color temperature you need to define the color temperature range. This range indicates the minimum and maximum color temperature value the light supports. This can be retrieved from the light by sending to zigbee2mqtt/DEVICE_FRIENDLY_NAME/set with payload {"read": {"cluster": "lightingColorCtrl", "attributes": ["colorTempPhysicalMin", "colorTempPhysicalMax"]}}

The result will be logged to the Zigbee2MQTT log, e.g.

Zigbee2MQTT:info  2021-03-21 21:10:40: Read result of 'lightingColorCtrl': {"colorTempPhysicalMin":153,"colorTempPhysicalMax":500}

In the above example set colorTempRange to {colorTempRange: [153, 500]}, e.g.:

const definition = {
    zigbeeModel: ['myZigbeeModel'],
    model: 'myModel',
    vendor: 'myVendor',
    description: 'Super bulb',
    extend: extend.light_onoff_brightness_colortemp({colorTempRange: [153, 500]}), // <---
},

In case none of the existing converters fit you can add custom ones, external converter example for this can be found here.

4. (Optional) Add device to zigbee2mqtt.io documentation #

This step is optional and can be skipped as the device page will automatically be generated on the next Zigbee2MQTT release. Only do it when you e.g. want to a specific pairing instructions for this device.

  1. Clone zigbee2mqtt.io
  2. Add a markdown file for your device to docs/devices, use the model property of your definition as the filename.
  3. Add a picture (.jpg, 150x150) to docs/images/devices and link it in file of the previous step.
  4. Create a Pull Request to zigbee2mqtt.io.

On the next release of Zigbee2MQTT, the documentation will be updated and your device file will be linked in docs/information/supported_devices.md automatically.

5. Done! #

Now it’s time to submit a pull request to zigbee-herdsman-converters so this device is supported out of the box by Zigbee2MQTT. This can be done by adding the definition to the vendor file of your device. :smiley: