{"id":7881,"library":"zigpy-deconz","title":"Zigbee Deconz Radio Backend for Zigpy","description":"zigpy-deconz is a Python library that provides a radio backend for the zigpy framework, enabling communication with Zigbee networks via a Deconz gateway (e.g., ConBee, RaspBee devices managed by the Deconz software). It acts as a bridge, allowing zigpy applications to leverage an existing Deconz installation for Zigbee operations. The current version is 0.25.5, and it typically releases updates in sync with new zigpy versions or significant Deconz API changes.","status":"active","version":"0.25.5","language":"en","source_language":"en","source_url":"https://github.com/zigpy/zigpy-deconz","tags":["zigbee","deconz","smart-home","home-automation","zigpy","radio","websocket"],"install":[{"cmd":"pip install zigpy-deconz","lang":"bash","label":"Install core library"},{"cmd":"pip install zigpy-deconz[full]","lang":"bash","label":"Install with all optional dependencies (e.g., websocket-client)"}],"dependencies":[{"reason":"Core Zigbee application framework, zigpy-deconz implements a radio backend for it.","package":"zigpy","optional":false},{"reason":"Required for communication with the Deconz gateway's websocket API. Included with `[full]` extra.","package":"websocket-client","optional":true}],"imports":[{"note":"The Deconz radio class is exposed under the `zigpy.radio` namespace, not directly from the `zigpy_deconz` package root.","wrong":"import zigpy_deconz","symbol":"Deconz","correct":"from zigpy.radio.deconz import Deconz"}],"quickstart":{"code":"import asyncio\nimport os\nfrom zigpy.radio.deconz import Deconz\n\nasync def main():\n    # Retrieve Deconz gateway details from environment variables\n    # For a real setup, ensure the Deconz gateway is running and accessible\n    deconz_host = os.environ.get('DECONZ_HOST', '127.0.0.1')\n    deconz_port = int(os.environ.get('DECONZ_PORT', '80'))\n    deconz_api_key = os.environ.get('DECONZ_API_KEY', 'YOUR_DECONZ_API_KEY_HERE') # Get API key from Deconz Phoscon App -> Gateway -> Advanced -> Authenticate app\n\n    if deconz_api_key == 'YOUR_DECONZ_API_KEY_HERE':\n        print(\"WARNING: Please set DECONZ_API_KEY environment variable or replace 'YOUR_DECONZ_API_KEY_HERE' with your actual Deconz API key.\")\n        print(\"You can obtain the API key from the Phoscon App (web interface for Deconz) by navigating to Gateway -> Advanced -> Authenticate app.\")\n        return\n\n    # Deconz radio device configuration specific for zigpy\n    device_config = {\n        'path': f'socket://{deconz_host}:{deconz_port}',\n        'api_key': deconz_api_key,\n        # baudrate and flow_control are often ignored by Deconz but required by zigpy's device config structure\n        'baudrate': 115200,\n        'flow_control': 'software',\n    }\n\n    try:\n        # Instantiate the Deconz radio object\n        radio = Deconz(device_config)\n        print(f\"Deconz radio object created for {device_config['path']}.\")\n        # In a full zigpy application, you would pass this 'radio' object to zigpy.application.Controller\n        # For this quickstart, we just demonstrate instantiation. A real connection attempt happens during controller.startup()\n        print(\"Successfully instantiated zigpy.radio.deconz.Deconz. This object is now ready to be passed to a zigpy application controller.\")\n\n    except Exception as e:\n        print(f\"Failed to instantiate Deconz radio: {e}\")\n        print(\"Ensure Deconz gateway is running, accessible at the specified host/port, and the API key is correct.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to instantiate the `Deconz` radio backend. For a complete Zigbee application, the instantiated `radio` object would then be passed to `zigpy.application.Controller` to manage the Zigbee network. Ensure your Deconz gateway is running and you have an API key from the Phoscon App."},"warnings":[{"fix":"Always obtain the latest API key from your Deconz gateway's Phoscon web interface. Store it securely (e.g., environment variable) and pass it as `api_key` in the device configuration.","message":"Deconz API Key is crucial for connection. It must be generated via the Phoscon App (Gateway -> Advanced -> Authenticate App) and passed correctly to the radio configuration. Keys can sometimes expire or be invalidated if the Deconz gateway is reset.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `websocket-client` is installed (preferably via `pip install zigpy-deconz[full]`) and use the `from zigpy.radio.deconz import Deconz` import path.","message":"Older versions of `zigpy-deconz` might have directly bundled `websocket` or used a different import path. Current versions rely on `websocket-client` and expose the radio via `zigpy.radio.deconz`.","severity":"breaking","affected_versions":"<0.20.0"},{"fix":"Verify that the Deconz gateway is running and accessible from the machine running zigpy-deconz. Check network configurations, firewalls, and ensure the host/port in the device path are correct.","message":"Network connectivity issues (host/port) or firewall blocking access to the Deconz gateway are common. The `path` in the device configuration must point to a valid `socket://<host>:<port>`.","severity":"gotcha","affected_versions":"All"},{"fix":"Regularly update your Deconz gateway software and the firmware of your ConBee/RaspBee USB stick through the Phoscon App or Deconz desktop application.","message":"The Deconz gateway firmware and the ConBee/RaspBee stick firmware should be up-to-date and compatible. Outdated firmware can lead to unexpected behavior or connection issues not directly caused by `zigpy-deconz` itself.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the `DECONZ_HOST`, `DECONZ_PORT`, and `DECONZ_API_KEY` are correct. Ensure the Deconz gateway service is running and accessible from your application's host.","cause":"The Deconz gateway closed the connection unexpectedly. This can be due to an invalid API key, the gateway being unavailable, or network instability.","error":"websocket.WebSocketConnectionClosedException: [Errno 104] Connection reset by peer"},{"fix":"Install the `websocket-client` dependency. The easiest way is `pip install zigpy-deconz[full]` or `pip install websocket-client`.","cause":"The `websocket-client` library, which `zigpy-deconz` depends on for communication with the Deconz gateway, is not installed.","error":"ModuleNotFoundError: No module named 'websocket'"},{"fix":"Check the IP address and port configured for your Deconz gateway. Ensure no firewall is blocking the connection and that the Deconz service is running on the gateway.","cause":"The `zigpy-deconz` library could not establish a network connection to the specified Deconz gateway host and port. This indicates a network or firewall issue.","error":"Failed to create radio: Cannot connect to host <IP_ADDRESS>:<PORT> ssl:default [Connect call failed ('<IP_ADDRESS>', <PORT>)]"}]}