TapHome

Shelly H&T Gen3

Packet Parser → MQTT
Inviato da
Ultimo aggiornamento: 03. 2026
Shelly H&T Gen3

Lo Shelly H&T Gen3 è un sensore di temperatura e umidità Wi-Fi alimentato a batteria (4x AA) con un grande display e-paper. TapHome comunica con il dispositivo tramite MQTT utilizzando le notifiche RPC Gen2+ sul topic events/rpc. Questo è il protocollo consigliato per i dispositivi Shelly Gen3 a batteria, poiché il sensore è in modalità sleep la maggior parte del tempo e pubblica dati solo al risveglio.

Il template crea un singolo dispositivo Sensore di temperatura e umidità e un attributo di servizio Batteria a livello di modulo. Un meccanismo di rilevamento offline monitora l’ultimo timestamp ricevuto e genera avvisi o errori quando il dispositivo non ha comunicato per un periodo prolungato.

Configurazione

MQTT Client ID

Ogni Shelly H&T Gen3 ha un MQTT Client ID univoco nel formato shellyhtg3-<MAC12>, dove <MAC12> è l’indirizzo MAC completo a 12 caratteri in esadecimale maiuscolo (es. shellyhtg3-AABBCCDDEEFF). Questo ID serve anche come prefisso predefinito dei topic MQTT.

Il Client ID si trova:

  • Sull’etichetta del dispositivo (indirizzo MAC)
  • Nell’interfaccia web Shelly: Settings → MQTT → Client ID
  • Tramite API: GET http://<device-ip>/rpc/Mqtt.GetConfig → campo client_id
Configurazione del template

Dopo l’importazione del template in TapHome:

  1. Apri il modulo Shelly H&T Gen3 MQTT
  2. Imposta l’MQTT Broker IP sull’indirizzo del broker MQTT
  3. Imposta la Port (predefinita 1883)
  4. Imposta il parametro di importazione MQTT ID sul Client ID del dispositivo (es. shellyhtg3-AABBCCDDEEFF)

Il modulo si iscrive a <device-id>/# e gli script listener analizzano gli eventi JSON-RPC NotifyStatus dal topic events/rpc.

Assicurati che MQTT sia abilitato sullo Shelly H&T Gen3 e che rpc_ntf (notifiche RPC) sia impostato su true (predefinito). Il template si basa sulle notifiche events/rpc, non sui singoli topic di stato.

Comportamento di misurazione e segnalazione

Lo Shelly H&T Gen3 opera diversamente in base alla fonte di alimentazione:

  • Modalità batteria — risveglio ogni 1 minuto per la misurazione. Segnala tramite MQTT se la temperatura cambia di più di 0,5 °C o l’umidità di più del 5%. Una segnalazione incondizionata viene inviata ogni 2 ore se non sono state attivate segnalazioni basate su soglia.
  • Alimentazione USB — risveglio ogni 5 minuti per misurazione, aggiornamento display e segnalazione ad ogni ciclo.

Il display e-paper si aggiorna quando la temperatura cambia di più di 0,2 °C o l’umidità di più del 3%.

Il dispositivo è alimentato a batteria e non è permanentemente connesso al broker MQTT. Aspettati intervalli tra le letture, specialmente in modalità batteria. Se la posizione del sensore ha un segnale Wi-Fi debole, frequenti tentativi di riconnessione possono ridurre la durata della batteria.

Capacità del dispositivo

Temperatura e umidità

Il dispositivo sensore legge temperatura e umidità dagli eventi NotifyStatus sul topic events/rpc:

  • Temperatura — temperatura ambiente in Celsius, letta da params['temperature:0'].tC
  • Umidità — umidità relativa in percentuale, letta da params['humidity:0'].rh (lo script listener divide il valore per 100 per convertirlo nell’intervallo 0–1 atteso da TapHome)

Entrambi i valori sono in sola lettura e si aggiornano ogni volta che il sensore si sveglia e pubblica dati.

La soglia di segnalazione della temperatura è configurabile sul dispositivo (predefinita 0,5 °C, intervallo 0,5–5,0 °C). La soglia di umidità è predefinita al 5% (intervallo 1–20%). Queste soglie possono essere regolate tramite l’interfaccia web Shelly o API per bilanciare la frequenza di segnalazione rispetto alla durata della batteria.

Monitoraggio batteria

Il modulo espone un attributo di servizio Batteria [%] che legge la percentuale di carica della batteria da params['devicepower:0'].battery.percent nell’evento NotifyStatus. Un avviso di batteria scarica si attiva quando il livello scende sotto il 30%.

Il livello della batteria si aggiorna con ogni segnalazione del sensore. Con batterie 4x AA, la durata prevista è di circa 1 anno in condizioni normali.

Rilevamento offline

Il template monitora la connettività del dispositivo tramite un meccanismo basato su timestamp. Lo script listener del modulo memorizza il timestamp Unix da ogni evento NotifyStatus nella variabile personalizzata timestamp. Lo script di lettura confronta quindi il timestamp memorizzato con l’ora corrente:

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

Questo è particolarmente utile per dispositivi a batteria che possono smettere di comunicare a causa di batterie scariche o perdita della connessione Wi-Fi.

Capacità aggiuntive

Lo Shelly H&T Gen3 pubblica anche lo stato online/offline tramite il topic MQTT Last Will and Testament (LWT), la tensione della batteria in Volt e lo stato dell’alimentazione esterna (se USB Type-C è collegato). I topic di stato individuali dei componenti (status/temperature:0, status/humidity:0, status/devicepower:0) sono disponibili quando status_ntf è abilitato, e la temperatura è disponibile anche in Fahrenheit. Il dispositivo dispone di un display e-paper con unità di temperatura e formato dell’orologio configurabili. Queste capacità possono essere aggiunte in un futuro aggiornamento del template.

Risoluzione dei problemi

Il sensore non segnala dati
  1. Verifica che lo Shelly H&T Gen3 sia connesso al Wi-Fi e che MQTT sia abilitato nelle impostazioni del dispositivo (Settings → MQTT → Enable)
  2. Controlla che rpc_ntf sia impostato su true (predefinito) — il template richiede notifiche RPC su events/rpc
  3. Conferma che il parametro di importazione MQTT ID corrisponda esattamente al Client ID del dispositivo (es. shellyhtg3-AABBCCDDEEFF)
  4. Usa un client MQTT (es. MQTT Explorer) per iscriverti a <device-id>/# e verifica che il sensore pubblichi messaggi NotifyStatus al risveglio
  5. Controlla il livello della batteria del dispositivo — batterie scariche impediscono al sensore di connettersi al Wi-Fi
La lettura dell’umidità sembra errata
  1. Il template TapHome divide il valore grezzo dell’umidità per 100 (es. rh: 55.3 diventa 0.553 in TapHome). Questo è il comportamento previsto — TapHome utilizza internamente un intervallo 0–1
  2. Il sensore ha un offset di umidità configurabile (Humidity.SetConfig → offset) — verifica che non sia impostato su un valore errato
  3. L’intervallo operativo di umidità del sensore è 30–70% RH. Le letture al di fuori di questo intervallo possono essere meno precise
Avvisi offline nonostante il sensore funzionante
  1. Il rilevamento offline confronta il timestamp memorizzato con l’ora corrente. Se l’orologio del TapHome Core è significativamente sfasato, possono apparire falsi avvisi
  2. Con alimentazione a batteria, il sensore segnala solo al superamento delle soglie o ogni 2 ore incondizionatamente — intervalli fino a 2 ore tra le segnalazioni sono normali
  3. Se il sensore si trova in una posizione con Wi-Fi intermittente, può mancare le finestre di segnalazione. Verifica la potenza del segnale Wi-Fi nella posizione del sensore

Come installare in TapHome

Prerequisiti

  • Dispositivo Shelly connesso al Wi-Fi (vedi la guida alla connessione HTTP se non ancora fatto)
  • Broker MQTT attivo sulla rete locale (es. Mosquitto, Home Assistant o il broker integrato di TapHome)
  • TapHome CCU sulla stessa rete del broker

Sui dispositivi Gen1, l’attivazione di MQTT disabilita Shelly Cloud. Entrambi non possono funzionare contemporaneamente. Sui dispositivi Gen2/Plus questa limitazione non si applica.

Passaggio 1 — Abilitare MQTT sul dispositivo Shelly

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

  1. Apri l’interfaccia web Shelly: http://<device-ip>/
  2. Vai su Internet & Security → Advanced — MQTT
  3. Abilita MQTT
  4. Imposta MQTT Server: <broker-ip>:<port> (es. 192.168.1.10:1883)
  5. Opzionalmente imposta MQTT User e MQTT Password se il broker richiede l’autenticazione
  6. Clicca su Save — il dispositivo si riavvierà e si connetterà al broker

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

  1. Apri l’interfaccia web Shelly: http://<device-ip>/
  2. Vai su Settings → MQTT
  3. Abilita MQTT
  4. Imposta Server: <broker-ip>:<port> (es. 192.168.1.10:1883)
  5. Il Client ID è precompilato con l’ID del dispositivo (es. shellyplus1pm-AABBCCDDEE) — lascialo così a meno che tu non abbia un motivo specifico per cambiarlo
  6. Clicca su Save e riavvia il dispositivo

Per verificare che MQTT funzioni, usa un client MQTT (es. MQTT Explorer) e sottoscrivi shellies/# (Gen1) o <device-id>/# (Gen2). Dovresti vedere i messaggi di stato dal dispositivo.

Passaggio 2 — Trovare il Device ID / MQTT Client ID

Alcuni template richiedono un parametro Device ID o MQTT Client ID. Questo è l’identificatore univoco utilizzato nei topic MQTT.

  • Gen1: si trova sull’etichetta come indirizzo MAC (es. AABBCCDDEE). Device ID = shelly<model>-<mac>, es. shelly1pm-AABBCCDDEE
  • Gen2/Plus: si trova nell’interfaccia web Shelly sotto Settings → Device Info → Device ID, oppure sull’etichetta del dispositivo

Passaggio 3 — Configurazione in TapHome

  1. In TapHome, aggiungi un nuovo modulo Packet Parser (MQTT)
  2. IP Address: inserisci l’IP del broker MQTT (es. 192.168.1.10)
  3. Port: 1883 (predefinito; usa 8883 per TLS)
  4. Device ID / MQTT Client ID: inserisci il valore dal passaggio 2 (se richiesto dal template)
  5. Importa il template — TapHome si sottoscriverà automaticamente ai topic del dispositivo

Dispositivi disponibili

Shelly H&T Gen3 MQTT Modulo
Attributi di servizio
BatteriaPercentuale di carica della batteria — avviso batteria scarica sotto il 30%
Variabili personalizzate

Shelly H&T Gen3 MQTT

Lettura (modulo)
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
Attributi di servizio
Battery [%]
BatteryPercentage
Sensore di temperatura e umidità Sensore di temperatura Solo lettura

Temperatura ambiente (°C) e umidità relativa da eventi NotifyStatus — umidità convertita nell'intervallo 0–1 per TapHome

json Unità: °C / %RH json_path

Sensore di temperatura e umidità

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
Connessione: Packet Parser → MQTT
Possibili miglioramenti (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.

Fonti