TapHome

Shelly H&T Gen3

Packet Parser → MQTT
Eingereicht von
Zuletzt aktualisiert: 03. 2026
Shelly H&T Gen3

Der Shelly H&T Gen3 ist ein batteriebetriebener (4x AA) Wi-Fi Temperatur- und Feuchtigkeitssensor mit einem großen E-Paper-Display. TapHome kommuniziert mit dem Gerät über MQTT mittels Gen2+ RPC-Benachrichtigungen auf dem Topic events/rpc. Dies ist das empfohlene Protokoll für batteriebetriebene Shelly Gen3 Geräte, da der Sensor die meiste Zeit schläft und Daten nur bei Aufwachereignissen veröffentlicht.

Die Vorlage erstellt ein einzelnes Gerät Temperatur- und Feuchtigkeitssensor sowie ein Modul-Serviceattribut Batterie. Ein Offline-Erkennungsmechanismus überwacht den zuletzt empfangenen Zeitstempel und gibt Warnungen oder Fehler aus, wenn das Gerät längere Zeit nicht gemeldet hat.

Konfiguration

MQTT Client ID

Jeder Shelly H&T Gen3 hat eine eindeutige MQTT Client ID im Format shellyhtg3-<MAC12>, wobei <MAC12> die vollständige 12-stellige MAC-Adresse in hexadezimaler Großschreibung ist (z.B. shellyhtg3-AABBCCDDEEFF). Diese ID dient auch als Standard-MQTT-Topic-Präfix.

Die Client ID finden Sie:

  • Auf dem Gerätelabel (MAC-Adresse)
  • In der Shelly Web-UI: Settings → MQTT → Client ID
  • Über API: GET http://<device-ip>/rpc/Mqtt.GetConfig → Feld client_id
Vorlageneinrichtung

Nach dem Import der Vorlage in TapHome:

  1. Öffnen Sie das Modul Shelly H&T Gen3 MQTT
  2. Setzen Sie die MQTT Broker IP auf die Adresse des MQTT-Brokers
  3. Setzen Sie den Port (Standard 1883)
  4. Setzen Sie den Import-Parameter MQTT ID auf die Client ID des Geräts (z.B. shellyhtg3-AABBCCDDEEFF)

Das Modul abonniert <device-id>/# und die Listener-Skripte parsen NotifyStatus JSON-RPC-Ereignisse vom Topic events/rpc.

Stellen Sie sicher, dass MQTT auf dem Shelly H&T Gen3 aktiviert ist und rpc_ntf (RPC-Benachrichtigungen) auf true gesetzt ist (Standard). Die Vorlage basiert auf events/rpc-Benachrichtigungen, nicht auf einzelnen Status-Topics.

Mess- und Meldeverhalten

Der Shelly H&T Gen3 arbeitet je nach Stromquelle unterschiedlich:

  • Batteriemodus — Aufwachen jede 1 Minute zur Messung. Meldet über MQTT, wenn sich die Temperatur um mehr als 0,5 °C oder die Luftfeuchtigkeit um mehr als 5 % ändert. Eine unbedingte Statusmeldung wird alle 2 Stunden gesendet, wenn keine schwellenwertbasierten Meldungen ausgelöst wurden.
  • USB-Betrieb — Aufwachen alle 5 Minuten zur Messung, Display-Aktualisierung und Meldung in jedem Zyklus.

Das E-Paper-Display aktualisiert sich bei Temperaturänderungen über 0,2 °C oder Feuchtigkeitsänderungen über 3 %.

Das Gerät ist batteriebetrieben und nicht dauerhaft mit dem MQTT-Broker verbunden. Erwarten Sie Lücken zwischen den Messungen, insbesondere im Batteriemodus. Bei schwachem Wi-Fi-Signal am Sensorstandort können häufige Wiederverbindungsversuche die Batterielebensdauer verkürzen.

Gerätefähigkeiten

Temperatur und Luftfeuchtigkeit

Das Sensorgerät liest Temperatur und Luftfeuchtigkeit aus NotifyStatus-Ereignissen auf dem Topic events/rpc:

  • Temperatur — Umgebungstemperatur in Celsius, gelesen aus params['temperature:0'].tC
  • Luftfeuchtigkeit — relative Luftfeuchtigkeit in Prozent, gelesen aus params['humidity:0'].rh (das Listener-Skript teilt den Wert durch 100 zur Umrechnung in den von TapHome erwarteten Bereich 0–1)

Beide Werte sind schreibgeschützt und aktualisieren sich bei jedem Aufwachen des Sensors und Veröffentlichen von Daten.

Der Temperaturschwellenwert ist am Gerät konfigurierbar (Standard 0,5 °C, Bereich 0,5–5,0 °C). Der Feuchtigkeitsschwellenwert beträgt standardmäßig 5 % (Bereich 1–20 %). Diese Schwellenwerte können über die Shelly Web-UI oder API angepasst werden, um die Meldefrequenz gegen die Batterielebensdauer abzuwägen.

Batterieüberwachung

Das Modul stellt ein Serviceattribut Batterie [%] bereit, das den prozentualen Ladestand der Batterie aus params['devicepower:0'].battery.percent im NotifyStatus-Ereignis liest. Eine Warnung bei niedrigem Batteriestand wird ausgelöst, wenn der Pegel unter 30 % fällt.

Der Batteriestand aktualisiert sich mit jeder Sensormeldung. Mit 4x AA-Batterien beträgt die erwartete Batterielaufzeit unter normalen Bedingungen ca. 1 Jahr.

Offline-Erkennung

Die Vorlage überwacht die Gerätekonnektivität mittels eines zeitstempelbasierten Mechanismus. Das Modul-Listener-Skript speichert den Unix-Zeitstempel aus jedem NotifyStatus-Ereignis in der Custom-Variable timestamp. Das Lese-Skript vergleicht dann den gespeicherten Zeitstempel mit der aktuellen Zeit:

  • Offline > 12 Stunden — WARNING: “Device is offline > 12H”
  • Offline > 24 Stunden — ERROR: “Device is offline > 24H”

Dies ist besonders nützlich für batteriebetriebene Geräte, die aufgrund leerer Batterien oder Wi-Fi-Verbindungsverlust verstummen können.

Weitere Fähigkeiten

Der Shelly H&T Gen3 veröffentlicht auch einen Online/Offline-Status über das MQTT Last Will and Testament (LWT) Topic, Batteriespannung in Volt und den Status der externen Stromversorgung (ob USB Type-C angeschlossen ist). Individuelle Komponenten-Status-Topics (status/temperature:0, status/humidity:0, status/devicepower:0) sind verfügbar, wenn status_ntf aktiviert ist, und die Temperatur ist auch in Fahrenheit verfügbar. Das Gerät verfügt über ein E-Paper-Display mit konfigurierbarer Temperatureinheit und Uhrzeitformat. Diese Fähigkeiten können in einer zukünftigen Vorlagenaktualisierung hinzugefügt werden.

Fehlerbehebung

Sensor meldet keine Daten
  1. Überprüfen Sie, dass der Shelly H&T Gen3 mit Wi-Fi verbunden ist und MQTT in den Geräteeinstellungen aktiviert ist (Settings → MQTT → Enable)
  2. Prüfen Sie, dass rpc_ntf auf true gesetzt ist (Standard) — die Vorlage erfordert RPC-Benachrichtigungen auf events/rpc
  3. Bestätigen Sie, dass der Import-Parameter MQTT ID exakt mit der Client ID des Geräts übereinstimmt (z.B. shellyhtg3-AABBCCDDEEFF)
  4. Verwenden Sie einen MQTT-Client (z.B. MQTT Explorer) zum Abonnieren von <device-id>/# und überprüfen Sie, ob der Sensor NotifyStatus-Nachrichten beim Aufwachen veröffentlicht
  5. Prüfen Sie den Batteriestand des Geräts — leere Batterien verhindern, dass sich der Sensor mit Wi-Fi verbindet
Feuchtigkeitsmessung erscheint falsch
  1. Die TapHome-Vorlage teilt den Rohwert der Luftfeuchtigkeit durch 100 (z.B. rh: 55.3 wird zu 0.553 in TapHome). Dies ist erwartetes Verhalten — TapHome verwendet intern einen Bereich von 0–1
  2. Der Sensor hat einen konfigurierbaren Feuchtigkeitsoffset (Humidity.SetConfig → offset) — überprüfen Sie, dass er nicht auf einen falschen Wert eingestellt ist
  3. Der Betriebsbereich des Sensors für Luftfeuchtigkeit beträgt 30–70 % RH. Messungen außerhalb dieses Bereichs können weniger genau sein
Offline-Warnungen trotz funktionierendem Sensor
  1. Die Offline-Erkennung vergleicht den gespeicherten Zeitstempel mit der aktuellen Zeit. Wenn die TapHome Core-Uhr erheblich abweicht, können falsche Warnungen erscheinen
  2. Im Batteriebetrieb meldet der Sensor nur bei Schwellenwertüberschreitung oder alle 2 Stunden unbedingt — Lücken von bis zu 2 Stunden zwischen Meldungen sind normal
  3. Wenn sich der Sensor an einem Ort mit instabilem Wi-Fi befindet, kann er Meldefenster verpassen. Überprüfen Sie die Wi-Fi-Signalstärke am Sensorstandort

Installation in TapHome

Voraussetzungen

  • Shelly-Gerät mit Wi-Fi verbunden (siehe HTTP-Verbindungsanleitung, falls noch nicht geschehen)
  • MQTT-Broker in Ihrem lokalen Netzwerk aktiv (z. B. Mosquitto, Home Assistant oder der integrierte TapHome-Broker)
  • TapHome CCU im selben Netzwerk wie der Broker

Auf Gen1-Geräten deaktiviert das Aktivieren von MQTT die Shelly Cloud. Beides kann nicht gleichzeitig betrieben werden. Auf Gen2/Plus-Geräten gilt diese Einschränkung nicht.

Schritt 1 — MQTT auf dem Shelly-Gerät aktivieren

Gen1-Geräte (Shelly 1, 1PM, 2.5, EM, 3EM, Plug S, RGBW2, Dimmer, TRV…)

  1. Öffnen Sie die Shelly-Weboberfläche: http://<device-ip>/
  2. Navigieren Sie zu Internet & Security → Advanced — MQTT
  3. Aktivieren Sie MQTT
  4. Setzen Sie MQTT Server: <broker-ip>:<port> (z. B. 192.168.1.10:1883)
  5. Optional setzen Sie MQTT User und MQTT Password, falls Ihr Broker eine Authentifizierung erfordert
  6. Klicken Sie auf Save — das Gerät startet neu und verbindet sich mit dem Broker

Gen2 / Plus-Geräte (Shelly Plus 1, Plus 1PM, Plus 2PM, Plus Plug S, Plus H&T, Pro 3EM…)

  1. Öffnen Sie die Shelly-Weboberfläche: http://<device-ip>/
  2. Navigieren Sie zu Settings → MQTT
  3. Aktivieren Sie MQTT
  4. Setzen Sie Server: <broker-ip>:<port> (z. B. 192.168.1.10:1883)
  5. Die Client ID ist mit der Geräte-ID vorausgefüllt (z. B. shellyplus1pm-AABBCCDDEE) — belassen Sie sie so, es sei denn, Sie haben einen bestimmten Grund zur Änderung
  6. Klicken Sie auf Save und starten Sie das Gerät neu

Um zu überprüfen, ob MQTT funktioniert, verwenden Sie einen MQTT-Client (z. B. MQTT Explorer) und abonnieren Sie shellies/# (Gen1) oder <device-id>/# (Gen2). Sie sollten Statusnachrichten vom Gerät sehen.

Schritt 2 — Device ID / MQTT Client ID ermitteln

Einige Vorlagen erfordern einen Parameter Device ID oder MQTT Client ID. Dies ist die eindeutige Kennung, die in MQTT-Topics verwendet wird.

  • Gen1: auf dem Etikett als MAC-Adresse zu finden (z. B. AABBCCDDEE). Device ID = shelly<model>-<mac>, z. B. shelly1pm-AABBCCDDEE
  • Gen2/Plus: in der Shelly-Weboberfläche unter Settings → Device Info → Device ID zu finden, oder auf dem Geräteetikett

Schritt 3 — Konfiguration in TapHome

  1. Fügen Sie in TapHome ein neues Modul Packet Parser (MQTT) hinzu
  2. IP Address: Geben Sie die IP-Adresse des MQTT-Brokers ein (z. B. 192.168.1.10)
  3. Port: 1883 (Standard; verwenden Sie 8883 für TLS)
  4. Device ID / MQTT Client ID: Geben Sie den Wert aus Schritt 2 ein (falls von der Vorlage benötigt)
  5. Importieren Sie die Vorlage — TapHome abonniert automatisch die Geräte-Topics

Verfügbare Geräte

Shelly H&T Gen3 MQTT Modul
Serviceattribute
BatterieProzentualer Ladestand — Warnung bei niedrigem Batteriestand unter 30 %
Benutzerdefinierte Variablen

Shelly H&T Gen3 MQTT

Lesen (Modul)
if !ISNAN(timestamp)
	DATETIME now := NOW();
	var secondsSeen := now.UNIXTIME - timestamp;
	if secondsSeen > 12 * 60 * 60
		if secondsSeen > 24 * 60 * 60
			ADDERROR("Device is offline > 24H");
		else
			ADDWARNING("Device is offline > 12H");        
		end
	end
end
Listener
if INDEXOF(RECEIVEDMSG.Topic, "events/rpc") > 0
	var ts := PARSEJSON(RECEIVEDMSG.Payload, "params.ts", true);
	if(!ISNULL(ts), timestamp := ts);
    var bat := PARSEJSON(RECEIVEDMSG.Payload, "params['devicepower:0'].battery.percent", true);
	if(!ISNULL(bat), BatteryPercentage := bat);
end

if BatteryPercentage < 30
	ADDWARNING("Low battery (<30%)");
end
Serviceattribute
Battery [%]
BatteryPercentage
Temperatur- und Feuchtigkeitssensor Temperatursensor Nur lesen

Umgebungstemperatur (°C) und relative Luftfeuchtigkeit aus NotifyStatus-Ereignissen — Feuchtigkeit auf Bereich 0–1 für TapHome konvertiert

json Einheit: °C / %RH json_path

Temperatur- und Feuchtigkeitssensor

Listener
if INDEXOF(RECEIVEDMSG.Topic, "events/rpc") > 0
	var temperature := PARSEJSON(RECEIVEDMSG.Payload, "params['temperature:0'].tC", true);
    if(!ISNULL(temperature), Te := temperature);
    var humidity := PARSEJSON(RECEIVEDMSG.Payload, "params['humidity:0'].rh", true);
    if(!ISNULL(humidity), Hu := humidity / 100);
end
Verbindung: Packet Parser → MQTT
Mögliche Verbesserungen (8)
  • Temperature Status Topic — Individual status topic (when status_ntf: true). Template uses events/rpc instead — functionally equivalent.
  • Humidity Status Topic — Individual status topic (when status_ntf: true). Template uses events/rpc instead — functionally equivalent.
  • DevicePower Status Topic — Individual status topic with battery.V (voltage). Template already reads battery.percent from events/rpc.
  • Connection Status (LWT) — Last Will and Testament topic — true on connect, false on disconnect. Template uses timestamp-based offline detection instead.
  • Temperature in Fahrenheit — Temperature also available in Fahrenheit (tF field). Template uses tC only.
  • E-Paper Display Configuration — Temperature unit (C/F) and clock format (12/24/disabled) — display-only configuration, not sensor data.
  • Battery Voltage — Battery voltage in Volts. Template reads only percent, not voltage.
  • External Power Status — Whether USB Type-C power is connected. Could distinguish battery vs USB power mode.

Quellen