Bellows

0.49.0 · active · verified Thu Apr 16

Bellows is a Python 3 library that implements the EmberZNet Serial Protocol (EZSP) to add Zigbee radio support for Silicon Labs EM35x and EFR32-based Zigbee coordinator devices. While it can function as a standalone library, its primary goal is to integrate these devices with Home Assistant's built-in ZHA (Zigbee Home Automation) component. The library is actively developed, with frequent releases, and the current version is 0.49.0.

Common errors

```
Error: Missing option "-d" / "--device".
```
cause When using `bellows` CLI commands (e.g., `bellows devices` or `bellows form`), the serial port for the Zigbee adapter was not specified.

fix Always provide the serial device path using the `-d` or `--device` option, e.g., `bellows -d /dev/ttyUSB0 devices` or `bellows --device COM3 form`.
```
sqlite3.OperationalError: unable to open database file
```
cause The `bellows` application or CLI could not create or access its Zigbee database file, often due to permission issues or an invalid path.

fix Ensure the directory where the database file is intended to be created has write permissions for the user running the `bellows` application. If specifying a path, ensure it is valid and accessible, e.g., `bellows -d /dev/ttyUSB0 form --database /opt/zigbee/zigbee.db`.
```
AttributeError: 'list' object has no attribute 'split'
```
cause This error occurs when running the `bellows scan` command without specifying channels, particularly in older versions or specific environments.

fix Explicitly provide the channels to scan, e.g., `bellows -d /dev/ttyUSB0 scan -c 11 15 20 25` to scan specific Zigbee channels.
```
NCP EZSP protocol version of XX does not match Host version YY
```
cause The EZSP protocol version implemented by the firmware on your Zigbee coordinator (NCP) does not match the version expected or supported by the `bellows` library (Host).

fix Upgrade or downgrade the firmware on your Zigbee coordinator to match the EZSP protocol version required by your `bellows` installation, or check if an older `bellows` version is compatible with your current firmware.

Warnings

breaking Bellows has dropped compatibility for Python 3.9 and 3.10 with version 0.49.0. Users must use Python 3.11 or newer.
Fix: Upgrade your Python environment to 3.11 or later: `pyenv install 3.11.9 && pyenv local 3.11.9` (example for pyenv users).
gotcha The Zigbee adapter requires specific EmberZNet PRO Zigbee Stack firmware that utilizes standard Silicon Labs EZSP APIs. An incompatible firmware version on the adapter can lead to communication failures or errors.
Fix: Ensure your Zigbee coordinator is flashed with a compatible EmberZNet PRO Zigbee Stack firmware version that matches the EZSP protocol version expected by your `bellows` installation. Refer to your adapter's documentation or the `zigpy` community for recommended firmware versions.
breaking The project documentation (README) mentions that it is in 'early stages' and 'APIs will change'. While the library is mature, users should be aware that minor version updates may introduce breaking changes, especially for advanced use cases.
Fix: Refer to the GitHub release notes and changelog (`https://github.com/zigpy/bellows/releases`) before upgrading to identify any breaking API changes or new requirements.

Install

pip install bellows Install latest version

Imports

ControllerApplication
```
from bellows.zigbee.application import ControllerApplication
```
Main application class for controlling a Zigbee network via EZSP.
EZSP
```
from bellows.ezsp import EZSP
```
Represents the EZSP protocol interface for communication with the Zigbee coordinator.

Quickstart

This quickstart demonstrates how to initialize the `bellows` library to connect to a Zigbee coordinator and start a Zigbee network. It requires a serial port where your EZSP-compatible Zigbee adapter is connected. The `asyncio` event loop is essential for `bellows` operations. Remember to replace the placeholder serial port with your actual device path.

import asyncio
from bellows.ezsp import EZSP
from bellows.zigbee.application import ControllerApplication

async def main():
    # Replace '/dev/ttyUSB0' with your serial port, e.g., 'COM3' on Windows
    # and adjust baudrate if necessary (default 115200)
    # For real use, ensure database_file is persistent.
    serial_port = os.environ.get('BELLOWS_SERIAL_PORT', '/dev/ttyUSB0')
    database_file = os.environ.get('BELLOWS_DATABASE_FILE', 'zigbee.db')

    print(f"Connecting to {serial_port} and using database {database_file}")

    try:
        ezsp = await EZSP.probe_and_connect(serial_port, 115200)
        application = ControllerApplication(ezsp, database_file)
        await application.startup(auto_form=True)
        print("Zigbee network started successfully!")
        # Keep the application running, e.g., for event listening or CLI interaction
        while True:
            await asyncio.sleep(3600) # Keep alive indefinitely

    except Exception as e:
        print(f"Error during Zigbee application startup: {e}")
    finally:
        if 'application' in locals() and application.state.running: # Check if application was successfully started and is still running
            await application.shutdown()
            print("Zigbee application shut down.")

if __name__ == '__main__':
    import os
    # Example of setting environment variables for demonstration
    # os.environ['BELLOWS_SERIAL_PORT'] = '/dev/ttyUSB0'
    # os.environ['BELLOWS_DATABASE_FILE'] = '/tmp/my_zigbee_network.db'
    
    asyncio.run(main())

view raw JSON →