Shelly-Geräte und MQTT: Einrichtung, Topics und RPC

Shelly-Geräte sprechen MQTT von Haus aus: Du öffnest die Weboberfläche des Geräts, aktivierst MQTT, trägst Host, Port und Zugangsdaten deines Brokers ein, und das Relais beginnt, seinen Zustand zu publizieren und Befehle anzunehmen. Unterschiedlich ist das Topic-Layout. Gen1-Geräte (Shelly 1, 2.5, Plug S, H&T …) nutzen einen festen shellies/...-Baum mit Klartext-Befehlen, Gen2-, Plus-, Pro- und Gen3-Geräte dagegen eine JSON-RPC-API, die du über MQTT aufrufen kannst.

Dieses Tutorial deckt beide Generationen ab: die Einstellungen, die Topics, die du sehen wirst, wie du Befehle sendest und wie du alles auf der Kommandozeile prüfst, bevor du es in Home Assistant, openHAB oder deinen eigenen Code einbindest.

Welche Generation hast du?

Die Geräte-ID wird aus der MAC-Adresse abgeleitet. Du findest sie in der Weboberfläche unter den Geräteinformationen – oder du abonnierst einfach #, sobald das Gerät verbunden ist, und liest sie aus den ersten eintreffenden Topics ab.

Einrichtung Gen1

Öffne in der Gen1-Weboberfläche Internet & Security → Advanced – Developer Settings und setze den Haken bei Enable action execution via MQTT. Trage ein:

• Server: broker.connectmq.com:1883
• Username / Password: die Zugangsdaten deines Brokers
• Use custom MQTT prefix (optional): zum Beispiel testmqtt/shelly/hallway statt shellies/shelly1-A1B2C3
• Clean session, Keep alive (60 s passt), Max QoS und Retain: Retain ist nützlich, damit ein Dashboard den letzten Relaiszustand sofort sieht

Speichere, und das Gerät baut seine MQTT-Verbindung neu auf. Denk daran: Bei Gen1 wird dadurch die Shelly Cloud abgeschaltet.

Gen1-Topics

shellies/shelly1pm-A1B2C3/online            true | false   (Last Will)
shellies/shelly1pm-A1B2C3/relay/0           on | off
shellies/shelly1pm-A1B2C3/relay/0/power     Momentanleistung in W
shellies/shelly1pm-A1B2C3/relay/0/energy    Energiezähler (Wattminuten)
shellies/shelly1pm-A1B2C3/input/0           0 | 1
shellies/shelly1pm-A1B2C3/temperature       interne Temperatur in °C
shellies/shelly1pm-A1B2C3/relay/0/command   ← on | off | toggle publizieren
shellies/announce                           Gerät meldet sich an (JSON)
shellies/command                            ← announce | update publizieren

Befehle sind einfache Strings. Um das Relais zu schalten, publizierst du on auf .../relay/0/command; das Gerät antwortet mit dem neuen Wert auf .../relay/0. Wenn du announce auf shellies/command publizierst, melden alle Gen1-Geräte am Broker ID, IP und Firmware – ein praktischer Discovery-Trick. Rollläden nutzen roller/0/command mit open, close, stop sowie roller/0/command/pos mit einem Prozentwert.

Batteriegeräte wie der H&T schlafen die meiste Zeit: Sie wachen auf, publizieren sensor/temperature und sensor/humidity und trennen sich wieder. Lass die Subscriber-Seite auf Retained-Werte setzen, nicht darauf, dass das Gerät online ist.

Einrichtung Gen2, Plus und Pro

Öffne Settings → MQTT und aktiviere es:

• Server: broker.connectmq.com:8883 (oder :1883 ohne TLS)
• Client ID: standardmäßig die Geräte-ID; halte sie eindeutig – siehe Best Practices für MQTT-Client-IDs
• Username / Password
• SSL/TLS: No TLS, TLS no validation, TLS with default CA (für öffentliche Zertifikate) oder TLS with user CA
• MQTT Prefix: standardmäßig die Geräte-ID; setze z. B. testmqtt/shelly/plug1
• RPC status notifications over MQTT: publiziert Events auf <präfix>/events/rpc
• Generic status update over MQTT: publiziert den Status jeder Komponente auf <präfix>/status/<komponente>
• Enable MQTT Control: nimmt einfache Befehle auf <präfix>/command/... an

Nach Änderungen an den MQTT-Einstellungen ist ein Neustart nötig. Du kannst die gesamte Konfiguration auch ohne UI erledigen, indem du die RPC-API per HTTP aufrufst:

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" wählt das eingebaute CA-Bundle; "*" schaltet die Validierung ab und "user_ca.pem" nutzt ein von dir hochgeladenes Zertifikat. Verwende "*" nur im Labor – siehe TLS-Verbindung testen.

Gen2-Topics

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             ← status_update publizieren
testmqtt/shelly/plug1/command/switch:0    ← on | off | toggle publizieren
testmqtt/shelly/plug1/rpc                 ← JSON-RPC-Requests publizieren

Komponenten werden als typ:index adressiert – switch:0, input:1, cover:0, temperature:100. Mit Generic status update landet der vollständige Status jeder Komponente auf einem eigenen Topic; das ist das am einfachsten zu verarbeitende Format. events/rpc transportiert NotifyStatus-Deltas und NotifyEvent-Nachrichten (zum Beispiel Tastendrücke).

RPC über MQTT

Jede Gen2-Methode, die du per HTTP aufrufen kannst, funktioniert auch über MQTT. Publiziere einen JSON-RPC-Frame auf <präfix>/rpc; das Gerät antwortet auf <src>/rpc, wobei src der Wert aus deinem Request ist. Das ist das klassische Request/Response-Muster.

{"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}}

Nützliche Methoden: Shelly.GetStatus, Shelly.GetDeviceInfo, Switch.Toggle, Switch.GetStatus, Cover.GoToPosition, Sys.SetConfig. Fehler kommen mit einem error-Objekt (code und message) statt result zurück.

Hier ein kleiner Python-Helfer (paho-mqtt 2.x), der einen RPC-Aufruf sendet und auf die passende Antwort wartet:

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 "keine Antwort (Präfix und RPC-Einstellung prüfen)")
client.loop_stop()

Die Einrichtung testen

Bevor du das Gerät in eine Hausautomations-Software aufnimmst, beobachte seinen Traffic direkt:

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

Schalte dann das Relais aus einem zweiten Terminal und prüfe, ob das Status-Topic folgt:

# 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 mit "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

Dasselbe geht im Browser mit dem Online-MQTT-Client: Abonniere das Präfix mit #, publiziere status_update auf <präfix>/command, und das Gerät antwortet mit seinem vollständigen Status. Wenn du unsicher bist, ob eine Wildcard die erwarteten Topics abdeckt, füge sie in den Topic Matcher ein.

Shelly-Topics im Browser beobachten

Wenn nichts ankommt: Prüfe, ob das online-Topic überhaupt true wird, ob der Port zur TLS-Einstellung passt (8883 mit TLS, 1883 ohne) und ob das Gerät den Hostnamen des Brokers auflösen kann. Ein Gerät, das ständig neu verbindet, kämpft oft mit einem anderen Client mit derselben Client-ID.

Hinweise zur Integration

• Home Assistant: Shelly-Geräte werden meist über die native Shelly-Integration eingebunden, die kein MQTT nutzt. Wenn du MQTT bevorzugst, definiere die Entitäten manuell oder nutze ein Discovery-Skript; siehe Home Assistant und MQTT.
• Topic-Design: Ein eigenes Präfix wie home/<raum>/<gerät> hält Shelly, Tasmota und Zigbee in einem einheitlichen Baum – siehe Topic-Design fürs Smart Home.
• Retained State: Aktiviere Retain (Gen1) oder setze auf status/... plus einen status_update-Request beim Start (Gen2), damit Dashboards nach einem Neustart nicht "unknown" anzeigen.
• Generationen mischen: Schreib deine Consumer für beide Layouts oder normalisiere sie in Node-RED, bevor sie deine Anwendung erreichen.

Shellys MQTT-Unterstützung gehört zu den vollständigsten bei Consumer-Hardware: einfache Topics bei Gen1, eine vollständige RPC-API ab Gen2. Setze ein eigenes Präfix, beobachte den Traffic mit einem Subscriber, bevor du integrierst, und beschränke jedes Gerät auf seine eigenen Topics.

Häufig gestellte Fragen