**It is highly recommended to use U series coordinators for this mode (SLZB-06xU / MRxU)**
## 4.1 What is Zigbee Hub in SLZB-OS? The **Zigbee Hub** feature allows the SLZB device to run its Zigbee network **directly on the device** — without needing an external computer, Raspberry Pi, or NAS to host the Zigbee stack. In Zigbee Hub mode, SLZB-OS launches an integrated Zigbee stack service that can connect directly to your smart home platform over MQTT. This mode is ideal for: - **Self-contained setups** where the device acts as both the coordinator and the host. - **Reducing complexity** by eliminating extra hardware. - **PoE/Ethernet-based installations** for maximum stability. When Zigbee Hub is active, a dedicated **Zigbee Hub** menu appears in the SLZB-OS interface, containing the following pages: 1. **Dashboard** – Live overview of Zigbee network status. 2. **Devices** – List and manage all paired Zigbee devices. 3. **MQTT** – Configure the MQTT broker connection. 4. **Settings** – Advanced Zigbee network and coordinator options. --- ## 4.2 Zigbee Hub → Dashboard The **Dashboard** is the central monitoring page for your Zigbee network. [](https://smlight.tech/support/manuals/uploads/images/gallery/2025-08/keCimage.png) The dashboard contains cards of your ZigBee devices with the data they provide and controls. The dashboard is updated in real time via SSE. --- ## 4.3 Zigbee Hub → Devices The **Devices** page lists every Zigbee device paired to your coordinator. [](https://smlight.tech/support/manuals/uploads/images/gallery/2025-08/527image.png) **Pairing control:** - **Permit Join** (+ button on the bottom right side of the device table) – Allow or deny new devices joining the network. **For each device, you’ll see:** - **Name / Friendly Name** – Human-readable identifier. - **IEEE Address** – Unique device ID. - **Network Address** – Short Zigbee address assigned by the coordinator. - **Last Seen** – Timestamp of the last communication. - **Powering** – Device power source (AC/battery) or ? if the device does not provide information. - **Link Quality (LQI)** – Signal strength indicator. - **Actions:** - Rename device - Remove/unpair device - View device details (clusters, endpoints, bindings) - Bind/unbind devices (if supported) **Typical uses:** - Verify devices are online and responsive. - Rename devices for easier identification in automations. - Remove devices no longer in use. ### Device config #### How to rename device Select the pencil icon [](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/image.png) [](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/TD5image.png) Enter new name and press "Save". Maximum length - 50 characters. #### Device config Click on the wrench[](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/5YYimage.png) ##### Binding [](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/cSRimage.png) This menu sends the device a bind request **to the coordinator**, the device must be active to accept this. If it is a battery-powered device you need to wake it up. ##### Configure reporting [](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/Gr5image.png) ##### Polling [](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/FPwimage.png) Allows you to configure polling of the selected attribute after a certain time interval ##### Exposes [](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/VReimage.png) [](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/Yh4image.png) Provides information about **expected** data from the device and examples of using MQTT, HTTP, and Berry API to get or set device state.**IMPORTANT!** This section provides information about **EXPECTED** data from the device, based on information about the device clusters or converter (if it exists). This information may not match the actual behavior of the device if it uses non-standard clusters! If this is a Tuya DP device, then information will be displayed here only if a converter exists for the device!
##### Other tools [](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/wBBimage.png) Here you can find the ZCN converter number (if used) and download device information --- ## 4.4 Zigbee Hub → MQTT This page configures the MQTT connection that Zigbee2MQTT (running on SLZB-OS) uses to communicate with your smart home platform. [](https://smlight.tech/support/manuals/uploads/images/gallery/2025-08/OHQimage.png) **Configuration fields include:** - **MQTT Server Address** – IP or hostname of your broker (e.g., `mqtt://192.168.1.100`). - **Port** – Default 1883 for MQTT, 8883 for MQTT over TLS. - **Username / Password** – Broker authentication (if required). - **Base Topic** – Topic prefix for Zigbee messages (default: `zigbee2mqtt`). - **Discovery Prefix** - Home assistant main topic name. **Tips:** - For Home Assistant with Mosquitto add-on, use the HA IP and port `1883`. - Always use a unique base topic if you run multiple Zigbee networks. - Save and restart Zigbee Hub after making MQTT changes. --- ## 4.5 Zigbee Hub → Settings The **Settings** page contains deeper configuration for the Zigbee coordinator and Zigbee2MQTT service. [](https://smlight.tech/support/manuals/uploads/images/gallery/2025-08/dJpimage.png) **Typical settings available:** - **Network Parameters**: - **PAN ID** – Zigbee network identifier. - **Channel** – RF channel (11–26; avoid Wi-Fi overlap if possible). - **Extended PAN ID** – Long network identifier. - **Transmit Power** – Radio TX power in dBm (higher = longer range, more power draw). - **Show in debug log -** Select which categories of Zigbee-related information are recorded in the Log & Debug page. - **Zigbee Hub messages** – Logs high-level events from the Zigbee Hub service (e.g., device joins, status updates). - **Raw Zigbee packets** – Logs low-level Zigbee frame data; useful for deep protocol debugging. - **Zigbee MQTT** – Logs MQTT messages related to Zigbee communication, including publishes and subscriptions. **Best practices:** - Change the Zigbee channel only on a fresh network (re-pair required after change). - Keep `Permit Join` disabled most of the time for security. - Adjust transmit power to match your coverage needs and regulatory limits. ## 4.6 Troubleshooting ### Problems when starting a Zigbee networkOS v3.0.9 update is breaking. If you updated OS to v3.0.9 and started getting this error then follow the instructions below
Attribute update will be sent to `data` topic!
**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.
### 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**](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 0006, attribute 4003 payload format**Please note that the write topic format for Tuya is different!**`base topic` / `write` / `zigbee device ieee` / `1` / `ef00` / `data point` / `data type`
`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": <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 |
If one device bound to another, the coordinator will stop receiving reports from the bound device cluster.
Payload format: {"action": "binding", "mode": "<binding mode>", "scrIeee": "<IEEE of the device to which the binding request will be sent, HEX string>", ""scrEp": <endpoint number that needs to be bound, DEC number>, "scrCl": <cluster number that needs to be bound, DEC number>, <additional parameters>} ##### To device mode Binds one device to another. Payload format: {"action": "binding", "mode": "to\_device", "scrIeee": "<IEEE of the device to which the binding request will be sent, HEX string>", ""scrEp": <endpoint number that needs to be bound, DEC number>, "scrCl": <cluster number that needs to be bound, DEC number>, "dstEp": <endpoint number **to which** the binding will be done, DEC number>, "dstIeee": "<IEEE device to which binding will be performed, HEX string>"} 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.Zigbee Hub will attempt to bind automatically when interviewing a device, but this does not always work perfectly.
Payload format: {"action": "binding", "mode": "to\_device", "scrIeee": "<IEEE of the device to which the binding request will be sent, HEX string>", ""scrEp": <endpoint number that needs to be bound, DEC number>, "scrCl": <cluster number that needs to be bound, DEC number>} Example: `{"action": "binding", "mode": "to_coordinator", "scrIeee": "3425b4fffe12e9e9", ""scrEp": 1, "scrCl": 6}` - binding a Zigbee button (ON/OFF cluster) to the coordinator. # Zigbee Converter Native (ZCN) concept ### Introduction When developing the Zigbee stack for zHub, we had to take into account the **strict RAM limitations of the ESP32**, so it is physically impossible to provide the same convenient and functional Zigbee converters as in Zigbee2Mqtt or ZHA. So, we develop an alternative **ZCN** concept based on **static C++ structures** that contain a set of **callbacks** that allow you to override the processing of packets from/to ZigBee devices. #### ZHB Incoming Zigbee message flow structureIs normalization mandatory? The answer is no, if the received value does not require conversion from one format to another, then you can skip this step.
##### Serialization Once the value has been normalized you need to tell zHub how to properly convert it to text, this is the serialization! zHub uses ArduinoJson to form a data packet for MQTT / WEB. Therefore, for ordinary int, bool or string, you can use a simple code: ```c++ data[zcl_json.type_sm] = zcl_json.report; data[zcl_json.val] = record.val.u32; ``` For float, it is better to format manually to get right number of characters: ```c++ char buf[11] = {0}; // "-222.00" snprintf(buf, sizeof(buf), "\"%.2f\"", record.val.fl); data[zcl_json.type_sm] = zcl_json.report; data[zcl_json.val] = serialized(buf); ``` To simplify things, we developed functions to serialize more common cases: ```c++ // converts color in X/Y to text (in R,G,B format (255,255,255)) static void zcn_ser_xy(ZCL_SER_ATTR_HANDLER_ARGS); // converts a float to its text representation (2 digits precision) static void zcn_ser_float(ZCL_SER_ATTR_HANDLER_ARGS); // converts a raw uint32 to its text representation static void zcn_ser_raw_uint(ZCL_SER_ATTR_HANDLER_ARGS); // return "ON" if integer value > 0. otherwise return "OFF" static void zcn_tuya_ser_switch(ZCL_SER_ATTR_HANDLER_ARGS); ```Is serialization mandatory? This can be omitted only for ZCL commands, all other records, if they are not empty, must be serialized so that zHub can send them to MQTT / WEB
#### ZCN structures