⚠️ page under construction ⚠️
Operation
Refer to the Zigbee Commands
Note: Zigbee will automatically boot the CC2530 device, configure it and wait for Zigbee messages.
Z2T Status
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}}
Statuscontains a numeric code about the status message0: initialization complete, Z2T is running normally1: booting2: resetting CC2530 configuration3: starting Zigbee coordinator20: disabling Permit Join21: allowing Permit Join for 60 seconds22: allowing Permit Join until next boot30: Zigbee device connects or reconnects31: Received Node Descriptor information for a Zigbee device32: Received the list of active endpoints for a Zigbee device33: Received the simple Descriptor with active ZCL clusters for a Zigbee device50: reporting CC2530 firmware version51: reporting CC2530 device information and associated devices98: error, unsupported CC2530 firmware99: general error, Z2T was unable to start
Message(optional) a human-readable message- other fields depending on the message (e.g., Status=
50or Status=51)
Pairing Zigbee Devices
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.
Reading sensors
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.
- Put Z2T into pairing mode using the
ZigbeePermitJoincommand as described above - 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 Status30indicates a device connect or reconnect. This is the opportunity to match IEEEAddress and short addressIEEEAddrLong unique address (64 bits) of the device - factory set ShortAddrShort address (16 bits) randomly assigned to the device on this Zigbee network PowerSourcetrue= the device is connected to a power sourcefalse= the device runs on batteryReceiveWhenIdletrue= the device can receive commands when idlefalse= the device is not listening. Commands should be sent when the device reconnects and is idleSecuritySecurity 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:
| Field name | Value |
|---|---|
Humidity |
Humidity in percentage (float) |
Pressure and PressureUnit |
Atmospheric pressure (float) and unit (string) Currently only hPa (A.K.A. mbar) is supported |
Temperature |
Temperature in Celsius (float) |
Voltage |
Battery voltage (float) |
Battery |
Battery charge in percentage (integer) |
ModelId |
Model name of the Zigbee device (string) Ex: lumi.weather |
Device Information
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"
}
]
}
Identifying Target Device Endpoints
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.
Known Endpoints
| Device | Endpoint |
|---|---|
| OSRAM Plug | 0x03 |
| Philips Hue Bulb | 0x0B |
{"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".
Supported Zigbee Device Commands
| Command | Parameters | Cluster |
|---|---|---|
| Power | 1|true|"true"|"on": On0|false|"false"|"off": Off2|"Toggle": Toggle |
0x0006 |
| Dimmer | 0..254: Dimmer value255 is normally considered as invalid, and may be converted to 254 |
0x0008 |
| Dimmer+ | null: no parameter. Increases dimmer by 10% |
0x0008 |
| Dimmer- | null: no parameter. Decreases dimmer by 10% |
0x0008 |
| DimmerStop | null: no parameter. Stops any running increase of decrease of dimmer. |
0x0008 |
| ResetAlarm | <alarmcode>,<clusterid>: (to be documented later) |
0x0009 |
| ResetAllAlarms | null: no parameter, (to be documented later) |
0x0009 |
| Hue | 0..254: change Hue value |
0x0300 |
| Sat | 0..254: change Sat value |
0x0300 |
| HueSat | 0..254,0..254: change both Hue and Sat values |
0x0300 |
| Color | 0..65534,0..65534: change the color using [x,y] coordinates |
0x0300 |
| CT | 0..65534: change the white color-temperature in Mireds |
0x0300 |
| Shutter | 0..254: send any Shutter command (prefer the commands below) |
0x0102 |
| ShutterOpen | null: no parameter, open shutter |
0x0102 |
| ShutterClose | null: no parameter, close shutter |
0x0102 |
| ShutterStop | null: no parameter, stop shutter movement |
0x0102 |
| ShutterLift | 0..100: move shutter to a specific position in percent0%=open, 100%=closed |
0x0102 |
| ShutterTilt | 0..100: move the shutter to the specific tilt position in percent |
0x0102 |
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} }