Integration with a ZigBee protocol

  • Document number: PO-197-EN
  • Version: 2.1
  • Date of publication: June 17, 2024


Introduction

Integration of devices that support the ZigBee protocol with the Ampio system is possible, for example, by connecting a gateway to the M-SERV-s module. Using Node-RED is a prerequisite to establishing a connection. This guide presents the example of ZBDongle-E from Sonoff with a dedicated antena as a gateway.

Gateway connection

In order to connect the gateway, disconnect M-SERV-s from its power supply, connect the gateway device and power up the server again. After a couple of minutes, activate an SSH connection via a www interface (more guidelines available in M-SERV server configuration). Log in onto the root account on the server with the password you have created e.g. through the putty application.

Click to enlarge and open in a new tab.

Searching for the gateway port

After entering the password, search for devices with the following command:

dmesg | grep tty

The gateway will most probably be added as ttyACM0.

Configuration for server images from version number 400 onwards

Installation

Navigate to the folder where you can make changes:

cd /root

Clone the zigbee2mqtt repository:

wget https://github.com/Koenkk/zigbee2mqtt/archive/refs/heads/master.zip 

Unpack zigbee2mqtt:

unzip master.zip

Rename the folder:

mv /root/zigbee2mqtt-master/ /root/zigbee2mqtt/

Change current folder

cd /root/zigbee2mqtt

Install content:

npm ci

Modifying the configuration file

Open the file for editing

nano /root/zigbee2mqtt/data/configuration.yaml

Set the server field to mqtt://localhost.

The port field according to what was retrieved above e.g. /dev/ttyACM0.

MQTT connection fields according to your server settings, user is usually admin and the relevant password (login details as for the mqtt blocks in Node-RED). Remember to remove the # character indicating a line comment.

Click to enlarge and open in a new tab.

After the change, save and close the configuration file. In putty this is done via Ctrl+x, then y and Enter.

First run

Type the command

npm start

Configuration for older images

Creating and configuring a folder

Create a folder:

sudo mkdir /ampio/rw/zigbee2mqtt

Grant permissions:

sudo chown -R ${USER}: /ampio/rw/zigbee2mqtt

Cloning of the zigbee2mqtt repository

git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /ampio/rw/zigbee2mqtt

Installing content

Change the current folder:

cd /ampio/rw/zigbee2mqtt

and install:

npm ci

Modification of the configuration file

Open the file to be edited

nano /ampio/rw/zigbee2mqtt/data/configuration.yaml

Set the server field to mqtt://localhost.

The port field should be completed with information obtained in the previous step e.g., /dev/ttyACM0.

MQTT connection field should be filled with your server settings, user set to admin and the correct password should be provided (login details are the same as for the mqtt blocks in Node-RED).

Click to enlarge and open in a new tab.

Once the changes are introduced, close the configuration file. You can do that in putty by clicking Ctrl+x, then y and Enter at the end.

First launch

Enter the following command:

npm start

Adding a secondary device

A device added as an example in this guide is a temperature and humidity sensor SNZB-02 from Sonoff. Manuals for specific devices are available on websites of particular manufacturers. In the case of the sensor described here, in order to have it added, you need to press and hold in the button on the casing for 5 seconds. After a successful addition of the device, you should see a couple of messages on the terminal, including for example:

Click to enlarge and open in a new tab.

After adding the sensor, it is possible to respond to data or send information to the CAN bus using certain nodes in Node-RED (e.g. mqtt out).

WARNING! For the purpose of upholding security, after adding all required devices, the process must be stopped. One way to do it is by clicking Ctrl+c, opening the configuration.yaml file and setting permit_join:false. Once that is done, the process can be started again.

Configuration in Node-RED

A guide that describes the basics of Node-RED use in the Ampio system is available here: Integration of the Ampio system with Node-RED. After adding secondary devices, data from the MQTT Ampio can be received. Topic on which the device is broadcasting can be viewed in a terminal via an SSH connection. In this case, it is the main topic and ID of the added device: zigbee2mqtt/0x00124b00250e039e.

Click to enlarge and open in a new tab.

Data can be viewed after adding a debug node.

Click to enlarge and open in a new tab.

If you want to for example, read the value of humidity from a sensor, you will need to send the following information through the node function:

Click to enlarge and open in a new tab.

Different end devices can broadcast information in different ways, which is why it is worthwhile to view the data first in the debug window, before creating a function to send the information.

Automatic launching

for server images from version number 400 onwards

Log in again via SSH, being in the root folder download and run the script with the command:

curl https://dist.ampio.pl/scripts/zigbee2mqtt400.sh | bash -s

for older images

For the application to launch automatically after a power supply reboot, a suitable script must be written. Open the SYSTEM tab in the www interface of M-SERV and go to SCRIPTS. Download the attached file zigbee2mqtt.sh. Upload it by clicking on SELECT FILE, and then UPLOAD THE FILE. Then, tick the 5 min box next to the correct script and click SAVE.

Click to enlarge and open in a new tab.

Performance test

In order to confirm the correctness of configuration, reboot the server’s power supply and, after a couple of minutes, check whether everything is working as intended in Node-RED, in the debug window, for instance.

Download files: