POPP ZB-Stick with OpenHAB

Introduction

This document describes how to use the POPP ZB-Stick with the existing Home Automation platform called OpenHAB (https://www.openhab.org/). The POPP ZB-Stick firmware version referenced in this guide is 6.0.3, and the OpenHAB2 software version referenced is 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.
• An example of using a Zigbee device.

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 Requirements and Setup Options

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

Diagram Description: The document illustrates two primary setup scenarios. The first shows a laptop with OpenHAB installed and running, connected to a POPP ZB-Stick, which in turn interfaces with various Zigbee devices such as light bulbs, a sensor, and a switch. The second scenario depicts a Raspberry Pi with OpenHABian installed and running, similarly connected to a POPP ZB-Stick and interacting with the same types of Zigbee devices.

Initial Setup and Connection

This section assumes that OpenHAB (or openHABian) is already installed and accessible via its web interface. The first step is to physically insert the POPP ZB-Stick into your host machine.

Diagram Description: A screenshot of the OpenHAB web interface (Paper UI) is shown, displaying the 'Inbox' section. The interface indicates that the inbox is empty and provides options to search for things. A textual instruction prompts the user to insert the POPP ZB-Stick into the host machine.

OpenHAB Zigbee Configuration

To enable functionality with the POPP ZB-Stick, the Zigbee Home Automation Binding must be installed within OpenHAB. This binding is not installed by default.

Setup Logging (Optional)

Enabling logging is recommended for identifying and resolving potential issues during setup and operation. The process involves:

• Connecting to the OpenHAB SSH console (e.g., using ssh openhabian@129.168.0.103 with credentials openhabian:openhabian).
• Accessing the "Karaf Console" by running ssh -p 8101 openhab@localhost.
• Executing the following commands to set logging levels:
  • log:set debug org.openhab.binding.zigbee
  • log:set debug com.zsmartsystems.zigbee
  • log:set info com.zsmartsystems.zigbee.dongle.ember.internal.ash
• Exiting the Karaf Console using the Ctrl+D keyboard combination.

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

Configuring the Zigbee Binding

After installing the Zigbee Binding (version 2.5.10 or later is required for Software Flow Control), navigate to the 'Configuration' > 'Things' section in the Paper UI to add a new thing. Select 'Zigbee Binding' > 'Ember EM35x Coordinator' and configure the following properties:

• Serial Port: Select /dev/ttyUSB0. If it's not listed, consult the Troubleshooting section.
• Flow Control: Select 'None'.
• Baud Rate: Select '115200'.

After configuring these settings, save the new thing.

Diagram Description: Screenshots show the OpenHAB Paper UI. One displays the 'Add-ons' section where the 'ZigBee Binding' is listed. Another shows the 'Configuration > Things > Edit > Ember EM35x Coordinator' screen with fields for 'Serial Port', 'Baud Rate', and 'Flow Control' being set.

Initialization and Status

Once the Ember EM35x Coordinator is added, it may take up to 10 seconds to initialize. A successful initialization will show the status as 'ONLINE'. If the status does not change to 'ONLINE', refer to the Troubleshooting section.

Diagram Description: A screenshot of the OpenHAB Paper UI's 'Configuration > Things' page displays the 'Ember EM35x Coordinator' with its status clearly marked as 'ONLINE'.

With the Zigbee Binding successfully configured, you can now begin using it.

Zigbee OpenHAB Binding Usage

Adding Devices to OpenHAB

To add Zigbee devices, open the 'Inbox' section in OpenHAB and press the scan button. You will have approximately 60 seconds to initiate the device's association mode, often by powering it on or following its specific manual instructions. The process can be tracked in the logs.

If a device is found, its status will be visible in both the logs and the Web UI.

Removing Devices from OpenHAB

To remove a device, navigate to the 'Configuration' > 'Things' menu, locate the device, and click the 'Delete' button next to it.

Diagram Description: A screenshot of the OpenHAB Paper UI 'Inbox' section is shown, highlighting the scan button. Instructions are provided for adding and removing devices.

Example: Ikea White E26 Lamp

This section provides an example using an Ikea White E26 lamp, which is applicable to other Zigbee products as well. 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.

Once added, the bulb can be controlled directly or integrated into scenarios.

Diagram Description: An image of an Ikea White E26 lamp is displayed. Screenshots show the OpenHAB Paper UI's 'Configuration > Things' page listing the added 'IKEA of Sweden TRADFRI bulb E27 WS opal 980lm' as ONLINE, identified as a 'ZigBee Device'.

Device Configuration and Control

After a device is added, it can be configured, and new control elements can be created for it. For the Ikea E26 bulb example, configuration options include channels for 'Color Temperature' and 'Dimmer'.

Diagram Description: Screenshots illustrate the configuration details of the added IKEA bulb in OpenHAB, showing available channels. Another screenshot demonstrates the 'Control' view, where the 'Dimmer' for the bulb can be adjusted, showing its current level (e.g., 0%).

Troubleshooting

This section addresses common issues encountered when using the POPP ZB-Stick with OpenHAB.

OpenHAB Zigbee Binding is OFFLINE

If the Zigbee Binding status remains 'OFFLINE' for more than 10 seconds after configuration, examine the logs. If minimal log activity is observed, particularly only a few packets from OpenHAB to /dev/ttyUSB0, the Serial Interface configuration might be incorrect.

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

Investigate the logs to confirm if communication between OpenHAB and the POPP ZB-Stick is initiating. If not, further troubleshooting is required.

There are no packets from the device at all

This symptom typically indicates that the device is already part of a different network and cannot join the new one. Attempt to reset the device using its manufacturer-specific reset procedure.

For issues not covered in this guide or if further assistance is needed, please contact support at info@popp.eu.