Shelly MQTT einrichten für Gen2- und Gen3-Geräte: Topics, RPC und Cloud-Broker

Mit der MQTT-Unterstützung von Shelly werden Shelly-Relais, -Steckdosen und -Energiezähler zu Local-First-Geräten, die jedes MQTT-Tool überwachen und steuern kann. In dieser Anleitung aktivieren Sie MQTT auf Shelly-Geräten der Gen2 und Gen3 (den Familien Plus, Pro, Mini und Gen3), lernen die veröffentlichten Topics kennen, steuern Ausgänge mit einfachen Befehlen und JSON-RPC und verbinden die Geräte per TLS mit einem Broker. Alle Beispiele funktionieren zunächst mit dem kostenlosen öffentlichen MQTT-Broker, der für Tests und Prototypen gedacht ist, nicht für Produktionsdaten.

So funktioniert Shelly MQTT bei Gen2 und Gen3

Die Firmware der zweiten Shelly-Generation hat das alte Gen1-Topic-Layout (shellies/<id>/relay/0) durch eine API auf Basis von JSON-RPC 2.0 ersetzt. Dieselben RPC-Methoden, die Sie über HTTP oder WebSocket aufrufen können, stehen auch über MQTT zur Verfügung, und Statusänderungen werden als Benachrichtigungen veröffentlicht. Gen3-Geräte nutzen dieselbe API, daher gilt alles Folgende für beide. Das betrifft auch die Pro-Serie für die Hutschiene, die neben dem Smart Home häufig in Gewerbegebäuden, Werkstätten und für einfaches Energiemonitoring im Mittelstand eingesetzt wird.

Jedes Gerät hat ein Topic-Präfix, das standardmäßig seiner Geräte-ID entspricht, zum Beispiel shellyplus1pm-a8032ab12345. Sie können es beliebig an Ihren Topic-Baum anpassen. Unter diesem Präfix sind folgende Topics wichtig:

Zwei Einstellungen bestimmen, was das Gerät veröffentlicht. RPC status notifications sendet kompakte NotifyStatus-Nachrichten auf events/rpc, sobald sich etwas ändert. Generic status update veröffentlicht den vollständigen Komponentenstatus auf status/<component>-Topics. Für die meisten Integrationen sind die komponentenbezogenen Status-Topics einfacher zu verarbeiten, weil jede Nachricht einen vollständigen Snapshot statt eines Deltas enthält.

Das Gerät verhält sich wie jeder andere MQTT-Client: Es öffnet eine Verbindung zum Broker, veröffentlicht seinen Zustand und abonniert seine eigenen Befehls-Topics. Falls Sie sich noch ein Bild davon machen, was ein MQTT-Broker dabei tut: Entscheidend ist, dass das Shelly nie direkt mit Ihrem Dashboard spricht. Beide sprechen mit dem Broker, und deshalb kann ein Gerät gleichzeitig Home Assistant, Node-RED und ein Python-Skript versorgen, ohne das Relais zusätzlich zu belasten.

MQTT in der Weboberfläche aktivieren

Öffnen Sie die lokale Weboberfläche des Geräts über seine IP-Adresse und gehen Sie zu Settings > MQTT (bei manchen Firmware-Versionen unter Networks > MQTT). Konfigurieren Sie:

1. Enable: MQTT aktivieren.
2. Server: broker.connectmq.com:1883 für einen ersten Test.
3. Client ID: Standardwert belassen oder etwas Eindeutiges wie shelly-garage-1pm setzen.
4. Username / Password: für den öffentlichen MQTT-Broker leer lassen.
5. MQTT prefix: auf einen eindeutigen Wert ändern, zum Beispiel connectmq/demo/r7t2/shelly/garage, denn der öffentliche MQTT-Broker wird geteilt und ist für alle lesbar.
6. RPC status notifications over MQTT und Generic status update over MQTT aktivieren.
7. Enable "MQTT Control" eingeschaltet lassen, wenn Sie Befehle senden möchten.
8. Speichern und bei Aufforderung neu starten.

MQTT läuft parallel zur lokalen Weboberfläche, zur HTTP-API und zu den ausgehenden WebSocket-Optionen des Geräts, Sie verlieren durch die Aktivierung also keine lokale Steuerung. Wenn Sie zusätzlich die Shelly-Cloud-App nutzen, prüfen Sie nach dem Aktivieren von MQTT, ob die App das Gerät mit Ihrer Firmware-Version weiterhin als online anzeigt.

Das Präfix aus Schritt 5 umfasst fünf Topic-Ebenen, Shelly fügt zwei weitere hinzu (status/switch:0). Damit bleiben Sie innerhalb des Limits von 8 Ebenen des öffentlichen MQTT-Brokers. Wenn Sie einen tieferen Baum möchten, kürzen Sie das Präfix.

Shelly MQTT über die RPC-API konfigurieren

Bei vielen Geräten ist das Durchklicken der Oberfläche mühsam. Sie können dieselbe Konfiguration mit einem HTTP-Aufruf pro Gerät über die Methode Mqtt.SetConfig anwenden und anschließend neu starten:

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

Prüfen Sie das Ergebnis mit curl -s "http://$SHELLY/rpc/Mqtt.GetStatus"; es liefert {"connected":true}, sobald das Gerät mit dem Broker kommuniziert. Ist das Gerät mit einem Passwort geschützt, ergänzen Sie die curl-Aufrufe um --anyauth -u admin:YOUR_DEVICE_PASSWORD.

Shelly-MQTT-Nachrichten beobachten

Abonnieren Sie das gesamte Präfix und schalten Sie das Relais von Hand oder in der App:

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

Jede Nachricht auf den Status-Topics ist zugleich ein guter Test Ihres Topic-Präfixes: Sehen Sie fremde Geräte in der Ausgabe, verwendet jemand anderes dasselbe Präfix auf dem öffentlichen MQTT-Broker, und Sie sollten ein zufälligeres wählen.

Ein Shelly Plus 1PM veröffentlicht auf .../status/switch:0 einen Status wie diesen:

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

Die Einheiten sind hier wichtig: apower ist in Watt, voltage in Volt, current in Ampere, und aenergy.total ist die Gesamtenergie seit Inbetriebnahme in Wattstunden. Die by_minute-Werte sind in Milliwattstunden für die letzten drei vollständigen Minuten angegeben. Geräte ohne Messfunktion, etwa ein einfaches Plus 1, lassen die Leistungsfelder weg.

Ausgänge steuern

Am einfachsten schalten Sie einen Ausgang über das Command-Topic, das reinen Text akzeptiert:

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

Verwenden Sie off oder toggle auf dieselbe Weise und veröffentlichen Sie status_update an <prefix>/command, damit das Gerät sofort seinen vollständigen Status sendet, was nach einem Neustart des Dashboards praktisch ist.

Für alles, was über Ein und Aus hinausgeht, nutzen Sie JSON-RPC. Das Feld src teilt dem Gerät mit, wohin es die Antwort senden soll: Es veröffentlicht an <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}}'

Damit wird der Ausgang eingeschaltet und nach zehn Minuten automatisch wieder ausgeschaltet, ein sicheres Muster für Pumpen und Heizgeräte. Abonnieren Sie connectmq/demo/r7t2/client1/rpc, um die Antwort einschließlich "was_on" zu sehen.

Eine Python-Integration

Das folgende Skript abonniert den Schaltstatus, gibt Leistungswerte aus und schaltet die Last ab, wenn sie mehr als einen Grenzwert zieht. Es ist ein Beispiel für eine lokale Schutzregel, die außerhalb des Geräts läuft.

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()

Für tägliche Energiediagramme über mehrere Steckdosen hinweg lesen Sie das Tutorial zum Energiemonitoring mit smarten Steckdosen über MQTT, und für die Messung des ganzen Hauses mit einem Shelly Pro 3EM oder Stromwandlerzangen den Leitfaden zum Energiemonitor für zu Hause.

Shelly-Geräte sicher verbinden

Ein öffentlicher MQTT-Broker ist zum Testen da; jeder, der Ihr Präfix kennt, kann Ihre Geräte mitlesen und sogar schalten. Für den Produktivbetrieb verwenden Sie einen privaten Broker mit Zugangsdaten und TLS. Shelly Gen2 und Gen3 unterstützen TLS über die Option SSL/TLS in den MQTT-Einstellungen mit drei Varianten: kein TLS, TLS mit dem eingebauten CA-Bundle oder TLS mit einer selbst bereitgestellten CA. Über RPC steuert das Feld ssl_ca dies: "ca.pem" nutzt das eingebaute Bundle, "user_ca.pem" eine von Ihnen hochgeladene CA, und "*" aktiviert TLS ohne Zertifikatsprüfung (vermeiden Sie das außerhalb schneller Tests).

ConnectMQ verwendet Let's-Encrypt-Zertifikate, die das eingebaute Bundle mit aktueller Firmware validiert. Eine produktive Konfiguration sieht so aus:

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

Da ConnectMQ Client-IDs an ausgestellte Zugangsdaten bindet, sollte jedes Shelly einen eigenen Satz Zugangsdaten aus dem Portal verwenden, statt dass sich mehrere Geräte einen Login teilen. Ein verwalteter MQTT-Broker erspart Ihnen außerdem, Mosquitto auf einem Heimserver zu betreiben und zu patchen, nur damit Ihre Relais von außen erreichbar bleiben.

Setzen Sie Shelly Pro 3EM oder Pro 4PM in einer Halle oder an Maschinen ein, lohnt sich ein Topic-Präfix, das der Standortstruktur folgt, etwa acme/werk-regensburg/halle-2/kompressor-1/shelly. So fügen sich die Energiedaten später nahtlos in einen Unified Namespace (UNS) nach ISA-95 ein, in dem auch SPS- und MES-Daten liegen. Für Schalthandlungen an Maschinen gilt aber: Ein Shelly ersetzt keine Sicherheitssteuerung.

Checkliste zur Fehlerbehebung

Ihre Shelly-Geräte mit ConnectMQ betreiben

ConnectMQ bietet Ihren Shelly-Relais, -Steckdosen und -Zählern einen privaten Broker mit TLS auf Port 8883, generierte Zugangsdaten pro Gerät und ein Portal mit Live-Topic-Explorer, in dem Sie jedes Statusupdate verfolgen. Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ganz ohne Kreditkarte. Für den Rest Ihres Smart Homes beginnen Sie mit dem Leitfaden zur IoT-Automatisierung.

Häufig gestellte Fragen

Ersetzt Shelly MQTT die lokale Weboberfläche?

Nein. Die Weboberfläche und der HTTP-RPC-Endpunkt funktionieren weiter, wenn MQTT aktiviert ist. Sie können das Gerät also auch dann lokal konfigurieren und schalten, wenn der Broker nicht erreichbar ist.

Was ist der Unterschied zwischen events/rpc und den Status-Topics?

events/rpc überträgt JSON-RPC-Benachrichtigungen, die meist nur die Änderung enthalten, während status/<component> einen vollständigen Snapshot einer Komponente liefert. Snapshots sind für Dashboards und Datenbanken einfacher zu verarbeiten.

Kann ich Home Assistant mit Shelly MQTT verwenden?

Ja. Home Assistant kann dieselben Topics über seine MQTT-Integration lesen. Viele Nutzer bevorzugen allerdings die native Shelly-Integration und verwenden MQTT für andere Abnehmer wie Node-RED oder einen Cloud-Broker.

Verwenden Shelly-Geräte der Gen1 dieselben Topics?

Nein. Gen1-Geräte nutzen das ältere Layout shellies/<device-id>/... und unterstützen kein JSON-RPC. Die Topic-Beispiele hier gelten daher nur für Gen2- und Gen3-Geräte.