{"id":5558,"library":"zigpy","title":"zigpy library","description":"A low-level Python library implementing a full Zigbee stack, allowing communication with Zigbee devices through various hardware adapters. It is currently at version 1.2.2 and maintains a frequent release cadence, often with new minor or patch versions every 1-3 months, primarily focusing on bug fixes, new quirk support, and dependency updates.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/zigpy/zigpy","tags":["zigbee","iot","home-automation","asyncio","hardware-interface"],"install":[{"cmd":"pip install zigpy","lang":"bash","label":"Install core library"},{"cmd":"pip install zigpy-znp","lang":"bash","label":"Example: Install Texas Instruments ZNP adapter"}],"dependencies":[{"reason":"Required for serial communication with most Zigbee coordinators.","package":"pyserial","optional":false},{"reason":"An adapter library specific to your Zigbee coordinator hardware. This is an example, you need to install the correct adapter for your device.","package":"zigpy-znp","optional":true}],"imports":[{"note":"The `zigpy.app` module was renamed to `zigpy.application` in zigpy 1.0.0.","wrong":"from zigpy.app import ControllerApplication","symbol":"ControllerApplication","correct":"from zigpy.application import ControllerApplication"},{"symbol":"CONF_DEVICE","correct":"from zigpy.config import CONF_DEVICE"},{"note":"Commonly imported as an alias for convenience when working with ZCL clusters.","symbol":"ZCL_CLUSTER_TYPE","correct":"import zigpy.zcl.clusters as ZCL_CLUSTER_TYPE"}],"quickstart":{"code":"import asyncio\nimport logging\nimport os\nfrom zigpy.application import ControllerApplication\nfrom zigpy.config import CONF_DATABASE_PATH, CONF_DEVICE, CONF_DEVICE_PATH, CONF_DEVICE_BAUDRATE\n\nlogging.basicConfig(level=logging.INFO)\n\nasync def run_zigbee_app():\n    # In a real scenario, the device path would be your Zigbee coordinator's path\n    # (e.g., '/dev/ttyUSB0' on Linux, 'COM3' on Windows) and its baudrate.\n    # For this quickstart without a physical device, it will likely fail to connect.\n    # Replace with valid device path and baudrate for successful execution with hardware.\n    config = {\n        CONF_DATABASE_PATH: \"zigbee_quickstart.db\",\n        CONF_DEVICE: {\n            CONF_DEVICE_PATH: os.environ.get(\"ZIGBEE_DEVICE_PATH\", \"/dev/ttyUSB0\"),\n            CONF_DEVICE_BAUDRATE: int(os.environ.get(\"ZIGBEE_DEVICE_BAUDRATE\", \"115200\")),\n        }\n    }\n\n    print(f\"Attempting to start zigpy application with device: {config[CONF_DEVICE][CONF_DEVICE_PATH]}\")\n    app = None # Initialize app to None\n    try:\n        # Initialize the Zigbee controller application\n        # auto_form=True will form a new network if one doesn't exist\n        # auto_backup=True will manage database backups\n        app = await ControllerApplication.new(\n            config=config, auto_form=True, auto_backup=True\n        )\n        print(\"Zigbee application initialized. Starting up...\")\n        await app.startup(auto_form=True) # Start the network connection\n\n        print(\"Zigbee application started. Press Ctrl+C to stop.\")\n        print(\"In a real application, you'd have event listeners, device discovery, etc. here.\")\n        # Keep the application running for a short period or until interrupted\n        await asyncio.sleep(60) \n        \n    except Exception as e:\n        logging.error(f\"Failed to start zigpy application: {e}\")\n        print(\"\\nError: Ensure your Zigbee coordinator is connected and path/baudrate are correct.\")\n        print(\"You may need to install an adapter library (e.g., 'pip install zigpy-znp') for your hardware.\")\n    finally:\n        if app and app.state.started:\n            print(\"\\nShutting down Zigbee application...\")\n            await app.shutdown()\n            print(\"Application shut down.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(run_zigbee_app())\n","lang":"python","description":"This quickstart demonstrates how to initialize and start a `zigpy` application. It attempts to connect to a Zigbee coordinator specified by `ZIGBEE_DEVICE_PATH` and `ZIGBEE_DEVICE_BAUDRATE` environment variables (defaulting to '/dev/ttyUSB0' and 115200). Note that this example requires a physical Zigbee coordinator and a corresponding `zigpy` adapter library (e.g., `zigpy-znp`) to run successfully. Without a device, it will raise an exception."},"warnings":[{"fix":"Update imports from `zigpy.app` to `zigpy.application`. Review migration guides for other changes (e.g., state management, utility functions).","message":"Major architectural changes were introduced in zigpy 1.0.0, including the renaming of the `zigpy.app` module to `zigpy.application` and the removal of `zigpy.state` and `zigpy.util` modules. Code written for pre-1.0 versions will require updates.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Identify your Zigbee coordinator model and install the appropriate `zigpy-` adapter library (e.g., `pip install zigpy-znp`). Ensure the coordinator is properly connected and its serial path/baudrate are correctly configured.","message":"zigpy is a low-level Zigbee stack library and requires a specific hardware adapter (Zigbee coordinator) to function. You must install a separate `zigpy-` plugin package (e.g., `zigpy-znp`, `zigpy-deconz`, `zigpy-zigate`) corresponding to your coordinator hardware.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to 3.11 or newer to ensure full compatibility and support for the latest zigpy features.","message":"zigpy versions >=1.1.0 officially require Python 3.11 or newer. While earlier Python 3.x versions might work with older zigpy releases, it's recommended to use the specified Python version for full compatibility and access to the latest features and bug fixes.","severity":"gotcha","affected_versions":"<1.1.0 (for older Python versions), All versions (for Python 3.11+ requirement)"},{"fix":"Ensure your application's entry point uses `asyncio.run()` and all zigpy-related calls are `await`ed within `async def` functions.","message":"zigpy is an asynchronous library built on `asyncio`. All interactions with the `ControllerApplication` and other core components must be performed within an `async` context and run by an `asyncio` event loop.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}