Open Peer Power Open Peer Power
Edit this page on GitHub

Zigbee Power Management

Zigbee Power Management integration for Open Peer Power allows you to connect many off-the-shelf Zigbee based devices to Open Peer Power, using one of the available Zigbee radio modules that is compatible with zigpy (an open source Python library implementing a Zigbee stack, which in turn relies on separate libraries which can each interface a with Zigbee radio module a different manufacturer).

There is currently support for the following device types within Open Peer Power:

  • Binary Sensor
  • Cover
  • Fan
  • Light
  • Lock
  • Sensor
  • Switch

ZHA exception and deviation handling

Zigbee devices that deviate from or do not fully conform to the standard specifications set by the Zigbee Alliance may require the development of custom ZHA Device Handlers (ZHA custom quirks handler implementation) to for all their functions to work properly with the ZHA integration in Open Peer Power. These ZHA Device Handlers for Open Peer Power can thus be used to parse custom messages to and from Zigbee devices.

The custom quirks implementations for zigpy implemented as ZHA Device Handlers for Open Peer Power are a similar concept to that of Hub-connected Device Handlers for the SmartThings Classics platform as well as that of Zigbee-Shepherd Converters as used by Zigbee2mqtt, meaning they are each virtual representations of a physical device that expose additional functionality that is not provided out-of-the-box by the existing integration between these platforms.

Known working Zigbee radio modules

Configuration - GUI

From the Open Peer Power front page go to Configuration and then select Integrations from the list.

Use the plus button in the bottom right to add a new integration called ZHA.

In the popup:

  • USB Device Path - on a Linux system will be something like /dev/ttyUSB0 or /dev/ttyACM0
  • Radio type - select device type ezsp, deconz, ti_cc, xbee or zigate
  • Submit
Radio Type Zigbee Radio Hardware
ezsp EmberZNet based radios, Telegesis ETRX357USB*** (using EmberZNet firmware)
deconz ConBee, ConBee II
xbee Digi XBee Series 2, 2C, 3
  • Press Submit to save changes.

The success dialog will appear or an error will be displayed in the popup. An error is likely if Open Peer Power can’t access the USB device or your device is not up to date. Refer to Troubleshooting below for more information.

Configuration - Manual

To configure the component, select ZHA on the Integrations page and provide the path to your Zigbee USB stick.

Or, you can manually configure zha section in configuration.yaml. The path to the database which will persist your network data is required.

# Example configuration.yaml entry
zha:
  usb_path: /dev/ttyUSB2
  database_path: /home/openpeerpower/.openpeerpower/zigbee.db

If you are use ZiGate, you have to use some special usb_path configuration:

  • ZiGate USB TTL or DIN: /dev/ttyUSB0 or auto to auto discover the zigate
  • PiZigate : pizigate:/dev/serial0
  • Wifi Zigate : socket://[IP]:[PORT] for example socket://192.168.1.10:9999

To add new devices to the network, call the permit service on the zha domain. Do this by clicking the Service icon in Developer tools and typing zha.permit in the Service dropdown box. Next, follow the device instructions for adding, scanning or factory reset.

Adding devices

Go to the Configuration page and select the ZHA integration that was added by the configuration steps above.

Click on ADD DEVICES to start a scan for new devices.

Reset your Zigbee devices according to the device instructions provided by the manufacturer (e.g., turn on/off lights up to 10 times, switches usually have a reset button/pin).

Troubleshooting

Add Philips Hue bulbs that have previously been added to another bridge

Philips Hue bulbs that have previously been added to another bridge won’t show up during search. You have to restore your bulbs back to factory settings first. To achieve this, you basically have the following options.

Philips Hue Dimmer Switch

Using a Philips Hue Dimmer Switch is probably the easiest way to factory-reset your bulbs. For this to work, the remote doesn’t have to be paired with your previous bridge.

  1. Turn on your Hue bulb you want to reset
  2. Hold the Dimmer Switch near your bulb (< 10 cm)
  3. Press and hold the (I)/(ON) and (O)/(OFF) buttons of the Dimmer Switch for about 10 seconds until your bulb starts to blink
  4. Your bulb should stop blinking and eventually turning on again. At the same time, a green light on the top left of your remote indicates that your bulb has been successfully reset to factory settings.

hue-thief

Follow the instructions on https://github.com/vanviegen/hue-thief/ (EZSP-based Zigbee USB stick required)

ZHA Start up issue with Open Peer Power Supervised or Open Peer Power Core on Docker

On Linux hosts ZHA can fail to start during HA startup or restarts because the Zigbee USB device is being claimed by the host’s modemmanager service. To fix this disable the modemmanger on the host system.

To remove modemmanager from an Debian/Ubuntu host run this command:

sudo apt-get purge modemmanager

Can’t connect to USB device and using Docker

If you are using Docker and can’t connect, you most likely need to forward your device from the host machine to the Docker instance. This can be achieved by adding the device mapping to the end of the startup string or ideally using Docker compose.

Docker Compose

Install Docker-Compose for your platform (Linux - sudo apt-get install docker-compose).

Create a docker-compose.yml with the following data:

version: '2'
services:
  openpeerpower:
    # customisable name
    container_name: open-peer-power

    # must be image for your platform, this is the rpi3 variant
    image: openpeerpower/raspberrypi3-openpeerpower
    volumes:
      - /etc/localtime:/etc/localtime:ro
    devices:
      # your usb device forwarding to the docker image
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: always
    network_mode: host