Configurer Shelly MQTT sur Gen2 et Gen3 : topics, RPC et broker cloud

La prise en charge de Shelly MQTT transforme les relais, prises et compteurs d'énergie Shelly en appareils « local first » que n'importe quel outil MQTT peut surveiller et piloter. Dans ce guide, vous allez activer MQTT sur les appareils Shelly Gen2 et Gen3 (familles Plus, Pro, Mini et Gen3), comprendre les topics qu'ils publient, piloter les sorties avec des commandes simples et JSON-RPC, puis les connecter à un broker en TLS. Tous les exemples fonctionnent d'abord avec le serveur MQTT public gratuit, réservé aux tests.

Fonctionnement de Shelly MQTT sur Gen2 et Gen3

Le firmware de deuxième génération de Shelly a remplacé l'ancienne arborescence de topics Gen1 (shellies/<id>/relay/0) par une API basée sur JSON-RPC 2.0. Les méthodes RPC que vous pouvez appeler en HTTP ou en WebSocket sont aussi disponibles via MQTT, et les changements d'état sont publiés sous forme de notifications. Les appareils Gen3 utilisent la même API ; tout ce qui suit s'applique donc aux deux.

Chaque appareil possède un préfixe de topic, qui vaut par défaut son identifiant d'appareil, par exemple shellyplus1pm-a8032ab12345. Vous pouvez le remplacer par ce qui convient à votre arborescence. Sous ce préfixe, les topics importants sont :

Deux réglages déterminent ce que publie l'appareil. RPC status notifications envoie des messages NotifyStatus compacts sur events/rpc à chaque changement. Generic status update publie l'état complet du composant sur les topics status/<component>. Pour la plupart des intégrations, les topics d'état par composant sont plus simples à exploiter, car chaque message est un instantané complet et non un delta.

L'appareil se comporte comme n'importe quel autre client MQTT : il ouvre une connexion vers le broker, publie son état et s'abonne à ses propres topics de commande. Si vous êtes encore en train de vous représenter le rôle d'un broker MQTT dans ce schéma, retenez que le Shelly ne parle jamais directement à votre tableau de bord ; tous deux parlent au broker, ce qui permet à un seul appareil d'alimenter Home Assistant, Node-RED et un script Python en même temps sans charge supplémentaire sur le relais. C'est tout l'intérêt de MQTT dans une maison connectée : Jeedom et Domoticz savent aussi communiquer en MQTT et peuvent s'abonner aux mêmes topics.

Activer MQTT dans l'interface web

Ouvrez l'interface web locale de l'appareil via son adresse IP et allez dans Settings > MQTT (sur certaines versions de firmware, c'est sous Networks > MQTT). Configurez :

1. Enable MQTT.
2. Server : broker.connectmq.com:1883 pour un premier test.
3. Client ID : laissez la valeur par défaut ou indiquez un identifiant unique comme shelly-garage-1pm.
4. Username / Password : vides pour le serveur MQTT public gratuit.
5. MQTT prefix : remplacez-le par une valeur unique, par exemple connectmq/demo/r7t2/shelly/garage, car le broker public est partagé et lisible par tous.
6. Activez RPC status notifications over MQTT et Generic status update over MQTT.
7. Laissez Enable "MQTT Control" activé si vous voulez envoyer des commandes.
8. Enregistrez et redémarrez lorsque c'est demandé.

MQTT fonctionne en parallèle de l'interface web locale, de l'API HTTP et des options WebSocket sortantes de l'appareil : vous ne perdez donc pas le contrôle local en l'activant. Si vous utilisez aussi l'application cloud Shelly, vérifiez après activation de MQTT que l'application affiche toujours l'appareil en ligne avec votre version de firmware.

Le préfixe de l'étape 5 utilise cinq niveaux de topic, et Shelly en ajoute deux (status/switch:0), ce qui reste dans la limite de 8 niveaux du broker public. Si vous voulez une arborescence plus profonde, raccourcissez le préfixe.

Configurer Shelly MQTT via l'API RPC

Pour de nombreux appareils, cliquer dans l'interface est fastidieux. Vous pouvez appliquer la même configuration avec un seul appel HTTP par appareil grâce à la méthode Mqtt.SetConfig, puis redémarrer :

SHELLY=192.168.1.50

curl -s -X POST "http://$SHELLY/rpc" -d '{
  "id": 1,
  "method": "Mqtt.SetConfig",
  "params": {
    "config": {
      "enable": true,
      "server": "broker.connectmq.com:1883",
      "client_id": "shelly-garage-1pm",
      "user": null,
      "pass": null,
      "topic_prefix": "connectmq/demo/r7t2/shelly/garage",
      "rpc_ntf": true,
      "status_ntf": true,
      "enable_control": true
    }
  }
}'

curl -s -X POST "http://$SHELLY/rpc" -d '{"id":2,"method":"Shelly.Reboot"}'

Vérifiez le résultat avec curl -s "http://$SHELLY/rpc/Mqtt.GetStatus", qui renvoie {"connected":true} dès que l'appareil dialogue avec le broker. Si l'appareil est protégé par un mot de passe, ajoutez --anyauth -u admin:YOUR_DEVICE_PASSWORD aux appels curl.

Observer les messages Shelly MQTT

Abonnez-vous à tout le préfixe et basculez le relais à la main ou depuis l'application :

mosquitto_sub -h broker.connectmq.com -p 1883 -i shelly-watch-4410 \
  -t "connectmq/demo/r7t2/shelly/garage/#" -v

Chaque message sur les topics d'état est aussi un bon test de votre préfixe : si vous voyez des appareils inconnus dans la sortie, quelqu'un d'autre utilise le même préfixe sur le broker public, et vous devriez en choisir un plus aléatoire.

Un Shelly Plus 1PM publie un état comme celui-ci sur .../status/switch:0 :

{
  "id": 0,
  "source": "WS_in",
  "output": true,
  "apower": 1184.6,
  "voltage": 229.8,
  "current": 5.21,
  "aenergy": { "total": 15832.417, "by_minute": [19542.1, 19688.3, 19601.8], "minute_ts": 1760592120 },
  "temperature": { "tC": 47.3, "tF": 117.2 }
}

Les unités comptent : apower est en watts, voltage en volts, current en ampères, et aenergy.total correspond à l'énergie cumulée depuis la mise en service, en wattheures. Les valeurs by_minute sont en milliwattheures pour les trois dernières minutes complètes. Les appareils sans mesure, comme un simple Plus 1, omettent les champs de puissance.

Piloter les sorties

La façon la plus simple de commuter une sortie est le topic de commande, qui accepte du texte brut :

mosquitto_pub -h broker.connectmq.com -p 1883 -i shelly-cmd-4411 \
  -t "connectmq/demo/r7t2/shelly/garage/command/switch:0" -m "on"

Utilisez off ou toggle de la même manière, et publiez status_update sur <prefix>/command pour que l'appareil publie immédiatement son état complet, ce qui est pratique après le redémarrage d'un tableau de bord.

Pour tout ce qui va au-delà de marche/arrêt, utilisez JSON-RPC. Le champ src indique à l'appareil où envoyer la réponse : il publie sur <src>/rpc.

mosquitto_pub -h broker.connectmq.com -p 1883 -i shelly-cmd-4412 \
  -t "connectmq/demo/r7t2/shelly/garage/rpc" \
  -m '{"id":10,"src":"connectmq/demo/r7t2/client1","method":"Switch.Set","params":{"id":0,"on":true,"toggle_after":600}}'

Cette commande allume la sortie puis l'éteint automatiquement au bout de dix minutes, un schéma sûr pour les pompes et les chauffages. Abonnez-vous à connectmq/demo/r7t2/client1/rpc pour voir la réponse, qui inclut "was_on".

Une intégration Python

Le script ci-dessous s'abonne à l'état du switch, affiche les mesures de puissance et coupe la charge si elle dépasse une limite : un exemple de règle de protection locale exécutée en dehors de l'appareil.

pip install "paho-mqtt>=2.0"

import json
import paho.mqtt.client as mqtt

PREFIX = "connectmq/demo/r7t2/shelly/garage"
LIMIT_W = 2000


def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)
    client.subscribe(f"{PREFIX}/status/switch:0", qos=1)
    client.subscribe(f"{PREFIX}/online", qos=1)
    client.publish(f"{PREFIX}/command", "status_update")


def on_message(client, userdata, msg):
    if msg.topic.endswith("/online"):
        print("Device online:", msg.payload.decode())
        return
    status = json.loads(msg.payload)
    power = status.get("apower", 0.0)
    energy_kwh = status.get("aenergy", {}).get("total", 0.0) / 1000
    print(f"output={status.get('output')} power={power:.1f} W total={energy_kwh:.3f} kWh")
    if status.get("output") and power > LIMIT_W:
        print("Over limit, switching off")
        client.publish(f"{PREFIX}/command/switch:0", "off", qos=1)


client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="shelly-py-7781")
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_forever()

Pour des graphiques d'énergie journaliers sur plusieurs prises, consultez le tutoriel suivi énergétique de prises connectées en MQTT, et pour la mesure de toute la maison avec un Shelly Pro 3EM ou des pinces ampèremétriques, le guide suivi de la consommation électrique de la maison.

Connecter les appareils Shelly en toute sécurité

Les brokers publics servent aux tests ; quiconque connaît votre préfixe peut lire et même commuter vos appareils. En production, utilisez un broker privé avec identifiants et TLS. Les Shelly Gen2 et Gen3 prennent en charge TLS via l'option SSL/TLS des réglages MQTT, avec trois choix : pas de TLS, TLS avec le bundle de CA intégré, ou TLS avec une CA fournie par l'utilisateur. En RPC, c'est le champ ssl_ca qui contrôle cela : "ca.pem" utilise le bundle intégré, "user_ca.pem" une CA que vous avez téléversée, et "*" active TLS sans validation du certificat (à éviter en dehors de tests rapides).

ConnectMQ utilise des certificats Let's Encrypt, que le bundle intégré valide sur les firmwares récents. Une configuration de production ressemble à ceci :

{
  "enable": true,
  "server": "broker.connectmq.com:8883",
  "client_id": "YOUR_CLIENT_ID",
  "user": "YOUR_USERNAME",
  "pass": "YOUR_PASSWORD",
  "ssl_ca": "ca.pem",
  "topic_prefix": "home/garage/shelly1pm",
  "rpc_ntf": true,
  "status_ntf": true,
  "enable_control": true
}

Comme ConnectMQ lie les client ID aux identifiants émis, chaque Shelly doit utiliser son propre jeu d'identifiants issu du portail plutôt que de partager un même login entre plusieurs appareils. Un broker MQTT managé vous évite aussi d'exploiter et de patcher Mosquitto sur un serveur domestique simplement pour garder vos relais accessibles de l'extérieur.

Liste de dépannage

Faites tourner vos appareils Shelly sur ConnectMQ

ConnectMQ offre à vos relais, prises et compteurs Shelly un broker privé avec TLS sur le port 8883, des identifiants générés pour chaque appareil et un portail doté d'un explorateur de topics en direct pour suivre chaque mise à jour d'état. Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire. Pour le reste de votre maison connectée, commencez par le guide de l'automatisation IoT.

Questions fréquentes

Shelly MQTT remplace-t-il l'interface web locale ?

Non. L'interface web et le point d'accès HTTP RPC continuent de fonctionner lorsque MQTT est activé : vous pouvez donc toujours configurer et commuter l'appareil en local, même si le broker est injoignable.

Quelle est la différence entre events/rpc et les topics status ?

events/rpc transporte des notifications JSON-RPC qui ne contiennent généralement que ce qui a changé, tandis que status/<component> transporte un instantané complet d'un composant. Les instantanés sont plus simples à exploiter pour les tableaux de bord et les bases de données.

Puis-je utiliser Home Assistant avec Shelly MQTT ?

Oui. Home Assistant peut lire les mêmes topics via son intégration MQTT, même si beaucoup d'utilisateurs préfèrent l'intégration Shelly native et réservent MQTT à d'autres consommateurs comme Node-RED ou un broker cloud.

Les appareils Shelly Gen1 utilisent-ils les mêmes topics ?

Non. Les appareils Gen1 utilisent l'ancienne arborescence shellies/<device-id>/... et ne prennent pas en charge JSON-RPC ; les exemples de topics présentés ici ne s'appliquent donc qu'aux appareils Gen2 et Gen3.