Support new devices

Zigbee2MQTT uses zigbee-herdsman-convertersopen in new window to parse messages to and from devices.

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

In case you require any help feel free to create an issueopen in new window.

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 hereopen in new window.

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/support_new_devices.html
1
2

TIP

Make sure that joining is enabled, 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;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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
1
2
3
4

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}'
1

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 devicesopen in new window.

TIP

If your device is advertised as TuYa compatible or reports anything with manuSpecificTuya additional instructions for adding your device can be found 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 hereopen in new window.

For e.g. the following message we could use the already existing fz.temperature converteropen in new window:

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

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;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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 hereopen in new window.

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}
1

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]}), // <---
},
1
2
3
4
5
6
7

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

4. Add device picture to zigbee2mqtt.io documentation

To make sure a picture is available for this device on the supported devices page and in the frontend:

  1. Clone zigbee2mqtt.ioopen in new window
  2. Optional: 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 public/images/devices and link it in file of the previous step.
  4. Create a Pull Request to zigbee2mqtt.ioopen in new window.

On the next release of Zigbee2MQTT, the documentation will be updated and your device file will be linked in ../../supported-devices.md automatically.

Done!

Now it's time to submit a pull request to zigbee-herdsman-convertersopen in new window so this device is supported out of the box by Zigbee2MQTT. This can be done by adding the definition to the vendor fileopen in new window of your device. 😃