{"id":7882,"library":"zigpy-xbee","title":"zigpy-xbee","description":"zigpy-xbee is a Python library that enables communication with XBee radio devices for the zigpy project. It acts as a hardware-specific radio library for zigpy, allowing users to integrate Digi XBee Zigbee modules into a Zigbee Home Automation setup. The library is currently at version 0.21.1 and requires Python 3.8 or newer. It is actively maintained as part of the broader zigpy ecosystem, with updates typically coinciding with changes in zigpy or Home Assistant's ZHA component.","status":"active","version":"0.21.1","language":"en","source_language":"en","source_url":"https://github.com/zigpy/zigpy-xbee","tags":["zigbee","xbee","smarthome","iot","radio","digi"],"install":[{"cmd":"pip install zigpy-xbee","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core Zigbee protocol stack that zigpy-xbee integrates with.","package":"zigpy"},{"reason":"Handles serial communication with the XBee radio.","package":"pyserial"}],"imports":[{"symbol":"ControllerApplication","correct":"from zigpy_xbee.zigbee.application import ControllerApplication"},{"symbol":"XBee","correct":"import zigpy_xbee"}],"quickstart":{"code":"import asyncio\nimport logging\nimport os\nfrom zigpy_xbee.zigbee.application import ControllerApplication\n\nlogging.basicConfig(level=logging.INFO)\nLOGGER = logging.getLogger(__name__)\n\nasync def main():\n    # Replace '/dev/ttyUSB0' with your XBee's serial port\n    # Ensure XBee is configured for API mode (ATAP2) and 57600 baud (ATBD6) using XCTU\n    serial_port = os.environ.get('ZB_SERIAL_PORT', '/dev/ttyUSB0')\n    baud_rate = 57600\n\n    # A persistent database file is highly recommended for zigpy applications\n    database_path = os.environ.get('ZB_DATABASE_PATH', 'zigbee.db')\n\n    try:\n        # Initialize the XBee ControllerApplication\n        application = ControllerApplication(\n            config={\n                'device': {\n                    'path': serial_port,\n                    'baudrate': baud_rate,\n                }\n            },\n            database_file=database_path\n        )\n\n        # Start the application\n        LOGGER.info(f\"Starting zigpy-xbee on {serial_port}...\")\n        await application.startup(auto_form=True)\n        LOGGER.info(\"zigpy-xbee application started successfully.\")\n\n        # Example: Enable pairing mode for 120 seconds\n        LOGGER.info(\"Enabling pairing mode for 120 seconds...\")\n        application.permit_joining(120)\n\n        # Keep the application running\n        while True:\n            await asyncio.sleep(3600) # Keep running for a long time or until interrupted\n\n    except Exception as e:\n        LOGGER.error(f\"Failed to start zigpy-xbee: {e}\")\n    finally:\n        if 'application' in locals() and application.state != 'dead':\n            LOGGER.info(\"Shutting down zigpy-xbee application.\")\n            await application.shutdown()\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to initialize and start a `zigpy-xbee` controller application. It configures the serial port and baud rate, then starts the Zigbee network, optionally forming a new one if it doesn't exist. It also includes an example of enabling pairing mode for new devices to join. Ensure your XBee radio is pre-configured for API mode and the correct baud rate using Digi's XCTU tool."},"warnings":[{"fix":"Use Digi XCTU software to flash the latest Zigbee Coordinator API firmware and set ATAP2 (API mode) and ATBD6 (57600 baud) parameters, then write changes (ATWR).","message":"XBee radio firmware must be updated and configured for API mode (ATAP2) and a consistent baud rate (e.g., ATBD6 for 57600) using Digi's XCTU tool. Incorrect firmware or settings will prevent `zigpy-xbee` from communicating.","severity":"breaking","affected_versions":"<=0.21.1"},{"fix":"Use a USB 2.0 port or a shielded USB extension cable (at least 1m long) to move the XBee coordinator away from the computer's USB port.","message":"USB 3.0 ports can cause 2.4GHz interference, negatively impacting Zigbee signal quality and reliability.","severity":"gotcha","affected_versions":"All"},{"fix":"Change your Wi-Fi router's 2.4GHz channel to avoid overlap with your Zigbee channel (e.g., Zigbee channel 25 often avoids common Wi-Fi channels). Refer to Zigbee best practices for channel selection.","message":"Zigbee and 2.4GHz Wi-Fi operate on overlapping frequencies, leading to signal interference and an unreliable Zigbee network.","severity":"gotcha","affected_versions":"All"},{"fix":"Monitor `zigpy` and `Home Assistant ZHA` release notes and discussions for updates on long-term support plans for XBee radios.","message":"There are ongoing discussions within the `zigpy/zha` ecosystem about potentially deprecating XBee and ZiGate radio support in future Home Assistant releases, which could affect `zigpy-xbee`'s primary use case.","severity":"deprecated","affected_versions":"Future versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add your user to the `dialout` group (or equivalent) and reboot: `sudo usermod -a -G dialout $USER`","cause":"The current user does not have permission to access the serial port.","error":"Failed to connect: 'serial.serialutil.SerialException: Could not open port /dev/ttyUSB0: [Errno 13] Permission denied:'"},{"fix":"Verify USB cable connection and XBee orientation. Use Digi's XCTU to confirm the XBee is in API mode (ATAP2) and the baud rate (e.g., 57600/ATBD6) matches your `zigpy-xbee` configuration. Ensure the XBee is powered.","cause":"The XBee device is not properly connected, its firmware is not in API mode, or the baud rate is incorrect.","error":"Failed to connect: 'serial.serialutil.SerialException: read failed: device reports readiness to read but returned no data (device disconnected or raw data error)'"},{"fix":"Add more mains-powered Zigbee router devices to strengthen the mesh. Place the Zigbee coordinator on a USB extension cable away from computer/router. Adjust Wi-Fi channels to avoid overlap with Zigbee. Ensure devices are factory reset and paired in their final location, or close to the coordinator initially.","cause":"Weak Zigbee mesh network, Wi-Fi interference, or poor physical placement of the coordinator/routers.","error":"Zigbee devices frequently disconnect or fail to respond, especially battery-powered end devices."},{"fix":"Ensure all `zigpy` related libraries, including `zigpy-xbee` and `zigpy`, are updated to their latest versions compatible with Python 3.10 or newer: `pip install --upgrade zigpy zigpy-xbee pyserial`.","cause":"Older versions of a dependency (possibly `digi-xbee` or `zigpy` itself, which `zigpy-xbee` relies on) might be using deprecated `collections` module imports that were moved to `collections.abc` in Python 3.10.","error":"AttributeError: module 'collections' has no attribute 'abc' (or similar during startup on Python 3.10+)"}]}