MicroPython Zigbee library for ESP32-C6
Built on ESP-Zigbee-SDK (ZBOSS) · Production-ready · RAM-optimized
uZigbee is a MicroPython library that brings full Zigbee 3.0 support to the ESP32-C6 through a native C bridge to the ESP-Zigbee-SDK (ZBOSS stack). It provides high-level Python APIs for Coordinator, Router, and EndDevice roles — with production tooling for build, flash, HIL testing, and CI/CD. Designed for the ESP32-C6's 512 KB SRAM constraint with zero PSRAM dependency.
 Native C Bridge Zero-overhead MicroPython-to-Zigbee binding via ESP-Zigbee-SDK. Direct ZBOSS stack access with scheduler-safe callbacks. |
 Full Zigbee Roles Coordinator, Router, and EndDevice APIs with auto commissioning (auto / guided / fixed), discovery, and lifecycle management. |
 Smart Home Ready First-class Zigbee2MQTT and Home Assistant integration with Z2M external converters and device pairing workflows. |
 Production Tooling Build, flash, host tests, hardware-in-the-loop (HIL) testing, and CI/CD firmware artifact pipelines. |
 RAM-Optimized Designed for ESP32-C6 constraints: 512 KB SRAM, no PSRAM. Frozen modules and minimal allocation hot paths. |
 Rich Protocol Support OTA firmware updates, GreenPower, Touchlink, ZCL cluster library, reporting, binding, and security features. |
| Board | SoC | Zigbee Radio | Notes |
|---|---|---|---|
| ESP32-C6-DevKitC-1 | ESP32-C6 | IEEE 802.15.4 | Primary development board |
| ESP32-C6-DevKitM-1 | ESP32-C6 | IEEE 802.15.4 | Module variant |
| Generic ESP32-C6 | ESP32-C6 | IEEE 802.15.4 | Any board with ESP32-C6 |
All boards require ESP32-C6 with built-in IEEE 802.15.4 radio. WiFi 6 and BLE 5.0 coexist on the same chip.
git clone https://github.com/mateuszsury/uZigbee.git
cd uZigbee
bash tools/bootstrap_third_party.sh./build_firmware.sh --profile esp32-c6-devkit --skip-mpy-crossUse offsets from <build_dir>/flash_args to flash the firmware to your board.
python -m pytest tests/test_import.py tests/test_network_api.py -qpython tools/hil_runner.py --ports COM3 COM5 --tests tests/hil_basic_identity_smoke.py --retries 3Full commands and variants are in BUILD.md and EXAMPLES.md.
The uZigbee stack is organized in layers:
- ESP32-C6 runs FreeRTOS with the RISC-V core and IEEE 802.15.4 radio
- C Bridge wraps ESP-Zigbee-SDK (ZBOSS) with MicroPython-compatible native modules
- Python API exposes high-level Coordinator, Router, and EndDevice abstractions
- Zigbee Network handles ZCL clusters, mesh routing, and device management
- Smart Home integrates with Zigbee2MQTT and Home Assistant via standard protocols
uZigbee/
├── c_module/ # Native MicroPython C bridge and Zigbee integration
├── python/uzigbee/ # Python API (core + high-level orchestration)
├── firmware/ # Manifests, sdkconfig defaults, partitions, board profiles
├── examples/ # Runnable device and coordinator examples
├── tests/ # Host and HIL tests
├── tools/ # Build / flash / test runners and utilities
├── docs/ # Full project documentation
├── z2m_converters/ # Zigbee2MQTT external converter definitions
└── assets/ # SVG branding and diagrams
| Document | Description |
|---|---|
| Getting Started | First-time setup guide |
| Build & Flash | Build system, profiles, and flash procedures |
| API Reference | Full Python API documentation |
| Usage Examples | Runnable code examples |
| Zigbee2MQTT Guide | Z2M integration and converter setup |
| Home Assistant | HA integration workflows |
| Memory Constraints | RAM budget and optimization notes |
| License Notes | Zigbee binary licensing details |
uZigbee uses a two-tier testing strategy:
- Host tests — fast, hardware-free validation of Python APIs and import sanity
- HIL tests — hardware-in-the-loop smoke tests on real ESP32-C6 boards with multi-device Zigbee scenarios
# Host tests
python -m pytest tests/test_import.py tests/test_network_api.py -q
# HIL tests (requires two boards)
python tools/hil_runner.py --ports COM3 COM5 --tests tests/hil_basic_identity_smoke.py --retries 3CI builds firmware artifacts automatically via GitHub Actions.
Contributions are welcome! Please read the Contributing Guide before opening a PR.
- Follow the Code of Conduct
- Check existing issues for related work
- See Good First Issues for beginner-friendly tasks
Project source code is licensed under the MIT License.
Important: Zigbee binary dependencies (e.g.,
esp-zboss-lib) have separate redistribution terms. Review LICENSE_NOTES.md before publishing firmware binaries.
GitHub · Report Bug · Request Feature · Documentation
Built with ESP-Zigbee-SDK · MicroPython · ESP-IDF