{"id":7041,"library":"bellows","title":"Bellows","description":"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.","status":"active","version":"0.49.0","language":"en","source_language":"en","source_url":"https://github.com/zigpy/bellows","tags":["zigbee","ezsp","home-automation","iot","serial","silicon-labs","zigpy","zha"],"install":[{"cmd":"pip install bellows","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core Zigbee stack implementation that Bellows integrates with.","package":"zigpy","optional":false},{"reason":"Timeout context manager for asyncio programs.","package":"async-timeout","optional":false},{"reason":"Command-Line Interface Creation Kit, used for Bellows CLI.","package":"click","optional":false},{"reason":"Logging integration for Click CLI.","package":"click-log","optional":false},{"reason":"Pure Python reimplementation of pcapy, possibly for serial capture/analysis.","package":"pure-pcapy3","optional":false},{"reason":"Asyncio-compatible serial port access.","package":"pyserial-asyncio","optional":false},{"reason":"Data validation library.","package":"voluptuous","optional":false}],"imports":[{"note":"Main application class for controlling a Zigbee network via EZSP.","symbol":"ControllerApplication","correct":"from bellows.zigbee.application import ControllerApplication"},{"note":"Represents the EZSP protocol interface for communication with the Zigbee coordinator.","symbol":"EZSP","correct":"from bellows.ezsp import EZSP"}],"quickstart":{"code":"import asyncio\nfrom bellows.ezsp import EZSP\nfrom bellows.zigbee.application import ControllerApplication\n\nasync def main():\n    # Replace '/dev/ttyUSB0' with your serial port, e.g., 'COM3' on Windows\n    # and adjust baudrate if necessary (default 115200)\n    # For real use, ensure database_file is persistent.\n    serial_port = os.environ.get('BELLOWS_SERIAL_PORT', '/dev/ttyUSB0')\n    database_file = os.environ.get('BELLOWS_DATABASE_FILE', 'zigbee.db')\n\n    print(f\"Connecting to {serial_port} and using database {database_file}\")\n\n    try:\n        ezsp = await EZSP.probe_and_connect(serial_port, 115200)\n        application = ControllerApplication(ezsp, database_file)\n        await application.startup(auto_form=True)\n        print(\"Zigbee network started successfully!\")\n        # Keep the application running, e.g., for event listening or CLI interaction\n        while True:\n            await asyncio.sleep(3600) # Keep alive indefinitely\n\n    except Exception as e:\n        print(f\"Error during Zigbee application startup: {e}\")\n    finally:\n        if 'application' in locals() and application.state.running: # Check if application was successfully started and is still running\n            await application.shutdown()\n            print(\"Zigbee application shut down.\")\n\nif __name__ == '__main__':\n    import os\n    # Example of setting environment variables for demonstration\n    # os.environ['BELLOWS_SERIAL_PORT'] = '/dev/ttyUSB0'\n    # os.environ['BELLOWS_DATABASE_FILE'] = '/tmp/my_zigbee_network.db'\n    \n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.11 or later: `pyenv install 3.11.9 && pyenv local 3.11.9` (example for pyenv users).","message":"Bellows has dropped compatibility for Python 3.9 and 3.10 with version 0.49.0. Users must use Python 3.11 or newer.","severity":"breaking","affected_versions":">=0.49.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"When using `bellows` CLI commands (e.g., `bellows devices` or `bellows form`), the serial port for the Zigbee adapter was not specified.","error":"Error: Missing option \"-d\" / \"--device\"."},{"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`.","cause":"The `bellows` application or CLI could not create or access its Zigbee database file, often due to permission issues or an invalid path.","error":"sqlite3.OperationalError: unable to open database file"},{"fix":"Explicitly provide the channels to scan, e.g., `bellows -d /dev/ttyUSB0 scan -c 11 15 20 25` to scan specific Zigbee channels.","cause":"This error occurs when running the `bellows scan` command without specifying channels, particularly in older versions or specific environments.","error":"AttributeError: 'list' object has no attribute 'split'"},{"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.","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).","error":"NCP EZSP protocol version of XX does not match Host version YY"}]}