{"id":9420,"library":"zigpy-zigate","title":"zigpy-zigate","description":"zigpy-zigate is a Python 3 library that provides an implementation for the `zigpy` project, enabling communication with ZiGate based Zigbee radio devices. It acts as a hardware abstraction layer for ZiGate USB, USB-DIN, PiZiGate, and ZiGate Ethernet modules. The library is actively maintained and is primarily used as a backend for Zigbee Home Automation (ZHA) integrations in Home Assistant. Its current version is 0.13.4, with releases generally following the development pace of `zigpy` and Home Assistant's ZHA component.","status":"active","version":"0.13.4","language":"en","source_language":"en","source_url":"https://github.com/zigpy/zigpy-zigate","tags":["zigbee","home-automation","zigate","zigpy","radio","home-assistant","zha"],"install":[{"cmd":"pip install zigpy-zigate","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core Zigbee protocol stack; zigpy-zigate is a radio backend for zigpy.","package":"zigpy"},{"reason":"Asynchronous serial communication with the ZiGate radio.","package":"pyserial-asyncio"},{"reason":"Data validation for configuration.","package":"voluptuous"}],"imports":[{"note":"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.","wrong":"from zigpy_zigate import ZiGateController","symbol":"Controller","correct":"from zigpy.application import Controller\nimport zigpy_zigate"}],"quickstart":{"code":"import asyncio\nimport os\nfrom zigpy.application import Controller\nfrom zigpy.config import CONF_DEVICE, CONF_DEVICE_PATH, CONF_RADIO_TYPE\n\n# Ensure zigpy-zigate is imported so its radio type is registered\nimport zigpy_zigate # noqa: F401\n\nasync def main():\n    # Replace '/dev/ttyUSB0' with your ZiGate's serial port\n    # For PiZiGate, it might be '/dev/serial0' or '/dev/ttyAMA0'\n    # For ZiGate Ethernet, it would be 'socket://IP_ADDRESS:PORT'\n    zigate_port = os.environ.get('ZIGATE_PORT', '/dev/ttyUSB0')\n\n    config = {\n        CONF_DEVICE: {\n            CONF_DEVICE_PATH: zigate_port,\n            CONF_RADIO_TYPE: 'zigate'\n        }\n    }\n\n    controller = None\n    try:\n        print(f\"Initializing zigpy Controller with ZiGate on {zigate_port}...\")\n        controller = await Controller.new(config)\n        print(\"Zigbee network initialized. Controller is running.\")\n        # In a real application, you would now interact with the controller\n        # e.g., controller.add_endpoint(), controller.start_network(), etc.\n        print(\"Controller object created. You can now use it to manage your Zigbee network.\")\n        print(\"Press Ctrl+C to stop.\")\n        await asyncio.Event().wait() # Keep the event loop running indefinitely\n    except Exception as e:\n        print(f\"Error during zigpy initialization: {e}\")\n    finally:\n        if controller:\n            await controller.shutdown()\n            print(\"Controller shut down.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"Future versions of Home Assistant ZHA (post-April 2025 discussion)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"< 3.1d firmware on ZiGate hardware"},{"fix":"Be aware of these limitations. If your use case requires these specific features, consider a different Zigbee adapter that explicitly supports them.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`).","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.","error":"AttributeError: module 'zigpy.types' has no attribute 'HexRepr'"},{"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.","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).","error":"ERROR: Command errored out with exit status 1: ... Unable to install package zigpy-zigate==X.X.X"},{"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).","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).","error":"Home Assistant ZHA component not starting with zigpy-zigate after upgrade (e.g., to 2022.10.0)"}]}