--- title: "Shelly H\u0026T Gen3" description: "Shelly H\u0026T Gen3 a batteria collegato a TapHome via MQTT (events/rpc): temperatura, umidità relativa, livello batteria e avviso offline." url: "https://taphome.com/it/compatibility/shelly-ht-gen3-mqtt/" language: it lastmod: 2026-10-08 generator: hugo ai: topics: ["mqtt","sensor","wifi","battery-powered","temperature-humidity"] questions: ["Come integrare Shelly H\u0026T Gen3 con TapHome tramite MQTT?","Cosa misura il template Shelly H\u0026T Gen3 in TapHome?","Come rileva TapHome se un Shelly H\u0026T Gen3 è offline?","Perché il mio Shelly H\u0026T Gen3 non rileva temperatura e umidità?","Shelly H\u0026T Gen3 riporta il livello batteria in TapHome?","Qual è la frequenza di segnalazione dello Shelly H\u0026T Gen3 a batteria?"] --- # Shelly H&T Gen3 Comunicazione: Packet Parser → MQTT - [Pagina prodotto Shelly H&T Gen3](https://www.shelly.com/en/products/shop/shelly-h-t-gen-3) > Indirizzo di rete > > Con il broker MQTT integrato in TapHome, inserisci `127.0.0.1` come indirizzo del broker in TapHome. Nel dispositivo inserisci l’indirizzo IP del TapHome Core e assegna al Core una prenotazione IP nel router. > > [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/) ## Guida all'integrazione 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-`, dove `` è 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:///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 `/#` e gli script listener analizzano gli eventi JSON-RPC `NotifyStatus` dal topic `events/rpc`. > [!TIP] > 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%. > [!WARNING] > 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 `/#` 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 (2,4 GHz), ad es. tramite l'app Shelly o l'access point del dispositivo stesso - Broker MQTT attivo sulla rete locale (es. Mosquitto, Home Assistant o il broker integrato di TapHome) - TapHome CCU sulla stessa rete del broker > [!WARNING] > 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:///` 2. Vai su **Internet & Security** → **Advanced — MQTT** 3. Abilita **MQTT** 4. Imposta **MQTT Server**: `:` (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:///` 2. Vai su **Settings** → **MQTT** 3. Abilita **MQTT** 4. Imposta **Server**: `:` (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 Con il broker integrato di TapHome, `` è l'indirizzo IP del TapHome Core. Assegna al Core una prenotazione IP nel router, altrimenti il dispositivo perde il broker quando il router cambia l'indirizzo → [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/). > [!TIP] > Per verificare che MQTT funzioni, usa un client MQTT (es. MQTT Explorer) e sottoscrivi `shellies/#` (Gen1) o `/#` (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-`, 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:** `127.0.0.1` per il broker integrato di TapHome (l'unità di controllo si connette a sé stessa, l'indirizzo non cambia mai); per un broker esterno il suo indirizzo IP (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 1 Questi dispositivi compaiono in TapHome dopo l'importazione. Shelly H&T Gen3 MQTT Modulo Attributi di servizio | | | |----------|-----------------------------------------------------------------------------| | Batteria | Percentuale di carica della batteria — avviso batteria scarica sotto il 30% | Variabili personalizzate Lettura (modulo) ```taphome 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 ```taphome 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 \[%] ```taphome 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 Listener ```taphome 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 • Hostname: `shellyhtg3-{MAC}.local` 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. ## Parametri di importazione Inserisci questi valori quando importi l'XML. | Richiesto nell'app | Predefinito | |--------------------------|---------------------------| | Mqtt Broker Indirizzo IP | `192.168.0.1` | | Mqtt Broker port | `1883` | | MQTT ID | `shellyhtg3-123456789012` | ## Fonti - Shelly Gen2+/Gen3 RPC API Reference [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/) 2026-03-27 - Shelly Gen2+ System (Sys) Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Sys/) 2026-03-27 - Shelly Gen2+ WiFi Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/WiFi/) 2026-03-27 - Shelly Gen2+ MQTT Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Mqtt/) 2026-03-29 - Home Assistant Shelly Integration [www.home-assistant.io](https://www.home-assistant.io/integrations/shelly/) 2026-03-27 - Shelly H&T Gen3 Device API (Temperature, Humidity, DevicePower) [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/Devices/Gen3/ShellyHTG3/) 2026-03-30 - Shelly H&T Gen3 Knowledge Base [kb.shelly.cloud](https://kb.shelly.cloud/knowledge-base/shelly-h-t-gen3) 2026-03-30 ## Documentazione correlata - [MQTT Integration](https://taphome.com/it/compatibility/mqtt-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/it/docs/integration/packet-parser/) - [Funzioni Packet parser](https://taphome.com/it/docs/script/packet-parser/) - [Funzioni di parsing](https://taphome.com/it/docs/script/parsing-functions/) - [Broker MQTT](https://taphome.com/it/docs/integration/packet-parser/mqtt-broker/) - [Script listener](https://taphome.com/it/docs/script/listener-scripts/)