Zigbee Operation - stodev-com-br/Tasmota GitHub Wiki

⚠️ page under construction ⚠️

Refer to the Zigbee Commands

Note: Zigbee will automatically boot the CC2530 device, configure it and wait for Zigbee messages.

You can inspect the log output to determine whether Z2T started correctly. Z2T sends several status messages to inform the MQTT host about initialization.

Ex: {"ZigbeeState":{"Status":1,"Message":"CC2530 booted","RestartReason":"Watchdog","MajorRel":2,"MinorRel":6}}

• Status contains a numeric code about the status message
  • 0: initialization complete, Z2T is running normally
  • 1: booting
  • 2: resetting CC2530 configuration
  • 3: starting Zigbee coordinator
  • 20: disabling Permit Join
  • 21: allowing Permit Join for 60 seconds
  • 22: allowing Permit Join until next boot
  • 30: Zigbee device connects or reconnects
  • 31: Received Node Descriptor information for a Zigbee device
  • 32: Received the list of active endpoints for a Zigbee device
  • 33: Received the simple Descriptor with active ZCL clusters for a Zigbee device
  • 50: reporting CC2530 firmware version
  • 51: reporting CC2530 device information and associated devices
  • 98: error, unsupported CC2530 firmware
  • 99: general error, Z2T was unable to start
• Message (optional) a human-readable message
• other fields depending on the message (e.g., Status=50 or Status=51)

By default, and for security reasons, the Zigbee coordinator does not automatically accept new devices. To pair new devices, use ZigbeePermitJoin 1. Once Z2T is in pairing mode, put the Zigbee device into pairing mode. This is usually accomplished by pressing the button on the device for 5 seconds or more. To stop pairing, use ZigbeePermitJoin 0.

Sensor messages are published via MQTT when they are received from the Zigbee device. Unlike Zigbee2MQTT, there is currently no debouncing nor caching.

Example: Xiaomi Aqara Sensor

This sensor monitors humidity, temperature, and air pressure. Its Zigbee model ID is lumi.weather.

1. Put Z2T into pairing mode using the ZigbeePermitJoin command as described above

2. Press the Xiaomi Aqara sensor's button for 5 seconds to pair the devices. You will see a message as follows:

   MQT: tele/<topic>/RESULT = {"ZigbeeState":{"Status":30,"IEEEAddr":"00158D00036B50AE","ShortAddr":"0x8F20","PowerSource":false,"ReceiveWhenIdle":false,"Security":false}}
   

   Field name	Value
   Status	30 indicates a device connect or reconnect. This is the opportunity to match IEEEAddress and short address
   IEEEAddr	Long unique address (64 bits) of the device - factory set
   ShortAddr	Short address (16 bits) randomly assigned to the device on this Zigbee network
   PowerSource	true = the device is connected to a power source false = the device runs on battery
   ReceiveWhenIdle	true = the device can receive commands when idle false = the device is not listening. Commands should be sent when the device reconnects and is idle
   Security	Security capability (meaning unknown, to be determined)

This device publishes sensor values roughly every hour or when a change occurs. You can also force an update pressing the device's button. It sends two kinds of messages, either 3x standard Zigbee messages, or a single proprietary message containing all sensor values.

Examples:

MQT: tele/<topic>/RESULT = {"0x8F20":{"Humidity":23.47}}
MQT: tele/<topic>/RESULT = {"0x8F20":{"Temperature":59.85}}
MQT: tele/<topic>/RESULT = {"0x8F20":{"Pressure":1005,"PressureUnit":"hPa"}}
MQT: tele/<topic>/RESULT = {"0x8F20":{"Temperature":23.47,"Humidity":58.97,"Pressure":1005.8,"PressureUnit":"hPa","Voltage":3.005,"Battery":100}}
MQT: tele/<topic>/RESULT = {"0x8F20":{"ModelId":"lumi.weather"}}

0x8F20 is the ShortAddress of the sensor.

Supported values:

You can dump the internal information gathered about connected Zigbee devices with the command ZigbeeStatus.

ZigbeeStatus1 - List all connected devices

{"ZigbeeStatus-99":[{"ShortAddr":"0x6B58"},{"ShortAddr":"0xE9C3"},{"ShortAddr":"0x3D82"}]}

(JSON pretty-printed for readability)

{
    "ZigbeeStatus-99": [
        {
            "ShortAddr":"0x6B58"
        },
        {
            "ShortAddr":"0xE9C3"
        },
        {
            "ShortAddr":"0x3D82"
        }
    ]
}

ZigbeeStatus 2 - Display detailed information for each device, including long address, model and manufacturer:

{"ZigbeeStatus2":[{"ShortAddr":"0x6B58","IEEEAddr":"7CB03EAA0A0292DD","ModelId":"Plug 01","Manufacturer":"OSRAM"},{"ShortAddr":"0xE9C3","IEEEAddr":"00158D00036B50AE","ModelId":"lumi.weather","Manufacturer":"LUMI"},{"ShortAddr":"0x3D82","IEEEAddr":"0017880102FE1DBD","ModelId":"LWB010","Manufacturer":"Philips"}]}

(JSON pretty-printed for readability)

{
    "ZigbeeStatus2": [
        {
            "ShortAddr": "0x6B58",
            "IEEEAddr": "7CB03EAA0A0292DD",
            "ModelId": "Plug 01",
            "Manufacturer": "OSRAM"
        },
        {
            "ShortAddr": "0xE9C3",
            "IEEEAddr": "00158D00036B50AE",
            "ModelId": "lumi.weather",
            "Manufacturer": "LUMI"
        },
        {
            "ShortAddr": "0x3D82",
            "IEEEAddr": "0017880102FE1DBD",
            "ModelId": "LWB010",
            "Manufacturer": "Philips"
        }
    ]
}

You can use ZigbeeStatus3 to display information about all the endpoints and ZCL clusters supported. If probing was successful (at pairing time or using ZigbeeProbe), Tasmota will automatically find the right endpoint. If the device was not probed, you need to specify the endpoint explicitly. It is always better to explicitly add the endpoint number if you know it.

{"ZigbeeStatus3":[{"ShortAddr":"0x6B58","Endpoints":{"0x03":{"ProfileId":"0xC05E","ProfileIdName":"ZigBee Light Link","ClustersIn":["0x1000","0x0000","0x0003","0x0004","0x0005","0x0006","0x0B04","0xFC0F"],"ClustersOut":["0x0019"]}}},{"ShortAddr":"0xE9C3","Endpoints":{"0x01":{"ProfileId":"0x0104","ClustersIn":["0x0000","0x0003","0xFFFF","0x0402","0x0403","0x0405"],"ClustersOut":["0x0000","0x0004","0xFFFF"]}}},{"ShortAddr":"0x3D82","Endpoints":{"0x0B":{"ProfileId":"0xC05E"," ...

(JSON pretty-printed for readability)

{
  "ZigbeeStatus3": [
    {
      "ShortAddr": "0x6B58",
      "Endpoints": {
        "0x03": {
          "ProfileId": "0xC05E",
          "ProfileIdName": "ZigBee Light Link",
          "ClustersIn": [
            "0x1000",
            "0x0000",
            "0x0003",
            "0x0004",
            "0x0005",
            "0x0006",
            "0x0B04",
            "0xFC0F"
          ],
          "ClustersOut": [
            "0x0019"
          ]
        }
      }
    },
    {
      "ShortAddr": "0xE9C3",
      "Endpoints": {
        "0x01": {
          "ProfileId": "0x0104",
          "ClustersIn": [
            "0x0000",
            "0x0003",
            "0xFFFF",
            "0x0402",
            "0x0403",
            "0x0405"
          ],
          "ClustersOut": [
            "0x0000",
            "0x0004",
            "0xFFFF"
          ]
        }
      }
    },
    {
      "ShortAddr": "0x3D82",
      "Endpoints": {
        "0x0B": {
          "ProfileId": "0xC05E",
          " ...
        }
      }
    }
  ]
}

Ex: OSRAM Zigbee plug:

{"Device":"0x69CF","IEEEAddr":"0000000000000000","ModelId":"Plug 01","Manufacturer":"OSRAM","Endpoints":{"0x03":{"ProfileId":"0xC05E","ProfileIdName":"ZigBee Light Link","ClustersIn":["0x1000","0x0000","0x0003","0x0004","0x0005","0x0006","0x0B04","0xFC0F"],"ClustersOut":["0x0019"]}}}

The message above shows that the device supports only one endpoint 0x03 which accepts messages (ClustersIn) for clusters "0x1000","0x0000","0x0003","0x0004","0x0005","0x0006","0x0B04","0xFC0F".

Examples:

OSRAM Plug

ZigbeeSend { "device":"0x69CF", "endpoint":"0x03", "send":{"Power":"On"} }
ZigbeeSend { "device":"0x69CF", "endpoint":"0x03", "send":{"Power":1} }
ZigbeeSend { "device":"0x69CF", "endpoint":"0x03", "send":{"Power":false} }
ZigbeeSend { "device":"0x69CF", "endpoint":"0x03", "send":{"Power":"Toggle"} }

Read the On/Off status: (all three commands below are synonyms)

ZigbeeRead { "device":"0x69CF", "endpoint":"0x03", "cluster":"0x0006", "read":"0x0000" }
ZigbeeRead { "device":"0x69CF", "endpoint":"0x03", "cluster":"0x0006", "read":["0x0000"] }
ZigbeeRead { "device":"0x69CF", "endpoint":3, "cluster":6, "read":0 }

Philips Hue bulb

ZigbeeSend { "device":"0x3D82", "endpoint":"0x0B", "send":{"Power":"Off"} }
ZigbeeSend { "device":"0x3D82", "endpoint":"0x0B", "send":{"Dimmer":128} }
ZigbeeSend { "device":"0x3D82", "endpoint":"0x0B", "send":{"Dimmer":254} }
ZigbeeSend { "device":"0x3D82", "endpoint":"0x0B", "send":{"Dimmer":0} }