Binding example

Can someone please provide an example of how to bind lets say a hue dimmer switch with a hue bulb through MQTT?

I have this so far:
mosquitto_pub -u xxxx -P xxxxx -m zigbee2mqtt/bridge/bind/sensor_dimmer (how do I add the target?)

Hi,

I just set up a group of 6 Hue light bulbs (model LCT001 and model LWB004) with a Hue remote dimmer (model RWL021 - 324131092621) together with zigbee2mqtt.

I run mqtt and zigbee2mqtt (koenkk/zigbee2mqtt:latest-dev 1.11.x) in docker containers.

I started with creating a group for my Hue blubs using this instructions:

  • Created a group in my zigbee2mqtt configuration.yaml file.
  • Added the Hue light blubs.
  • Tested the group.

Then I just followed the zigbee2mqtt pairing and binding instructions for Hue remotes:

  • Factory resetted the Hue dimmer switch by pressing and holding the setup button on the back for 10 seconds.
  • Restarted the Hue dimmer switch by holding all 4 buttons of the Hue dimmer switch. You can let go when the light on the front flashes red/green briefly.
  • Renamed the Hue remote friendlyname to something nice.
  • Binded the Hue remote to the Blub group.
  • Unbinded the Hue remote from the Coordinator

At first this looked very straight forward, but I when into some obstacles down the road. I will show in detail how I performed all the necessary steps.

Logging

During this action I had a terminal windows with the zigbee2mqtt logging open, to see what was happening. Since I start my docker containers using systemd, I used journalctl the look at te logging:

$ journalctl --unit zigbee2mqtt.service --follow

You can also look at other ways at the zigbee2mqtt logging, for example in a docker container like this:

$ # docker exec -it zigbee2mqtt tail -f data/log/2020-02-28.15-40-24/log.txt
debug 2020-02-29 10:46:40: Received Zigbee message from 'powerplug', type 'read', cluster 'genTime', data '["time"]' from endpoint 1 with groupID 0
debug 2020-02-29 10:46:40: No converter available for 'ZNCZ02LM' with cluster 'genTime' and type 'read' and data '["time"]'

In some cases it is useful to turn on debug logging: https://www.zigbee2mqtt.io/information/debug.html

My configuration.yaml

homeassistant: true
permit_join: true
mqtt:      
  base_topic: zigbee2mqtt
  server: 'mqtt://***.***.***.***'
  user: admin                 
  password: ***********
  reject_unauthorized: false
  include_device_information: true
serial:                  
  port: /dev/ttyACM0        
advanced:                
  network_key: *****************************
  pan_id: 0x165a
  ext_pan_id: ********************
  channel: 26
  cache_state: true
  log_level: debug
  last_seen: ISO_8601
  elapsed: false
  availability_timeout: 0
  availability_blacklist:
    - DEVICE_FRIENDLY_NAME
  report: true
  homeassistant_discovery_topic: homeassistant
  homeassistant_status_topic: hass/status
map_options:
  graphviz:
    colors:
      fill:
        enddevice: '#fff8ce'
        coordinator: '#e04e5d'
        router: '#4ea3e0'
      font:
        coordinator: '#ffffff'
        router: '#ffffff'
        enddevice: '#000000'
      line:
        active: '#009900'
        inactive: '#994444'
queue:
  delay: 250
  simultaneously: 5
device_options: null
devices: devices.yaml
groups: groups.yaml

My devices.yaml

(snipped)

'0x0017880100e10913':
  friendly_name: lamp1woonkamerachter
  retain: false
'0x0017880100e11f43':
  friendly_name: lamp2woonkamerachter
  retain: false
'0x00124b0003cdd8c9':
  friendly_name: lamp3woonkamerachter
  retain: false
'0x0017880100e4e5d3':
  friendly_name: lamp1woonkamervoor
  retain: false
'0x0017880100d52c7f':
  friendly_name: lamp2woonkamervoor
  retain: false
'0x0017880100d7bff7':
  friendly_name: lamp3woonkamervoor
  retain: false
'0x0017880110327073':
  friendly_name: dimmerwoonkamer

My groups.yaml

Be sure you create a group for your light blubs.
(snipped)

'3':
  friendly_name: woonkamerdimmergroep
  devices:
    - '0x0017880100d7bff7'
    - '0x0017880100d52c7f'
    - '0x0017880100e4e5d3'
    - '0x00124b0003cdd8c9'
    - '0x0017880100e11f43'
    - '0x0017880100e10913'

You can leave out the devices, we will add them later. Declare an empty device list like this:

'3':
  friendly_name: woonkamerdimmergroep
  devices: []

Pair Hue remote dimmer

press all four buttons on the remote for 10 sec and let go:

feb 29 09:06:23 zigbee2mqtt:info  2020-02-29 09:06:23: Device '0x0017880110327073' joined
feb 29 09:06:23 zigbee2mqtt:info  2020-02-29 09:06:23: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"device_connected","message":{"friendly_name":"0x0017880110327073"}}'
feb 29 09:06:23 zigbee2mqtt:info  2020-02-29 09:06:23: Starting interview of '0x0017880110327073'
feb 29 09:06:23 zigbee2mqtt:info  2020-02-29 09:06:23: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"pairing","message":"interview_started","meta":{"friendly_name":"0x0017880110327073"}}'
feb 29 09:06:25 zigbee2mqtt:info  2020-02-29 09:06:25: Received Zigbee message from '0x0017880110327073', type 'attributeReport', cluster 'genPowerCfg', data '{"batteryPercentageRemaining":200}' from endpoi
nt 2 with groupID 0
feb 29 09:06:35 zigbee2mqtt:error 2020-02-29 09:06:35: Failed to interview '0x0017880110327073', device has not successfully been paired
feb 29 09:06:35 zigbee2mqtt:info  2020-02-29 09:06:35: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"pairing","message":"interview_failed","meta":{"friendly_name":"0x0017880110327073"}}'

As you can see, the device has not successfully been paired! At first I had not noticed that, but I saw this in the logging when I pressed one of the remote buttons:

feb 29 09:23:39 zigbee2mqtt:warn  2020-02-29 09:23:39: Received message from unsupported device with Zigbee model 'undefined'
feb 29 09:23:39 zigbee2mqtt:warn  2020-02-29 09:23:39: Please see: https://www.zigbee2mqtt.io/how_tos/how_to_support_new_devices.html.
feb 29 09:23:40  zigbee2mqtt:debug 2020-02-29 09:23:40: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"typ
e":1,"unknown2":1,"time":72}' from endpoint 2 with groupID 0       

To fix this I re-paired the remote and after directly after I let go the four buttons I keep on pressing one of the buttons. This ensures the remote not to go to sleep and become unreachable during paring. This time it went successful:

feb 29 09:30:10 zigbee2mqtt:debug 2020-02-29 09:30:10: Received Zigbee message from 'dimmerwoonkamer', type 'readResponse', cluster 'genBasic', data '{"swBuildId":"5.45.1.16265"}' from endpoint 1 with groupID 0
feb 29 09:30:10 zigbee2mqtt:debug 2020-02-29 09:30:10: No converter available for '324131092621' with cluster 'genBasic' and type 'readResponse' and data '{"swBuildId":"5.45.1.16265"}'
feb 29 09:30:10 zigbee2mqtt:debug 2020-02-29 09:30:10: Received Zigbee message from 'powerplug', type 'readResponse', cluster 'genBasic', data '{"swBuildId":"5.45.1.16265"}' from endpoint 1 with groupID 7979
feb 29 09:30:10 zigbee2mqtt:info  2020-02-29 09:30:10: Successfully interviewed 'dimmerwoonkamer', device has successfully been paired
feb 29 09:30:10 zigbee2mqtt:info  2020-02-29 09:30:10: Device 'dimmerwoonkamer' is supported, identified as: Philips Hue dimmer switch (324131092621)
feb 29 09:30:10 zigbee2mqtt:info  2020-02-29 09:30:10: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"pairing","message":"interview_successful","meta":{"friendly_name":"dimmerwoonkamer","model":"324131092621","vendor":"Philips","description":"Hue dimmer switch","supported":true}}'
feb 29 09:30:10 zigbee2mqtt:info  2020-02-29 09:30:10: Configuring 'dimmerwoonkamer'

Publish on mqtt topics

You need some mqtt client to publish to mqtt topics. I use the mqtt client with in the zigbee to mqtt container. You can also use other clients or the Home assistant GUI: https://your-home-assistant:8123/developer-tools/mqtt

$ docker exec -it zigbee2mqtt /bin/sh

On the zigbee2mqtt docker container command line I can execute mqtt stuff:

/app # /app/node_modules/.bin/mqtt publish --help                                                                                                                                                                                     [1/1867]
Usage: mqtt publish [opts] topic [message]                                                                                                                                                                                                    

Available options:

  -h/--hostname HOST    the broker host
  -p/--port PORT        the broker port
  -i/--client-id ID     the client id
  -q/--qos 0/1/2        the QoS of the message
  -t/--topic TOPIC      the message topic
  -m/--message MSG      the message body
  -r/--retain           send a retained message
  -s/--stdin            read the message body from stdin
  -M/--multiline        read lines from stdin as multiple messages 
  -u/--username USER    the username
  -P/--password PASS    the password
  -C/--protocol PROTO   the protocol to use, 'mqtt',
                        'mqtts', 'ws' or 'wss'
  --key PATH            path to the key file
  --cert PATH           path to the cert file
  --ca PATH             path to the ca certificate
  --insecure            do not verify the server certificate
  --will-topic TOPIC    the will topic
  --will-payload BODY   the will message
  --will-qos 0/1/2      the will qos
  --will-retain         send a will retained message 
  -H/--help             show this

  /app # /app/node_modules/.bin/mqtt subscribe --help
    Usage: mqtt subscribe [opts] [topic]

  Available options:

      -h/--hostname HOST    the broker host
      -p/--port PORT        the broker port
      -i/--client-id ID     the client id
      -q/--qos 0/1/2        the QoS of the message
      --no-clean            do not discard any pending message for
                            the given id
      -t/--topic TOPIC      the message topic
      -k/--keepalive SEC    send a ping every SEC seconds
      -u/--username USER    the username
      -P/--password PASS    the password
      -l/--protocol PROTO   the protocol to use, 'mqtt',
                            'mqtts', 'ws' or 'wss'
      --key PATH            path to the key file
      --cert PATH           path to the cert file
      --ca PATH             path to the ca certificate
      --insecure            do not verify the server certificate
      --will-topic TOPIC    the will topic
      --will-message BODY   the will message
      --will-qos 0/1/2      the will qos
      --will-retain         send a will retained message
      -v/--verbose          print the topic before the message
      -H/--help             show this

Add Hue light blubs to group.

see: zigbee2mqtt/bridge/group/[friendly_name]/add [friendly_name]

As I had shown above, I had created a goup called “woonkamerdimmergroep” in my groups.yaml. Now I can add my 6 light blubs to the groups using:

$ /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/group/woonkamerdimmergroep/add -m lamp3woonkamervoor
$ /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/group/woonkamerdimmergroep/add -m lamp2woonkamervoor
$ /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/group/woonkamerdimmergroep/add -m lamp1woonkamervoor
$ /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/group/woonkamerdimmergroep/add -m lamp1woonkamerachter
$ /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/group/woonkamerdimmergroep/add -m lamp2woonkamerachter
$ /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/group/woonkamerdimmergroep/add -m lamp3woonkamerachter

Change group state

see: zigbee2mqtt/[FRIENDLY_NAME]/set
Now I can also change the state of the group and manage all the light blubs in the group:

  $ /app # /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/woonkamerdimmergroep/set -m '{   "state": "ON", "brightness": "62" }'
  $ /app # /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/woonkamerdimmergroep/set -m '{   "state": "OFF", "brightness": "100" }'
  $ /app # /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/woonkamerdimmergroep/set -m '{   "state": "ON", "brightness": "200" }'

Listen / subcribe to group

see: zigbee2mqtt/[FRIENDLY_NAME]
I now can also subscribe to this group and follow changes:

$ /app/node_modules/.bin/mqtt subscribe -h IPADDRESS -t zigbee2mqtt/woonkamerdimmergroep  -u admin -P PASSWORD -v                                                                                                                 
        zigbee2mqtt/woonkamerdimmergroep {"state":"OFF","brightness":106,"color_temp":323,"color":{"x":0.4306614419521,"y":0.401822525685539}}                                                                                                         
        zigbee2mqtt/woonkamerdimmergroep {"state":"ON","brightness":106,"color_temp":323,"color":{"x":0.4306614419521,"y":0.401822525685539}}                                                                                                         
        zigbee2mqtt/woonkamerdimmergroep {"state":"ON","brightness":72,"color_temp":323,"color":{"x":0.4306614419521,"y":0.401822525685539}}

List groups and group memberships

see: zigbee2mqtt/bridge/config/groups
If you want to check which light blubs belong to which groups, you can publish this:

$ /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/config/groups -m “”

The result will be shown in the zigbee2mqtt logging:

feb 28 22:47:28 zigbee2mqtt:info  2020-02-28 22:47:28: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"groups","message":[{"optimistic":true,"devices":["0x0017880100e10913","0x0017880100e11f
43","0x00124b0003cdd8c9"],"friendly_name":"woonkamerachtergroep","ID":1},{"optimistic":true,"devices":["0x0017880100e4e5d3","0x0017880100d52c7f","0x0017880100d7bff7"],"friendly_name":"woonkamervoorgroep","ID":2},{"optimistic":true,"device
s":["0x0017880100d7bff7","0x0017880100d52c7f","0x0017880100e4e5d3","0x00124b0003cdd8c9","0x0017880100e11f43","0x0017880100e10913"],"friendly_name":"woonkamerdimmergroep","ID":3}]}'  

List devices

see: zigbee2mqtt/bridge/config/devices/get
If you want to check which zigbee devices are registered in your network, you can publish this:

/app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/config/devices -m ""

The result will be shown in the zigbee2mqtt logging (snipped):

feb 28 22:47:48 zigbee2mqtt:info  2020-02-28 22:47:48: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"devices","message":[{"ieeeAddr":"0x00124b001ca5ea35","type":"Coordinator","networkAddress":0,"friendly_name":"Coordinator","softwareBuildID":"zStack3x0","dateCode":"20191106","lastSeen":1582926468246},{"ieeeAddr":"0x00158d00027257cd","type":"EndDevice","networkAddress":20261,"model":"WSDCGQ11LM","friendly_name":"omgevingssensorkamerstijn","manufacturerID":4151,"manufacturerName":"LUMI","powerSource":"Battery","modelID":"lumi.weather","hardwareVersion":30,"softwareBuildID":"3000-0001","dateCode":"20161129","lastSeen":1582926426421},{"ieeeAddr":"0x00158d00036b1af7","type":"EndDevice","networkAddress":36456,"model":"WSDCGQ11LM","friendly_name":"omgevingssensorzolder","manufacturerID":4151,"manufacturerName":"LUMI","powerSource":"Battery","modelID":"lumi.weather","hardwareVersion":30,"softwareB
uildID":"3000-0001","dateCode":"20161129","lastSeen":1582926124362},{"ieeeAddr":"0x00158d0002584585","type":"EndDevice","networkAddress":49716,"model":"RTCGQ11LM","friendly_name":"bewegingssensorstudeerkamer","manufacturerID":4151,"manufa
cturerName":"LUMI","powerSource":"Battery","

Rename remote ID to a friendly name

see: zigbee2mqtt/bridge/config/rename
It is useful when your remote has a friendly name. This is how you rename the friendly name:

/app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/config/rename -m '{"old": "0x0017880110327073", "new": "dimmerwoonkamer"}'

You should see something like this in the mqtt logging:

feb 28 22:55:12 zigbee2mqtt:debug 2020-02-28 22:55:12: Received MQTT message on 'zigbee2mqtt/bridge/config/rename' with data '{"old": "0x0017880110327073", "new": "dimmerwoonkamer"}'
feb 28 22:55:12 zigbee2mqtt:info  2020-02-28 22:55:12: Successfully renamed - 0x0017880110327073 to dimmerwoonkamer
feb 28 22:55:12 zigbee2mqtt:info  2020-02-28 22:55:12: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"device_renamed","message":{"from":"0x0017880110327073","to":"dimmerwoonkamer"}}'

Also notice the the friendly name in your device.yaml is changed!

Bind Hue remote dimmer to group

see: zigbee2mqtt/bridge/bind/[friendly_name]
To prevent that the remote is asleep (and unreachable) you must press (and hold!) one of the remote buttons during this procedure.

# /app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/bind/dimmerwoonkamer -m woonkamerdimmergroep

This would look like this in the logging:

feb 28 23:18:30 zigbee2mqtt:debug 2020-02-28 23:18:30: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"type":1,"unknown2":0,"time":24}' from endpoint 2 with groupID 0
feb 28 23:18:31 zigbee2mqtt:debug 2020-02-28 23:18:31: Received MQTT message on 'zigbee2mqtt/bridge/bind/dimmerwoonkamer' with data 'woonkamerdimmergroep' 
feb 28 23:18:31 zigbee2mqtt:debug 2020-02-28 23:18:31: binding cluster 'genOnOff' from 'dimmerwoonkamer' to 'woonkamerdimmergroep'                                                                            
feb 28 23:18:31 zigbee2mqtt:debug 2020-02-28 23:18:31: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"type":1,"unknown2":0,"time":32}' from endpoint 2 with groupID 0   
feb 28 23:18:32 zigbee2mqtt:debug 2020-02-28 23:18:32: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"type":1,"unknown2":0,"time":40}' from endpoint 2 with groupID 0  
feb 28 23:18:33 zigbee2mqtt:debug 2020-02-28 23:18:33: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"type":1,"unknown2":0,"time":48}' from endpoint 2 with groupID 0
feb 28 23:18:33 zigbee2mqtt:info  2020-02-28 23:18:33: Successfully bound cluster 'genOnOff' from 'dimmerwoonkamer' to 'woonkamerdimmergroep'                                                                 
feb 28 23:18:33 zigbee2mqtt:info  2020-02-28 23:18:33: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"device_bind","message":{"from":"dimmerwoonkamer","to":"woonkamerdimmergroep","cluster":"genOnOff"}}' 
feb 28 23:18:33 zigbee2mqtt:debug 2020-02-28 23:18:33: binding cluster 'genLevelCtrl' from 'dimmerwoonkamer' to 'woonkamerdimmergroep'                                                                        
feb 28 23:18:33 zigbee2mqtt:info  2020-02-28 23:18:33: Successfully bound cluster 'genLevelCtrl' from 'dimmerwoonkamer' to 'woonkamerdimmergroep'                                                             
feb 28 23:18:33 zigbee2mqtt:info  2020-02-28 23:18:33: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"type":"device_bind","message":{"from":"dimmerwoonkamer","to":"woonkamerdimmergroep","cluster":"genLevelCtrl"}}'                             
feb 28 23:18:33 zigbee2mqtt:debug 2020-02-28 23:18:33: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"type":1,"unknown2":0,"time":56}' from endpoint 2 with groupID 0  

Now the remote is bind the the light blubs group, but it in NOT working yet. You need to unbind the remote from the coordinator.

Unbind remote from coordinator

see: zigbee2mqtt/bridge/unbind/[friendly_name]
Last step is to unbind the remote from the coordinator.

/app/node_modules/.bin/mqtt publish -h IPADDRESS -u admin -P PASSWORD -v -t zigbee2mqtt/bridge/unbind/dimmerwoonkamer -m Coordinator

note that people had issues with unbinding the coordinator spelled with a ‘c’ or ‘C’, see: https://github.com/Koenkk/zigbee2mqtt/issues/2100

Again press and hold one of the buttons of the remote, before unbinding it, otherwise the remote can not be reached!

feb 29 09:46:16 zigbee2mqtt:debug 2020-02-29 09:46:16: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"type":1,"unknown2":0,"time":8}' from endpoint 2 with groupID 0 
feb 29 09:46:17 zigbee2mqtt:debug 2020-02-29 09:46:17: Received MQTT message on 'zigbee2mqtt/bridge/unbind/dimmerwoonkamer' with data 'Coordinator'
feb 29 09:46:17 zigbee2mqtt:debug 2020-02-29 09:46:17: unbinding cluster 'genOnOff' from 'dimmerwoonkamer' to 'Coordinator'
feb 29 09:46:17 zigbee2mqtt:debug 2020-02-29 09:46:17: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"type":1,"unknown2":0,"time":16}' from endpoint 2 with groupID 0
feb 29 09:46:18 zigbee2mqtt:debug 2020-02-29 09:46:18: Received Zigbee message from 'dimmerwoonkamer', type 'commandHueNotification', cluster 'manuSpecificPhilips', data '{"button":1,"unknown1":3145728,"type":1,"unknown2":0,"time":24}' from endpoint 2 with groupID 0

Now you should be able to use the remote.

In case one of the steps do not work:

  • remember to press and hold one of the remote buttons while publishing to the remote topic.
  • look in the log for a cause.
  • try again.

Ted

1 Like

Hi Ted

Thanks very much for sharing this. I will try it out :slight_smile:

Thanks for sharing, this worked well for me to set up a binding between a hue dimmer switch and a group of hue bulbs of different generations and capabilities. Really well documented, thanks!