{"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":"python","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":[{"wrong":"from zigpy_xbee import ControllerApplication","symbol":"ControllerApplication","correct":"from zigpy_xbee import ControllerApplication"}],"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,"search_vec":"'0.21.1':53 '3.8':57 'act':23 'activ':62 'allow':33 'assist':81 'autom':45 'broader':68 'chang':76 'coincid':74 'communic':13 'compon':84 'current':50 'devic':17 'digi':37,90 'ecosystem':70 'enabl':12 'hardwar':27 'hardware-specif':26 'home':44,80 'integr':36 'iot':88 'librari':10,30,48 'maintain':63 'modul':40 'newer':59 'part':65 'project':21 'python':9,56 'radio':16,29,89 'requir':55 'setup':46 'smarthom':87 'specif':28 'typic':73 'updat':72 'user':34 'version':52 'xbee':3,6,15,38,86 'zha':83 'zigbe':39,43,85 'zigpi':2,5,20,32,69,78 'zigpy-xbe':1,4","created_at":"2026-04-16T14:17:27.275766+00:00","updated_at":"2026-04-16T14:17:27.275766+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nImportError: cannot import name 'ControllerApplication' from 'zigpy_xbee' (/tmp/tmp92ts6pt4/venv/lib/python3.12/site-packages/zigpy_xbee/__init__.py)"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.21.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/zigpy/zigpy-xbee","docs":null,"changelog":null,"pypi":"https://pypi.org/project/zigpy-xbee/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","aws","llm-agents"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}