zigpy library

Warnings

• breaking 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.
  Fix: Update imports from `zigpy.app` to `zigpy.application`. Review migration guides for other changes (e.g., state management, utility functions).
• gotcha 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.
  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.
• gotcha 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.
  Fix: Upgrade your Python environment to 3.11 or newer to ensure full compatibility and support for the latest zigpy features.
• gotcha 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.
  Fix: Ensure your application's entry point uses `asyncio.run()` and all zigpy-related calls are `await`ed within `async def` functions.

Install

• pip install zigpy Install core library
• pip install zigpy-znp Example: Install Texas Instruments ZNP adapter

Imports

• ControllerApplication

  from zigpy.application import ControllerApplication

  The `zigpy.app` module was renamed to `zigpy.application` in zigpy 1.0.0.
• CONF_DEVICE

  from zigpy.config import CONF_DEVICE

• ZCL_CLUSTER_TYPE

  import zigpy.zcl.clusters as ZCL_CLUSTER_TYPE

  Commonly imported as an alias for convenience when working with ZCL clusters.

Quickstart

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.

import asyncio
import logging
import os
from zigpy.application import ControllerApplication
from zigpy.config import CONF_DATABASE_PATH, CONF_DEVICE, CONF_DEVICE_PATH, CONF_DEVICE_BAUDRATE

logging.basicConfig(level=logging.INFO)

async def run_zigbee_app():
    # In a real scenario, the device path would be your Zigbee coordinator's path
    # (e.g., '/dev/ttyUSB0' on Linux, 'COM3' on Windows) and its baudrate.
    # For this quickstart without a physical device, it will likely fail to connect.
    # Replace with valid device path and baudrate for successful execution with hardware.
    config = {
        CONF_DATABASE_PATH: "zigbee_quickstart.db",
        CONF_DEVICE: {
            CONF_DEVICE_PATH: os.environ.get("ZIGBEE_DEVICE_PATH", "/dev/ttyUSB0"),
            CONF_DEVICE_BAUDRATE: int(os.environ.get("ZIGBEE_DEVICE_BAUDRATE", "115200")),
        }
    }

    print(f"Attempting to start zigpy application with device: {config[CONF_DEVICE][CONF_DEVICE_PATH]}")
    app = None # Initialize app to None
    try:
        # Initialize the Zigbee controller application
        # auto_form=True will form a new network if one doesn't exist
        # auto_backup=True will manage database backups
        app = await ControllerApplication.new(
            config=config, auto_form=True, auto_backup=True
        )
        print("Zigbee application initialized. Starting up...")
        await app.startup(auto_form=True) # Start the network connection

        print("Zigbee application started. Press Ctrl+C to stop.")
        print("In a real application, you'd have event listeners, device discovery, etc. here.")
        # Keep the application running for a short period or until interrupted
        await asyncio.sleep(60) 
        
    except Exception as e:
        logging.error(f"Failed to start zigpy application: {e}")
        print("\nError: Ensure your Zigbee coordinator is connected and path/baudrate are correct.")
        print("You may need to install an adapter library (e.g., 'pip install zigpy-znp') for your hardware.")
    finally:
        if app and app.state.started:
            print("\nShutting down Zigbee application...")
            await app.shutdown()
            print("Application shut down.")

if __name__ == "__main__":
    asyncio.run(run_zigbee_app())