External converters

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

External converters provide a way to test support for new devices, they work identically to internal converters.

External converters are stored in the external_converters folder (at the same level in the file system as the Zigbee2MQTT configuration.yaml file). They have to export a JavaScript Object or Array of Object matching the type DefinitionWithExtend. Refer to existing converters to get familiar with the framework.

TIP

Once your converter is ready, open a pull request so it can be integrated into Zigbee2MQTT for all to use. Once the new Zigbee2MQTT version is released, you can just delete the external converter.

TIP

The easiest way to develop is by using the external converter development environment

Example:

File: external_converters/my-first-converter.mjs

import {temperature, humidity, battery} from 'zigbee-herdsman-converters/lib/modernExtend';

export default {
    zigbeeModel: ['lumi.sens'],
    model: 'WSDCGQ01LM',
    vendor: 'Xiaomi',
    description: 'MiJia temperature & humidity sensor',
    extend: [temperature(), humidity(), battery()],
};

More examples

Sensor using modern extends (same as above)
Sensor using non modern extends
Bulb (light)
Plug (switch)
Advanced example
Definitions of already supported devices can be found here. It may help to look at devices from the same vendor or type.

Using modern extends

The entire API can be found here.

Using non modern extends

The most common API endpoints are accessible from the following imports:

import * as m from 'zigbee-herdsman-converters/lib/modernExtend';
import * as fz from 'zigbee-herdsman-converters/converters/fromZigbee';
import * as tz from 'zigbee-herdsman-converters/converters/toZigbee';
import * as exposes from 'zigbee-herdsman-converters/lib/exposes';
import * as reporting from 'zigbee-herdsman-converters/lib/reporting';
import * as ota from 'zigbee-herdsman-converters/lib/ota';
import * as utils from 'zigbee-herdsman-converters/lib/utils';
import * as globalStore from 'zigbee-herdsman-converters/lib/store';

// exposes.presets
// exposes.access

To optimize imports, you can import only the required items instead. For example:

import {onOff} from 'zigbee-herdsman-converters/lib/modernExtend';
import {presets, access} from 'zigbee-herdsman-converters/lib/exposes';

Converters list

When Zigbee2MQTT starts it publishes zigbee2mqtt/bridge/converters with payload [{"name": "my-first-converter.js": "code": <HERE COMES YOUR CONVERTER CODE>}] containing all the converters loaded from the file system. The same message is also published when a converter changes at runtime (from one of the below actions), with the appropriately updated payload.

TIP

Via the Zigbee2MQTT front end in Home Assistant, you can add or update external converters via Settings > Dev console > External converters.

Save converter

To save a converter at runtime, send a message to zigbee2mqtt/bridge/request/converter/save with payload {"name": "my-first-converter.js", "code": <HERE COMES YOUR CONVERTER CODE>}. The code will be saved in external_converters in the file with the given name.

Remove converter

To remove a converter at runtime, send a message to zigbee2mqtt/bridge/request/converter/remove with payload {"name": "my-first-converter.js"}. The file will be deleted from external_converters.