zigpy-znp

Common errors

• SerialException: [Errno 13] Permission denied: '/dev/ttyUSB0'

  cause The user running the Python script does not have sufficient permissions to access the specified serial device.
  fix Add the user to the `dialout` group (Linux) using `sudo usermod -a -G dialout $USER` and then log out and back in, or reboot. Alternatively, adjust device permissions or udev rules.

• FileNotFoundError: [Errno 2] No such file or directory: 'COM3'

  cause The specified serial port path does not exist or is incorrect for your system.
  fix Verify the serial port name. On Linux, check `/dev/tty*` (e.g., `/dev/ttyACM0`, `/dev/ttyUSB0`). On Windows, check Device Manager for the correct `COM` port (e.g., `COM3`, `COM4`).

• ValueError: Unknown radio type: 'znp'

  cause The `zigpy` application cannot find the `zigpy-znp` radio backend. This usually means `zigpy-znp` is not installed or `zigpy` hasn't correctly discovered its entry points.
  fix Ensure `zigpy-znp` is correctly installed (`pip install zigpy-znp`). If running in a virtual environment, activate it before installation. Restart the application or environment if necessary.

Warnings

• gotcha On Linux, users often encounter 'Permission denied' errors when accessing serial ports (`/dev/ttyACM0` or `/dev/ttyUSB0`).
  Fix: Add your user to the `dialout` group (e.g., `sudo usermod -a -G dialout $USER`) and reboot or log out/in. Ensure correct udev rules are applied if using a custom device.
• gotcha Incompatible ZNP firmware versions on your TI radio can lead to connection issues, instability, or missing features.
  Fix: Ensure your ZNP radio is flashed with a compatible and recent firmware. Refer to the `zigpy-znp` documentation or community resources for recommended firmware versions for your specific hardware (e.g., CC2531, CC2652P).
• gotcha Only one application can access a serial port at a time. Trying to run multiple instances of `zigpy` or other serial tools simultaneously will cause errors.
  Fix: Ensure no other programs (e.g., Home Assistant, another `zigpy` instance, a serial terminal) are using the specified serial port before starting your `zigpy-znp` application. Check for zombie processes.
• breaking Changes in the core `zigpy` library's API or configuration scheme can affect `zigpy-znp` users, as `zigpy-znp` is a radio backend for `zigpy`.
  Fix: Always check the release notes for `zigpy` itself when upgrading `zigpy-znp` or `zigpy`. Update your `zigpy` configuration (`CONF_DEVICE`, `CONF_DATABASE_PATH`, etc.) as per `zigpy`'s latest documentation.

Install

• pip install zigpy-znp Install latest version

Imports

• ZnpApplication

  from zigpy_znp.zigbee.application import ZnpApplication

  While ZnpApplication is the core class, most users interact with zigpy-znp by configuring `zigpy.application.Controller` with `radio_type: znp` rather than direct import.

Quickstart

This quickstart demonstrates how to initialize a `zigpy` controller using `zigpy-znp` as the radio backend. It sets up a basic configuration, attempts to start the controller, and optionally forms a new Zigbee network. Remember to replace `/dev/ttyUSB0` with your actual serial port and ensure you have the necessary permissions.

import asyncio
import os
from zigpy.application import Controller
from zigpy.config import CONF_DATABASE_PATH, CONF_DEVICE, CONF_RADIO_TYPE

async def main():
    # Replace with your actual serial port for the ZNP radio
    # On Linux: '/dev/ttyACM0' or '/dev/ttyUSB0'
    # On Windows: 'COM3'
    serial_port = os.environ.get("ZNP_SERIAL_PORT", "/dev/ttyUSB0")
    
    # Define the zigpy configuration
    config = {
        CONF_DEVICE: {
            CONF_RADIO_TYPE: "znp",  # This activates zigpy-znp
            "port": serial_port,
        },
        CONF_DATABASE_PATH: "zigpy_znp.db", # Database for network state
    }

    print(f"Starting zigpy controller with ZNP radio on {serial_port}...")
    controller = Controller(config)

    try:
        # auto_form=True creates a new network if none exists. Set to False if you expect to join an existing network.
        await controller.startup(auto_form=True)
        print("Controller started successfully. Network formed/joined.")
        # At this point, you can interact with the Zigbee network, e.g., discover devices
        print("Controller running for 10 seconds. Press Ctrl+C to stop sooner.")
        await asyncio.sleep(10) # Keep running for 10 seconds
        print("Shutting down controller.")
    except Exception as e:
        print(f"Error starting controller: {e}")
    finally:
        await controller.shutdown()
        print("Controller shut down.")

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Exiting.")