Registry / communication / zigpy-deconz

zigpy-deconz

JSON →
library0.25.5pypypiunverified

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.

pip install zigpy-deconz
INSTALL
IMPORT
SIG · ZIGPY-DECONZ
Z
zigpy-deconz
communicationpythonv0.25.5
Install
6.1s avg
Import
Disk
51MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.25.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 50.5MB
glibc
py 3.103.940 runs
installs and imports cleanly · install 6.1s · import 0.000s · 52MB
51MB installed
● package 51MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Deconz
from zigpy_deconz import Deconz
from zigpy_deconz import Deconz

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())
Debug
Known issues
gotchaDeconz 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.
affects: All
breakingOlder 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.
affects: <0.20.0
gotchaNetwork 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.
affects: All
gotchaThe 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.
affects: All
Upgrade
Version history
0.25.5latest on PyPI · released Nov 2, 2025
Audit
Dependencies
zigpyrequiredCore Zigbee application framework, zigpy-deconz implements a radio backend for it.
websocket-clientoptionalRequired for communication with the Deconz gateway's websocket API. Included with `[full]` extra.
Agent activity
51 hits · last 30 days
node
44
OpenAI (training)
1
Resources
zigpy-deconz — pip install zigpy-deconz · libregistry