Registry / communication / bellows

bellows

JSON →
library0.49.2pypypi✓ verified 85d ago

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.

pip install bellows
INSTALL
IMPORT
SIG · BELLOWS
B
bellows
communicationpythonv0.49.2
Install
6.4s avg
Import
1942ms
Disk
53MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.46.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 2.009s · 52.5MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 6.4s · import 1.875s · 54MB
53MB installed
● package 53MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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())
bellows --version
Debug
Known issues
breakingBellows 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).
affects: >=0.49.0
gotchaThe 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.
affects: All
breakingThe 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.
affects: All
Errors
Common errors & fixes
Error: Missing option "-d" / "--device".
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
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'
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
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.
Upgrade
Version history
0.49.2latest on PyPI · released May 27, 2026
Audit
Dependencies
zigpyrequiredCore Zigbee stack implementation that Bellows integrates with.
async-timeoutrequiredTimeout context manager for asyncio programs.
clickrequiredCommand-Line Interface Creation Kit, used for Bellows CLI.
click-logrequiredLogging integration for Click CLI.
pure-pcapy3requiredPure Python reimplementation of pcapy, possibly for serial capture/analysis.
pyserial-asynciorequiredAsyncio-compatible serial port access.
voluptuousrequiredData validation library.
Agent activity
45 hits · last 30 days
node
36
OpenAI (training)
1
Resources
bellows — pip install bellows · libregistry