Zigbee

About

The Zigbee library provides support for creating Zigbee 3.0 compatible devices including:

Support for different Zigbee roles (Coordinator, Router, End Device)
Network management (scanning, joining, commissioning)
Multiple endpoint types for various device categories
OTA (Over-The-Air) update support
Power management for battery-powered devices
Time synchronization
Advanced binding and group management

The Zigbee library is built on top of ESP-ZIGBEE-SDK and provides a high-level Arduino-style interface for creating Zigbee devices.

Zigbee Network Topology

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│   Coordinator   │◄─────►│     Router      │◄─────►│     Router      │
│   (Gateway)     │       │   (Repeater)    │       │  (Thermostat)   │
└─────────────────┘       └─────────────────┘       └─────────────────┘
        │                          │                         │
        │                          ▼                         │
        │                 ┌─────────────────┐                │
        │                 │   End Device    │                │
        │                 │    (Sensor)     │                │
        │                 └─────────────────┘                │
        │                                                    │
        ▼                                                    ▼
┌─────────────────┐                                 ┌─────────────────┐
│   End Device    │                                 │   End Device    │
│   (Sensor)      │                                 │    (Sensor)     │
└─────────────────┘                                 └─────────────────┘

Device Roles

Coordinator: Forms and manages the network, stores network information
Router: Extends network range, routes messages, mains powered devices (typically lights, switches, etc.)
End Device: Battery-powered devices that can sleep for extended periods (typically sensors)

Zigbee Library Structure

The library is split into three main components:

ZigbeeCore: The main class that manages the Zigbee network
ZigbeeEP: The base class for all Zigbee endpoints, which provides common functionality for all endpoint types
Specific endpoint classes: The classes for all Zigbee endpoints, which provides the specific functionality for each endpoint type

ZigbeeCore

The ZigbeeCore class is the main entry point for all Zigbee operations. It serves as the central coordinator that manages:

Network Operations: Starting, stopping, and managing the Zigbee network
Device Role Management: Configuring the device as Coordinator, Router, or End Device
Endpoint Management: Adding and managing multiple device endpoints
Network Discovery: Scanning for and joining existing networks
OTA Updates: Managing over-the-air firmware updates
Power Management: Configuring sleep modes for battery-powered devices

The ZigbeeCore class is implemented as a singleton, meaning there’s only one instance available globally. You access it directly as Zigbee without creating an instance.

ZigbeeCore
- About
- ZigbeeCore APIs

ZigbeeEP

The ZigbeeEP class is the base class for all Zigbee endpoints. It provides common functionality for all endpoint types.

Device Information: Every endpoint can be configured with manufacturer and model information that helps identify the device on the network
Binding Management: Binding allows endpoints to establish direct communication links with other devices. This enables automatic command transmission without requiring manual addressing
Power Management: Endpoints can report their power source type and battery status, which helps the network optimize communication patterns
Time Synchronization: Endpoints can synchronize with network time, enabling time-based operations and scheduling
OTA Support: Endpoints can receive over-the-air firmware updates to add new features or fix bugs
Device Discovery: Endpoints can read manufacturer and model information from other devices on the network

ZigbeeEP

Specific endpoint classes

Library provides the following endpoint classes from lights, switches, sensors, etc. Each endpoint class provides the specific functionality for each endpoint type and inherits from the ZigbeeEP class.

Common Problems and Issues

Troubleshooting

Common Issues

Device won’t join network

Ensure the coordinator is in pairing mode
Check that the device is configured with the correct role
Verify the channel mask includes the coordinator’s channel

OTA updates fail

Ensure the OTA server is properly configured
Check that the device has sufficient memory for the update
Verify network connectivity

Battery devices not working

Ensure proper power source configuration
Check sleep/wake timing settings
Verify parent device (router/coordinator) is always powered

Binding issues

Check that both devices support the required clusters
Verify that binding is enabled on both devices
Ensure devices are on the same network

Network connectivity problems

Check that devices are within range
Verify that routers are properly configured
Check for interference from other 2.4 GHz devices

Factory Reset

If you have problems with connecting to the network, you can try to factory reset the device. This will erase all the network settings and act as brand new device.

Zigbee.factoryReset(true); // true = restart after reset

Debug Mode

For better debugging, you can enable debug mode to get detailed information about network operations. Call debug mode before starting Zigbee. Also selecting zigbee mode with debug suffix is recommended.

Zigbee.setDebugMode(true);
// Start Zigbee with debug output
Zigbee.begin();