zigpy-xbee

Common errors

• Failed to connect: 'serial.serialutil.SerialException: Could not open port /dev/ttyUSB0: [Errno 13] Permission denied:'

  cause The current user does not have permission to access the serial port.
  fix Add your user to the `dialout` group (or equivalent) and reboot: `sudo usermod -a -G dialout $USER`

• Failed to connect: 'serial.serialutil.SerialException: read failed: device reports readiness to read but returned no data (device disconnected or raw data error)'

  cause The XBee device is not properly connected, its firmware is not in API mode, or the baud rate is incorrect.
  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.

• Zigbee devices frequently disconnect or fail to respond, especially battery-powered end devices.

  cause Weak Zigbee mesh network, Wi-Fi interference, or poor physical placement of the coordinator/routers.
  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.

• AttributeError: module 'collections' has no attribute 'abc' (or similar during startup on Python 3.10+)

  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.
  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`.

Warnings

• breaking 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.
  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).
• gotcha USB 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.
• gotcha Zigbee 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.
• deprecated 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.
  Fix: Monitor `zigpy` and `Home Assistant ZHA` release notes and discussions for updates on long-term support plans for XBee radios.

Install

• pip install zigpy-xbee Install latest version

Imports

• ControllerApplication

  from zigpy_xbee.zigbee.application import ControllerApplication

• XBee

  import zigpy_xbee

Quickstart

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())