# MQTT API

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2025-10/scaled-1680-/iqOimage.png)](https://smlight.tech/support/manuals/uploads/images/gallery/2025-10/iqOimage.png)

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`

### Read topic (IN) (available from v3.3.0)

This topic accepts requests to read attributes of ZigBee devices.  
When you send a message to this topic, the coordinator generates and sends a request for the specified attribute to the target ZigBee device. The device must be online to accept the request, so this is usually used for AC-powered devices.

Topic format: `base topic` / `read` / `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.  
`read` - 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.

Read topic example: `zhub/read/a4c1383439bf5cc9/1/0006/0000`   
payload: `any text`

<p class="callout info">Attribute update will be sent to `data` topic!  
</p>

<p class="callout warning">**PLEASE NOTE!**  
**You must add any text content to the payload! Do not send an empty payload to this topic!** An empty payload will only delete this topic (if it exists). The coordinator will not respond to empty payloads.</p>

### 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:

##### <span style="text-decoration: underline;">ON/OFF</span> 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.

##### <span style="text-decoration: underline;">Level control for Light</span> 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.

##### <span style="text-decoration: underline;">Color control</span> 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**](https://en.wikipedia.org/wiki/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 <span style="text-decoration: underline;">0006</span>, attribute <span style="text-decoration: underline;">4003</span> payload format

<div id="bkmrk-last-state---device-"><div><div><div>`Last state` - device will remember its state</div><div>`ON` - device will be on after power loss  
`OFF` - device will be off after power loss</div></div>  
</div></div>##### Cluster <span style="text-decoration: underline;">EF00</span> (Tuya DP) payload format

<p class="callout warning">**Please note that the write topic format for Tuya is different!**`base topic` / `write` / `zigbee device ieee` / `1` / `ef00` / `data point` / `data type`</p>

`data point` - Tuya data point id. You can read more about it here: [https://www.zigbee2mqtt.io/advanced/support-new-devices/03\_find\_tuya\_data\_points.html](https://www.zigbee2mqtt.io/advanced/support-new-devices/03_find_tuya_data_points.html)  
`data type` - a number that represents the type of data being sent.  
0 - RAW, **1** - BOOL, **2** - INT, **3** - STRING, **4** - ENUM, **5** - BITMAP

Examples:  
topic: zhub/write/a4c138d089d1418c/1/ef00/0018/1  
payload: 1

##### Any other clusters/attributes payload format

Payload should contain **JSON**: {"type": &lt;zigbee data type&gt;, "data":&lt;data to be sent&gt;}  
`type` - a number that represents the type of data being sent.

##### Zigbee Data Types and Data Type IDs

<div class="table-wrap" id="bkmrk-data-class-data-type"><table class="wrapped confluenceTable"><colgroup><col></col><col></col><col></col></colgroup><thead><tr><th class="confluenceTh">**Data Class**

</th><th class="confluenceTh">**Data Type**

</th><th class="confluenceTh">**Data Type ID**

</th></tr></thead><tbody><tr><td class="confluenceTd">Null

</td><td class="confluenceTd">No data  
Reserved

</td><td class="confluenceTd">0x00  
0x01—0x07

</td></tr><tr><td class="confluenceTd">General Data

</td><td class="confluenceTd">8-bit data  
16-bit data  
24-bit data  
32-bit data  
40-bit data  
48-bit data  
56-bit data  
64-bit data

</td><td class="confluenceTd">0x08  
0x09  
0x0a  
0x0b  
0x0c  
0x0d  
0x0e  
0x0f

</td></tr><tr><td class="confluenceTd">Logical

</td><td class="confluenceTd">Boolean  
Reserved

</td><td class="confluenceTd">0x10  
0x11—0x17

</td></tr><tr><td class="confluenceTd">Bitmap

</td><td class="confluenceTd">8-bit data  
16-bit data  
24-bit data  
32-bit data  
40-bit data  
48-bit data  
56-bit data  
64-bit data

</td><td class="confluenceTd">0x18  
0x19  
0x1a  
0x1b  
0x1c  
0x1d  
0x1e  
0x1f

</td></tr><tr><td class="confluenceTd">Unsigned integer

</td><td class="confluenceTd">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

</td><td class="confluenceTd">0x20  
0x21  
0x22  
0x23  
0x24  
0x25  
0x26  
0x27

</td></tr><tr><td class="confluenceTd">Signed integer

</td><td class="confluenceTd">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

</td><td class="confluenceTd">0x28  
0x29  
0x2a  
0x2b  
0x2c  
0x2d  
0x2e  
0x2f

</td></tr><tr><td class="confluenceTd">Enumeration

</td><td class="confluenceTd">8-bit enumeration  
16-bit enumeration  
Reserved

</td><td class="confluenceTd">0x30  
0x31  
0x32—0x37

</td></tr><tr><td class="confluenceTd">Floating point

</td><td class="confluenceTd">Semi-precision  
Single precision  
Double precision  
Reserved

</td><td class="confluenceTd">0x38  
0x39  
0x3a  
0x3b—0x3f

</td></tr><tr><td class="confluenceTd">String

</td><td class="confluenceTd">Reserved  
Octet string  
Character string  
Long octet string  
Long character string  
Reserved

</td><td class="confluenceTd">0x40  
0x41  
0x42  
0x43  
0x44  
0x45—0x47

</td></tr><tr><td class="confluenceTd">Ordered sequence

</td><td class="confluenceTd">Array  
Reserved  
Structure  
Reserved

</td><td class="confluenceTd">0x48  
0x49—0x4b  
0x4c  
0x4d—0x4f

</td></tr><tr><td class="confluenceTd">Collection

</td><td class="confluenceTd">Set  
Bag  
Reserved

</td><td class="confluenceTd">0x50  
0x51  
0x52—0x57

</td></tr><tr><td class="confluenceTd">Reserved

</td><td class="confluenceTd">-

</td><td class="confluenceTd">0x58—0xdf

</td></tr><tr><td class="confluenceTd">Time

</td><td class="confluenceTd">Time of day  
Date  
UTC Time  
Reserved

</td><td class="confluenceTd">0xe0  
0xe1  
0xe2  
0xe3—0xe7

</td></tr><tr><td class="confluenceTd">Identifier

</td><td class="confluenceTd">Cluster ID  
Attribute ID  
BACnet ID  
Reserved

</td><td class="confluenceTd">0xe8  
0xe9  
0xea  
0xeb—0xef

</td></tr><tr><td class="confluenceTd">Miscellaneous

</td><td class="confluenceTd">IEEE Address  
128-bit security key  
Reserved

</td><td class="confluenceTd">0xf0  
0xf1  
0xf2—0xfe

</td></tr><tr><td class="confluenceTd">Unknown

</td><td class="confluenceTd">Unknown

</td><td class="confluenceTd">0xff

</td></tr></tbody></table>

</div>`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

### System control topic (IN) (available from v3.3.0)

This topic allows you to control main functions of the Zigbee Hub.

Topic format: `base topic` / `system_control`

Payload format: {"action": "&lt;system control actions&gt;", &lt;additional parameters&gt;}

#### Permit join action

Allows you to open a ZigBee network to add new devices.

Payload format: {"action": "permit\_join", "time": &lt;time to open the network in seconds, from 1 to 254&gt;, "addr": &lt;network address of the device on which to open the network. Can be omitted if the network needs to be opened on all devices&gt;}

Examples:  
`{"action": "permit_join", "time": 60}` - open the entire network for 60 seconds  
`{"action": "permit_join", "time": 0}` - close network  
`{"action": "permit_join", "time": 60, "addr": 64580}` - open the network for 60 seconds only on device with network address 64580 (DEC number, not HEX)

#### Configure reporting action

Configures reporting for the selected device. If the device is battery-powered, it must be woken up to accept this command.

Payload format: {"action": "configure\_reporting", "ieee": &lt;IEEE address of the target device, HEX string&gt;, "ep": &lt;target endpoint, DEC&gt;, "cl": &lt;target cluster, DEC&gt;, "attr": &lt;target attribute, DEC&gt;, "minRep": &lt;minimum time for reporting in seconds, DEC&gt;, "maxRep": &lt;max time for reporting in seconds, DEC&gt;, "dType": &lt;zigbee reporting data type for this attribute, DEC&gt;, "change": &lt;how much the attribute value must change for reporting to occur. Should be omitted for discrete attributes&gt;}

Examples:  
`{"action": "configure_reporting", "ieee": "3425b4fffe12e9e9", "ep": 1, "cl": 6, "attr": 0, "minRep": 1, "maxRep": 3600, "dType": 0}` - configure ON/OFF attribute repotring to minimum 1s and max 3600s report time. "change" field is omitted because it is a discrete attribute.  
`{"action": "configure_reporting", "ieee": "3425b4fffe12e9e9", "ep": 1, "cl": 2820, "attr": 1285, "minRep": 30, "maxRep": 3600, "dType": 33, "change": 200}` - configure RMS Voltage attribute repotring to minimum 1s and max 3600s report time. Reporting will occur no earlier than 30s if the value has changed by 200 or more (2v) or after a 3600s timeout if value does not changed.

#### Binding action

Binds the target device to the coordinator or to another device.

<p class="callout warning">If one device bound to another, the coordinator will stop receiving reports from the bound device cluster.</p>

Payload format: {"action": "binding", "mode": "&lt;binding mode&gt;", "scrIeee": "&lt;IEEE of the device to which the binding request will be sent, HEX string&gt;", ""scrEp": &lt;endpoint number that needs to be bound, DEC number&gt;, "scrCl": &lt;cluster number that needs to be bound, DEC number&gt;, &lt;additional parameters&gt;}

##### To device mode

Binds one device to another.

Payload format: {"action": "binding", "mode": "to\_device", "scrIeee": "&lt;IEEE of the device to which the binding request will be sent, HEX string&gt;", ""scrEp": &lt;endpoint number that needs to be bound, DEC number&gt;, "scrCl": &lt;cluster number that needs to be bound, DEC number&gt;, "dstEp": &lt;endpoint number **to which** the binding will be done, DEC number&gt;, "dstIeee": "&lt;IEEE device to which binding will be performed, HEX string&gt;"}

Example: `{"action": "binding", "mode": "to_device", "scrIeee": "3425b4fffe12e9e9", ""scrEp": 1, "scrCl": 6, "dstEp": 1, "dstIeee": "a4c1389ffb198304"}` - binding a Zigbee button (ON/OFF cluster) to a Zigbee relay.

##### To coordinator mode

Binds to the coordinator so that it can receive reports from this cluster.

<p class="callout info">Zigbee Hub will attempt to bind automatically when interviewing a device, but this does not always work perfectly.</p>

Payload format: {"action": "binding", "mode": "to\_device", "scrIeee": "&lt;IEEE of the device to which the binding request will be sent, HEX string&gt;", ""scrEp": &lt;endpoint number that needs to be bound, DEC number&gt;, "scrCl": &lt;cluster number that needs to be bound, DEC number&gt;}

Example: `{"action": "binding", "mode": "to_coordinator", "scrIeee": "3425b4fffe12e9e9", ""scrEp": 1, "scrCl": 6}` - binding a Zigbee button (ON/OFF cluster) to the coordinator.