zigpy-zigate

Common errors

• AttributeError: module 'zigpy.types' has no attribute 'HexRepr'

  cause This error typically occurs when using development or unreleased branches of `zigpy-zigate` with an incompatible (often older) development branch of `zigpy`, where `HexRepr` was moved or renamed.
  fix Ensure that both `zigpy` and `zigpy-zigate` are installed from stable releases or that their development branches are mutually compatible. Pin versions if necessary (e.g., `pip install zigpy==X.Y.Z zigpy-zigate==A.B.C`).

• ERROR: Command errored out with exit status 1: ... Unable to install package zigpy-zigate==X.X.X

  cause Installation failures, particularly around versions 0.7.x, were sometimes linked to conflicts with the `typing` package and specific `pip` versions, especially in older Python environments (e.g., Python 3.8 with older pip).
  fix Try upgrading `pip` (`python3 -m pip install --upgrade pip`). If the issue persists, a specific workaround involved uninstalling `typing` and downgrading `pip` to version 20.0.2 or lower, then reinstalling `zigpy-zigate`. However, generally, ensure your Python environment is up-to-date.

• Home Assistant ZHA component not starting with zigpy-zigate after upgrade (e.g., to 2022.10.0)

  cause Upgrades to Home Assistant or underlying `zigpy` components can introduce incompatibilities if `zigpy-zigate` is not also updated or if there are specific system configuration requirements (like UART enablement on Raspberry Pi).
  fix 1. Ensure `zigpy-zigate` is updated to the latest compatible version (`pip install --upgrade zigpy-zigate`). 2. Verify system-level configurations for serial communication (e.g., `enable_uart=1` in `/boot/config.txt` and removing `console=serial0,115200` from `/boot/cmdline.txt` on Raspberry Pi for PiZiGate).

Warnings

• breaking Future deprecation within Home Assistant's ZHA integration: An issue was opened in April 2025 to discuss deprecating XBee and ZiGate radio support within the `zigpy/zha` project, which is the primary consumer of `zigpy-zigate`. This indicates a potential future breaking change for users relying on `zigpy-zigate` through Home Assistant ZHA.
  Fix: Monitor `zigpy/zha` and `zigpy-zigate` GitHub repositories for official announcements. Consider migrating to a different, actively recommended Zigbee adapter if you rely on ZHA.
• gotcha ZiGate Firmware Compatibility: ZiGate hardware requires firmware 3.1a or later to function with `zigpy-zigate`. Firmware 3.1d or later is strongly recommended as it includes critical bug fixes related to `zigpy` compatibility. Using older firmware can lead to unexpected issues or instability.
  Fix: Ensure your ZiGate adapter's firmware is updated to at least version 3.1d. `zigpy-zigate` includes an integrated 'flasher' tool for NXP Jennic JN5168 chips. Refer to official ZiGate firmware releases for updates.
• gotcha Limited Feature Support: Some advanced Zigbee features are not supported by ZiGate adapters when used with `zigpy-zigate` and `zigbee-herdsman` (which can also use ZiGate). These include changing the Zigbee channel without re-pairing all devices, adding install codes (required for some devices), full backups, and Inter-PAN communication (required for Touchlink).
  Fix: Be aware of these limitations. If your use case requires these specific features, consider a different Zigbee adapter that explicitly supports them.

Install

• pip install zigpy-zigate Install latest version

Imports

• Controller
  wrong:

  from zigpy_zigate import ZiGateController

  correct:

  from zigpy.application import Controller
  import zigpy_zigate

  zigpy-zigate registers itself as a radio type with zigpy; direct instantiation of a ZiGate-specific controller class is not the typical pattern. You import zigpy_zigate to ensure the radio type 'zigate' is available for zigpy.application.Controller.

Quickstart

This quickstart demonstrates how to initialize a `zigpy` controller with a ZiGate radio. The `zigpy-zigate` library automatically registers the 'zigate' radio type when imported. You need to provide the correct serial port path for your ZiGate device. For Ethernet ZiGate, use a `socket://IP:PORT` format. This example initializes the controller and keeps the event loop running; a real application would then build and manage the Zigbee network.

import asyncio
import os
from zigpy.application import Controller
from zigpy.config import CONF_DEVICE, CONF_DEVICE_PATH, CONF_RADIO_TYPE

# Ensure zigpy-zigate is imported so its radio type is registered
import zigpy_zigate # noqa: F401

async def main():
    # Replace '/dev/ttyUSB0' with your ZiGate's serial port
    # For PiZiGate, it might be '/dev/serial0' or '/dev/ttyAMA0'
    # For ZiGate Ethernet, it would be 'socket://IP_ADDRESS:PORT'
    zigate_port = os.environ.get('ZIGATE_PORT', '/dev/ttyUSB0')

    config = {
        CONF_DEVICE: {
            CONF_DEVICE_PATH: zigate_port,
            CONF_RADIO_TYPE: 'zigate'
        }
    }

    controller = None
    try:
        print(f"Initializing zigpy Controller with ZiGate on {zigate_port}...")
        controller = await Controller.new(config)
        print("Zigbee network initialized. Controller is running.")
        # In a real application, you would now interact with the controller
        # e.g., controller.add_endpoint(), controller.start_network(), etc.
        print("Controller object created. You can now use it to manage your Zigbee network.")
        print("Press Ctrl+C to stop.")
        await asyncio.Event().wait() # Keep the event loop running indefinitely
    except Exception as e:
        print(f"Error during zigpy initialization: {e}")
    finally:
        if controller:
            await controller.shutdown()
            print("Controller shut down.")

if __name__ == "__main__":
    asyncio.run(main())