Appareils Shelly et MQTT : configuration, topics et RPC

Les appareils Shelly parlent MQTT nativement : ouvrez l'interface web de l'appareil, activez MQTT, saisissez l'hôte, le port et les identifiants de votre broker, et le relais commence à publier son état et à accepter des commandes. Ce qui change, c'est l'organisation des topics. Les Gen1 (Shelly 1, 2.5, Plug S, H&T…) utilisent une arborescence fixe shellies/... avec des commandes en texte brut, tandis que les Gen2, Plus, Pro et Gen3 exposent une API JSON-RPC que vous pouvez appeler via MQTT.

Ce tutoriel couvre les deux générations : les réglages, les topics que vous verrez, l'envoi de commandes et la vérification de tout en ligne de commande avant de brancher l'appareil sur Home Assistant, openHAB ou votre propre code.

Quelle génération avez-vous ?

L'ID de l'appareil est dérivé de l'adresse MAC. Vous le trouverez dans les informations de l'appareil dans l'interface web, ou abonnez-vous simplement à # une fois l'appareil connecté et lisez-le dans les premiers topics qui arrivent.

Configuration Gen1

Dans l'interface web Gen1, ouvrez Internet & Security → Advanced – Developer Settings et cochez Enable action execution via MQTT. Renseignez :

• Server : broker.connectmq.com:1883
• Username / Password : les identifiants de votre broker
• Use custom MQTT prefix (facultatif) : par exemple testmqtt/shelly/hallway au lieu de shellies/shelly1-A1B2C3
• Clean session, Keep alive (60 s convient), Max QoS et Retain : retain est utile pour qu'un dashboard voie immédiatement le dernier état du relais

Enregistrez : l'appareil relance sa connexion MQTT. N'oubliez pas que sur Gen1 cela coupe le Shelly Cloud.

Topics Gen1

shellies/shelly1pm-A1B2C3/online            true | false   (Last Will)
shellies/shelly1pm-A1B2C3/relay/0           on | off
shellies/shelly1pm-A1B2C3/relay/0/power     puissance instantanée en W
shellies/shelly1pm-A1B2C3/relay/0/energy    compteur d'énergie (watts-minutes)
shellies/shelly1pm-A1B2C3/input/0           0 | 1
shellies/shelly1pm-A1B2C3/temperature       température interne en °C
shellies/shelly1pm-A1B2C3/relay/0/command   ← publier on | off | toggle
shellies/announce                           l'appareil s'annonce (JSON)
shellies/command                            ← publier announce | update

Les commandes sont de simples chaînes. Pour commuter le relais, publiez on sur .../relay/0/command ; l'appareil répond en publiant la nouvelle valeur sur .../relay/0. Publier announce sur shellies/command amène tous les Gen1 du broker à communiquer leur ID, IP et firmware : une astuce de découverte pratique. Les volets utilisent roller/0/command avec open, close, stop, et roller/0/command/pos avec un pourcentage.

Les appareils sur batterie comme le H&T dorment la plupart du temps : ils se réveillent, publient sensor/temperature et sensor/humidity, puis se déconnectent. Côté abonné, appuyez-vous sur les valeurs retenues plutôt que sur la présence en ligne de l'appareil.

Configuration Gen2, Plus et Pro

Ouvrez Settings → MQTT et activez-le :

• Server : broker.connectmq.com:8883 (ou :1883 sans TLS)
• Client ID : par défaut l'ID de l'appareil ; gardez-le unique, voir bonnes pratiques pour le client ID MQTT
• Username / Password
• SSL/TLS : No TLS, TLS no validation, TLS with default CA (pour des certificats publics) ou TLS with user CA
• MQTT Prefix : par défaut l'ID de l'appareil ; définissez par exemple testmqtt/shelly/plug1
• RPC status notifications over MQTT : publie les événements sur <préfixe>/events/rpc
• Generic status update over MQTT : publie l'état de chaque composant sur <préfixe>/status/<composant>
• Enable MQTT Control : accepte des commandes simples sur <préfixe>/command/...

Un redémarrage est nécessaire après modification des réglages MQTT. Vous pouvez aussi tout configurer sans l'interface, en appelant l'API RPC en HTTP :

curl -s -X POST http://192.168.1.50/rpc/MQTT.SetConfig \
  -d '{"config":{"enable":true,"server":"broker.connectmq.com:8883","ssl_ca":"ca.pem",
       "user":"username","pass":"password","topic_prefix":"testmqtt/shelly/plug1",
       "rpc_ntf":true,"status_ntf":true,"enable_control":true}}'

curl -s -X POST http://192.168.1.50/rpc/Shelly.Reboot

"ssl_ca": "ca.pem" sélectionne le bundle de CA intégré ; "*" désactive la validation et "user_ca.pem" utilise un certificat que vous avez téléversé. Évitez "*" hors d'un labo ; voir tester une connexion TLS.

Topics Gen2

testmqtt/shelly/plug1/online              true | false   (Last Will)
testmqtt/shelly/plug1/status/switch:0     {"id":0,"output":true,"apower":12.4,...}
testmqtt/shelly/plug1/events/rpc          {"method":"NotifyStatus","params":{...}}
testmqtt/shelly/plug1/command             ← publier status_update
testmqtt/shelly/plug1/command/switch:0    ← publier on | off | toggle
testmqtt/shelly/plug1/rpc                 ← publier des requêtes JSON-RPC

Les composants sont adressés sous la forme type:index : switch:0, input:1, cover:0, temperature:100. Avec Generic status update, l'état complet de chaque composant arrive sur son propre topic, le format le plus simple à consommer. events/rpc transporte des deltas NotifyStatus et des messages NotifyEvent (appuis sur un bouton, par exemple).

RPC sur MQTT

Toute méthode Gen2 appelable en HTTP fonctionne aussi via MQTT. Publiez une trame JSON-RPC sur <préfixe>/rpc ; l'appareil répond sur <src>/rpc, où src est la valeur indiquée dans la requête. C'est le modèle requête/réponse classique.

{"id": 1, "src": "testmqtt/shelly/cli", "method": "Switch.Set", "params": {"id": 0, "on": true}}

{"id": 1, "src": "shellyplusplugs-a8032ab12345", "dst": "testmqtt/shelly/cli", "result": {"was_on": false}}

Méthodes utiles : Shelly.GetStatus, Shelly.GetDeviceInfo, Switch.Toggle, Switch.GetStatus, Cover.GoToPosition, Sys.SetConfig. Les erreurs reviennent avec un objet error (code et message) à la place de result.

Voici un petit utilitaire Python (paho-mqtt 2.x) qui envoie un appel RPC et attend la réponse correspondante :

import json, os, threading
import paho.mqtt.client as mqtt

PREFIX = "testmqtt/shelly/plug1"
SRC = "testmqtt/shelly/cli"
done = threading.Event()

def on_connect(client, userdata, flags, reason_code, properties):
    client.subscribe(f"{SRC}/rpc", qos=1)

def on_subscribe(client, userdata, mid, reason_codes, properties):
    req = {"id": 1, "src": SRC, "method": "Shelly.GetStatus"}
    client.publish(f"{PREFIX}/rpc", json.dumps(req), qos=1)

def on_message(client, userdata, msg):
    resp = json.loads(msg.payload)
    if resp.get("id") == 1:
        print(json.dumps(resp.get("result", resp.get("error")), indent=2))
        done.set()

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="shelly-rpc-cli")
client.username_pw_set(os.environ["MQTT_USER"], os.environ["MQTT_PASS"])
client.tls_set()
client.on_connect, client.on_subscribe, client.on_message = on_connect, on_subscribe, on_message
client.connect("broker.connectmq.com", 8883)
client.loop_start()
print("ok" if done.wait(10) else "pas de réponse (vérifiez le préfixe et l'option RPC)")
client.loop_stop()

Tester la configuration

Avant d'ajouter l'appareil à un logiciel domotique, observez directement son trafic :

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'shellies/#' -t 'testmqtt/shelly/#' -v

Commutez ensuite le relais depuis un second terminal et vérifiez que le topic d'état suit :

# Gen1
mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'shellies/shelly1pm-A1B2C3/relay/0/command' -m toggle

# Gen2 avec "Enable MQTT Control"
mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/shelly/plug1/command/switch:0' -m toggle

Vous pouvez faire la même chose dans le navigateur avec le client MQTT en ligne : abonnez-vous au préfixe avec #, publiez status_update sur <préfixe>/command et l'appareil répond avec son état complet. Si vous doutez qu'un wildcard couvre les topics attendus, collez-les dans le topic matcher.

Observer les topics de votre Shelly dans le navigateur

Si rien n'apparaît : vérifiez que le topic online passe bien à true, que le port correspond au réglage TLS (8883 avec TLS, 1883 sans) et que l'appareil sait résoudre le nom du broker. Un appareil qui se reconnecte sans cesse est souvent en conflit avec un autre client utilisant le même client ID.

Notes d'intégration

• Home Assistant : les Shelly s'ajoutent généralement via l'intégration native Shelly, qui n'utilise pas MQTT. Si vous préférez MQTT, définissez les entités à la main ou utilisez un script de discovery ; voir Home Assistant et MQTT.
• Conception des topics : un préfixe personnalisé comme home/<pièce>/<appareil> garde Shelly, Tasmota et Zigbee dans une arborescence cohérente ; voir conception des topics pour la maison connectée.
• État retenu : activez retain (Gen1) ou appuyez-vous sur status/... plus une requête status_update au démarrage (Gen2) pour que les dashboards n'affichent pas "unknown" après un redémarrage.
• Mélanger les générations : écrivez vos consommateurs pour les deux formats, ou normalisez-les dans Node-RED avant qu'ils n'atteignent votre application.

La prise en charge MQTT de Shelly est l'une des plus complètes du matériel grand public : des topics simples en Gen1, une API RPC complète à partir de Gen2. Définissez un préfixe personnalisé, observez le trafic avec un abonné avant d'intégrer, et limitez chaque appareil à ses propres topics.

Questions fréquentes