TapHome

Shelly H&T Gen3

Packet Parser → MQTT
Dodane przez
Ostatnia aktualizacja: 03. 2026
Shelly H&T Gen3

Shelly H&T Gen3 to bateryjny (4x AA) czujnik temperatury i wilgotności Wi-Fi z dużym wyświetlaczem e-paper. TapHome komunikuje się z urządzeniem przez MQTT za pomocą powiadomień RPC Gen2+ na topicu events/rpc. Jest to zalecany protokół dla bateryjnych urządzeń Shelly Gen3, ponieważ czujnik większość czasu pozostaje w trybie uśpienia i publikuje dane tylko po wybudzeniu.

Szablon tworzy jedno urządzenie Czujnik temperatury i wilgotności oraz atrybut serwisowy Bateria na poziomie modułu. Mechanizm wykrywania offline monitoruje ostatni odebrany znacznik czasu i generuje ostrzeżenia lub błędy, gdy urządzenie nie raportowało przez dłuższy okres.

Konfiguracja

MQTT Client ID

Każdy Shelly H&T Gen3 ma unikalny MQTT Client ID w formacie shellyhtg3-<MAC12>, gdzie <MAC12> to pełny 12-znakowy adres MAC w szesnastkowym zapisie wielkimi literami (np. shellyhtg3-AABBCCDDEEFF). Ten identyfikator służy również jako domyślny prefiks topiców MQTT.

Client ID można znaleźć:

  • Na etykiecie urządzenia (adres MAC)
  • W interfejsie webowym Shelly: Settings → MQTT → Client ID
  • Przez API: GET http://<device-ip>/rpc/Mqtt.GetConfig → pole client_id
Konfiguracja szablonu

Po zaimportowaniu szablonu w TapHome:

  1. Otwórz moduł Shelly H&T Gen3 MQTT
  2. Ustaw MQTT Broker IP na adres brokera MQTT
  3. Ustaw Port (domyślnie 1883)
  4. Ustaw parametr importu MQTT ID na Client ID urządzenia (np. shellyhtg3-AABBCCDDEEFF)

Moduł subskrybuje <device-id>/#, a skrypty nasłuchujące parsują zdarzenia JSON-RPC NotifyStatus z topicu events/rpc.

Upewnij się, że MQTT jest włączone na Shelly H&T Gen3 i rpc_ntf (powiadomienia RPC) jest ustawione na true (domyślnie). Szablon opiera się na powiadomieniach events/rpc, a nie na indywidualnych topicach statusu.

Pomiary i raportowanie

Shelly H&T Gen3 działa różnie w zależności od źródła zasilania:

  • Tryb bateryjny — wybudzenie co 1 minutę na pomiar. Raportuje przez MQTT, jeśli temperatura zmieni się o więcej niż 0,5 °C lub wilgotność o więcej niż 5%. Bezwarunkowy raport statusu jest wysyłany co 2 godziny, jeśli nie zostały wyzwolone raporty progowe.
  • Zasilanie USB — wybudzenie co 5 minut na pomiar, aktualizację wyświetlacza i raportowanie w każdym cyklu.

Wyświetlacz e-paper aktualizuje się przy zmianie temperatury o więcej niż 0,2 °C lub wilgotności o więcej niż 3%.

Urządzenie jest zasilane bateryjnie i nie jest stale podłączone do brokera MQTT. Spodziewaj się przerw między odczytami, szczególnie w trybie bateryjnym. Jeśli lokalizacja czujnika ma słaby sygnał Wi-Fi, częste próby ponownego połączenia mogą skrócić żywotność baterii.

Możliwości urządzenia

Temperatura i wilgotność

Urządzenie czujnikowe odczytuje temperaturę i wilgotność ze zdarzeń NotifyStatus na topicu events/rpc:

  • Temperatura — temperatura otoczenia w stopniach Celsjusza, odczytana z params['temperature:0'].tC
  • Wilgotność — wilgotność względna w procentach, odczytana z params['humidity:0'].rh (skrypt nasłuchujący dzieli wartość przez 100 w celu konwersji na zakres 0–1 oczekiwany przez TapHome)

Obie wartości są tylko do odczytu i aktualizują się przy każdym wybudzeniu czujnika i publikacji danych.

Próg raportowania temperatury jest konfigurowalny na urządzeniu (domyślnie 0,5 °C, zakres 0,5–5,0 °C). Próg wilgotności domyślnie wynosi 5% (zakres 1–20%). Progi te można dostosować przez interfejs webowy Shelly lub API, aby zrównoważyć częstotliwość raportowania z żywotnością baterii.

Monitorowanie baterii

Moduł udostępnia atrybut serwisowy Bateria [%], który odczytuje procentowy poziom naładowania baterii z params['devicepower:0'].battery.percent w zdarzeniu NotifyStatus. Ostrzeżenie o niskim poziomie baterii jest wyzwalane, gdy poziom spadnie poniżej 30%.

Poziom baterii aktualizuje się z każdym raportem czujnika. Na bateriach 4x AA oczekiwana żywotność wynosi około 1 roku w normalnych warunkach.

Wykrywanie offline

Szablon monitoruje łączność urządzenia za pomocą mechanizmu opartego na znaczniku czasu. Skrypt nasłuchujący modułu zapisuje znacznik czasu Unix z każdego zdarzenia NotifyStatus w zmiennej niestandardowej timestamp. Skrypt odczytu porównuje następnie zapisany znacznik czasu z bieżącym czasem:

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

Jest to szczególnie przydatne dla urządzeń bateryjnych, które mogą przestać komunikować się z powodu wyczerpanych baterii lub utraty połączenia Wi-Fi.

Dodatkowe możliwości

Shelly H&T Gen3 publikuje również status online/offline przez topic MQTT Last Will and Testament (LWT), napięcie baterii w woltach oraz status zasilania zewnętrznego (czy USB Type-C jest podłączony). Indywidualne topice statusu komponentów (status/temperature:0, status/humidity:0, status/devicepower:0) są dostępne gdy status_ntf jest włączone, a temperatura jest również dostępna w Fahrenheitach. Urządzenie posiada wyświetlacz e-paper z konfigurowalną jednostką temperatury i formatem zegara. Możliwości te mogą zostać dodane w przyszłej aktualizacji szablonu.

Rozwiązywanie problemów

Czujnik nie raportuje danych
  1. Sprawdź, czy Shelly H&T Gen3 jest podłączony do Wi-Fi i MQTT jest włączone w ustawieniach urządzenia (Settings → MQTT → Enable)
  2. Upewnij się, że rpc_ntf jest ustawione na true (domyślnie) — szablon wymaga powiadomień RPC na events/rpc
  3. Potwierdź, że parametr importu MQTT ID dokładnie odpowiada Client ID urządzenia (np. shellyhtg3-AABBCCDDEEFF)
  4. Użyj klienta MQTT (np. MQTT Explorer) do subskrypcji <device-id>/# i sprawdź, czy czujnik publikuje wiadomości NotifyStatus po wybudzeniu
  5. Sprawdź poziom baterii urządzenia — wyczerpane baterie uniemożliwiają czujnikowi połączenie z Wi-Fi
Odczyt wilgotności wydaje się nieprawidłowy
  1. Szablon TapHome dzieli surową wartość wilgotności przez 100 (np. rh: 55.3 staje się 0.553 w TapHome). To oczekiwane zachowanie — TapHome wewnętrznie używa zakresu 0–1
  2. Czujnik ma konfigurowalny offset wilgotności (Humidity.SetConfig → offset) — sprawdź, czy nie jest ustawiony na nieprawidłową wartość
  3. Zakres operacyjny wilgotności czujnika to 30–70% RH. Odczyty poza tym zakresem mogą być mniej dokładne
Ostrzeżenia offline mimo działającego czujnika
  1. Wykrywanie offline porównuje zapisany znacznik czasu z bieżącym czasem. Jeśli zegar TapHome Core jest znacząco przesunięty, mogą pojawiać się fałszywe ostrzeżenia
  2. Na zasilaniu bateryjnym czujnik raportuje tylko po przekroczeniu progów lub co 2 godziny bezwarunkowo — przerwy do 2 godzin między raportami są normalne
  3. Jeśli czujnik znajduje się w miejscu z niestabilnym Wi-Fi, może pominąć okna raportowania. Sprawdź siłę sygnału Wi-Fi w lokalizacji czujnika

Jak zainstalować w TapHome

Wymagania wstępne

  • Urządzenie Shelly połączone z Wi-Fi (jeśli jeszcze nie, zobacz przewodnik po połączeniu HTTP)
  • Broker MQTT działający w sieci lokalnej (np. Mosquitto, Home Assistant lub wbudowany broker TapHome)
  • TapHome CCU w tej samej sieci co broker

Na urządzeniach Gen1 włączenie MQTT wyłącza Shelly Cloud. Oba nie mogą działać jednocześnie. Na urządzeniach Gen2/Plus to ograniczenie nie obowiązuje.

Krok 1 — Włącz MQTT na urządzeniu Shelly

Urządzenia Gen1 (Shelly 1, 1PM, 2.5, EM, 3EM, Plug S, RGBW2, Dimmer, TRV…)

  1. Otwórz interfejs webowy Shelly: http://<device-ip>/
  2. Przejdź do Internet & Security → Advanced — MQTT
  3. Włącz MQTT
  4. Ustaw MQTT Server: <broker-ip>:<port> (np. 192.168.1.10:1883)
  5. Opcjonalnie ustaw MQTT User i MQTT Password, jeśli broker wymaga uwierzytelniania
  6. Kliknij Save — urządzenie zrestartuje się i połączy z brokerem

Urządzenia Gen2 / Plus (Shelly Plus 1, Plus 1PM, Plus 2PM, Plus Plug S, Plus H&T, Pro 3EM…)

  1. Otwórz interfejs webowy Shelly: http://<device-ip>/
  2. Przejdź do Settings → MQTT
  3. Włącz MQTT
  4. Ustaw Server: <broker-ip>:<port> (np. 192.168.1.10:1883)
  5. Client ID jest wstępnie wypełnione identyfikatorem urządzenia (np. shellyplus1pm-AABBCCDDEE) — pozostaw bez zmian, chyba że masz konkretny powód do zmiany
  6. Kliknij Save i zrestartuj urządzenie

Aby sprawdzić, czy MQTT działa, użyj klienta MQTT (np. MQTT Explorer) i zasubskrybuj shellies/# (Gen1) lub <device-id>/# (Gen2). Powinieneś zobaczyć komunikaty o stanie z urządzenia.

Krok 2 — Znajdź Device ID / MQTT Client ID

Niektóre szablony wymagają parametru Device ID lub MQTT Client ID. Jest to unikalny identyfikator używany w topikach MQTT.

  • Gen1: znajduje się na etykiecie jako adres MAC (np. AABBCCDDEE). Device ID = shelly<model>-<mac>, np. shelly1pm-AABBCCDDEE
  • Gen2/Plus: znajduje się w interfejsie webowym Shelly w sekcji Settings → Device Info → Device ID lub na etykiecie urządzenia

Krok 3 — Konfiguracja w TapHome

  1. W TapHome dodaj nowy moduł Packet Parser (MQTT)
  2. IP Address: wprowadź adres IP brokera MQTT (np. 192.168.1.10)
  3. Port: 1883 (domyślny; użyj 8883 dla TLS)
  4. Device ID / MQTT Client ID: wprowadź wartość z kroku 2 (jeśli wymagane przez szablon)
  5. Zaimportuj szablon — TapHome automatycznie zasubskrybuje topiki urządzenia

Dostępne urządzenia

Shelly H&T Gen3 MQTT Moduł
Atrybuty serwisowe
BateriaProcentowy poziom naładowania baterii — ostrzeżenie o niskim poziomie poniżej 30%
Zmienne niestandardowe

Shelly H&T Gen3 MQTT

Odczyt (moduł)
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
Nasłuchiwanie
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
Atrybuty serwisowe
Battery [%]
BatteryPercentage
Czujnik temperatury i wilgotności Czujnik temperatury Tylko do odczytu

Temperatura otoczenia (°C) i wilgotność względna ze zdarzeń NotifyStatus — wilgotność konwertowana na zakres 0–1 dla TapHome

json Jednostka: °C / %RH json_path

Czujnik temperatury i wilgotności

Nasłuchiwanie
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
Połączenie: Packet Parser → MQTT
Możliwe ulepszenia (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.

Źródła