{"id":7883,"library":"zigpy-znp","title":"zigpy-znp","description":"zigpy-znp is a Python library that provides a radio implementation for the `zigpy` ecosystem, enabling communication with Texas Instruments (TI) ZNP (Zigbee Network Processor) based radios. It allows `zigpy` applications to control Zigbee networks using devices like TI CC2531, CC2652R/P, CC1352P, etc., acting as the coordinator or router. The current version is 0.14.3, and it receives updates as needed to support `zigpy` advancements, new ZNP firmware features, and bug fixes.","status":"active","version":"0.14.3","language":"en","source_language":"en","source_url":"https://github.com/zigpy/zigpy-znp","tags":["zigbee","home-automation","serial-communication","hardware","ti","znp","iot"],"install":[{"cmd":"pip install zigpy-znp","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core Zigbee application framework which zigpy-znp extends.","package":"zigpy","optional":false},{"reason":"Provides asynchronous serial communication capabilities required to talk to the ZNP radio.","package":"pyserial-asyncio","optional":false},{"reason":"Used for CRC (Cyclic Redundancy Check) calculations, essential for the ZNP protocol's data integrity.","package":"crcmod","optional":false}],"imports":[{"note":"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.","symbol":"ZnpApplication","correct":"from zigpy_znp.zigbee.application import ZnpApplication"}],"quickstart":{"code":"import asyncio\nimport os\nfrom zigpy.application import Controller\nfrom zigpy.config import CONF_DATABASE_PATH, CONF_DEVICE, CONF_RADIO_TYPE\n\nasync def main():\n    # Replace with your actual serial port for the ZNP radio\n    # On Linux: '/dev/ttyACM0' or '/dev/ttyUSB0'\n    # On Windows: 'COM3'\n    serial_port = os.environ.get(\"ZNP_SERIAL_PORT\", \"/dev/ttyUSB0\")\n    \n    # Define the zigpy configuration\n    config = {\n        CONF_DEVICE: {\n            CONF_RADIO_TYPE: \"znp\",  # This activates zigpy-znp\n            \"port\": serial_port,\n        },\n        CONF_DATABASE_PATH: \"zigpy_znp.db\", # Database for network state\n    }\n\n    print(f\"Starting zigpy controller with ZNP radio on {serial_port}...\")\n    controller = Controller(config)\n\n    try:\n        # auto_form=True creates a new network if none exists. Set to False if you expect to join an existing network.\n        await controller.startup(auto_form=True)\n        print(\"Controller started successfully. Network formed/joined.\")\n        # At this point, you can interact with the Zigbee network, e.g., discover devices\n        print(\"Controller running for 10 seconds. Press Ctrl+C to stop sooner.\")\n        await asyncio.sleep(10) # Keep running for 10 seconds\n        print(\"Shutting down controller.\")\n    except Exception as e:\n        print(f\"Error starting controller: {e}\")\n    finally:\n        await controller.shutdown()\n        print(\"Controller shut down.\")\n\nif __name__ == \"__main__\":\n    try:\n        asyncio.run(main())\n    except KeyboardInterrupt:\n        print(\"Exiting.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"On Linux, users often encounter 'Permission denied' errors when accessing serial ports (`/dev/ttyACM0` or `/dev/ttyUSB0`).","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"Incompatible ZNP firmware versions on your TI radio can lead to connection issues, instability, or missing features.","severity":"gotcha","affected_versions":"All versions, depending on hardware firmware"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"Dependent on `zigpy` major version bumps (e.g., zigpy 0.x to 0.y)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The user running the Python script does not have sufficient permissions to access the specified serial device.","error":"SerialException: [Errno 13] Permission denied: '/dev/ttyUSB0'"},{"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`).","cause":"The specified serial port path does not exist or is incorrect for your system.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'COM3'"},{"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.","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.","error":"ValueError: Unknown radio type: 'znp'"}]}