How to support new devices

Zigbee2mqtt uses zigbee-shepherd-converters to parse messages to and from devices. This was originally part of Zigbee2mqtt but has been moved to a separate library so that other projects can also take advantage of this.

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

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

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 times via a factory reset. For some vendors this is already documented here.

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

2018-5-1 18:06:41 INFO New device with address 0x00158d0001b79111 connected!
2018-5-1 18:06:42 WARN Device with modelID 'lumi.sens' is not supported.
2018-5-1 18:06:42 WARN Please see: https://koenkk.github.io/zigbee2mqtt/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 the to add an entry of your device to node_modules/zigbee-shepherd-converters/devices.js. In order to provide support for E.G. the lumi.sens from step 1 you would add:

{
    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)
    supports: 'temperature and humidity', // Actions this device supports (only used for documentation)
    fromZigbee: [], // We will add this later
    toZigbee: [], // Should be empty, unless device can be controlled (e.g. lights, switches).
},

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

2018-5-1 18:19:41 WARN No converter available for 'WSDCGQ01LM' with cid 'msTemperatureMeasurement' and type 'attReport'
2018-5-1 18:19:41 WARN Please create an issue on https://github.com/Koenkk/zigbee2mqtt/issues with this message.

In case your device is not reporting anything, it could be that this device requires additional configure. This can be done by adding a configure: section, examples. In case your device is a contact or motion sensor, it could be that this is an IAS device. Example of an IAS configure: section can be found here.

3. Adding converter(s) for your device

In order to parse the messages of your zigbee device we need to add converter(s) to node_modules/zigbee-shepherd-converters/converters/fromZigbee.js.

Before adding new converters, please check if you can reuse any existing one.

For E.G. the following message

2018-5-1 18:19:41 WARN No converter available for 'WSDCGQ01LM' with cid 'msTemperatureMeasurement' and type 'attReport'
2018-5-1 18:19:41 WARN Please create an issue on https://github.com/Koenkk/zigbee2mqtt/issues with this message.

You would add to node_modules/zigbee-shepherd-converters/converters/fromZigbee.js:

xiaomi_temperature: {
    cid: 'msTemperatureMeasurement',
    type: 'attReport',
    convert: (model, msg, publish, options) => {
        return {temperature: parseFloat(msg.data.data['measuredValue']) / 100.0};
    },
},

To find out the structure of the message and which attributes you need to grab from the message you could first start with:

xiaomi_temperature: {
    cid: 'msTemperatureMeasurement',
    type: 'attReport',
    convert: (model, msg, publish, options) => {
        console.log(msg.data)
    },
},

Now update your device in node_modules/zigbee-shepherd-converters/devices.js with the new converter.

{
    zigbeeModel: ['lumi.sens'],
    model: 'WSDCGQ01LM',
    vendor: 'Xiaomi',
    description: 'MiJia temperature & humidity sensor ',
    supports: 'temperature and humidity',
    fromZigbee: [fz.xiaomi_temperature],  # <-- added here
    toZigbee: [],
},

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 cid 'msTemperatureMeasurement' and type 'attReport'
2018-5-1 18:19:41 WARN Please create an issue on https://github.com/Koenkk/zigbee2mqtt/issues with this message.

4. (Optional) Add home assistant configuration for your device

In order to automatically discover this device in home assistant your device needs to be added to mapping in lib/extension/homeassistant.js.

5. Done!

Now it's time to submit a pull request to zigbee-shepherd-converters so this device is supported out of the box by zigbee2mqtt. 😃

5.5 KiB Raw Blame History