Zigbee2MQTT avec un broker cloud : pilotez vos appareils Zigbee de n'importe où via TLS

Utiliser Zigbee2MQTT avec un broker cloud vous permet de lire vos capteurs et de commander vos appareils Zigbee de n'importe où, sans redirection de ports ni VPN sur le réseau de votre maison connectée. Dans ce guide, vous allez faire pointer une installation Zigbee2MQTT existante vers un broker sécurisé par TLS sur le port 8883, la tester d'abord sur le serveur MQTT public gratuit, puis passer à des identifiants privés pour l'usage quotidien.

Pourquoi utiliser un broker cloud avec Zigbee2MQTT ?

La plupart des installations Zigbee2MQTT dialoguent avec un conteneur Mosquitto sur le même Raspberry Pi. Cela fonctionne bien jusqu'au jour où quelque chose hors de la maison doit voir les données : une application mobile en données cellulaires, un tableau de bord au bureau, un second site comme une résidence secondaire, ou un service backend qui enregistre la consommation d'énergie. Exposer un broker local sur Internet implique redirection de ports, DNS dynamique et certificats, et chacun de ces éléments est une nouvelle occasion de se tromper.

Un broker dans le cloud inverse le sens de la connexion. Zigbee2MQTT ouvre une connexion TLS sortante vers le broker, exactement comme un navigateur qui ouvre un site web ; rien n'a donc besoin de changer sur votre box. N'importe quel client autorisé, où qu'il soit, peut ensuite s'abonner aux mêmes topics. Si vous découvrez le rôle du broker dans ce schéma, la courte explication de ce que fait un broker MQTT constitue une bonne introduction.

Le compromis est réel : l'état de vos appareils transite désormais par un service sur Internet, le chiffrement et les identifiants privés ne sont donc pas optionnels. La suite de ce guide les considère comme la norme.

Ce dont vous avez besoin

• Une installation Zigbee2MQTT fonctionnelle (1.x ou 2.x) avec un coordinateur appairé. Si vous partez de zéro, suivez d'abord le guide d'installation de Zigbee2MQTT, puis revenez ici.
• Un accès au fichier configuration.yaml de Zigbee2MQTT (dans le dossier data, ou la page de configuration de l'add-on dans Home Assistant).
• Pour les tests : rien d'autre, car le serveur MQTT public gratuit accepte les connexions anonymes.
• Pour la production : un broker avec son propre nom d'utilisateur, mot de passe et client ID, par exemple un broker ConnectMQ créé depuis le portail.

Étape 1 : tester sur le serveur MQTT public gratuit

Avant de toucher aux identifiants, vérifiez que Zigbee2MQTT peut joindre Internet et publier en TLS. Le serveur MQTT public gratuit sur broker.connectmq.com, réservé aux tests et aux prototypes, accepte les clients anonymes avec n'importe quel client ID unique et non vide. Tout ce qui y est publié est lisible par tous ; utilisez donc un préfixe de topic aléatoire et uniquement des appareils de test sans enjeu.

Modifiez la section mqtt de configuration.yaml :

mqtt:
  base_topic: connectmq/demo/z2m-7f3k9q/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  client_id: z2m-7f3k9q
  version: 5
  keepalive: 60
  reject_unauthorized: true

Quelques remarques sur ces valeurs :

• mqtts:// et le port 8883 activent TLS. Le broker utilise un certificat Let's Encrypt, auquel Node.js fait déjà confiance ; vous n'avez donc pas besoin d'une entrée ca.
• base_topic avec votre identifiant aléatoire sépare vos messages de ceux des autres. Zigbee2MQTT ajoute le nom convivial de l'appareil et des suffixes comme /set ; le topic complet compte donc ici six niveaux, sous la limite de huit du serveur MQTT public gratuit.
• version: 5 sélectionne MQTT 5. La version 4 (MQTT 3.1.1) fonctionne aussi.
• reject_unauthorized: true est la valeur par défaut ; laissez-la activée. La désactiver fait accepter n'importe quel certificat et annule l'intérêt de TLS.

Redémarrez Zigbee2MQTT et cherchez dans le journal une ligne du type Connected to MQTT server. Abonnez-vous ensuite depuis n'importe quelle machine :

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i watcher-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/#' -v

Vous devriez voir bridge/state, bridge/info, bridge/devices et un topic par appareil. Commandez une lampe depuis l'autre côté :

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i sender-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/living_lamp/set' \
  -m '{"state":"TOGGLE"}'

Sous Windows ou macOS, remplacez --capath /etc/ssl/certs par --cafile pointant vers un bundle d'autorités de certification contenant ISRG Root X1.

Les limites du serveur MQTT public gratuit à garder en tête

L'espace public autorise 64 Ko par message et 10 messages par seconde et par client. Un grand réseau Zigbee peut atteindre les deux : bridge/devices liste chaque appareil avec sa définition complète et peut dépasser 64 Ko sur un grand maillage, et une rafale de remontées de capteurs peut dépasser la limite de débit. Pour un test avec quelques appareils, ce n'est pas un problème, mais c'est une raison de plus de passer à un broker privé pour l'installation réelle.

Étape 2 : passer à un broker cloud privé pour Zigbee2MQTT

Une fois le test concluant, créez un broker privé. Dans ConnectMQ, vous choisissez un plan, créez un broker et recevez un nom d'utilisateur, un mot de passe et un client ID générés. Les client IDs sont liés aux identifiants émis ; utilisez donc exactement le client ID fourni par le portail.

Gardez les secrets hors du fichier principal grâce à la syntaxe !secret de Zigbee2MQTT. Créez secret.yaml à côté de configuration.yaml :

mqtt_user: YOUR_USERNAME
mqtt_password: YOUR_PASSWORD
mqtt_client_id: YOUR_CLIENT_ID

Puis faites-y référence :

mqtt:
  base_topic: home/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: '!secret mqtt_user'
  password: '!secret mqtt_password'
  client_id: '!secret mqtt_client_id'
  version: 5
  keepalive: 60
  reject_unauthorized: true
  include_device_information: false

frontend:
  enabled: true
  port: 8080

advanced:
  last_seen: ISO_8601

Remplacez l'hôte par celui indiqué pour votre broker dans le portail s'il diffère. Redémarrez, puis confirmez la connexion dans le journal et dans l'explorateur de topics en direct du portail, où home/zigbee2mqtt/bridge/state doit apparaître dès le démarrage de Zigbee2MQTT.

last_seen ajoute un horodatage à chaque message d'appareil, ce qui permet de repérer bien plus facilement un capteur devenu muet lorsque vous consultez les données à distance. Laissez include_device_information désactivé sauf si un consommateur en a besoin, car il ajoute un bloc de métadonnées à chaque payload.

Étape 3 : piloter les appareils Zigbee à distance

Avec Zigbee2MQTT sur un broker cloud, tout client MQTT disposant d'identifiants peut agir sur vos appareils. Le contrat de topics est le même que sur un broker local :

Le topic bridge/state est retenu et défini comme Last Will ; un tableau de bord distant peut donc faire la différence entre « la lampe est éteinte » et « toute la passerelle Zigbee est hors ligne ». Exploitez-le dans votre interface au lieu de vous fier indéfiniment au dernier état de l'appareil.

Un contrôleur distant minimal en Python, avec paho-mqtt 2.x, ressemble à ceci :

import json
import paho.mqtt.client as mqtt

BASE = "home/zigbee2mqtt"

def on_connect(client, userdata, flags, reason_code, properties):
    print("connected:", reason_code)
    client.subscribe(f"{BASE}/bridge/state")
    client.subscribe(f"{BASE}/living_lamp")
    client.publish(f"{BASE}/living_lamp/set", json.dumps({"state": "ON", "brightness": 120}))

def on_message(client, userdata, msg):
    print(msg.topic, msg.payload.decode())

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="YOUR_CLIENT_ID")
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 8883, keepalive=60)
client.loop_forever()

Notez que ce script a besoin de son propre client ID. L'exécuter avec le même identifiant que Zigbee2MQTT déconnecterait la passerelle à chaque connexion du script, car un broker n'autorise qu'une session par client ID. Donnez à chaque application ses propres identifiants.

Home Assistant et autres consommateurs

Si Home Assistant doit découvrir les appareils Zigbee, activez homeassistant: enabled: true dans Zigbee2MQTT et faites pointer l'intégration MQTT de Home Assistant vers le même broker avec les mêmes identifiants. La version pas à pas, y compris les réglages TLS dans l'interface de Home Assistant, se trouve dans le guide d'utilisation de Home Assistant avec un broker MQTT externe. Les messages de découverte sont retenus ; ils arrivent donc même si Home Assistant démarre après Zigbee2MQTT.

Les autres systèmes s'intègrent de la même manière : Node-RED, Telegraf ou un petit script se connecte comme client MQTT, s'abonne à home/zigbee2mqtt/# et écrit dans le stockage de votre choix. Le broker se contente d'acheminer les messages, ce qui garde l'architecture simple et remplaçable. Jeedom et Domoticz savent aussi communiquer en MQTT.

Liste de contrôle de dépannage

1. Connection refused: Not authorized - vérifiez le nom d'utilisateur et le mot de passe, et que client_id correspond exactement à celui émis pour ces identifiants.
2. La passerelle se reconnecte toutes les quelques secondes - un autre client utilise le même client ID. Passez en revue vos scripts, vos flux Node-RED et vos anciens conteneurs.
3. self signed certificate ou unable to verify - vous êtes derrière un proxy qui intercepte TLS ou l'horloge système est fausse. Corrigez l'horloge (fréquent sur un Pi sans synchronisation réseau) avant toute autre chose.
4. Rien n'arrive chez l'abonné - vérifiez que le base_topic est orthographié de façon identique des deux côtés ; les topics MQTT sont sensibles à la casse.
5. bridge/devices absent sur le serveur MQTT public gratuit - le message dépasse probablement la limite publique de 64 Ko. Testez avec moins d'appareils ou passez à un broker privé, où le plan Free autorise 256 Ko.
6. Limite de connexions atteinte - chaque instance Zigbee2MQTT, tableau de bord et script compte pour une connexion. Le plan Free en autorise jusqu'à 25.

Pour une revue plus large de TLS, des identifiants et de la conception des topics, consultez le guide des bonnes pratiques de sécurité MQTT.

Choisir un broker hébergé pour Zigbee2MQTT

Zigbee2MQTT n'exige pas grand-chose d'un broker : MQTT 3.1.1 ou 5, TLS, les retained messages et un Last Will. Ce qui compte davantage pour un accès distant, c'est que le broker soit joignable, chiffré et isolé des autres clients. Un broker MQTT managé comme ConnectMQ gère les certificats, la disponibilité et les mises à jour, pour que votre Raspberry Pi n'ait qu'à faire tourner Zigbee2MQTT. Les brokers Serverless gratuits prennent en charge les QoS 0 et 1, ce qui couvre sans modification la publication en QoS 0 par défaut de Zigbee2MQTT. Pour un tour d'horizon plus large des options d'hébergement, lisez le guide du broker MQTT cloud, et pour d'autres projets d'automatisation reposant sur le même broker, parcourez le guide de l'automatisation IoT.

Mettez votre réseau Zigbee sur ConnectMQ

Créez un broker Serverless gratuit sur app.connectmq.com (sans carte bancaire), collez les identifiants générés dans secret.yaml et regardez vos appareils Zigbee apparaître dans l'explorateur de topics en direct moins d'une minute après le redémarrage de Zigbee2MQTT.

Questions fréquentes

Zigbee2MQTT peut-il se connecter à un broker cloud en TLS ?

Oui. Réglez server sur mqtts://host:8883 dans la section mqtt de configuration.yaml. Pour les brokers utilisant des certificats publiquement reconnus comme Let's Encrypt, aucun fichier d'autorité de certification supplémentaire n'est nécessaire.

Est-il sûr d'utiliser un broker public pour Zigbee2MQTT ?

Uniquement pour de courts tests avec des appareils sans enjeu. N'importe qui peut lire et publier sur les topics d'un broker public ; une serrure ou une alarme ne doit donc jamais être connectée ainsi. Utilisez des identifiants privés pour tout usage réel.

Ai-je encore besoin d'un broker Mosquitto local ?

Non. Zigbee2MQTT peut publier directement vers le broker cloud. Certains conservent un broker local pour des automatisations purement locales qui doivent fonctionner pendant une coupure Internet, ce qui est un choix de conception valable.

Pourquoi ma passerelle Zigbee2MQTT se déconnecte-t-elle quand j'ouvre une autre application ?

L'autre application utilise très certainement le même client ID. Un broker conserve une session par client ID et coupe la connexion la plus ancienne ; donnez donc à chaque client son propre identifiant et ses propres identifiants de connexion.