Zigbee Deconz Radio Backend for Zigpy

0.25.5 · active · verified Thu Apr 16

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.

Common errors

```
websocket.WebSocketConnectionClosedException: [Errno 104] Connection reset by peer
```
cause The Deconz gateway closed the connection unexpectedly. This can be due to an invalid API key, the gateway being unavailable, or network instability.

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.
```
ModuleNotFoundError: No module named 'websocket'
```
cause The `websocket-client` library, which `zigpy-deconz` depends on for communication with the Deconz gateway, is not installed.

fix Install the `websocket-client` dependency. The easiest way is `pip install zigpy-deconz[full]` or `pip install websocket-client`.
```
Failed to create radio: Cannot connect to host <IP_ADDRESS>:<PORT> ssl:default [Connect call failed ('<IP_ADDRESS>', <PORT>)]
```
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.

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.

Warnings

gotcha 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.
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.
breaking 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`.
Fix: Ensure `websocket-client` is installed (preferably via `pip install zigpy-deconz[full]`) and use the `from zigpy.radio.deconz import Deconz` import path.
gotcha 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>`.
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.
gotcha 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.
Fix: Regularly update your Deconz gateway software and the firmware of your ConBee/RaspBee USB stick through the Phoscon App or Deconz desktop application.

Install

pip install zigpy-deconz Install core library
pip install zigpy-deconz[full] Install with all optional dependencies (e.g., websocket-client)

Imports

Deconz
wrong:
```
import zigpy_deconz
```
correct:
```
from zigpy.radio.deconz import Deconz
```
The Deconz radio class is exposed under the `zigpy.radio` namespace, not directly from the `zigpy_deconz` package root.

Quickstart

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.

import asyncio
import os
from zigpy.radio.deconz import Deconz

async def main():
    # Retrieve Deconz gateway details from environment variables
    # For a real setup, ensure the Deconz gateway is running and accessible
    deconz_host = os.environ.get('DECONZ_HOST', '127.0.0.1')
    deconz_port = int(os.environ.get('DECONZ_PORT', '80'))
    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

    if deconz_api_key == 'YOUR_DECONZ_API_KEY_HERE':
        print("WARNING: Please set DECONZ_API_KEY environment variable or replace 'YOUR_DECONZ_API_KEY_HERE' with your actual Deconz API key.")
        print("You can obtain the API key from the Phoscon App (web interface for Deconz) by navigating to Gateway -> Advanced -> Authenticate app.")
        return

    # Deconz radio device configuration specific for zigpy
    device_config = {
        'path': f'socket://{deconz_host}:{deconz_port}',
        'api_key': deconz_api_key,
        # baudrate and flow_control are often ignored by Deconz but required by zigpy's device config structure
        'baudrate': 115200,
        'flow_control': 'software',
    }

    try:
        # Instantiate the Deconz radio object
        radio = Deconz(device_config)
        print(f"Deconz radio object created for {device_config['path']}.")
        # In a full zigpy application, you would pass this 'radio' object to zigpy.application.Controller
        # For this quickstart, we just demonstrate instantiation. A real connection attempt happens during controller.startup()
        print("Successfully instantiated zigpy.radio.deconz.Deconz. This object is now ready to be passed to a zigpy application controller.")

    except Exception as e:
        print(f"Failed to instantiate Deconz radio: {e}")
        print("Ensure Deconz gateway is running, accessible at the specified host/port, and the API key is correct.")

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

view raw JSON →