Zigbee2MQTT

A Zigbee2MQTT egy szabad szoftver, amely a Zigbee-eszközeink önálló kezelését teszi lehetővé, híd a Zigbee és az MQTT protokollok között, és beköthető a Home Assistant-ba is az MQTT integráció által. Bár a HA Zigbee2MQTT nélkül is képes kezelni Zigbee-eszközöket (ZHA integráció), de ez jobb módszernek tűnik,¹ mert

• akár a HA-tól függetlenül is használható;
• szélesebb körű eszköztámogatást nyújt;
• valamivel többet tud a kezelőfelülete;
• jobb útválasztó stratégiát alkalmaz.

Viszont szüksége van egy külön MQTT üzenetközvetítőre (message broker). A Mosquitto egy ilyen, pub/sub mintát követő szabad szoftver, amely összeköti a kommunikáló klienseket. (Említsük meg az érdekesség kedvéért, hogy léteznek IoT szolgáltatók is, nyilván elsősorban ipari igényekre: pl. a HiveMQ egy MQTT üzenetközvetítésen alapuló, de annál komplexebb szolgáltatást nyújtó német cég.²)

A Zigbee-hálózat

A szoftverkomponensek összefüggéseit szemlélteti e diagram. A hardver tekintetében az alábbi komponensekről beszélhetünk:

• Zigbee coordinator (ZC):
  • A Zigbee-hálózat kapuja (gateway).
  • Csak egy darab kell belőle hálózatonként.
  • A gyártói megoldásoknál ez egy többfunkciós HUB eszközként jelenik meg, amely az internetre, a gyártói felhőszolgáltatáshoz köti a Zigbee-hálózatot (pl. LEGRAND átjárók).
  • Saját megoldásoknál ez általában egy USB-eszköz, használatához számítógép és szoftverek szükségeltetnek (pl. SONOFF ZBDongle-E).
• Zigbee router/repeater (ZR):
  • Jellemzően az elektromos hálózatba kötött.
  • Kiterjeszti a Zigbee-hálózatot, más eszközök kapcsolódhatnak hozzá.
  • Általában nem önállóan, hanem egy relével párosítva jelenik meg, amely Zigbee által vezérelhető, de a Zigbee-hálózat nélkül is működik szokványos kapcsolóként vagy dugaljként (pl. SONOFF ZBminiR2 vagy LEGRAND végrehajtó okos kapcsolók és dugaljak).
• Zigbee end device (ZED):
  • Jellemzően elemes, vezetéknélküli.
  • Más eszközök nem kapcsolódhatnak hozzá.
  • Lehet szenzor: hőmérséklet, mozgás, jelenlét, fényerősség stb. mérésére, érzékelésére szolgál (pl. SONOFF SNZB-02P hőmérséklet- és páratartalommérő).
  • Lehet távvezérlő: vezetéknélküli kapcsolóként szolgál, működhet elemmel vagy kinetikus energiával (pl. LEGRAND távvezérlő okos kapcsolók). Szcenáriókapcsoló néven is találkozhatunk vele. Szoftveresen kell konfigurálni, mi történjen a megnyomásakor.

ZBDongle-E

Mint kiderült, frissítenünk kell a ZBDongle-E kódnevű ZC firmware-ét ahhoz, hogy a Zigbee2MQTT tudja használni, de ehhez rendelkezésre állnak szoftverek, könnyen elvégezhető a művelet, és előnyösnek is tűnik az újabb firmware. Először telepítsük a NabuCasa/universal-silabs-flasher progit:

# pipx install universal-silabs-flasher

Letöltjük a ZBDongle-E-hez való, legutóbbi verziójú firmware-t a darkxst/silabs-firmware-builder repóból, ahol ilyen fájlnevet keressünk: ncp-uart-hw-v#.#.#.#-zbdonglee-115200.gbl, amelyben v#.#.#.# a verzió.

$ wget https://github.com/darkxst/silabs-firmware-builder/raw/refs/heads/main/firmware_builds/zbdonglee/ncp-uart-hw-v7.4.5.0-zbdonglee-115200.gbl

Keressük meg a ZBDongle-E fájlnevét, esetünkben ez az egyetlen csatlakoztatott USB-eszköz, így nem kell válogatnunk:

$ find /dev/serial/by-id/* | xargs realpath
/dev/ttyACM0

Végül frissítsük a firmware-t az eszközünkön:

# /root/.local/bin/universal-silabs-flasher --device /dev/ttyACM0 flash --firmware ncp-uart-hw-v7.4.5.0-zbdonglee-115200.gbl

Docker compose szolgáltatások

Picit küzdeni kellett a helyes beállítások megtalálásával; a doksiban, illetve máshol³ talált konfigok nem működtek elsőre. A dokumentáció további olvasgatása persze segített.

compose.yaml:

services:

  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    user: 1000:1000
    volumes:
      - ./mosquitto:/mosquitto
    ports:
      - "1883:1883"
      - "9001:9001"
    command: "mosquitto -c /mosquitto-no-auth.conf"

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt:2
    container_name: zigbee2mqtt
    restart: unless-stopped
    user: 1000:1000
    group_add:
      - dialout
    environment:
      - TZ=Europe/Copenhagen
      - Z2M_WATCHDOG=default
    volumes:
      - ./zigbee2mqtt:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8282:8282"
    devices:
      - /dev/ttyACM0:/dev/ttyACM0
    depends_on:
      - mosquitto

A Zigbee2MQTT beállításai a webes frontenden is szerkeszthetők lesznek, sőt konfigfájl hiányában van egy onboarding felület is, de jobb, ha előre összeállítjuk a nekünk megfelelő konfigot. A Mosquitto nem igényel külön beállításokat, viszont így nem is ír semmit a volume-ra. Ezen elég akkor változtatni, ha az igény felmerül.

zigbee2mqtt/configuration.yaml:

version: 4
permit_join: true
mqtt:
  server: mqtt://mosquitto:1883
#  client_id: MY_CLIENT_ID
#  user: my_user
#  password: my_password
  base_topic: zigbee2mqtt
device_options:
  retain: true
serial:
  adapter: ember
  port: /dev/ttyACM0
frontend:
  enabled: true
  port: 8282
  auth_token: ezittkamujelszo
homeassistant:
  enabled: false
advanced:
  network_key: GENERATE

Elindíthatjuk a szolgáltatásokat, mindenképp nézzük át a logokat:

$ docker compose up -d
$ docker compose logs -f

A http://homeserver:8282 URL-en érjük el a Zigbee2MQTT webes frontendjét. Itt rá kell nyomnunk a menüsorban található Permit join (All) gombra ahhoz, hogy párosítani tudjuk a ZR és ZED eszközeinket.

A listában megjelenő eszközöket tetszés szerint el tudjuk nevezni (friendly_name), láthatjuk a jelerősségüket (LQI, [0,255]) és az akkumulátoruk töltöttségi szintjét (power, [0,100]). Az LQI (Link Quality Indicator) általános minőségi és megbízhatósági mutató figyelembe veszi a zajosságot és a hibarátát is.

Node.js MQTT-kliens

Írjunk egy egyszerű Node.js MQTT-klienst, amely lekérdezi az SNZB-02P hőmérséklet-szenzorunk által publikált értéket! Ehhez feliratkozunk a megfelelő topic-ra, amely a Zigbee2MQTT mqtt.base_topic beállításában szereplő értékből és az eszközünk friendly_name tulajdonságából áll.

Inicializáljuk egy Node.js projektet, és telepítsük az mqtt.js csomagot.

$ node --version
v22.15.0
$ npm init --yes
$ npm install mqtt --save

subscribe.js:

#!/usr/bin/env node

const mqtt = require('mqtt');

const topic = 'zigbee2mqtt/temp_hum_01';
const serverUrl = 'mqtt://localhost:1883';
const client = mqtt.connect(serverUrl);

console.log('client id:', client.options.clientId);

client.on('connect', () => {
    console.log('connected to broker:', serverUrl);
    client.subscribe(topic, (err) => {
        if (!err) {
            console.log('subscribed to topic:', topic);
        } else {
            console.error('FAILED to subscribe to topic:', topic, err);
        }
    });
});

client.on('message', (t, buf) => {
    console.log('message from topic:', t);
    if (t === topic) {
        try {
            const payload = JSON.parse(buf.toString());
            console.log('payload:', payload);
        } catch (err) {
            console.error('FAILED to parse message:', err.message);
        }
    }
});

Ha lefuttatjuk e szkriptet, rögtön látni fogunk egy választ. Ezt a Zigbee2MQTT device_options.retain=true beállítása okozza, amely miatt a bróker elteszi az eszközök utolsó publikált üzenetét új kliensek számára, nem kell várni a következő publikálásra. A kliensünk aztán megszakításig figyel tovább, és rendszeres időközönként kiírja az újonnan publikált értéket.

$ chmod u+x subscribe.js
$ ./subscribe.js
client id: mqttjs_ae7b820b
connected to broker: mqtt://localhost:1883
subscribed to topic: zigbee2mqtt/temp_hum_01
message from topic: zigbee2mqtt/temp_hum_01
payload: { battery: 100, humidity: 53.2, linkquality: 79, temperature: 22.4 }
^C
$ docker compose logs mosquitto
...
New connection from 172.23.0.1:34868 on port 1883.
New client connected from 172.23.0.1:34868 as mqttjs_ae7b820b (p2, c1, k60).
Client mqttjs_ae7b820b closed its connection.

Home Assistant MQTT-integráció

Kövessük itt is a Zigbee2MQTT doksi tanácsait.

• Távolítsuk el a HA-ból a ZHA integrációt.
• Távolítsuk el a HA compose.yaml konfigból a USB device-ot.
• Adjuk hozzá a Z2M configuration.yaml konfighoz a homeassistant.enabled=true beállítást.
• Adjuk hozzá a HA-ban az MQTT-integrációt. Ez azonnal felveszi a Z2M Bridge-et és az általa kezelt eszközöket.