# Zigbee Hub

Build your local ZigBee network without Z2M/ZHA

# About Zigbee Hub mode

# **4. About Zigbee Hub mode**

<p class="callout success">**It is highly recommended to use U series coordinators for this mode (SLZB-06xU / MRxU / Ultima)**</p>

<p class="callout info">**Limitations:  
- <s>no support for ZigBee devices that require a manufacturer code </s>(Added starting from v3.4.3.dev3)  
- no support for ZGP and Touchlink  
- no OTA updates for ZigBee devices  
- <s>limited support for ZigBee devices that use non-standard clusters</s> (about 3,000 converters generated by AI since v3.4.3.dev3)  
- limited number of devices that can be paired:  
   U series coordinators - up to 80 devices.  
   non-U series - up to 16 devices.** </p>

## 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. **ZCN Builder** - A tool that helps create custom converters for Zigbee devices.
4. **Network map** - Map of your Zigbee network (v3.4.3.dev3+)
5. **Groups** - Creating and managing Zigbee groups (v3.4.3.dev3+)
6. **MQTT** – Configure the MQTT broker connection.
7. **Backup and Restore** - Creating and restoring Zigbee network backups.
8. **Settings** – Advanced Zigbee network and coordinator options.

### Feature overview

- **Pairing**
    - Permit join for the whole network or through one router, at most 254 s; the hub closes the network again by itself.
    - Install codes (QR code text of Aqara, Hue and Zigbee 3.0 devices).
- **Automatic interview** of every new device: 
    - node descriptor, endpoints, manufacturer, model, power source.
    - binding and attribute reporting configured config.
    - IAS zone enrollment for alarm sensors.
    - Tuya initialization.
- **Polling fallback**: a mains device that cannot report an attribute (many Tuya plugs) has it polled automatically.
- **Thousands of supported device models**: standard Zigbee devices work without a converter. Device-specific converters.
- **Home Assistant MQTT discovery** for sensors, switches, lights, covers, climates, fans, locks, sirens, numbers, selects, buttons, texts and device triggers (buttons, remotes, scenes).
- **Device availability**: a device silent for too long is marked offline in Home Assistant and on the dashboard. Defaults: 10 min for mains devices, 25 h for battery devices.
- **Groups**: one Zigbee group command switches all members at once. Each group appears in Home Assistant as a light or switch.
- **Network map** of routers and their links with link quality (LQI).
- **Channel change without re-pairing**: the running network moves to the new channel together with its devices.
- **Network key change without re-pairing**.
- **Backup and restore** of the network, the devices and the settings. A backup is also made automatically after a channel or key change.
- **Device tools** in the web interface: 
    - bindings (to the hub or to another device), reporting and polling;
    - read and write attributes, send any ZCL command;
    - choose or update the device's converter.
- **Local automation scripts**: read device values and control devices from scripts running on the SLZB device.
- **History for sensor values**: U devices stores the history of value changes for your Zigbee sensors over the past 24 hours, with a sampling interval of 5 minutes.

### Device support

Most devices that follow the Zigbee Cluster Library standard work **without any converter**: the hub reads the clusters the device has.

Devices with their own data formats (Tuya datapoint devices, Xiaomi / Aqara, manufacturer-specific clusters) need a **converter**. There are three types:

1. **Built-in converters**: a few dozen popular devices (Tuya, Lumi / Aqara, SONOFF, MOES, Third Reality), compiled into the firmware.
2. **Generated converters**: about **3,900 converters**, generated by AI. 
    - **Coverage**: 
        - Tuya: about 630 datapoint device models, 508 of them with every datapoint mapped;
        - Philips Hue, IKEA, Aqara / Lumi, SONOFF, Innr, Gledopto, Heiman, Schneider Electric, Sunricher, Namron, Ledvance, Osram, MOES, Legrand, Danfoss, Shelly, Yale, Third Reality and many more.
    - **What they carry**: 
        - the device's entities (with fields, composite climates / covers / lights / fans, schedules, button actions);
        - the device configuration for pairing (bindings, reporting, attribute writes, time sync, periodic queries).
    - **Delivery**: converters are not part of the firmware. The hub fetches the converter of a paired device from the SMLIGHT server and stores it. 
        - **U devices** download it themselves, and check for a newer version daily.
        - **Older devices** get it through your browser while the web interface is open.
        - Both are controlled by the setting **"Allow downloading device converters from the SMLIGHT server"** on the Zigbee Hub settings page.
        - A converter fragment file (`.zcf`) can also be installed by hand in the device dialog.
3. **Berry ZCN converters**: your own converters written in Berry (ESP32-S3 devices). **Zigbee Hub → ZCN Builder** generates the code. See the [Berry ZCN manual](https://smlight.tech/support/manuals/books/slzb-os/page/berry-zcn-system-manual).

### Supported Zigbee clusters

These clusters are handled for every device. The hub binds them and configures their reporting at the interview where needed.

<table class="code-line" data-line="107" dir="auto" id="bkmrk-cluster-id-what-you-"><thead class="code-line" data-line="107" dir="auto"><tr class="code-line" data-line="107" dir="auto"><th>Cluster</th><th>ID</th><th>What you get</th></tr></thead><tbody class="code-line" data-line="109" dir="auto"><tr class="code-line" data-line="109" dir="auto"><td>Power Configuration</td><td>0x0001</td><td>Battery % and battery voltage (battery devices)</td></tr><tr class="code-line" data-line="110" dir="auto"><td>Identify</td><td>0x0003</td><td>Answered as Zigbee 3.0 requires</td></tr><tr class="code-line" data-line="111" dir="auto"><td>Scenes</td><td>0x0005</td><td>Scene recall / store of remotes as actions (<code>recall&#95;1</code>, ...)</td></tr><tr class="code-line" data-line="112" dir="auto"><td>On/Off</td><td>0x0006</td><td>State and control; remote commands as actions (<code>on</code>, <code>off</code>, <code>toggle</code>, per button)</td></tr><tr class="code-line" data-line="113" dir="auto"><td>On/Off Switch Configuration</td><td>0x0007</td><td>Switch type and switch actions of relays</td></tr><tr class="code-line" data-line="114" dir="auto"><td>Level Control</td><td>0x0008</td><td>Brightness, Level settings (on level, transition times, start-up level); remote commands as actions (<code>brightness&#95;move&#95;up</code>, ...)</td></tr><tr class="code-line" data-line="115" dir="auto"><td>Analog / Binary / Multistate Input</td><td>0x000C / 0x000F / 0x0012</td><td>Values named after the device's description, with units and state names</td></tr><tr class="code-line" data-line="116" dir="auto"><td>Time</td><td>0x000A</td><td>The hub answers the device's time requests (time zone and DST)</td></tr><tr class="code-line" data-line="117" dir="auto"><td>Poll Control</td><td>0x0020</td><td>Check-ins answered; queued requests are sent to sleepy devices quickly</td></tr><tr class="code-line" data-line="118" dir="auto"><td>OTA Upgrade</td><td>0x0019</td><td>Answered "no image available" (no firmware updates)</td></tr><tr class="code-line" data-line="119" dir="auto"><td>Door Lock</td><td>0x0101</td><td>Lock / unlock, lock state, door state, lock operation events as actions</td></tr><tr class="code-line" data-line="120" dir="auto"><td>Window Covering</td><td>0x0102</td><td>Open / close / stop, position and tilt</td></tr><tr class="code-line" data-line="121" dir="auto"><td>Thermostat</td><td>0x0201</td><td>One climate entity: temperature, setpoint, modes, running state</td></tr><tr class="code-line" data-line="122" dir="auto"><td>Fan Control</td><td>0x0202</td><td>Fan mode</td></tr><tr class="code-line" data-line="123" dir="auto"><td>Thermostat User Interface</td><td>0x0204</td><td>Display unit, keypad lock</td></tr><tr class="code-line" data-line="124" dir="auto"><td>Color Control</td><td>0x0300</td><td>Color, color temperature with the light's own range; remote color commands as actions</td></tr><tr class="code-line" data-line="125" dir="auto"><td>Illuminance</td><td>0x0400 / 0x0401</td><td>Illuminance in lux, level status</td></tr><tr class="code-line" data-line="126" dir="auto"><td>Temperature / Pressure / Flow / Humidity</td><td>0x0402 / 0x0403 / 0x0404 / 0x0405</td><td>Measurements</td></tr><tr class="code-line" data-line="127" dir="auto"><td>Occupancy</td><td>0x0406</td><td>Occupancy</td></tr><tr class="code-line" data-line="128" dir="auto"><td>CO2 / PM2.5</td><td>0x040D / 0x042A</td><td>CO2 in ppm, PM2.5 in µg/m³</td></tr><tr class="code-line" data-line="129" dir="auto"><td>IAS Zone</td><td>0x0500</td><td>Alarm by zone type (motion, door, smoke, water leak, CO, vibration, ...), tamper, battery low</td></tr><tr class="code-line" data-line="130" dir="auto"><td>IAS ACE</td><td>0x0501</td><td>Keypads / alarm remotes: arm / disarm / panic as actions; the hub answers the keypad and keeps the panel status (a select in Home Assistant)</td></tr><tr class="code-line" data-line="131" dir="auto"><td>IAS WD</td><td>0x0502</td><td>Siren entity: tone, volume, duration</td></tr><tr class="code-line" data-line="132" dir="auto"><td>Metering</td><td>0x0702</td><td>Energy / gas / water totals in the meter's own unit, instantaneous demand (power)</td></tr><tr class="code-line" data-line="133" dir="auto"><td>Electrical Measurement</td><td>0x0B04</td><td>Voltage, current, power with the device's own multipliers and divisors</td></tr><tr class="code-line" data-line="134" dir="auto"><td>Tuya</td><td>0xEF00</td><td>Datapoints through converters</td></tr></tbody></table>

A dimmable endpoint (On/Off + Level, optionally Color) appears as one light, not as a switch and a number. An attribute the device answers as "unsupported" gets no entity.

### Home Assistant

Enable **Home Assistant MQTT Discovery** on the **Zigbee Hub → MQTT** page (discovery prefix: `homeassistant` by default). The hub then publishes the discovery of every device after each MQTT connection.

- **Devices**: every Zigbee device becomes a Home Assistant device, named with the name you give it in the hub, with its model and manufacturer.
- **Entities**: sensor, binary sensor, switch, light, cover, climate, fan, lock, siren, number, select, button, text.
- **Actions**: buttons and remotes appear as device triggers, ready for automations.
- **Availability**: with device availability on, entities become unavailable while the device is offline.
- **Groups**: a group appears as a light (members with brightness / color) or a switch.
- **Stale entities**: when a device gets a new converter, the old entities it no longer has can be deleted. Use **Delete all Home Assistant discovery of the device** in the device dialog; the current entities are published again right after.
- **Retain**: "Use retain for data topics" keeps the last values on the broker. With the timestamp on, you can see how old a retained value is.

### Zigbee network management

- **Channel change**: pick a new channel on the settings page, or send the MQTT action `channel_change`. The hub tells the devices to move with it; sleeping devices follow when they wake up. No re-pairing is needed. The result arrives on `system_info/channel`.
- **Network key**: 
    - **Use your own key**: the default key is the same on every hub, so generate your own for a new network. A new key on the settings page forms a new network.
    - **Change the key keeping the devices**: the hub sends the new key to every device, then switches the network to it. A device that missed the key rejoins through the trust center.
- **Install codes**: for devices that join only with their install code. Enter the code in the permit join dialog, or send the MQTT action `add_install_code`. Accepted formats: QR code text (`Z:...$I:...`), Aqara, Hue, `<ieee>|<code>`.
- **Leaves and rejoins**: 
    - A device that leaves the network is removed after 60 s, unless it comes back.
    - A factory-reset device paired again keeps its name and settings.
    - A device unknown to the hub (for example, from an old network) is asked to leave.
- **Radio watchdog**: the hub checks the radio regularly and restarts it if it stops answering.

---

## 4.2 Zigbee Hub → Dashboard

The **Dashboard** is the central monitoring page for your Zigbee network.

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2025-08/scaled-1680-/keCimage.png)](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.

### Sensor history

Numeric sensors store a history of changes over the last 24 hours with a 5-minute interval; in the dashboard, such sensors are marked with a graph icon.

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

To check the history, hover the cursor over the sensor and left-click.

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

You will see a modal window with a graph of sensor changes. You can select a time range: 1h, 6h, or 24h.

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

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

<p class="callout info">The hub stores information in **5-minute intervals**, including the maximum, minimum, and average.</p>

<p class="callout warning">This functionality is available only on U devices.</p>

---

## 4.3 Zigbee Hub → Devices

The **Devices** page lists every Zigbee device paired to your coordinator.

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2025-08/scaled-1680-/527image.png)](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 [![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/image.png)](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/image.png)

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/TD5image.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[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/5YYimage.png)](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/5YYimage.png)

##### Binding

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/cSRimage.png)](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

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/Gr5image.png)](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/Gr5image.png)

##### Polling

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/FPwimage.png)](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

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/VReimage.png)](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/VReimage.png)

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/Yh4image.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.

<p class="callout info">**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!  
</p>

##### Other tools

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-04/scaled-1680-/wBBimage.png)](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

---

## ZCN Builder

A helper tool to facilitate the creation of custom Berry converters for your Zigbee devices.

Full manual: [https://smlight.tech/support/manuals/books/slzb-os/page/berry-zcn-system-manual](https://smlight.tech/support/manuals/books/slzb-os/page/berry-zcn-system-manual)

[![192.168.1.4&#95;zhub&#95;zcn&#95;builder (1).png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-10/scaled-1680-/192-168-1-4-zhub-zcn-builder-1.png)](https://smlight.tech/support/manuals/uploads/images/gallery/2026-10/192-168-1-4-zhub-zcn-builder-1.png)

---

## Network Map

Visual representation of your Zigbee network.

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

---

## Groups

This page allows you to combine multiple Zigbee relays or lamps into a single group and control them all simultaneously with a single command.

Supports up to 32 groups of 32 members each.

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

---

## 4.4 Zigbee Hub → MQTT

#### v3.2.4 and later OS versions

<p class="callout warning">Starting with v3.2.4, MQTT can be used independently of the Zigbee Hub and all general MQTT settings have been moved to a separate page.</p>

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

#### OS versions up to v3.2.4

This page configures the MQTT connection that SLZB-OS uses to communicate with your smart home platform.

<p class="callout warning">This screenshot shows an older version of the page</p>

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2025-08/scaled-1680-/OHQimage.png)](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: `zhub`).
- **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.

---

## Backup and Restore[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2026-10/scaled-1680-/a0yimage.png)](https://smlight.tech/support/manuals/uploads/images/gallery/2026-10/a0yimage.png)

1. Creates a new full backup
2. Allows you to upload a backup to the device's storage
3. Specifies to restore this backup
4. Downloads this backup to your PC
5. Delete this backup

---

## 4.5 Zigbee Hub → Settings

The **Settings** page contains deeper configuration for the Zigbee coordinator.

#### v3.4.3.dev3 and later

<p class="callout warning">SLZB-OS uses a **well-known** default network key!  
If you want to achieve maximum security, you should **generate a random network key**.</p>

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

##### Network key

Generate - generates a new random network key.  
Default - sets the default network key.  
Change the key keeping the devices - Initiates the network key migration procedure while retaining most of your devices. Some sleeping devices may not receive the new key if they are asleep at the time of migration.

##### Device converters

Allow downloading device converters from the SMLIGHT server - Enables the downloading (and periodic updating) of special `.zcf` converters for your paired Zigbee devices. These converters are required to provide support for non-standard Zigbee devices and vendor-locked devices.

When this option is enabled, the Zigbee Hub will send the **model** and **manufacturer** of a newly paired Zigbee device to our server to search for an available converter, if one is found, it will be downloaded. **NO ANY PERSONAL DATA IS SENDED!**  
The Zigbee Hub will check for converter updates every 24 hours.

**<span style="color: rgb(224, 62, 45);">If this option is disabled, support for non-standard Zigbee devices will not be available.</span>**

##### Device availability

Tracks Zigbee packets from your devices and stores the timestamp of the last received packet. If this time exceeds the limit specified in the settings, it will mark the device as unavailable in the dashboard and via MQTT discovery.

#### Older OS versions

[![image.png](https://smlight.tech/support/manuals/uploads/images/gallery/2025-08/scaled-1680-/dJpimage.png)](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 &amp; 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 network

<p class="callout info">OS v3.0.9 update is breaking. If you updated OS to v3.0.9 and started getting this error then follow the instructions below</p>

<div id="bkmrk-network-commissionin"><div>**Network commissioning timed out - most likely network with the same panId or extendedPanId already exists nearby.**  
<div><div>**Network formation refused there is too much RF interference or network with the same panId or extendedPanId already exists.**</div></div></div></div><div id="bkmrk-if-you-got-this-erro"><div>If you got this error after updating Zigbee chip:  
- turn off coordinator  
- turn off ALL Zigbee routers that were connected to Zigbee Hub. **This is important, it will not work without this**  
- turn on coordinator. Zigbee Hub should start now but zigbee devices will be unavailable  
- remove all devices (click on the red trash can)  
- download and run berry script below, this script will keep permit join enabled as long as it is running</div></div>

```python
#META {"start":0}
#Insert your code below
import ZHB

ZHB.waitForStart(0xFF)

while 1
  ZHB.permitJoin(254)
  SLZB.delay(255 * 1000)
end
```

<div id="bkmrk---turn-back-on-previ"><div>- turn back on previously disabled zigbee devices  
- repair all devices  
- after devices repaired you can stop and delete script</div></div><div id="bkmrk--28">  
</div><div id="bkmrk-other-cases%3A--move-t">Other cases:  
- move the coordinator away from the wifi router  
- make sure there is no other coordinator nearby with the same zigbee network settings  
</div>

# MQTT API

Zigbee Hub mode has the ability to connect to local or remote MQTT/MQTTS brokers.  
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

`<base>` is the base topic of the MQTT settings; `<ieee>` is the device's IEEE address in hex (16 digits).

<table class="code-line" data-line="190" dir="auto" id="bkmrk-topic-direction-purp" style="width: 111.667%;"><thead class="code-line" data-line="190" dir="auto"><tr class="code-line" data-line="190" dir="auto"><th style="width: 26.4601%;">Topic</th><th style="width: 9.29536%;">Direction</th><th style="width: 64.2446%;">Purpose</th></tr></thead><tbody class="code-line" data-line="192" dir="auto"><tr class="code-line" data-line="192" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;data&#47;&#60;ieee&#62;&#47;&#60;ep&#62;&#47;&#60;cluster&#62;&#47;&#60;attr&#62;</code></td><td style="width: 9.29536%;">**OUT**</td><td style="width: 64.2446%;">Values: <code>&#123;&#34;data&#34;&#58;&#123;&#34;val&#34;&#58;&#46;&#46;&#46;&#125;&#125;</code> (with <code>&#34;ts&#34;</code> when the timestamp is on, see below); <code>&#60;attr&#62;&#95;&#60;sub&#62;</code> for a field of a value</td></tr><tr class="code-line" data-line="193" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;data&#47;&#60;ieee&#62;&#47;lqi</code></td><td style="width: 9.29536%;">**OUT**</td><td style="width: 64.2446%;">Link quality of the device</td></tr><tr class="code-line" data-line="194" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;cmd&#47;&#60;ieee&#62;&#47;&#60;ep&#62;&#47;&#60;cluster&#62;&#47;&#60;cmd&#62;</code></td><td style="width: 9.29536%;">**IN**</td><td style="width: 64.2446%;">Cluster commands (payload: the command's value, or raw hex)</td></tr><tr class="code-line" data-line="195" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;write&#47;&#60;ieee&#62;&#47;&#60;ep&#62;&#47;&#60;cluster&#62;&#47;&#60;attr&#62;</code></td><td style="width: 9.29536%;">**IN**</td><td style="width: 64.2446%;">Attribute writes</td></tr><tr class="code-line" data-line="196" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;read&#47;&#60;ieee&#62;&#47;&#60;ep&#62;&#47;&#60;cluster&#62;&#47;&#60;attr&#62;</code></td><td style="width: 9.29536%;">**IN**</td><td style="width: 64.2446%;">Attribute reads</td></tr><tr class="code-line" data-line="197" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;gcmd&#47;&#60;group&#62;&#47;&#60;cluster&#62;&#47;&#60;cmd&#62;</code></td><td style="width: 9.29536%;">**IN**</td><td style="width: 64.2446%;">Group commands: On/Off <code>ON</code> / <code>OFF</code> / <code>TOGGLE</code>, Level 1..254, Color <code>&#35;rrggbb</code> / <code>r&#44;g&#44;b</code>, color temperature (mireds)</td></tr><tr class="code-line" data-line="198" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;gdata&#47;&#60;group&#62;&#47;&#60;cluster&#62;&#47;&#60;attr&#62;</code></td><td style="width: 9.29536%;">**OUT**</td><td style="width: 64.2446%;">Group state from its members</td></tr><tr class="code-line" data-line="199" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;availability&#47;&#60;ieee&#62;</code></td><td style="width: 9.29536%;">**OUT**</td><td style="width: 64.2446%;"><code>online</code> / <code>offline</code> (retained, when availability is on)</td></tr><tr class="code-line" data-line="200" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;system&#95;control</code></td><td style="width: 9.29536%;">**IN**</td><td style="width: 64.2446%;">Hub actions (below)</td></tr><tr class="code-line" data-line="201" dir="auto"><td style="width: 26.4601%;"><code>&#60;base&#62;&#47;system&#95;info&#47;&#60;event&#62;</code></td><td style="width: 9.29536%;">**OUT**</td><td style="width: 64.2446%;">Events: <code>device&#95;joined</code>, <code>device&#95;annonce</code>, <code>device&#95;leave</code>, <code>device&#95;removed</code>, <code>device&#95;limit</code>, <code>device&#95;request</code>, <code>device&#95;converter</code>, <code>attr&#95;write&#95;rsp</code>, <code>data&#95;confirm</code>, <code>channel</code>, <code>nwk&#95;key</code></td></tr></tbody></table>

**Timestamp** (Zigbee Hub → MQTT → "Timestamp in data reports", off by default): every value report, link quality and group state gets `"ts"`, the time the hub received the value. Formats:

<table class="code-line" data-line="205" dir="auto" id="bkmrk-setting-example-iso_" style="width: 103.571%; height: 120.125px;"><thead class="code-line" data-line="205" dir="auto"><tr class="code-line" data-line="205" dir="auto" style="height: 29.7969px;"><th style="width: 21.3333%; height: 29.7969px;">Setting</th><th style="width: 78.6667%; height: 29.7969px;">Example</th></tr></thead><tbody class="code-line" data-line="207" dir="auto"><tr class="code-line" data-line="207" dir="auto" style="height: 30.1094px;"><td style="width: 21.3333%; height: 30.1094px;"><code>ISO&#95;8601</code></td><td style="width: 78.6667%; height: 30.1094px;"><code>&#34;2026&#45;10&#45;21T07&#58;15&#58;30Z&#34;</code></td></tr><tr class="code-line" data-line="208" dir="auto" style="height: 30.1094px;"><td style="width: 21.3333%; height: 30.1094px;"><code>ISO&#95;8601&#95;Local</code></td><td style="width: 78.6667%; height: 30.1094px;"><code>&#34;2026&#45;10&#45;21T10&#58;15&#58;30&#43;03&#58;00&#34;</code> (the time zone set on the SLZB device)</td></tr><tr class="code-line" data-line="209" dir="auto" style="height: 30.1094px;"><td style="width: 21.3333%; height: 30.1094px;"><code>epoch</code></td><td style="width: 78.6667%; height: 30.1094px;"><code>1792566930</code> (**seconds**)</td></tr></tbody></table>

```
{"data": {"type_sm": "report", "val": "21.50", "status": "SUCCESS", "ts": "2026-10-21T07:15:30Z"}}
<button aria-label="Copy code block" class="code-block-copy-button"><svg aria-hidden="true" fill="none" focusable="false" height="16" viewbox="0 0 16 16" width="16"><path d="M4 4H2V14H11V12H4V4Z" fill="currentColor"></path><path clip-rule="evenodd" d="M5 2H14V11H5V2ZM6 3H13V10H6V3Z" fill="currentColor" fill-rule="evenodd"></path></svg></button>
```

<p class="callout info">There is no timestamp until the SLZB device has set its clock over NTP.</p>

### 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><code>Last state</code> - device will remember its state</div><div><code>ON</code> - device will be on after power loss  
<code>OFF</code> - 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><code>data</code> - a HEX string of the following format:  
\- Bytes without spaces, uppercase, multiple of two. Example: <code>010203FF</code>  
\- Bytes with spaces, uppercase, grouped by two. Example: <code>01 02 03 FF</code>

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;}

```json
{"action": "permit_join", "time": 60}
{"action": "channel_change", "channel": 25}
{"action": "nwk_key_rotate"}
{"action": "add_install_code", "code": "Z:00124B00...$I:..."}
{"action": "binding", "mode": "to_coordinator", "scrIeee": "...", "scrEp": 1, "scrCl": 6}
{"action": "binding", "mode": "to_device", "scrIeee": "...", "scrEp": 1, "scrCl": 6, "dstIeee": "...", "dstEp": 1}
{"action": "configure_reporting", "ieee": "...", "ep": 1, "cl": 1026, "attr": 0, "dType": 41, "minRep": 10, "maxRep": 3600, "change": 10}

```

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

# Berry ZCN system manual

<p class="callout info">Everything here requires the device to run in **Zigbee Hub** mode and SLZB-OS **v3.3.8.dev0** or **higher.**</p>

This document describes the **Berry** side of the ZCN converter system: writing device-specific Zigbee Hub converters as Berry scripts, without rebuilding the firmware.

The concept of ZCN primarily refers to native C++ converters, but we decided to keep this name for Berry converters for simplicity. Actually Berry converters are not native, they are a scripting interface.

---

## 1. What Berry ZCN is and when to use it

A Berry ZCN converter is the runtime-scriptable twin of a native `zcn_converter_t`: a description of how a specific Zigbee device deviates from standard ZCL handling — extra/proprietary attributes, remapped clusters, custom value normalization, custom MQTT/Home Assistant discovery — plus Berry callback functions that the hub invokes at the same points where native converters invoke C function pointers.

Use Berry ZCN when you want to:

- **Prototype** a converter for a new device without a firmware rebuild — iterate directly in the on-device script editor, then port the result to a native converter for shipping.
- **Support a device locally** that the stock firmware does not have a converter for.
- **Experiment** with normalization/serialization/discovery logic against a live device.

---

## 2. Architecture and lifecycle

### 2.1 Slots

There are  **(currently 2) slots** for Berry converters. Each registered converter occupies one slot. Registration fails with `"no free slots for ZCN"` when all slots are taken.

### 2.2 VM binding and garbage collection

- A converter belongs to the **VM that registered it**.
- All callback functions passed into the structure are **GC-pinned** while the converter exists, and unpinned on delete — you can use closures/anonymous `def` blocks safely.
- When a script's VM stops, **all its converters are automatically deleted**. Restarting the script re-registers them.

### 2.3 Attachment is NOT persisted — attach on every boot

This is the most important lifecycle difference from native ZCN:

- The native converter index is saved in the device database and restored on boot.
- The Berry converter index is **runtime-only**. It resets every boot and is set only by: 
    1. **Interview matching** — during a device interview.
    2. **Explicit `ZCN.attach(slot, ieee)`** from your script.

Since interviews only run at pairing, a converter script must call `ZCN.attach()` for its devices every time it starts. The standard pattern:

```python
var slot = ZCN.register(my_converter)
ZCN.attach(slot, "0x3425b4fffe12e9e9") # repeat for each device
```

Optional, run the script with autostart (`#META {"start":1}`) so the converter is registered and attached right after boot.

### 2.4 Priority over native converters

Berry converters take priority everywhere:

- **Interview matching**: all Berry slots are checked *first*; if one matches, is set and native matching is skipped.
- **Runtime dispatch**: every hook site checks `ZCN_CHECK_BE(dev)` before the native `ZCN_CHECK(dev)` — data handling, on\_cmd, MQTT write/cmd, HA discovery, trigger discovery. A device can technically have both `zcn` and `zcn_be` set; the Berry one is consulted first wherever it provides an override.

### 2.5 Matching logic

- If the converter has a **`matcher` function** — it is called as `def (dev)` with a `ZigbeeDevice` instance and must return `true`/`false`. `model`/`manuf` strings are ignored.
- Otherwise — exact string compare of **both** `manuf` (Basic attr 0x0004) and `model` (Basic attr 0x0005) against the interviewed values.

---

## 3. Quick start

The easiest way to produce a converter is the **ZCN Builder** page in the web UI (*Zigbee Hub → ZCN Builder*): assemble the structure in the form, pick callback presets, and copy the generated Berry code.

`ZCN.register()` validates the map, finds a free slot, and feeds the structure into the native slot. It returns the **slot number** (needed for `ZCN.attach`) and raises a descriptive error on failure (the partially built slot is deleted automatically).

---

## 4. Converter map reference

The converter is a plain Berry `map`. Missing keys get defaults: **int → 0, string → `""`, bool → `false`, function → `nil`** (exceptions noted below). Extra/unknown keys are ignored.

### 4.1 Top level

<table id="bkmrk-key-type-required-me"><thead><tr><th>Key</th><th>Type</th><th>Required</th><th>Meaning</th></tr></thead><tbody><tr><td><code>signature</code></td><td>map</td><td>**yes** (raises otherwise)</td><td>Device matching, see below</td></tr><tr><td><code>on&#95;annonce</code></td><td>function</td><td>no</td><td>Called when the device announces itself (power-on / rejoin)</td></tr><tr><td><code>on&#95;intw&#95;stage</code></td><td>function</td><td>no</td><td>Called before interview stages; see §5.2</td></tr><tr><td><code>overrides&#95;count</code></td><td>int</td><td>yes, if <code>overrides</code> present</td><td>**Must equal** <code>overrides&#46;size&#40;&#41;</code> — it is not derived automatically</td></tr><tr><td><code>overrides</code></td><td>list of maps</td><td>no</td><td>Endpoint overrides</td></tr></tbody></table>

### 4.2 `signature`

The signature tells SLZB-OS whether this converter is suitable for the device for which the interview is currently being performed.

<table id="bkmrk-key-type-meaning-mat"><thead><tr><th>Key</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>matcher</code></td><td>function</td><td>If present, used instead of model/manuf. Must be a function</td></tr><tr><td><code>model</code></td><td>string</td><td>Zigbee model identifier (exact match via strcmp())</td></tr><tr><td><code>manuf</code></td><td>string</td><td>Manufacturer name (exact match)</td></tr></tbody></table>

### 4.3 Endpoint override (element of `overrides`)

<table id="bkmrk-key-type-meaning-end"><thead><tr><th>Key</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>endpoint</code></td><td>int</td><td>Zigbee endpoint number this override applies to</td></tr><tr><td><code>clusterCount</code></td><td>int</td><td>Number of clusters in <code>clusters</code></td></tr><tr><td><code>clusters</code></td><td>list of maps</td><td>Cluster object array</td></tr></tbody></table>

### 4.4 Cluster override (element of `clusters`)

<table id="bkmrk-key-type-default-mea" style="width: 100%;"><thead><tr><th style="width: 14.3027%;">Key</th><th style="width: 9.41597%;">Type</th><th style="width: 6.45156%;">Default</th><th style="width: 69.8297%;">Meaning</th></tr></thead><tbody><tr><td style="width: 14.3027%;"><code>id</code></td><td style="width: 9.41597%;">int</td><td style="width: 6.45156%;">0</td><td style="width: 69.8297%;">ZCL cluster id (e.g. <code>0x0402</code>)</td></tr><tr><td style="width: 14.3027%;"><code>addMode</code></td><td style="width: 9.41597%;">int</td><td style="width: 6.45156%;">0</td><td style="width: 69.8297%;"><code>0</code> = ADD (merge with the standard cluster: your attrs are used where ids collide, standard attrs fill the rest),  
<code>1</code> = OVERRIDE (standard cluster fully ignored; only your definition used)</td></tr><tr><td style="width: 14.3027%;"><code>bind</code></td><td style="width: 9.41597%;">bool</td><td style="width: 6.45156%;">false</td><td style="width: 69.8297%;">Bind this cluster to the hub during interview</td></tr><tr><td style="width: 14.3027%;"><code>attrCount</code></td><td style="width: 9.41597%;">int</td><td style="width: 6.45156%;">0</td><td style="width: 69.8297%;">Number of attributes in <code>attrs</code></td></tr><tr><td style="width: 14.3027%;"><code>attrs</code></td><td style="width: 9.41597%;">list of maps</td><td style="width: 6.45156%;">—</td><td style="width: 69.8297%;">Attribute objects array</td></tr><tr><td style="width: 14.3027%;"><code>cmd&#95;config</code></td><td style="width: 9.41597%;">map</td><td style="width: 6.45156%;">—</td><td style="width: 69.8297%;">Cluster **command** handling (buttons/actions), see below</td></tr><tr><td style="width: 14.3027%;"><code>on&#95;mqtt&#95;cmd</code></td><td style="width: 9.41597%;">function</td><td style="width: 6.45156%;">nil</td><td style="width: 69.8297%;">Used for <code>cmd&#95;config</code>.  
Handles MQTT messages on the <code>&#123;base&#125;&#47;cmd&#47;&#46;&#46;&#46;</code> topic for this cluster. Return <code>true</code> = handled (standard handling skipped)</td></tr></tbody></table>

### 4.5 `cmd_config`

Tells SLZB-OS what actions(triggers) this cluster provides. Typically used for Zigbee buttons and scene remotes.

<table id="bkmrk-key-type-meaning-on_" style="width: 100%;"><thead><tr><th style="width: 11.323%;">Key</th><th style="width: 8.34213%;">Type</th><th style="width: 80.3349%;">Meaning</th></tr></thead><tbody><tr><td style="width: 11.323%;"><code>on&#95;cmd</code></td><td style="width: 8.34213%;">function</td><td style="width: 80.3349%;">Converts the received command record into an action string (e.g. <code>&#34;btn&#95;single&#34;</code>).

Must return a **string** to publish it as an action.

</td></tr><tr><td style="width: 11.323%;"><code>exposes</code></td><td style="width: 8.34213%;">string</td><td style="width: 80.3349%;"><code>&#34;&#124;&#34;</code>-separated list of all possible action strings — used to generate device-trigger discovery</td></tr><tr><td style="width: 11.323%;"><code>exposesOverride</code></td><td style="width: 8.34213%;">function</td><td style="width: 80.3349%;">Dynamic alternative to <code>exposes</code>: return the <code>&#34;&#124;&#34;</code>-separated list at discovery time; empty-string return skips triggers for this cluster</td></tr></tbody></table>

Note: the command path is only taken when the cluster has `on_cmd` **and** at least one of `exposes` / `exposesOverride`.

### 4.6 Attribute override (element of `attrs`)

<table id="bkmrk-key-type-default-mea-1" style="width: 100%;"><thead><tr><th style="width: 19.0703%;">Key</th><th style="width: 8.82002%;">Type</th><th style="width: 6.20225%;">Default</th><th style="width: 65.9074%;">Meaning</th></tr></thead><tbody><tr><td style="width: 19.0703%;"><code>id</code></td><td style="width: 8.82002%;">int</td><td style="width: 6.20225%;">0</td><td style="width: 65.9074%;">ZCL attribute id</td></tr><tr><td style="width: 19.0703%;"><code>name</code></td><td style="width: 8.82002%;">string</td><td style="width: 6.20225%;">""</td><td style="width: 65.9074%;">Human-readable name (shown in web UI)</td></tr><tr><td style="width: 19.0703%;"><code>mqttClass</code></td><td style="width: 8.82002%;">int</td><td style="width: 6.20225%;">0</td><td style="width: 65.9074%;">MQTT entity type, see table below</td></tr><tr><td style="width: 19.0703%;"><code>mqttSubClass</code></td><td style="width: 8.82002%;">string</td><td style="width: 6.20225%;">""</td><td style="width: 65.9074%;">MQTT entity <code>device&#95;class</code> (e.g. <code>&#34;temperature&#34;</code>, <code>&#34;moisture&#34;</code>)</td></tr><tr><td style="width: 19.0703%;"><code>unit</code></td><td style="width: 8.82002%;">string</td><td style="width: 6.20225%;">""</td><td style="width: 65.9074%;">Unit of measurement (e.g. <code>&#34;°C&#34;</code>)</td></tr><tr><td style="width: 19.0703%;"><code>dataType</code></td><td style="width: 8.82002%;">int</td><td style="width: 6.20225%;">0</td><td style="width: 65.9074%;">ZCL data type.

Required for configuring reporting and if this attribute is writable.

Can be omitted if the attribute is not writable and not reported.

</td></tr><tr><td style="width: 19.0703%;"><code>ram</code></td><td style="width: 8.82002%;">bool</td><td style="width: 6.20225%;">false</td><td style="width: 65.9074%;">If True, ZHB will create a special container (record) for this attribute in RAM at startup. The received value will be cached in this container, only the last value is stored.</td></tr><tr><td style="width: 19.0703%;"><code>rp</code></td><td style="width: 8.82002%;">bool</td><td style="width: 6.20225%;">false</td><td style="width: 65.9074%;">Configure attribute reporting during interview. Also adds this attribute to web UI "configure reporting" dialog.</td></tr><tr><td style="width: 19.0703%;"><code>minReport</code></td><td style="width: 8.82002%;">int</td><td style="width: 6.20225%;">1</td><td style="width: 65.9074%;">Reporting: minimum interval, s.  
Can be omitted if <code>rp</code> is <code>false</code></td></tr><tr><td style="width: 19.0703%;"><code>maxReport</code></td><td style="width: 8.82002%;">int</td><td style="width: 6.20225%;">3600</td><td style="width: 65.9074%;">Reporting: maximum interval, s.  
Can be omitted if <code>rp</code> is <code>false</code></td></tr><tr><td style="width: 19.0703%;"><code>change</code></td><td style="width: 8.82002%;">int</td><td style="width: 6.20225%;">1</td><td style="width: 65.9074%;">Reporting: reportable change threshold.  
Can be omitted if <code>rp</code> is <code>false</code></td></tr><tr><td style="width: 19.0703%;"><code>rpChangeMult</code></td><td style="width: 8.82002%;">real</td><td style="width: 6.20225%;">0</td><td style="width: 65.9074%;">Multiplier for the web UI "configure reporting" dialog:

raw ZCL reportable change = human value × `rpChangeMult` (e.g. `100` for 0.01-unit temperature).  
Can be omitted if `rp` is `false`

</td></tr><tr><td style="width: 19.0703%;"><code>query</code></td><td style="width: 8.82002%;">bool</td><td style="width: 6.20225%;">false</td><td style="width: 65.9074%;">If True, the coordinator will send a request to read this attribute when the hub starts.</td></tr><tr><td style="width: 19.0703%;"><code>on&#95;normalize</code></td><td style="width: 8.82002%;">function</td><td style="width: 6.20225%;">nil</td><td style="width: 65.9074%;">Tells ZHB how to convert raw Zigbee data into usable data, see §5.4</td></tr><tr><td style="width: 19.0703%;"><code>on&#95;serialization</code></td><td style="width: 8.82002%;">function</td><td style="width: 6.20225%;">nil</td><td style="width: 65.9074%;">Tells ZHB how to convert data in a container (record) into a text representation, see §5.5</td></tr><tr><td style="width: 19.0703%;"><code>on&#95;discovery</code></td><td style="width: 8.82002%;">function</td><td style="width: 6.20225%;">nil</td><td style="width: 65.9074%;">Allow you to customize/veto discovery for this attribute, see §5.6</td></tr><tr><td style="width: 19.0703%;"><code>on&#95;mqtt&#95;write</code></td><td style="width: 8.82002%;">function</td><td style="width: 6.20225%;">nil</td><td style="width: 65.9074%;">Tells ZHB how to handle <code>&#123;base&#125;&#47;write&#47;&#46;&#46;&#46;</code> MQTT messages, see §5.7</td></tr></tbody></table>

`mqttClass` values:

<table id="bkmrk-value-class-0-none-%28"><thead><tr><th>Value</th><th>Class</th></tr></thead><tbody><tr><td>0</td><td>NONE (not exposed to WEB/MQTT)</td></tr><tr><td>1</td><td>BINARY\_SENSOR</td></tr><tr><td>2</td><td>BUTTON</td></tr><tr><td>3</td><td>TRIGGER</td></tr><tr><td>4</td><td><s>EVENT</s> (*Not supported by ZHB dashboard*)</td></tr><tr><td>5</td><td><s>FAN</s> (*Not supported by ZHB dashboard*)</td></tr><tr><td>6</td><td>LIGHT</td></tr><tr><td>7</td><td>NUMBER</td></tr><tr><td>8</td><td>SELECT</td></tr><tr><td>9</td><td>SENSOR</td></tr><tr><td>10</td><td>SWITCH</td></tr><tr><td>11</td><td><s>TEXT</s> (*Not supported by ZHB dashboard*)</td></tr><tr><td>12</td><td><s>COVER</s> (*Not supported by ZHB dashboard*)</td></tr></tbody></table>

---

## 5. Callback reference

All callbacks run inside your script's VM, scheduled through the Berry event system. The hub task waits up to ~20 ms for the VM to become available; if the VM is busy longer (e.g. a blocked loop in your script), the **event is dropped** — keep both the callbacks and the rest of the script non-blocking.

`dev` arguments are `ZigbeeDevice` instances, `record` arguments are `ZclAttrRecord` instances (§6). `doc`/`data` are JSON proxy objects supporting `obj["key"] = value` style access.

### 5.1 on\_annonce

Called when an attached device sends a device announce (typically power-on or rejoin). Return value ignored.

### 5.2 on\_intw\_stage

Called before interview stages, identified by string `tag`. Return one of:

<table id="bkmrk-return-meaning-0-%28do"><thead><tr><th>Return</th><th>Meaning</th></tr></thead><tbody><tr><td><code>0</code> (DONE)</td><td>Stage handled by the converter — hub skips its standard logic and go to next stage</td></tr><tr><td><code>1</code> (WAIT)</td><td>Converter started something async — hub waits, stage will be re-entered</td></tr><tr><td><code>2</code> (ERR)</td><td>Fail interview on this stage</td></tr><tr><td><code>3</code> (ZCN\_UNUSED)</td><td>Converter does not care — hub runs standard logic (**default choice**)</td></tr></tbody></table>

Stage tags: `req_ep`, `discover_ep`, `get_power_source`, `autobind`, `conf_reporting`, `ias_enroll`, `get_ias_type`, `send_tuya_magic`.

Caveat (same as native): on the **first** interview the converter is matched at the `intw_zcn` stage, so tags for stages ordered *before* it (`req_ep`, `discover_ep`) only fire on re-interview — unless the device was pre-attached with `ZCN.attach()`.

### 5.3 cmd\_config.on\_cmd

Called when a ZCL **command** arrives on the cluster (`record.isCmd()` is true; `record.getAttr()` holds the command id). Return the action string to publish (must be one of the `exposes` values for HA to recognize it). Non-string return = not handled.  
Important for Tuya commands: `record.asInt()` contains the ID of the Tuya command and `record.getAttr()` its data.

### 5.4 on\_normalize

Called right after the raw ZCL value is parsed into the record, **before** it is stored and serialized.  
Mutate the record in place:

```python
"on_normalize": def (record, dev)
  record.setFloat(record.asInt() / 100.0)
end
```

You can also *redirect* a record to another cluster/attr (`record.setCl()`, `record.setAttr()`, `record.setEp()`) — e.g. unpacking a proprietary struct into standard records. The redirect target attr must exist (declare it with `ram: true`).

### 5.5 on\_serialization

Called when the stored record is converted to JSON for MQTT / web dashboard.  
Write into `data`:

```python
"on_serialization": def (record, dev, data)
  data["type_sm"] = "report"
  data["val"] = record.asFloat()
end
```

Keys follow the native `zcl_json` convention: `"type_sm"` (usually `"report"`) and `"val"`. If absent, standard serialization for the data type applies.

### 5.6 on\_discovery

Called when generating discovery payload for this attribute. `doc` is the discovery JSON (base payload already filled from `mqttClass`/`mqttSubClass`/`name`/`unit`); `zhbBase` is the MQTT base topic. Add or override keys, e.g. `doc["state_class"] = "measurement"`. In most cases, you only use `doc` if you need to add something (like `min`, `max` and `step` for a slider).

Return `true` to publish, **`false` to veto** discovery of this attribute. Note: with no callback set the attribute is still discovered when `mqttClass != 0`; but if you *do* set a callback, you must return `true` for it to be published.

### 5.7 on\_mqtt\_write

Called for MQTT messages on the `{base}/write/...` topic targeting this attribute. `data` is the raw payload string. Convert and send to the device (`dev.sendCmd`, `dev.sendTuyaData`, etc.). Return `true` = handled (standard ZCL write skipped).

### 5.8 on\_mqtt\_cmd (cluster level)

Same idea for the `{base}/cmd/...` topic — cluster commands sent from MQTT (e.g. switch toggles). Return `true` = handled.

---

## 6. Objects available in callbacks

### 6.1 ZigbeeDevice - Berry Zigbee device proxy

<table id="bkmrk-method-description-m"><thead><tr><th>Method</th><th>Description</th></tr></thead><tbody><tr><td><code>matcher&#40;manuf&#44; model&#41; &#45;&#62; bool</code></td><td>Exact manuf+model compare</td></tr><tr><td><code>getName&#40;&#41;</code> / <code>getIeee&#40;&#41;</code> / <code>getModel&#40;&#41;</code> / <code>getManuf&#40;&#41;</code> / <code>getNwk&#40;&#41;</code></td><td>Identity</td></tr><tr><td><code>hasName&#40;&#41;</code> / <code>setName&#40;s&#41;</code> / <code>setModel&#40;s&#41;</code> / <code>setManuf&#40;s&#41;</code></td><td>Identity write access (e.g. normalizing Tuya <code>&#95;TZE200&#95;&#46;&#46;&#46;</code> model strings in a <code>matcher</code>)</td></tr><tr><td><code>getPS&#40;&#41;</code> / <code>setPS&#40;v&#41;</code></td><td>Power source (<code>CONST&#95;ZCL&#95;PS&#46;&#42;</code>)</td></tr><tr><td><code>getBattery&#40;&#41;</code> / <code>getLqi&#40;&#41;</code> / <code>getLastSeen&#40;&#41;</code></td><td>Telemetry</td></tr><tr><td><code>getIAS&#40;&#41;</code> / <code>setIAS&#40;v&#41;</code></td><td>IAS zone type (<code>CONST&#95;ZCL&#95;IAS&#46;&#42;</code>)</td></tr><tr><td><code>isBattery&#40;&#41;</code> / <code>isAc&#40;&#41;</code> / <code>isTuya&#40;&#41;</code> / <code>haveTuyaDP&#40;&#41;</code> / <code>isInterviewing&#40;&#41;</code> / <code>isZcnUsed&#40;&#41;</code></td><td>State predicates (<code>isZcnUsed</code> = a **native** converter is attached)</td></tr><tr><td><code>haveEndpoint&#40;ep&#41;</code> / <code>addEp&#40;ep&#41;</code> / <code>removeEp&#40;ep&#41;</code></td><td>Endpoint list management (<code>addEp</code> creates an empty endpoint — populate it with <code>addInCluster</code>/<code>addOutCluster</code>)</td></tr><tr><td><code>hasInCluster&#40;cl&#41;</code> / <code>addInCluster&#40;cl &#91;&#44; ep&#93;&#41;</code></td><td>Input cluster list (ep 0 / omitted = first endpoint); duplicate-safe</td></tr><tr><td><code>hasOutCluster&#40;cl&#41;</code> / <code>addOutCluster&#40;cl &#91;&#44; ep&#93;&#41;</code></td><td>Output cluster list, same semantics</td></tr><tr><td><code>removeCluster&#40;ep&#44; cl&#41;</code></td><td>Remove a single input cluster from an endpoint ("ignore cluster X" quirks)</td></tr><tr><td><code>getVal&#40;ep&#44; cl&#44; attr&#41;</code> / <code>setVal&#40;ep&#44; cl&#44; attr&#44; value&#41;</code></td><td>Read / update a stored record value (<code>setVal</code> accepts bool/int/real/string/bytes and only updates an **existing** record)</td></tr><tr><td><code>addRecord&#40;ep&#44; cl&#44; attr&#41;</code> / <code>haveRecord&#40;ep&#44; cl&#44; attr&#41;</code> / <code>removeRecord&#40;ep&#44; cl&#44; attr&#41;</code> / <code>removeAllRecords&#40;&#41;</code></td><td>RAM record management</td></tr><tr><td><code>queryAllRecords&#40;&#91;pauseMs&#93;&#41;</code> / <code>queryMissingRecords&#40;&#91;pauseMs&#93;&#41;</code></td><td>Actively read all / value-less records from the device (**warning**: a non-zero pause blocks the script and the hub for pause × records ms — prefer 0)</td></tr><tr><td><code>startPooling&#40;intervalSec&#44; ep&#44; cl&#44; attr&#41;</code> / <code>stopPooling&#40;ep&#44; cl&#44; attr&#41;</code></td><td>Periodic attribute polling driven by the hub task</td></tr><tr><td><code>sendOnOff</code> / <code>sendBri</code> / <code>sendColor</code> / <code>sendColorTemp</code></td><td>High-level actuator commands</td></tr><tr><td><code>sendCmd&#40;ep&#44; cl&#44; cmd &#91;&#44; bytes&#93;&#41;</code></td><td>Raw ZCL cluster command</td></tr><tr><td><code>sendTuyaData&#40;dp&#44; ztype&#44; val&#41;</code></td><td>Tuya 0xEF00 datapoint write</td></tr><tr><td><code>sendTuyaQuery&#40;&#41;</code> / <code>sendTuyaMagic&#40;&#41;</code></td><td>Tuya: query all datapoints / send the "magic" init packet (typical in <code>on&#95;annonce</code>)</td></tr><tr><td><code>readAttr&#40;ep&#44; cl&#44; attr&#46;&#46;&#46;&#41;</code></td><td>ZCL Read Attributes request</td></tr><tr><td><code>writeAttr&#40;ep&#44; cl&#44; attr&#44; dType&#44; bytes&#41;</code></td><td>ZCL Write Attribute with a raw payload (for custom <code>on&#95;mqtt&#95;write</code> handlers)</td></tr><tr><td><code>confReporting&#40;ep&#44; cl&#44; attr&#44; dType&#44; minReport&#44; maxReport&#44; change&#41;</code></td><td>ZCL Configure Reporting (for custom <code>on&#95;intw&#95;stage&#40;&#34;conf&#95;reporting&#34;&#41;</code> handling)</td></tr><tr><td><code>nodeDescReq&#40;&#41;</code> / <code>simpleDescReq&#40;ep&#41;</code> / <code>reqEndpoints&#40;&#41;</code></td><td>Low-level ZDO requests; responses are processed by the interview state machine, so these are mainly useful inside <code>on&#95;intw&#95;stage</code></td></tr><tr><td><code>bindToHub</code> / <code>bindToDevice</code> / <code>bindToGroup</code></td><td>Binding operations</td></tr><tr><td>*(module-level)* <code>ZHB&#46;await&#40;seq &#91;&#44; timeoutMs&#93;&#41; &#45;&#62; bool</code> / <code>ZHB&#46;lastStatus&#40;&#41;</code> / <code>ZHB&#46;on&#95;response&#40;seq&#44; cb&#40;ok&#44; status&#41; &#91;&#44; timeoutMs&#93;&#41; &#45;&#62; bool</code></td><td>Wait for the device's response to a previous send (sync / async); the device is resolved from <code>seq</code>. **<code>ZHB&#46;await&#40;&#41;</code> raises inside ZCN callbacks** — they run on the ZHB task; use <code>ZHB&#46;on&#95;response&#40;&#41;</code> there. See <code>docs&#47;slzb&#45;os&#45;scripts&#47;docs&#47;modules&#47;zhb&#46;md</code></td></tr></tbody></table>

### 6.2 ZclAttrRecord - Zigbee data container

Getters: `getEp()`, `getCl()`, `getAttr()`, `getStatus()`, `getZtype()` (raw ZCL type), `getSMtype()` (internal storage type, compare against `ZclAttrRecord.TYPE_*` constants: `TYPE_NONE/U32/I32/FLOAT/BUF/STR/BOOL/CMD/CMD_PAYLOAD`).

Predicates: `isCmd()`, `isCmdPayload()`, `isTuya()` (cluster == 0xEF00), `hasPayload()` (type is not `TYPE_NONE`), `matcher(cl, attr [, ep]) -> bool`.

Value access: `asInt()`, `asFloat()`, `asStr()`, `asBytes()`, `asLumiStruct([start])` — parses the Lumi/Aqara proprietary struct (Basic 0xFF01/0xFF02 buffer) into a `{tag_id: int}` map; `getMSB16()` / `getLSB16()` — high/low 16-bit halves of the raw 32-bit value (e.g. packed color X/Y).

Mutation: `setInt(v)`, `setUInt(v)`, `setFloat(v)`, `setBool(v)`, `setStr(v)`, `setBuf(bytes)` (replaces the payload with a copy of a Berry `bytes()` buffer, 1–255 bytes), `setCmd(cmdId [, tuyaCluster])`, `setMSB16(v)` / `setLSB16(v)`, `setEp(v)`, `setCl(v)`, `setAttr(v)`.

---

## 7. ZCNP — native callback presets

The `ZCNP` module exposes ready-made **preset functions** used by built-in converters, so a Berry converter can reference them directly instead of re-implementing the logic:

```python
import ZCNP
...
"on_normalize": ZCNP.zcn_norm_i16_divide_100, # the received zigbee value has data type int16 and needs to be divided by 100 to convert it to float
"on_serialization": ZCNP.zcn_ser_float, # the received value is converted to float, so we convert float to string
"on_discovery": ZCNP.zcn_dis_gen_basic_measurement, # add "measurement" class on discovery
```

<table id="bkmrk-kind-functions-norma"><thead><tr><th>Kind</th><th>Functions</th></tr></thead><tbody><tr><td>normalize</td><td><code>zcn&#95;norm&#95;i16&#95;divide&#95;10&#47;100&#47;1000</code>, <code>zcn&#95;norm&#95;u16&#95;divide&#95;10&#47;100&#47;1000</code>, <code>zcn&#95;norm&#95;lumi&#95;basic</code></td></tr><tr><td>serialization</td><td><code>zcn&#95;ser&#95;float</code>, <code>zcn&#95;ser&#95;raw&#95;uint</code>, <code>zcn&#95;ser&#95;xy</code>, <code>zcn&#95;tuya&#95;ser&#95;switch</code>, <code>zcn&#95;ser&#95;tuya&#95;batt&#95;enum</code>, <code>zcn&#95;ser&#95;lumi&#95;basic</code></td></tr><tr><td>discovery</td><td><code>zcn&#95;dis&#95;gen&#95;basic</code>, <code>zcn&#95;dis&#95;gen&#95;basic&#95;measurement</code>, <code>zcn&#95;dis&#95;tuya&#95;batt&#95;enum</code></td></tr><tr><td>mqtt write</td><td><code>zcn&#95;write&#95;tuya&#95;int</code>, <code>zcn&#95;write&#95;tuya&#95;float&#95;int100</code>, <code>zcn&#95;write&#95;int16</code>, <code>tuya&#95;switch&#95;handler</code></td></tr><tr><td>cmd</td><td><code>zcn&#95;cmd&#95;onoff&#95;action</code>, <code>tuya&#95;ias&#95;wd&#95;cmd&#95;action</code></td></tr></tbody></table>

<table border="1" id="bkmrk-zcn_norm_i16_divide_" style="border-collapse: collapse; width: 100%; height: 427.25px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 46.5938px;"><td style="height: 46.5938px;"><code>zcn&#95;norm&#95;i16&#95;divide&#95;10&#47;100&#47;1000</code></td><td style="height: 46.5938px;">divides received two-byte signed int by 10/100/1000 and converts result to **float**.

Typically used for temperature sensors, etc.

</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;"><code>zcn&#95;norm&#95;u16&#95;divide&#95;10&#47;100&#47;1000</code></td><td style="height: 46.5938px;">divides received two-byte unsigned int by 10/100/1000 and converts result to **float**.

Typically used for humidity or voltage sensors, etc

</td></tr><tr style="height: 30.1094px;"><td style="height: 30.1094px;"><code>zcn&#95;norm&#95;lumi&#95;basic</code></td><td style="height: 30.1094px;">parses the battery value from the proprietary LUMI structure and sends it to the basic cluster</td></tr><tr style="height: 30.1094px;"><td style="height: 30.1094px;"><code>zcn&#95;dis&#95;gen&#95;basic</code></td><td style="height: 30.1094px;">generates the minimum possible discovery payload</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;"><code>zcn&#95;dis&#95;gen&#95;basic&#95;measurement</code></td><td style="height: 46.5938px;">generates the minimum possible discovery payload and add:

<div><div>{"state_class": "measurement"}</div></div></td></tr><tr style="height: 30.1094px;"><td style="height: 30.1094px;"><code>zcn&#95;dis&#95;tuya&#95;batt&#95;enum</code></td><td style="height: 30.1094px;">battery enumeration: high, med, low</td></tr><tr style="height: 30.1094px;"><td style="height: 30.1094px;"><code>zcn&#95;cmd&#95;onoff&#95;action</code></td><td style="height: 30.1094px;">handles standard ZCL ON/OFF commands for cluster 0x0006</td></tr><tr style="height: 30.1094px;"><td style="height: 30.1094px;"><code>tuya&#95;ias&#95;wd&#95;cmd&#95;action</code></td><td style="height: 30.1094px;">  
</td></tr><tr style="height: 30.1094px;"><td style="height: 30.1094px;"><code>zcn&#95;write&#95;tuya&#95;int</code></td><td style="height: 30.1094px;">sends the received value as **tuya int** type</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;"><code>zcn&#95;write&#95;tuya&#95;float&#95;int100</code></td><td style="height: 46.5938px;">converts the received **float** value to **int** by multiplying by 100 and sends it as **tuya int** type</td></tr><tr style="height: 30.1094px;"><td style="height: 30.1094px;"><code>zcn&#95;write&#95;int16</code></td><td style="height: 30.1094px;">writes a ZCL attribute with int16 data type</td></tr><tr style="height: 30.1094px;"><td style="height: 30.1094px;"><code>tuya&#95;switch&#95;handler</code></td><td style="height: 30.1094px;">converts the received text "ON"/"OFF" text to **bool** (1/0) and sends it as **tuya bool** type</td></tr></tbody></table>

---

## 8. ZCN module API

Public functions:

<table id="bkmrk-function-description" style="width: 100%;"><thead><tr><th style="width: 32.8938%;">Function</th><th style="width: 67.1062%;">Description</th></tr></thead><tbody><tr><td style="width: 32.8938%;"><code>ZCN&#46;register&#40;converter&#95;map&#41; &#45;&#62; int</code></td><td style="width: 67.1062%;">Register a converter from a Berry map (see §4).

returns used slot number, raises a error on failure

</td></tr><tr><td style="width: 32.8938%;"><code>ZCN&#46;attach&#40;slot&#44; ieee&#95;str&#41; &#45;&#62; bool</code></td><td style="width: 67.1062%;">Attach converter to a paired device (IEEE as hex string, e.g. <code>&#34;0x00124b00&#46;&#46;&#46;&#34;</code>). Clears the device's saved-message cache and (re)creates the converter's RAM records.

Raises on: hub not started, bad slot, unknown IEEE.

</td></tr><tr><td style="width: 32.8938%;"><code>ZCN&#46;delete&#40;slot&#41;</code></td><td style="width: 67.1062%;">Free the slot: unpins all callbacks, frees all allocations. Automatic when the VM stops</td></tr></tbody></table>

## 9. Example — SNZB-01P custom button actions(triggers)

```python
#META {"start":0}
#ZCN_BUILDER {"scriptVariableName":"snzb01p_zcn","autostartOnBoot":false,"signatureMode":"model","signatureModel":"SNZB-01P","signatureManufacturer":"eWeLink","matcherCallback":{"enabled":false,"presetReference":"","bodyText":""},"onAnnonce":{"enabled":false,"presetReference":"","bodyText":""},"onIntwStage":{"enabled":true,"presetReference":"","bodyText":"if (tag == \"intw_get_power_source\")\n  dev.setPS(3)  # battery\n  return 0\nend\nreturn 3  # ZCN unused - standard handling"},"attachEnabled":false,"attachIeeeAddress":"","endpointOverrides":[{"endpointNumber":1,"clusters":[{"clusterIdText":"0x0006","addMode":0,"bindCluster":false,"onMqttCmd":{"enabled":false,"presetReference":"","bodyText":""},"commandConfig":{"enabled":true,"exposesList":"btn_single|btn_double|btn_long","onCmd":{"enabled":true,"presetReference":"","bodyText":"# attr: 0 = long, 1 = double, 2 = single\nvar names = ['btn_long', 'btn_double', 'btn_single']\nvar id = record.getAttr()\nif (id < 3) return names[id] end\nreturn \"\""},"exposesOverride":{"enabled":false,"presetReference":"","bodyText":""}},"attributes":[]}]}]}
import ZCN

var snzb01p_zcn = {
  "signature": {
    "model": "SNZB-01P",
    "manuf": "eWeLink",
  },
  "on_intw_stage": def(dev, tag)
    if (tag == "intw_get_power_source")
      dev.setPS(3)  # battery
      return 0
    end
    return 3  # ZCN unused - standard handling
  end,
  "overrides_count": 1,
  "overrides": [
    {
      "endpoint": 1,
      "clusterCount": 1,
      "clusters": [
        {
          "id": 0x0006,
          "cmd_config": {
            "exposes": "btn_single|btn_double|btn_long",
            "on_cmd": def(dev, record)
              # attr: 0 = long, 1 = double, 2 = single
              var names = ['btn_long', 'btn_double', 'btn_single']
              var cmd_id = record.getAttr()
              if (cmd_id < 3)
                return names[id]
              end

              return ""
            end,
          },
        },
      ],
    },
  ],
}

var zcn_slot = ZCN.register(snzb01p_zcn)
ZCN.attach(zcn_slot, "0x00124b0012345678")  # attach to a device manually
```

---

## 10. Gotchas

1. **Counts are explicit.** `overrides_count`, `clusterCount`, `attrCount` are read from the map, not derived from list sizes. A count smaller than the list silently drops entries; a count larger than the list reads will crash device.
2. **Attach every boot.** `zcn_be` is not saved to the device DB. No `ZCN.attach()` after reboot (and no fresh interview) = converter silently inactive.
3. **`signature` is mandatory** — registration raises without it. `matcher` must be a function if present.
4. **Callbacks must be fast.**
5. **`on_cmd` needs `exposes`.** Without `exposes` or `exposesOverride` on the same cluster, the command path is never taken.
6. **`on_discovery` must return `true`** for the attribute to be discovered — a forgotten return (nil) vetoes it.
7. **`ram: true` for redirect targets and dashboard-only values** — otherwise the record does not exist until the device first reports it (or ever, for synthetic attrs).
8. **Slot exhaustion.** Only `2` Berry converters can exist at once, across all scripts. A crashed-then-restarted script frees and re-takes its slots automatically, but a script that registers in a loop will run out.
9. **`ZCN.attach` requires a running hub and a paired device** — it raises `"enable zHub first"` / `"wrong device ieee"` otherwise. If your script autostarts before the hub is up, wait via `ZHB.waitForStart()` first.
10. **Multiple matching converters:** Not recommended. Converters are meant to be unique.
11. **Berry converters are much slower than native ones!** Berry ZCN intended for rapid prototyping, not for continuous use as it will slow down the system.