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.
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.
EmberZNet based Zigbee radios using the EZSP protocol (via the bellows library for zigpy)
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.
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.
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.
This project is in early stages, so it is likely that APIs will change.
Currently implemented features are:
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= 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=> $ bellows zcl 00:0d:6f:00:05:7d:2d:34 1 1026 read_attribute 0 0=1806
lsusb). For the Bitron Video/Smabit BV AV2010/10 that might for example be 10c4 8b34.
lsusbon your system):
sudo -s modprobe cp210x echo 10c4 8b34 > /sys/bus/usb-serial/drivers/cp210x/new_id
socket://<adapter-IP>:<port>and use 115200 baud rate as the port speed.
Warning! Please note that this is a highly experimental feature! Theoretically this allows backing up and restoring NCP state between the hardware version.
NVRAM backup can be performed to migrate between different radio hardware as long as they based on the same chip. Anything else will not work. If this is done between different hardwares, the EUI64 is going to be different on the new hardware meaning the binding tables on all the devices are going to be wrong.
To export TC config, see bellows backup --help usually it is just bellows backup > your-backup-file.txt. The backup contains your network key, so you probably should keep that file secure. To import, see bellows restore --backup-file your-backup-file.txt
Note! The restoration does not restore NCP children and relies on children just to find a new parent. You either have to reconfigure all the devices (recommended so the bindings are updated) or alternatively you could override the EUI64 on the new hardware, essentially producing a clone. Be very careful if you decide to go with the latter route. You can change the EUI64 only once and once you set it it is impossible to change it without a specialized hardware (SWD programmer).
Testing a new release of the bellows library before it is released in Home Assistant.
If you are using Supervised Home Assistant (formerly known as the Hassio/Hass.io distro):
where 0.16.0 is the new version
pypi: - bellows==0.16.0 apk: 
If you are instead using some custom python installation of Home Assistant then do this:
pip install bellows==0.16.0
New packages of tagged versions are also released via the "bellows" project on PyPI
Older packages of tagged versions are still available on the "bellows-homeassistant" project on PyPI
If you are looking to make a contribution to this project we suggest that you follow the steps in these guides:
Some developers might also be interested in receiving donations in the form of hardware such as Zigbee modules or devices, and even if such donations are most often donated with no strings attached it could in many cases help the developers motivation and indirect improve the development of this project.