bellows

bellows is a Python 3 library implementation for the zigpy project to add Zigbee radio support for Silicon Labs EM35x ("Ember") and EFR32 ("Mighty Gecko") based Zigbee coordinator devices using the EZSP (EmberZNet Serial Protocol) interface.

The project can be used as a stand-alone library, however, the main goal of this project is to add native support for EmberZNet Zigbee radio based USB stick devices (a.k.a. "Ember" and "Mighty Gecko" based adapters/dongles/modules) to Home Assistant's built-in ZHA (Zigbee Home Automation) integration component, allowing Home Assistant with such hardware to nativly support direct control of compatible Zigbee devices, such as; Philips HUE, GE, Ledvance, Osram Lightify, Xiaomi/Aqara, IKEA Tradfri, Samsung SmartThings, and many more.

https://www.home-assistant.io/integrations/zha/

bellows interacts with the Zigbee Network Coprocessor (NCP) with EmberZNet PRO Zigbee coordinator firmware using the EZSP protocol serial interface APIs via via UART for Silicon Labs EM35x and EFR32 Zigbee radio module/chips hardware. The library currently supports the Silicon Labs EZSP (EmberZNet Serial Protocol) API versions v4/v5/v6/v7/v8 for Silabs older EM35x "Ember" and their newer EFR32 "Mighty Gecko" SoCs using ASH protocols over a serial interface.

Hardware requirement

EmberZNet based Zigbee radios using the EZSP protocol (via the bellows library for zigpy)

Tube's Zigbee Gateways (Silabs EFR32 variant) Note! ESP32 based Ethernet bridge available as pre-assembed or as a DIY project.
ITEAD Sonoff ZBBridge (Note! WiFi-based bridges are not recommended for ZHA with EZSP radios. Also, this first have to be flashed with Tasmota firmware and EmberZNet firmware)
ITead Zigbee 3.0 USB Dongle (EFR32MG21) Model 9888010100045 Note! Currently not recommended due to stability issues.
Nortek GoControl QuickStick Combo Model HUSBZB-1 (Z-Wave & Zigbee Ember 3581 USB Adapter) (Note! Not a must but recommend upgrade the EmberZNet NCP application firmware)
Elelabs Zigbee USB Adapter (Note! Not a must but recommend upgrade the EmberZNet NCP application firmware)
Elelabs Zigbee Raspberry Pi Shield (Note! Not a must but recommend upgrade the EmberZNet NCP application firmware)
DEFARO SprutStick Pro (also known as Defaro SprutStick ZigBee 2 Pro)
Telegesis ETRX357USB/ETRX357USB-LRS/TRX357USB-LRS+8M (Note! This first have to be flashed with other EmberZNet firmware)
IKEA Billy EZSP - DIY ICC-1 / ICC-A-1 module from IKEA TRÅDFRI devices. (Note! This first have to be hacked and flashed with other EmberZNet firmware)
Tuya TYGWZ01 and rebranded Lidl Silvercrest Smart Home Gateway (Note! This first have to be hacked and flashed with other EmberZNet firmware)
Bitron Video/Smabit BV AV2010/10 USB-Stick (a.k.a. Telekom Magenta Stick) based on Silicon Labs Ember 3587
EByte E180-Z120B SMD Module and EByte E180-Z120B-TB Evaluation Board (Note! This first have to be hacked and flashed with other EmberZNet firmware)

Warning about Zigbee to WiFi bridges

zigpy requires a robust connection between the zigpy radio library and the serial port of the Zigbee radio. With solutions such as ITEAD Sonoff ZBBridge or a Ser2Net serial proxy connection over a WiFi network it is expected to see NCP entered failed state. Requesting APP controller restart in the logs. This is a normal part of the operation and indicates there was a drop in communication which caused packet loss to occurred between the zigpy radio library and the Zigbee radio. The use of serial network proxies/bridges/servers over WiFi is therefore not recommended when wanting a stable Zigbee environment with zigpy.

Firmware requirement

bellows requires that the Zigbee adapter/board/module is pre-flashed/flashed with compatible firmware with EmberZNet PRO Zigbee Stack that uses the standard Silicon Labs EZSP (EmberZNet Serial Protocol) APIs for ASH protocol over a serial interface.

Silabs used to provide two main NCP images pre-build with firmware for EM35x, one image supported hardware flow control with a baud rate of 115200 and the other image supported software flow control with a rate of 57600.

Silicon Labs no longer provide pre-build firmware images, so now you have to build and compile firmware with their Simplicity Studio SDK for EmberZNet PRO Zigbee Protocol Stack Software. Simplicity Studio is a free download but building and compiling EmberZNet PRO Zigbee firmware images required that you have the serialnumber of an official Zigbee devkit registered to your Silicon Labs user account.

Firmware upgrade resources

For firmware requirements and recommended firmware see the Zigpy Wiki.
Elelabs EZSP Firmware Update Utility (should work with most EFR32 based Zigbee coordinators with Silicon Labs standard bootloader).
Docker firmware updater image by walthowd upgrading Nortek/GoControl/Linear HUSBZB-1 and Telegesis ETRX357 Zigbee coordinator adapters.

EmberZNet and EZSP Protocol Version

Silicon Labs does not currently have a consolidated list of changes by EmberZNet SDK or EZSP protocol version. The EZSP additions, changes and deletions have only ever been listed in the "Zigbee EmberZNet Release Notes" (EmberZNet SDK) under the "New items" section as well as the matching UG100 EZSP Reference Guide included with each EmberZNet SDK release.

The largest change was between EZSP v4 (first added in EmberZNet 4.7.2 SDK) and EZSP v5 that was added in EmberZNet 5.9.0 SDK which requires the Legacy Frame ID 0xFF. The change from EZSP v5 to EZSP v6 was done in EmberZNet 6.0.0 SDK. The change from EZSP v6 to EZSP v7 was in EmberZNet 6.4.0 SDK. EmberZNet 6.7.0 SDK added EZSP v8 (and Secure EZSP Protocol Version 2).

Perhaps more important to know today is that EZSP v5, v6 and v7 (EmberZNet 6.6.x.x) use the same framing format, but EmberZNet 6.7.x.x/EZSP v8 introduced new framing format and expanded command id field from 8 bits to 16 bits and is and is not backward compatible.

Project status

This project is in early stages, so it is likely that APIs will change.

Currently implemented features are:

EZSP UART Gateway Protocol
EZSP application protocol
CLI wrapping basic ZigBee network operations (eg, scanning and forming a network)
ZDO functionality (with CLI)
ZCL functionality (with CLI)
An application framework with device state persistence

An example use of the CLI:

$ export EZSP_DEVICE=/dev/ttyUSB1
$ bellows devices
Device:
  NWK: 0x1ee4
  IEEE: 00:0d:6f:00:05:7d:2d:34
  Endpoints:
    1: profile=0x104, device_type=None, clusters=[0, 1, 3, 32, 1026, 1280, 2821]
    2: profile=0xc2df, device_type=None, clusters=[0, 1, 3, 2821]
Device:
  NWK: 0x64a6
  IEEE: d0:52:a8:00:e0:be:00:05
  Endpoints:
    1: profile=0x104, device_type=None, clusters=[0]
    2: profile=0xfc01, device_type=None, clusters=[]
$ bellows zdo 00:0d:6f:00:05:7d:2d:34 get_endpoint 1
<SimpleDescriptor endpoint=1 profile=260 device_type=1026 device_version=0 input_clusters=[0, 1, 3, 32, 1026, 1280, 2821] output_clusters=[25]>
$ bellows zcl 00:0d:6f:00:05:7d:2d:34 1 1026 read_attribute 0
0=1806

Configuration

Port configuration for USB, UART/Serial and GPIO adapters

To configure use of a locally connected USB adapter device path its serial interface by specifying the TTY (serial com) port, example : /dev/ttyUSB1
- It is worth noting that while a few adapters have an embedded USB core (like EM3588 based devices) which will likely work with any baud rate speed, most USB sticks/dongles have an external USB to serial converter/bridge chip (eg Silabs CP210x, FTDI FT23x, or WCH CH340) which require you to set a specific baud rate. It should as such be noted that some NCP firmware images require the use of 115200 baud rate speed while others use 57600 baud rate speed, also, some use no flow control (NSW flow control) while others require use of either software flow control (SW or XON/XOFF flow control) or hardware flow control (HW or RTS/CTS flow control).
- If a USB radio is not recognized, it might be necessary to make the serial adapters device id known to driver, e.g. CP210x driver by Silicon Labs.
- Find the device id (as listed by the command lsusb). For the Bitron Video/Smabit BV AV2010/10 that might for example be 10c4 8b34.
- Unplug the device.
- Enter the following commands (replace the example id 10c4 8b34 with

Bellows

Install / Use

README