MQTT API

Zigbee Hub mode has the ability to connect to local or remote MQTT brokers. Currently only TCP connections are supported.
This document describes MQTT API for SLZB-OS 3.0.9 or higher

Topics are divided into IN and OUT.
IN - you can send messages to these topics.
OUT - Zigbee Hub sends messages to these topics.

zHub topics format

Data topic (OUT)

General data topic format below:
base topic / data / zigbee device ieee / zigbee endpoint / zigbee cluster / zigbee attribute

base topic - global prefix, so you can have few Zigbee Hubs connected to one broker, you just have to set different base topics.
data - static text (topic type)
zigbee device ieee - sender IEEE address in HEX format.
zigbee endpoint - zigbee endpoint from which this message is coming, DEC format.
zigbee cluster - zigbee cluster from which this message is coming, HEX format.
zigbee attribute - zigbee attribute from which this message is coming, HEX format.

Data topic example: zhub/data/a4c1383439bf5cc9/1/0000/0001

Command topic (IN)

This topic is intended for sending ZCL commands to a Zigbee device.
General cmd topic format below:
base topic / cmd / zigbee device ieee / zigbee endpoint / zigbee cluster / zigbee command

base topic - global prefix, so you can have few Zigbee Hubs connected to one broker, you just have to set different base topics.
cmd - static text (topic type)
zigbee device ieee - target zigbee device IEEE address in HEX format.
zigbee endpoint - target zigbee device endpoint to which this message is coming, DEC format.
zigbee cluster - target zigbee device cluster to which this message is coming, HEX format.
zigbee command - zigbee command to send, HEX format.

Some clusters have special handlers for input commands, such as the ON/OFF or Light cluster. You can find their formats below:

ON/OFF cluster payload format for command topic

ON - send ON command
OFF - send OFF command

Example: zhub/cmd/a4c1383439bf5cc9/1/0006 payload: ON
Will send command to enable relay or light device.

Level control for Light cluster payload format

0000 command payload is a number in DEC from 1 to 254, the larger the number, the brighter the lamp will be.

Color control cluster payload format

0007 command payload is a color in HEX or RGB format. For example: 255,29,0 or #FFFFFF
000a command payload is a light temperature in mired. For example: 200

Other clusters

If no built-in clusters or ZCN converters has overridden the processing of this command, if the command contains a payload, it must be a HEX string of the following format:
- Bytes without spaces, uppercase, multiple of two. Example: 010203FF
- Bytes with spaces, uppercase, grouped by two. Example: 01 02 03 FF

Write topic (IN)

This topic is intended for writing ZigBee device ZCL attributes.
General write topic format below:
base topic / write / zigbee device ieee / zigbee endpoint / zigbee cluster / zigbee attribute

base topic - global prefix, so you can have few Zigbee Hubs connected to one broker, you just have to set different base topics.
write - static text (topic type)
zigbee device ieee - target zigbee device IEEE address in HEX format.
zigbee endpoint - target zigbee device endpoint to which this message is coming, DEC format.
zigbee cluster - target zigbee device cluster to which this message is coming, HEX format.
zigbee attribute - target zigbee device attribute to which this message is coming, HEX format.

Cluster 0006, attribute 4003 payload format

Last state - device will remember its state

ON - device will be on after power loss
OFF - device will be off after power loss

Cluster EF00 (Tuya DP) payload format

Payload should contain JSON: {"type": <tuya data type>, "data":<data to be sent>}
type - a number that represents the type of data being sent.
0 - RAW, 1 - BOOL, 2 - INT, 3 - STRING, 4 - ENUM, 5 - BITMAP

data - data type varies, please check the examples below

Complete payload examples:
{ "type": 0, "data": "010203" }
{ "type": 1, "data": 1 }
{ "type": 2, "data": 100 }
{ "type": 3, "data": "some string" }
{ "type": 4, "data": 0 }
{ "type": 5, "data": 0 }

Any other clusters/attributes payload format

Payload should contain JSON: {"type": <zigbee data type>, "data":<data to be sent>}
type - a number that represents the type of data being sent.

Zigbee Data Types and Data Type IDs

Data Class	Data Type	Data Type ID
Null	No data Reserved	0x00 0x01—0x07
General Data	8-bit data 16-bit data 24-bit data 32-bit data 40-bit data 48-bit data 56-bit data 64-bit data	0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f
Logical	Boolean Reserved	0x10 0x11—0x17
Bitmap	8-bit data 16-bit data 24-bit data 32-bit data 40-bit data 48-bit data 56-bit data 64-bit data	0x18 0x19 0x1a 0x1b 0x1c 0x1d 0x1e 0x1f
Unsigned integer	Unsigned 8-bit integer Unsigned 16-bit integer Unsigned 24-bit integer Unsigned 32-bit integer Unsigned 40-bit integer Unsigned 48-bit integer Unsigned 56-bit integer Unsigned 64-bit integer	0x20 0x21 0x22 0x23 0x24 0x25 0x26 0x27
Signed integer	Signed 8-bit integer Signed 16-bit integer Signed 24-bit integer Signed 32-bit integer Signed 40-bit integer Signed 48-bit integer Signed 56-bit integer Signed 64-bit integer	0x28 0x29 0x2a 0x2b 0x2c 0x2d 0x2e 0x2f
Enumeration	8-bit enumeration 16-bit enumeration Reserved	0x30 0x31 0x32—0x37
Floating point	Semi-precision Single precision Double precision Reserved	0x38 0x39 0x3a 0x3b—0x3f
String	Reserved Octet string Character string Long octet string Long character string Reserved	0x40 0x41 0x42 0x43 0x44 0x45—0x47
Ordered sequence	Array Reserved Structure Reserved	0x48 0x49—0x4b 0x4c 0x4d—0x4f
Collection	Set Bag Reserved	0x50 0x51 0x52—0x57
Reserved	-	0x58—0xdf
Time	Time of day Date UTC Time Reserved	0xe0 0xe1 0xe2 0xe3—0xe7
Identifier	Cluster ID Attribute ID BACnet ID Reserved	0xe8 0xe9 0xea 0xeb—0xef
Miscellaneous	IEEE Address 128-bit security key Reserved	0xf0 0xf1 0xf2—0xfe
Unknown	Unknown	0xff

data - a HEX string of the following format:
- Bytes without spaces, uppercase, multiple of two. Example: 010203FF
- Bytes with spaces, uppercase, grouped by two. Example: 01 02 03 FF

Please note that the number of bytes in the payload strictly depends on the data type!
For example, if you send data with type 16-bit integer, the number of bytes in the payload should be 2.
Example: {"type": 33, "data":"0000"}
33 - is 0x21 converted to DEC