APEX #3 — Zigbee2MQTT : faire parler des modules à 15 balles avec une GTB pro

Série ECLYPSE APEX — épisode 3/6 · Précédent : #2 Les fondations

Il y a des mélanges qui ne devraient pas marcher. Ananas et pizza. Chaussettes et sandales. Et un module domotique SONOFF piloté par un automate de GTB tertiaire. Pourtant, je vous assure, ce dernier marche très bien, et c’est le programme du jour.

On installe Zigbee2MQTT dans un conteneur sur l’ECLYPSE APEX, on le branche sur un coordinateur Zigbee Ethernet, et on appaire un premier module. Toutes les données arriveront dans le Mosquitto de l’épisode 2.

Le matos

• Un ECLYPSE APEX avec Facilities (menu Conteneurisation) et le conteneur mosquitto qui tourne sur le port 50083.
• Un coordinateur SMLIGHT SLZB-06MG24, en Ethernet.
• Un module Zigbee pour tester. Chez moi, un SONOFF ZBMINIR2.

Pourquoi un coordinateur Ethernet et pas une bonne vieille clé USB ? Tout simplement parce que l’APEX ne fait pas de passthrough USB vers les conteneurs. Le SLZB expose le Zigbee sur un port TCP, Zigbee2MQTT s’y connecte, et c’est réglé. Bonus : on peut placer le coordinateur là où la radio passe bien, et pas forcément dans l’armoire métallique.

L’architecture

SLZB-06MG24 (Ethernet, coordinateur)
     ▲ TCP 6638
┌────┴────────────────┐      ┌──────────────────────┐
│  zigbee2mqtt        │─────▶│  mosquitto  :50083   │ ◀── Node-RED / Telegraf / Niagara
│  web :50084         │ MQTT └──────────────────────┘
│  volume z2m-data    │
└─────────────────────┘
        ECLYPSE APEX

Bonne nouvelle : pas besoin d’image custom. L’image officielle koenkk/zigbee2mqtt est basée sur Alpine et elle est multi-arch ARM64. Elle a donc un shell, et on va s’en servir.

Étape 1 — Préparer le SLZB-06MG24

Premier petit piège : le SLZB a une adresse MAC administrée localement, donc les scanners réseau l’affichent en « Unknown ». Le plus simple pour le retrouver, c’est de chercher le port socket Zigbee :

nmap -p 6638 --open 192.168.X.0/24

Ensuite, dans son interface web :

• mode Ethernet ;
• firmware Zigbee coordinator (ni routeur, ni Thread) ;
• port socket 6638 ;
• IP fixe, par réservation DHCP ou en statique. Si l’IP change, Zigbee2MQTT perd son coordinateur.

Étape 2 — Récupérer l’image

Facilities → Images → Ajouter : koenkk/zigbee2mqtt:2.14.1.

Oui, un tag fixe. On en a parlé : latest, c’est pour les gens qui aiment les surprises.

Étape 3 — Créer le conteneur

Nom : zigbee2mqtt. Remplacez IP_APEX et IP_SLZB par vos adresses :

{
  "Image": "koenkk/zigbee2mqtt:2.14.1",
  "ExposedPorts": { "8080/tcp": {} },
  "Entrypoint": ["sh", "-c"],
  "Cmd": [
    "if [ ! -f /app/data/configuration.yaml ]; then printf '%s\\n' 'mqtt:' '  base_topic: zigbee2mqtt' '  server: mqtt://IP_APEX:50083' 'serial:' '  port: tcp://IP_SLZB:6638' '  adapter: ember' 'frontend:' '  enabled: true' '  port: 8080' 'advanced:' '  network_key: GENERATE' '  pan_id: GENERATE' '  ext_pan_id: GENERATE' > /app/data/configuration.yaml; fi && cd /app && exec node index.js > /app/data/z2m-console.log 2>&1"
  ],
  "HostConfig": {
    "CpusetCpus": "0",
    "RestartPolicy": { "Name": "unless-stopped", "MaximumRetryCount": 0 },
    "PortBindings": { "8080/tcp": [{ "HostPort": "50084" }] },
    "Mounts": [
      { "Target": "/app/data", "Source": "z2m-data", "Type": "volume", "ReadOnly": false, "Consistency": "default" }
    ]
  }
}

Pourquoi ce if un peu bizarre ?

Au premier démarrage, Zigbee2MQTT génère la clé réseau, le PAN ID et l’Extended PAN ID, et les écrit dans configuration.yaml. Il y enregistre ensuite les appareils appairés. Si on réécrivait la config à chaque démarrage, on recréerait un réseau Zigbee vierge à chaque redémarrage : tous les modules à réappairer, un par un, à chaque coupure de courant. Pas franchement l’idée.

Le if n’écrit donc la config que si elle n’existe pas encore. Et la sortie console part dans un fichier du volume, puisque l’APEX n’a pas de docker logs.

⚠️ Ne supprimez jamais le volume z2m-data. Il contient la clé réseau et la base des appareils. Le supprimer, c’est réappairer tout le parc. Le conteneur, lui, peut être supprimé et recréé sans risque.

Étape 4 — Démarrer et vérifier

1. Mosquitto doit déjà tourner. Démarrez zigbee2mqtt.
2. Patientez 20 à 30 secondes.
3. Ouvrez http://IP_APEX:50084 : l’interface Zigbee2MQTT apparaît.
4. Dans Paramètres → À propos, le coordinateur EmberZNet doit être reconnu.
5. Dans MQTT Explorer, zigbee2mqtt/bridge/state doit valoir {"state":"online"}.

Si l’onglet Journaux affiche « Rien à afficher », pas de panique : il ne montre que les logs émis depuis l’ouverture de la page.

Étape 5 — Le premier appairage

1. Cliquez sur Autoriser l’appairage (254 secondes par défaut).
2. Mettez le module en mode appairage. Pour le ZBMINIR2, c’est à la première mise sous tension, ou par un appui long d’environ 5 secondes.
3. Il apparaît dans Appareils. Renommez-le, il publiera alors sur zigbee2mqtt/<nom>.
4. Testez la commande dans l’onglet Exposes. Clac, le relais claque. Je vous avoue que la première fois, j’ai souri bêtement devant mon bureau.

Quelques remarques sur le ZBMINIR2 :

• il a besoin du neutre (L + N). C’est le ZBMINIL2 qui fonctionne sans ;
• les bornes S1/S2 sont un contact sec pour un interrupteur mural, pas de 230 V dessus ;
• alimenté sur secteur, il devient routeur et étend le maillage Zigbee ;
• deux messages « Device left » pendant l’appairage, c’est normal : il quitte son ancien réseau après le reset.

Dernier test, celui qui compte : arrêtez puis redémarrez le conteneur. Le module doit toujours être là, avec son nom, et répondre sans réappairage. Chez moi : validé.

Le kit de dépannage : FileBrowser

Pas de SSH, mais il faut bien lire les logs et retoucher la config de temps en temps. Solution : un FileBrowser monté sur le même volume.

{
  "Image": "filebrowser/filebrowser:latest",
  "ExposedPorts": { "80/tcp": {} },
  "Cmd": ["--noauth"],
  "HostConfig": {
    "CpusetCpus": "0",
    "RestartPolicy": { "Name": "unless-stopped", "MaximumRetryCount": 0 },
    "PortBindings": { "80/tcp": [{ "HostPort": "50092" }] },
    "Mounts": [
      { "Target": "/srv", "Source": "z2m-data", "Type": "volume", "ReadOnly": false, "Consistency": "default" }
    ]
  }
}

Sur http://IP_APEX:50092, vous trouvez z2m-console.log pour les erreurs de démarrage et le dossier log/ pour les logs Zigbee2MQTT.

⚠️ --noauth plus un configuration.yaml qui contient la clé réseau, c’est une porte grande ouverte. On arrête ce conteneur dès que le dépannage est fini.

Et oui, vous avez l’œil : filebrowser/filebrowser:latest, juste après vous avoir fait la morale sur les tags fixes. Ouais, je sais : faites ce que je dis, pas ce que je fais ! FileBrowser m’a surtout servi à débugger à l’arrache, on l’allume, on lit ses logs, on le coupe. C’est comme ça que j’ai pris mes notes, et je vous les livre telles quelles. Si vous comptez le garder plus de dix minutes, fixez-lui une version comme aux copains.

Symptôme	Cause probable	Action
Création refusée « administrative policy »	OPA : port ou format JSON	Vérifier ExposedPorts, Mounts, CpusetCpus, port hôte en 50xxx
Redémarrage en boucle	Broker absent ou SLZB injoignable	Lire z2m-console.log via FileBrowser
Coordinateur introuvable	IP du SLZB changée, mauvais mode ou firmware	IP fixe, mode Ethernet, firmware coordinator, port 6638
Zigbee2MQTT ne démarre pas	Mosquitto arrêté	Démarrer mosquitto avant zigbee2mqtt

Et la RAM, dans tout ça ?

Zigbee2MQTT consomme entre 150 et 250 Mo sur l’APEX. Ça passe très bien seul, mais gardez un œil dessus si vous faites aussi tourner InfluxDB, Grafana, Telegraf et Node-RED. Rappel de l’épisode 1 : on a environ 1,8 Go pour tout le monde.

La suite

Votre module Zigbee publie maintenant sur zigbee2mqtt/<nom>. Problème : l’ECLYPSE ne sait pas s’abonner à du MQTT, il ne sait qu’en publier. Les données sont donc là, dans le broker… mais l’automate ne les voit pas encore. Pas pour longtemps.

Au prochain épisode, c’est le grand festival : Node-RED et l’API REST transforment ce module en vrais points BACnet, tout seuls. Sortez les cotillons.

Liens

• Fiche produit ECLYPSE APEX — Distech Controls
• Zigbee2MQTT · SMLIGHT SLZB-06MG24