diff --git a/Zigbee-Commands.md b/Zigbee-Commands.md index e8c12094..ad7a8961 100644 --- a/Zigbee-Commands.md +++ b/Zigbee-Commands.md @@ -1,3 +1,213 @@ # Zigbee Commands > **:warning: page under construction :warning:** + + +Here are the additional commands available when Zigbee is activated. Note: Zigbee will automatically boot the CC2530 device, configure it and wait for Zigbee messages. + + +|Command|Paramaters| +|---|---| +|ZigbeePermitJoin|Enables or disables pairing of new devices, see below.

`ZigbeePermitjoin 1` enables pairing for 60 seconds
`ZigbeePermitJoin 99` enables pairing until next boot
`ZigbeePermitJoin 0` disables pairing| +|ZigbeeReset|Does a factory reset and reconfiguration of the CC2530. Warning: you will need to re-pair all Zigbee devices

Ex: `ZigbeeReset 1`| +|ZigbeeStatus|Shows data collected from connected Zigbee devices, see examples below.

`ZigbeeStatus` shows the list of all Zigbee devices seen on the network until last boot, with their short address and friendly name.
`ZigbeeStatus 1` adds Manufacturer ID and Model ID of each devices
`ZigbeeStatus 2` adds list of endpoints of each device and the clusterIds supported in each endpoint.| +|ZigbeeZCLSend|Send a raw ZCL message to a Zigbee device. This is a low-level command, and requires to manually build the ZCL parameters. Most common usage will be provided as high-level functions.| + +### Z2T Status +You can inspect the log output to determine whether Z2T started correctly. Z2T sends several `ZigbeeStatus` messages to inform the MQTT host about initialization: +Ex: ```{"ZigbeeStatus":{"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 (Status=50 or Status=51) + +### Permit Join +By default, and for security reasons, the Zigbee coordinator does not automatically accept new devices. To pair new devices, use one of the following commands: +- `ZigbeePermitJoin 1`: enables pairing for 60 seconds +- `ZigbeePermitJoin 99`: enables pairing until next boot + +Then put your 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](https://www.aliexpress.com/item/32876734250.html) + + +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//RESULT = {"ZigbeeStatus":{"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//RESULT = {"0x8F20":{"Humidity":23.47}} +MQT: tele//RESULT = {"0x8F20":{"Temperature":59.85}} +MQT: tele//RESULT = {"0x8F20":{"Pressure":1005,"PressureUnit":"hPa"}} +MQT: tele//RESULT = {"0x8F20":{"Temperature":23.47,"Humidity":58.97,"Pressure":1005.8,"PressureUnit":"hPa","Voltage":3.005,"Battery":100}} +MQT: tele//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`| + +### Other commands +You can dump the internal information gathered about connected Zigbee devices with the command `ZigbeeStatus`. + +List all connected devices with `ZigbeeStatus` +```yaml +{"ZigbeeStatus-99":[{"ShortAddr":"0x6B58"},{"ShortAddr":"0xE9C3"},{"ShortAddr":"0x3D82"}]} +``` + +_(JSON pretty-printed for readability)_ +```yaml +{ + "ZigbeeStatus-99": [ + { + "ShortAddr":"0x6B58" + }, + { + "ShortAddr":"0xE9C3" + }, + { + "ShortAddr":"0x3D82" + } + ] +} +``` + +Get detailed information for each device, including long address, model and manufacturer with `ZigbeeStatus 1`: +```yaml +{"ZigbeeStatus1":[{"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)_ +```yaml +{ + "ZigbeeStatus1": [ + { + "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" + } + ] +} +``` + +Get information about endpoints and ZCL clusters supported with `ZigbeeStatus 2`: +```yaml +{"ZigbeeStatus2":[{"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)_ +```yaml +{ + "ZigbeeStatus2": [ + { + "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", + " ... + } + } + } + ] +} +``` \ No newline at end of file