Registry / data / zigpy-xbee

zigpy-xbee

JSON →
library0.21.1pypypiunverified

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.

pip install zigpy-xbee
INSTALL
IMPORT
SIG · ZIGPY-XBEE
Z
zigpy-xbee
datapythonv0.21.1
Install
6.0s avg
Import
1731ms
Disk
51MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.21.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 1.800s · 50.5MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 6.0s · import 1.662s · 52MB
51MB installed
● package 51MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ControllerApplication
from zigpy_xbee import ControllerApplication
from zigpy_xbee import ControllerApplication

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.

import asyncio import logging import os from zigpy_xbee.zigbee.application import ControllerApplication logging.basicConfig(level=logging.INFO) LOGGER = logging.getLogger(__name__) async def main(): # Replace '/dev/ttyUSB0' with your XBee's serial port # Ensure XBee is configured for API mode (ATAP2) and 57600 baud (ATBD6) using XCTU serial_port = os.environ.get('ZB_SERIAL_PORT', '/dev/ttyUSB0') baud_rate = 57600 # A persistent database file is highly recommended for zigpy applications database_path = os.environ.get('ZB_DATABASE_PATH', 'zigbee.db') try: # Initialize the XBee ControllerApplication application = ControllerApplication( config={ 'device': { 'path': serial_port, 'baudrate': baud_rate, } }, database_file=database_path ) # Start the application LOGGER.info(f"Starting zigpy-xbee on {serial_port}...") await application.startup(auto_form=True) LOGGER.info("zigpy-xbee application started successfully.") # Example: Enable pairing mode for 120 seconds LOGGER.info("Enabling pairing mode for 120 seconds...") application.permit_joining(120) # Keep the application running while True: await asyncio.sleep(3600) # Keep running for a long time or until interrupted except Exception as e: LOGGER.error(f"Failed to start zigpy-xbee: {e}") finally: if 'application' in locals() and application.state != 'dead': LOGGER.info("Shutting down zigpy-xbee application.") await application.shutdown() if __name__ == '__main__': asyncio.run(main())
Debug
Known issues
breakingXBee 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.
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).
affects: <=0.21.1
gotchaUSB 3.0 ports can cause 2.4GHz interference, negatively impacting Zigbee signal quality and reliability.
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.
affects: All
gotchaZigbee and 2.4GHz Wi-Fi operate on overlapping frequencies, leading to signal interference and an unreliable Zigbee network.
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.
affects: All
deprecatedThere 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.
fix
Monitor `zigpy` and `Home Assistant ZHA` release notes and discussions for updates on long-term support plans for XBee radios.
affects: Future versions
Upgrade
Version history
0.21.1latest on PyPI · released Nov 1, 2025
Audit
Dependencies
zigpyrequiredCore Zigbee protocol stack that zigpy-xbee integrates with.
pyserialrequiredHandles serial communication with the XBee radio.
Agent activity
59 hits · last 30 days
node
52
Perplexity
1
OpenAI (training)
1
Resources
zigpy-xbee — pip install zigpy-xbee · libregistry