ZB-Stick with OpenHAB

Introduction

This document describes how to use POPP ZB-Stick with an existing Home Automation platform called OpenHAB. You can find more information at https://www.openhab.org/.

POPP ZB-Stick firmware version referenced in this guide: 6.0.3

OpenHAB2 software version referenced in this guide: v2.5.10

This guide focuses on:

• Connecting the POPP ZB-Stick to the target Host system
• Setting up the Zigbee Home Automation Binding in OpenHAB
• Troubleshooting common issues
• Pairing and removing Zigbee devices
• Examples of Zigbee device integration

This guide does NOT cover OpenHAB (openHABian) installation and initial configuration. Please follow the official instructions available at https://docs.openhab.org/installation/openhabian.html.

System Scenarios

The POPP ZB-Stick can be used with a generic Linux machine with OpenHAB installed, or with a Raspberry Pi that has OpenHABian installed.

Diagram Description: The document illustrates two setup scenarios. The first shows a laptop connected to a network of smart home devices (light bulbs, sensors). The second shows a Raspberry Pi board connected to a similar network of smart home devices.

Initial setup and connection

This guide assumes you can access the OpenHAB Web Interface using your browser, as it does not cover OpenHAB (openHABian) installation.

Insert the POPP ZB-Stick into your Host machine.

Screenshot Description: The OpenHAB web interface is shown, specifically the "Inbox" section. It indicates that the inbox is empty and provides a button to "SEARCH FOR THINGS".

OpenHAB Zigbee configuration

To integrate the POPP ZB-Stick Adapter with OpenHAB, the Zigbee Home Automation Binding is used. Refer to the documentation at https://docs.openhab.org/addons/bindings/zigbee/readme.html. This binding must be installed separately as it is not included by default.

Setup Logging (optional)

To help diagnose potential issues, it is recommended to enable logging during the setup and installation phase. Follow these steps:

• Connect to the OpenHAB SSH console using your preferred tool (default login:password is openhabian:openhabian). For example: ssh openhabian@192.168.0.103
• Connect to the "Karaf Console" using the following command (for more details, see https://docs.openhab.org/administration/console.html): ssh -p 8101 openhab@localhost
• Execute the following commands:
  • log:set debug org.openhab.binding.zigbee
  • log:set debug com.zsmartsystems.zigbee
  • log:set info com.zsmartsystems.zigbee.dongle.ember.internal.ash
• Exit the "Karaf Console" by pressing Ctrl+D.

Logs can be viewed in the web browser or the SSH console using the command (for more details, see https://docs.openhab.org/administration/logging.html): openhab-cli showlogs

Configure Zigbee Binding

To ensure the Zigbee Home Automation binding functions correctly with the POPP ZB-Stick, install the Zigbee Binding from the Add-ons section in the Paper UI. It is crucial to use version v2.5.10 or later, as earlier versions do not support Software Flow Control.

Screenshot Description: The OpenHAB Paper UI Add-ons screen is displayed, showing the "ZigBee Binding" with version 2.5.10 selected.

Once installed, navigate to the Configuration > Things section in the menu. Add a new Thing, select Zigbee Binding > Ember EM35x Coordinator, and configure its properties:

• Set the Serial Port to /dev/ttyUSB0. If this port is not visible, consult the Troubleshooting section.
• Set the Flow Control to None.
• Set the Baud Rate to 115200.

Save the new Thing configuration.

Screenshot Description: The configuration parameters for the Ember EM35x Coordinator are shown, including fields for Serial Port, Baud Rate, and Ember NCP Configuration (Power Mode, Transmit Power, Child Aging Timeout, Network Size).

After adding the Thing, it will take approximately 10 seconds to initialize. A successful initialization will display the status as ONLINE. If the status remains unchanged, refer to the Troubleshooting section.

Screenshot Description: The OpenHAB Things list is displayed, showing the "Ember EM35x Coordinator" with its status as ONLINE.

The Zigbee Binding is now configured and ready for use.

Zigbee OpenHAB Binding Usage

With the Zigbee Binding successfully added and configured, you can now proceed to use it.

Add your devices to OpenHAB

Open the Inbox section and press the scan button.

Screenshot Description: The OpenHAB Inbox screen is shown, with the scan button highlighted.

You have a 60-second window to add a device after initiating a scan. It is advisable to monitor the process in the logs. During this time, follow the device's manual to place it in Association mode. In some cases, simply powering the device on is sufficient.

If the device is detected, it will appear in the logs and the Web UI.

Remove your device from OpenHAB

Navigate to the Configuration > Things menu and click the Delete button next to the device you wish to remove.

Example: Ikea White E26 Lamp

This example demonstrates the process using an Ikea White E26 lamp, but the steps are generally applicable to other compatible devices.

Image Description: A depiction of an Ikea White E26 Lamp.

To control the Ikea E26 bulb with OpenHAB, it must first be reset. After resetting, follow the standard procedure to add it to OpenHAB:

• Initiate the scan procedure using the Zigbee Binding.
• Power ON the lightbulb.
• Confirm that it has been added to OpenHAB.

You can now control the device directly or incorporate it into automation scenarios.

Screenshot Description: The OpenHAB Things list displays the "IKEA of Sweden TRADFRI bulb E27 WS opal 980lm" with its status as ONLINE.

Once a device is added, you can configure it further and create new control elements for it.

Screenshot Description: The configuration details for the IKEA TRADFRI bulb are shown, listing its available channels such as "Color Temperature" and "Dimmer".

The device is now available for control.

Screenshot Description: The OpenHAB Control section shows the "IKEA of Sweden TRADFRI bulb E27 WS opal 980lm" with a dimmer control set to 0%.

Troubleshooting

If your issue is not covered here or you require further assistance, please contact support at info@popp.eu.

OpenHAB Zigbee Binding is OFFLINE

If the ZigBee Binding is configured correctly but its status does not change to ONLINE within 10 seconds, examine the logs. If there is minimal log activity, or only a few packets are observed from OpenHAB to /dev/ttyUSB0, the Serial Interface configuration may be incorrect.

Zigbee Binding is ONLINE, but no device added during Scan period

Begin by investigating the logs to confirm the start of communication between OpenHAB and the POPP ZB-Stick. If any errors are detected, please contact us at info@popp.eu.

There are no packets from the device at all

This situation most likely means that your device is already connected to a different network and cannot join your new network. Attempt to reset the device using its manufacturer-specific reset procedure.