| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
This application note provides a step-by-step guide on how to set up Zigbee2MQTT on the NAVQ Plus and establish connections with Zigbee devices.
1. Zigbee
Zigbee is a wireless communication protocol that is designed for low-power, low-data-rate applications. It operates on the IEEE 802.15.4 standard and is commonly used for home automation, industrial automation, and other Internet of Things (IoT) applications. Zigbee enables devices to communicate with each other in a mesh network, allowing for reliable and scalable wireless communication. It offers features such as low power consumption, low latency, and support for large networks with thousands of devices. Zigbee is widely used for applications such as smart lighting, smart thermostats, home security systems, and industrial monitoring and control systems.
2. Zigbee Adapter
A Zigbee Adapter is the interface between the NAVQ Plus, where Zigbee2MQTT runs under Linux, and the Zigbee radio communication. Zigbee2MQTT supports a variety of adapters. This application note describes using the SONOFF Zigbee 3.0 USB Dongle Plus-P, commonly referred to as the ZBDongle-P (available for purchasing on Amazon).
Please refer to the Supported adapters section on the Zigbee2MQTT site for more information.
2.1. Zigbee Sensor
This example below describes the use of the Aqara Temperature and Humidity Sensor as an example Zigbee sensor (available for purchasing on Amazon).
3. Hardware Setup
Connect the ZBDongle-P to the NAVQ Plus using an USB hub that is plugged into the USB1 port of the NAVQ Plus. Run the below command to verify it is properly connected:
| Code Block |
|---|
user@imx8mpnavq:~$ ls -la /dev/ttyUSB0 crw-rw-rw- 1 root dialout 188, 0 Oct 24 11:56 /dev/ttyUSB0 |
Depending on the dongle type and its firmware, the path to serial device could also be /dev/ttyACM0:
| Code Block |
|---|
user@imx8mpnavq:~$ ls -la /dev/ttyACM0 crw-rw---- 1 root dialout 166, 0 Oct 26 18:53 /dev/ttyACM0 |
4. Software Setup
To ensure the proper operation of the Zigbee network with the NAVQ Plus, use the NAVQ+ BSP Release 1.1.8 or higher.
Additionally, Zigbee2MQTT requires installation of an MQTT broker. This application note specifically covers the usage of the Mosquitto MQTT broker.
Mosquitto is an open-source MQTT (Message Queuing Telemetry Transport) broker that provides a lightweight and scalable messaging protocol for IoT (Internet of Things) applications. It acts as a central hub or an intermediary between MQTT clients, allowing them to publish and subscribe to messages.
4.1. Installing the Mosquitto MQTT Broker
Install the Mosquitto package by running the below commands:
| Code Block |
|---|
user@imx8mpnavq:~$ sudo apt update user@imx8mpnavq:~$ sudo apt install -y mosquitto mosquitto-clients |
Enable the Mosquitto service to start automatically when the system boots up:
| Code Block |
|---|
user@imx8mpnavq:~$ sudo systemctl enable mosquitto.service |
Start the Mosquitto service:
| Code Block |
|---|
user@imx8mpnavq:/opt/zigbee2mqtt$ sudo systemctl restart mosquitto.service |
4.2. Installing Node.js
Node.js is an open-source JavaScript runtime environment that allows developers to run JavaScript code outside of a web browser. It uses the V8 JavaScript engine from Google Chrome to execute code on the server-side, enabling the development of scalable and high-performance web applications.
Set up the Node.js 16.x repository:
| Code Block |
|---|
user@imx8mpnavq:~$ sudo curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - |
This command downloads and runs a script that adds the Node.js 16.x repository to your system.
Install the Node.js package. This command installs Node.js on your system using the package manager:
| Code Block |
|---|
user@imx8mpnavq:~$ sudo apt-get install -y nodejs |
To verify the proper installation of Node.js and npm (Node Package Manager) versions, use the following commands:
| Code Block |
|---|
user@imx8mpnavq:~$ node --version v16.20.2 user@imx8mpnavq:~$ npm --version 8.19.4 |
5. Installing Zigbee2MQTT
Zigbee2MQTT is an open-source project that allows you to control Zigbee devices from different manufacturers using a single Zigbee coordinator and a MQTT-based communication protocol. It provides a bridge between Zigbee devices and MQTT, enabling you to integrate Zigbee devices into your smart home or an IoT system.
Create a directory for Zigbee2MQTT:
| Code Block |
|---|
user@imx8mpnavq:~$ sudo mkdir /opt/zigbee2mqtt user@imx8mpnavq:~$ sudo chown -R user: /opt/zigbee2mqtt |
Clone the Zigbee2MQTT repository:
| Code Block | ||
|---|---|---|
| ||
user@imx8mpnavq:~$ git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt |
Install the required dependencies using npm:
| Code Block |
|---|
user@imx8mpnavq:~$ cd /opt/zigbee2mqtt user@imx8mpnavq:/opt/zigbee2mqtt$ npm ci |
Build Zigbee2MQTT:
| Code Block |
|---|
user@imx8mpnavq:/opt/zigbee2mqtt$ npm run build |
6. Configuring Zigbee2MQTT
Copy the default configuration file and edit it:
| Code Block |
|---|
user@imx8mpnavq:~$ cp /opt/zigbee2mqtt/data/configuration.example.yaml /opt/zigbee2mqtt/data/configuration.yaml user@imx8mpnavq:~$ vim /opt/zigbee2mqtt/data/configuration.yaml |
Change the file contents to:
| Code Block |
|---|
homeassistant: false permit_join: true mqtt: base_topic: zigbee2mqtt server: mqtt://localhost keepalive: 60 version: 4 serial: port: /dev/ttyUSB0 adapter: auto frontend: port: 8080 host: 0.0.0.0 |
7. Starting Zigbee2MQTT
Start Zigbee2MQTT using the commands below:
| Code Block |
|---|
user@imx8mpnavq:~$ cd /opt/zigbee2mqtt user@imx8mpnavq:/opt/zigbee2mqtt$ npm start |
8. Connecting Temperature Sensor
Open your browser and enter the IP address of the NAVQ Plus followed by port 8080. This will open the Zigbee2MQTT interface in your browser:
Move the dongle antenna away from any large metal objects, such as a PC case.
By default, Zigbee2MQTT usually starts with the permit_join option set to true, allowing new devices to join the network. When all your devices are connected, you can change the permit_join option to false in the Zigbee2MQTT configuration.
Press and hold the reset button on the sensor until the LED on the sensor starts blinking. This usually takes approximately 5 seconds.
The Zigbee2MQTT console log will display the following information:
| Code Block |
|---|
Zigbee2MQTT:info 2023-10-24 16:58:14: Successfully interviewed '0x00158d0007014bca', device has successfully been paired
Zigbee2MQTT:info 2023-10-24 16:58:14: Device '0x00158d0007014bca' is supported, identified as: Xiaomi Aqara temperature, humidity and pressure sensor (WSDCGQ11LM)
Zigbee2MQTT:info 2023-10-24 16:58:14: MQTT publish: topic 'zigbee2mqtt/bridge/event', payload '{"data":{"definition":{"description":"Aqara temperature, humidity and pressure sensor","exposes":[{"access":1,"description":"Remaining battery in %, can take up to 24 hours before reported.","label":"Battery","name":"battery","property":"battery","type":"numeric","unit":"%","value_max":100,"value_min":0},{"access":1,"description":"Measured temperature value","label":"Temperature","name":"temperature","property":"temperature","type":"numeric","unit":"°C"},{"access":1,"description":"Measured relative humidity","label":"Humidity","name":"humidity","property":"humidity","type":"numeric","unit":"%"},{"access":1,"description":"The measured atmospheric pressure","label":"Pressure","name":"pressure","property":"pressure","type":"numeric","unit":"hPa"},{"access":1,"description":"Voltage of the battery in millivolts","label":"Voltage","name":"voltage","property":"voltage","type":"numeric","unit":"mV"},{"access":1,"description":"Link quality (signal strength)","label":"Linkquality","name":"linkquality","property":"linkquality","type":"numeric","unit":"lqi","value_max":255,"value_min":0}],"model":"WSDCGQ11LM","options":[{"access":2,"description":"Calibrates the temperature value (absolute offset), takes into effect on next report of device.","label":"Temperature calibration","name":"temperature_calibration","property":"temperature_calibration","type":"numeric"},{"access":2,"description":"Number of digits after decimal point for temperature, takes into effect on next report of device.","label":"Temperature precision","name":"temperature_precision","property":"temperature_precision","type":"numeric","value_max":3,"value_min":0},{"access":2,"description":"Calibrates the pressure value (absolute offset), takes into effect on next report of device.","label":"Pressure calibration","name":"pressure_calibration","property":"pressure_calibration","type":"numeric"},{"access":2,"description":"Number of digits after decimal point for pressure, takes into effect on next report of device.","label":"Pressure precision","name":"pressure_precision","property":"pressure_precision","type":"numeric","value_max":3,"value_min":0},{"access":2,"description":"Number of digits after decimal point for humidity, takes into effect on next report of device.","label":"Humidity precision","name":"humidity_precision","property":"humidity_precision","type":"numeric","value_max":3,"value_min":0},{"access":2,"description":"Calibrates the humidity value (absolute offset), takes into effect on next report of device.","label":"Humidity calibration","name":"humidity_calibration","property":"humidity_calibration","type":"numeric"}],"supports_ota":false,"vendor":"Xiaomi"},"friendly_name":"0x00158d0007014bca","ieee_address":"0x00158d0007014bca","status":"successful","supported":true},"type":"device_interview"}'
Zigbee2MQTT:info 2023-10-24 16:58:14: Configuring '0x00158d0007014bca'
Zigbee2MQTT:info 2023-10-24 16:58:14: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"message":"interview_successful","meta":{"description":"Aqara temperature, humidity and pressure sensor","friendly_name":"0x00158d0007014bca","model":"WSDCGQ11LM","supported":true,"vendor":"Xiaomi"},"type":"pairing"}'
Zigbee2MQTT:info 2023-10-24 16:58:14: Successfully configured '0x00158d0007014bca' |
The Aqara Temperature and Humidity Sensor will appear in the Devices list:
To read the temperature and humidity, click on the device name and navigate to the state section.
9. Running Zigbee2MQTT as a Service
Create a systemctl service file:
| Code Block |
|---|
user@imx8mpnavq:~$ sudo vim /etc/systemd/system/zigbee2mqtt.service |
Insert the following content into the file:
| Code Block |
|---|
[Unit] Description=zigbee2mqtt After=network.target [Service] Environment=NODE_ENV=production ExecStart=/usr/bin/npm start WorkingDirectory=/opt/zigbee2mqtt StandardOutput=inherit StandardError=inherit Restart=always RestartSec=10s User=user [Install] WantedBy=multi-user.target |
Save the changes and exit the text editor.
Start the Zigbee2MQTT service by running:
| Code Block |
|---|
user@imx8mpnavq:~$ sudo systemctl start zigbee2mqtt |
Enable the service to start on boot-up:
| Code Block |
|---|
user@imx8mpnavq:~$ sudo systemctl enable zigbee2mqtt.service |