Recently, I set up Home Assistant for all my home automation endeavors. To connect it to my Zigbee devices, I use Zigbee2MQTT. This works great so far except for one LED controller that is detected as a different model and does not support full control.
The LED Controller
I am using a ISOLed 114729 Zigbee 3.0 5-channel LED controller that can be configured into four different modes (DIM, CCT, RGBW, RGB+CCT). For simple white LED strips I use it in dimmer mode and for RGBWW LED strips I use them in RGB+CCT mode. The controller is a white-labelled Sunricher SR-ZG1029-5C controller.
My controller reports as a Zigbee model of HK-ZD-RGBCCT-A in RGB+CCT mode and as HK-ZD-DIM-A in DIM mode.
In DIM mode there is only one LED channel with adjustable brightness. Zigbee2MQTT detects it as Sunricher SRP-ZG9105-CC device (reports as Zigbee model HK-ZD-DIM-A). This configuration works, so no need to fix anything here.
In RGB+CCT mode there are 5 LED channels: RGB, cold white, and warm white. This is where Zigbee2MQTT detects it as Iluminize 511.000 model as its configuration uses the reported Zigbee model HD-ZD-RGBCCT-A.
Unforunately, the LED controller was recognized as a Iluminize 511.000 model. Apparently, both the ISOLed and the Iluminize are white-labelled Sunricher devices. The configuration that ships with Zigbee2MQTT for HK-ZD-RGBCCT-A only addresses the RGB endpoint of the two available endpoints. So I am not able to switch or adjust the two white LED channels.
To fix that, I need to create a new configuration for the model HD-ZD-RGBCCT-A that supports both endpoints, and not just one. So I started to research how I could customize Zigbee2MQTT for my use.
Configuration
I started using Zigbee2MQTT only a couple of weeks ago. So the most time consuming task was to get up to speed with how it works and how to add or modify device configurations.
The documentation on how to support new devices proved to
be a good starting point. There I learned that putting a custom device configuration
next to the configuration.yaml file and adding a reference to the configuration
will make sure that it has precedence over the built-in configurations.
external_converters:
- sr-zg1029-5c.js
Also, Zigbee2MQTT uses the zigbee-herdsman-converters project to do manage Zigbee devices. So I started to dig around the device configurations there to see how other devices are configured. In particular, I had a look at the Iluminize 511.000 device that was detected.
I noticed that the Iluminize configuration extended from the light_onoff_brightness_colortemp_color()
configuration in lib/extends.js. This was a good start.
The biggest challenge was to find out how to configure two endpoints. Most light configurations I found only had one endpoint and did not expose them. I found some remotes and multi-switches that had several endpoints.
It took me the better part of a day to dig through all the configurations and to get a clue how to use presets with custom endpoints. After some trial-and-error I found this solution that does work:
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: ['HK-ZD-RGBCCT-A'],
// https://www.sunricher.com/dim-cct-rgbw-rgb-cct-4-in-1-constant-voltage-zigbee-led-controller-sr-zg1029-5c.html
// The controller can be put into different modes using DIP switches: DIM, CCT, RGBW, and RGB+CCT
// Also sold as ISOLed Model 114729: https://www.isoled.shop/de/zigbee-30-pwm-dimmer-fuer-led-flexbaenderspots-5-kanal-12-24v-dc-5x4a_114729.html
model: 'SR-ZG1029-5C',
vendor: 'Sunricher',
whiteLabel: [{vendor: 'Sunricher', model: 'SR-ZG1029-5C'}],
description: 'DIM CCT RGBW RGB+CCT 4-in-1 Constant Voltage Zigbee LED Controller',
extend: extend.light_onoff_brightness_colortemp_color(),
exposes: [
e.light_brightness_colortemp_colorxy().withEndpoint('l1'),
e.light_brightness_colortemp().withEndpoint('l2')
],
endpoint: (device) => {
return {'l1' : 1, 'l2' : 2 };
},
meta: {multiEndpoint: true},
};
module.exports = definition;
As you can see, I also extend from light_onoff_brightness_colortemp_color().
It has all the Zigbee clusters configured to make the LED controller work. The
major difference to the existing Iluminize model is that I define two endpoints
and configure them with presets in exposes. Also, the RGB light mode needs to
be CIE X/Y (colorxy) rather than HS (hue / saturation).
In Zigbee2MQTT the light shows with two endpoints l1 and l2 now. The endpoint l1 allows to switch the RGB channels, adjust the brightness, the color temperature, and the RGB color. The endpoint l2 allows to switch the white LEDs and adjust their brightness and color temperature.
In Home Assistant the controller shows as single device with two entities. So I need to switch and configure the RGB and white channels separately.