Iot-protocolsHow-ToBeginner · 4 min read

How to Use Zigbee with Raspberry Pi: Setup and Example

To use Zigbee with a Raspberry Pi, connect a Zigbee USB adapter like the CC2531 or ConBee II to the Pi, install necessary software such as zigbee2mqtt or deCONZ, and use Python libraries like zigpy or pyzigbee to communicate with Zigbee devices. This setup allows your Raspberry Pi to send and receive Zigbee signals for home automation or sensor data.

📐

Syntax

Here is the basic syntax to communicate with Zigbee devices on Raspberry Pi using Python and the zigpy library:

import zigpy: Import the Zigbee library.
zigbee_app = zigpy.ApplicationController(): Create a Zigbee controller instance.
zigbee_app.start(): Start the Zigbee network.
zigbee_app.permit(duration): Allow new devices to join for a set time.
zigbee_app.devices: Access connected Zigbee devices.

This pattern helps you initialize and manage Zigbee devices programmatically.

python

import asyncio
from zigpy.application import ControllerApplication

async def main():
    app = await ControllerApplication.new(config={
        'database_path': 'zigbee.db',
        'device': {'path': '/dev/ttyUSB0', 'baudrate': 115200}
    })
    await app.start()
    print('Zigbee network started')
    await app.permit(60)  # Allow devices to join for 60 seconds
    print('Permit join enabled for 60 seconds')
    await asyncio.sleep(60)
    await app.stop()

asyncio.run(main())

Output

Zigbee network started Permit join enabled for 60 seconds

💻

Example

This example shows how to start a Zigbee network on Raspberry Pi using a CC2531 USB adapter and the zigpy Python library. It enables device joining for 60 seconds and then stops the network.

python

import asyncio
from zigpy.application import ControllerApplication

async def main():
    app = await ControllerApplication.new(config={
        'database_path': 'zigbee.db',
        'device': {'path': '/dev/ttyUSB0', 'baudrate': 115200}
    })
    await app.start()
    print('Zigbee network started')
    await app.permit(60)  # Allow devices to join for 60 seconds
    print('Permit join enabled for 60 seconds')
    await asyncio.sleep(60)
    await app.stop()

asyncio.run(main())

Output

Zigbee network started Permit join enabled for 60 seconds

⚠️

Common Pitfalls

Wrong USB device path: The Zigbee adapter may not be at /dev/ttyUSB0. Use ls /dev/tty* to find the correct path.
Missing drivers: Some adapters need drivers installed on Raspberry Pi.
Not enabling permit join: Devices cannot join the network if permit join is not enabled.
Power issues: USB adapters may need a powered USB hub if Pi USB ports supply low power.

python

import asyncio
from zigpy.application import ControllerApplication

async def main():
    # Wrong device path example
    app = await ControllerApplication.new(config={
        'database_path': 'zigbee.db',
        'device': {'path': '/dev/ttyUSB1', 'baudrate': 115200}  # May be incorrect
    })
    await app.start()
    print('Zigbee network started')
    await app.permit(60)
    await asyncio.sleep(60)
    await app.stop()

asyncio.run(main())

# Correct device path example
# Change '/dev/ttyUSB1' to the actual device path found on your Pi

📊

Quick Reference

Zigbee USB adapters: CC2531, ConBee II, Zigbee HAT
Software: zigbee2mqtt, deCONZ, zigpy
Python libraries: zigpy for direct control, paho-mqtt for MQTT integration
Device path: Usually /dev/ttyUSB0 or /dev/serial/by-id/
Permit join: Must be enabled to add new devices

✅

Key Takeaways

Connect a Zigbee USB adapter to Raspberry Pi and identify its device path.

Install and use software like zigbee2mqtt or Python libraries like zigpy to manage Zigbee devices.

Enable permit join mode to allow new Zigbee devices to connect.

Check for correct USB device path and power supply to avoid connection issues.

Use Python async code to start, manage, and stop the Zigbee network cleanly.