--- title: "Shelly BLU TRV" description: "Integrazione valvola termostatica via HTTP tramite Shelly BLU Gateway Gen3 — temperatura target e corrente, posizione valvola, batteria, RSSI." url: "https://taphome.com/it/compatibility/shelly-blu-trv/" language: it lastmod: 2026-04-15 generator: hugo ai: topics: ["http","thermostat","ble","gateway","battery-powered","heating"] questions: ["Come integrare Shelly BLU TRV con TapHome?","Come comunica TapHome con Shelly BLU TRV tramite il Gateway Gen3?","Quanti Shelly BLU TRV si possono accoppiare a un BLU Gateway Gen3?","Come trovare l'ID del componente Shelly BLU TRV sul gateway?","Quando occorre calibrare il Shelly BLU TRV?","Perché Shelly BLU TRV segnala un avviso di batteria scarica in TapHome?"] --- # Shelly BLU TRV Comunicazione: Packet Parser → HTTP - [Pagina prodotto Shelly BLU TRV](https://www.shelly.com/products/shelly-blu-trv-single-pack) - [Pagina prodotto Shelly BLU Gateway Gen3](https://www.shelly.com/products/shelly-blu-gateway-gen3) > Indirizzo di rete > > TapHome raggiunge il dispositivo all'indirizzo inserito durante l'importazione. Assegna al dispositivo un indirizzo fisso — una prenotazione IP nel router, oppure il suo nome mDNS se lo supporta —, altrimenti l'integrazione smette di funzionare quando il router cambia l'indirizzo. > > [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/) ## Guida all'integrazione Il Shelly BLU TRV (modello SBTR-001AEU) è una valvola termostatica per radiatore alimentata a batteria con connettività Bluetooth LE 5 e Zigbee 802.15.4. Non parla direttamente Wi-Fi né HTTP — TapHome raggiunge la valvola via HTTP tramite un **Shelly BLU Gateway Gen3**, che inoltra le chiamate JSON-RPC del namespace `BluTrv` verso la valvola accoppiata via BLE. Un singolo Shelly BLU Gateway Gen3 può gestire **più BLU TRV** come componenti periferici (Shelly vende confezioni singole, doppie e triple con un gateway). Ogni valvola è identificata dal proprio ID componente sul gateway (tipicamente 200, 201, 202). Il template TapHome va importato una volta per ciascuna valvola, con lo stesso IP del gateway e un ID componente diverso. ## Cosa serve - **Shelly BLU TRV** (SBTR-001AEU) — la testa della valvola, include 2× batterie AA 1,5 V e un adattatore di montaggio per filetti M28 × 1,5 - **Shelly BLU Gateway Gen3** (SBGT-3B-001) — gateway Wi-Fi alimentato via USB-A che espone le periferiche BLE come HTTP RPC; disponibile anche in kit starter con la valvola - **Alimentazione** — il TRV funziona con 2× AA 1,5 V (durata tipica fino a 2 anni); il gateway si collega a qualsiasi porta USB-A (caricatore telefono, router, hub alimentato) - **Rete** — connettività LAN/Wi-Fi per il gateway; il TRV stesso non si collega alla rete Wi-Fi - **Filettatura valvola** — montaggio diretto su valvole M30 × 1,5 o utilizzo dell'adattatore in dotazione per Danfoss RA/RAV/RAVL, Caleffi, Giacomini e filetti M28 × 1,5 ## Accoppiamento del TRV con il gateway Accoppia ogni TRV al gateway **prima** di importare il template in TapHome — l'ID componente viene assegnato solo dopo l'accoppiamento riuscito. 1. Collega il Shelly BLU Gateway Gen3 a una porta USB-A e attendi che si connetta alla rete locale 2. Premi il **tasto di accoppiamento** sul gateway — il LED segnala la modalità di accoppiamento attiva per 30 secondi 3. Entro 30 secondi, rimuovi la linguetta di isolamento della batteria da un TRV nuovo di fabbrica, oppure premi brevemente il tasto **Reset** su un TRV già in funzione 4. Il display del TRV lampeggia e mostra un'animazione di conferma al successo dell'accoppiamento 5. Aggiungi il gateway all'app Shelly Smart Control — il TRV appena accoppiato appare come componente figlio del gateway con un ID componente assegnato Ripeti i passi 2–4 per ogni TRV aggiuntivo. Ogni accoppiamento produce un nuovo ID componente (200, 201, 202…). ## Configurazione Il template TapHome si connette all'**IP del gateway** (non al TRV) e punta a una singola valvola tramite il suo ID componente sul gateway. ### Parametri di importazione | Parametro | Descrizione | Come ottenerlo | Esempio | |-----------|-------------|----------------|---------| | `IpAddress` | Indirizzo IP del gateway sulla rete locale | App Shelly Smart Control → Gateway → Settings → Network oppure tabella lease DHCP del router | `192.168.0.42` | | `ID` | ID del componente BluTrv di questa valvola sul gateway | Web UI del gateway (`http://`) → elenco componenti → copia l'ID numerico assegnato a questo TRV | `200` | Ogni TRV richiede un proprio import del template. Per tre TRV accoppiati allo stesso gateway, importa il template tre volte con lo stesso `IpAddress` e i valori di `ID` 200, 201 e 202 (gli ID sono visibili nella web UI del gateway). > [!WARNING] > La HTTP Digest Authentication sul gateway deve essere **disattivata** affinché TapHome possa raggiungere gli endpoint `/rpc/*` — stesso vincolo degli altri dispositivi Shelly Gen2+/Gen3. ## Funzionalità del dispositivo ### Termostato Il template espone la valvola come dispositivo termostato. La temperatura corrente viene letta da `$.status.trv:0.current_C` e il setpoint target da `$.status.trv:0.target_C` (entrambi ottenuti tramite `BluTrv.GetRemoteStatus`). La scrittura di un nuovo setpoint invia `TRV.SetTarget` tramite `BluTrv.Call` nell'intervallo 4–31 °C supportato dal dispositivo. Un service attribute **stato valvola** riporta l'apertura corrente della valvola in percentuale (`$.status.trv:0.pos`), dove 0 % indica completamente chiusa e 100 % completamente aperta. La posizione della valvola è controllata dal loop di regolazione interno del TRV — il template la legge soltanto. ### Batteria Lo stato di carica della batteria è esposto come indicatore a 5 stati, mappato dal valore percentuale grezzo (`$.battery`): | Stato | Livello batteria | Icona | |-------|------------------|-------| | **Critico** | < 25 % | Batteria quasi scarica | | **Basso** | 25–50 % | Batteria bassa | | **Normale** | 50–75 % | Batteria media | | **Pieno** | > 75 % | Batteria piena | | **In carica** | In carica (atipico per celle AA) | Icona di carica | Un service attribute **Valore [%]** espone la lettura grezza 0–100 % della batteria. A livello di modulo vengono generati avvisi automatici quando la batteria scende sotto il 50 % (Batteria bassa) e sotto il 25 % (Batteria criticamente bassa). ### Diagnostica e azioni Segnali a livello di modulo: - **Intensità del segnale ricevuto** — RSSI (dBm) del collegamento BLE tra gateway e TRV (`$.rssi`) - Avviso automatico quando `$.update.has_update` è vero (aggiornamento firmware disponibile tramite Shelly Smart Control) - Errore automatico con il contenuto di `$.trv[0].errors` quando il TRV segnala un problema Sono disponibili due azioni di servizio a livello di modulo: - **Riavvio** — riavvia il TRV accoppiato tramite `Shelly.Reboot` inoltrato attraverso `BluTrv.Call` - **Calibrazione** — avvia la calibrazione del motore passo-passo (`TRV.Calibrate`) tramite il gateway. La calibrazione dura fino a 10 secondi, durante i quali il TRV non risponde. Necessaria dopo il primo montaggio o il cambio dell'adattatore. ## Risoluzione dei problemi ### Gateway non raggiungibile 1. Verifica che il gateway sia alimentato (LED USB-A acceso) e abbia aderito a Wi-Fi/LAN (visibile nell'app Shelly Smart Control) 2. Apri nel browser `http:///rpc/Shelly.GetDeviceInfo` — una risposta JSON conferma la raggiungibilità del gateway 3. Se l'IP è cambiato dopo un rinnovo del lease DHCP, prova il hostname mDNS `shellyblugwg3-.local` (il gateway annuncia `_http._tcp.local.`) 4. Conferma che HTTP Digest Auth sia disattivato sul gateway (`Settings → Authentication`) ### Errori TRV segnalati in TapHome Il template inoltra `$.trv[0].errors` come stringa di errore generica. Flag comuni e rimedi: - `not_calibrated` — esegui l'azione **Calibrazione**; la calibrazione deve completarsi entro 10 secondi senza interferenze manuali sulla valvola - `not_mounted` — il coperchio posteriore del TRV è aperto o il corpo della valvola non è ben posizionato; rimonta il TRV sulla valvola e chiudi il vano batterie - `battery_low` — sostituisci le 2× celle AA; gli avvisi di batteria vengono generati automaticamente anche al di sotto del 50 % / 25 % - `ext_temp_missing` — è stato configurato un sensore esterno sul TRV ma non invia più letture; accoppia nuovamente il sensore o azzera la lettura esterna ### La variazione della temperatura target non viene applicata 1. Controlla il service attribute dello stato della valvola — se è a 0 % con una temperatura target superiore a quella corrente, la valvola potrebbe richiedere una nuova calibrazione 2. Verifica che non sia attivo un override manuale (anello rotante, app Shelly o `TRV.SetPosition` da un altro client) — la scrittura del target dal termostato TapHome riabilita la regolazione automatica, ma qualsiasi rotazione locale dell'anello sul TRV ha la precedenza immediata 3. Conferma la qualità del link BLE — un RSSI inferiore a −85 dBm provoca spesso 1–3 s di latenza aggiuntiva e comandi occasionalmente persi; considera di avvicinare il gateway al TRV (portata interna ≤ 10 m) ### Avviso di aggiornamento firmware Il template emette un avviso di aggiornamento firmware quando `$.update.has_update` è `true`. Gli aggiornamenti firmware del BLU TRV devono essere eseguiti tramite l'app **Shelly Smart Control** — non sono esposti dalla RPC locale. > [!TIP] > La latenza round-trip BLE tra gateway e TRV è tipicamente di 1–3 secondi. Il template effettua polling ogni 3000 ms, già vicino al minimo pratico — ridurlo ulteriormente aumenta le collisioni BLE senza migliorare la reattività. ## Come installare in TapHome ### Prerequisiti - Dispositivo Shelly installato e acceso - Rete Wi-Fi locale (2,4 GHz) - TapHome CCU sulla stessa rete ### Passaggio 1 — Collegare Shelly al Wi-Fi **Opzione A — App Shelly (consigliata):** 1. Scarica l'[app Shelly](https://www.shelly.com/en/support/shelly-app) (iOS / Android) 2. Tocca **+** → **Add Device** e segui la procedura guidata di associazione Bluetooth 3. Inserisci le credenziali Wi-Fi quando richiesto **Opzione B — Modalità AP (senza app):** 1. Al primo avvio il dispositivo crea un hotspot: `ShellyXXX-AABBCCDDEE` 2. Collega il tuo telefono/PC a questo hotspot 3. Apri `http://192.168.33.1` → **Internet & Security** → **Wi-Fi Mode - Client** 4. Inserisci SSID e password → **Save** > [!NOTE] > Shelly supporta solo reti a **2,4 GHz**. Le reti a 5 GHz non appariranno nella scansione. ### Passaggio 2 — Trovare l'indirizzo IP Dopo la connessione al Wi-Fi, trova l'indirizzo IP assegnato tramite uno di questi metodi: - **App Shelly:** Dettaglio dispositivo → **Device info** → Indirizzo IP - **Interfaccia web Shelly:** Connettiti all'AP del dispositivo prima della configurazione Wi-Fi — l'IP viene mostrato dopo il salvataggio - **Tabella DHCP del router:** Cerca un hostname come `shelly1pm-AABBCCDDEE` - **mDNS:** Esegui il ping di `shelly-.local` (es. `shelly1pm-AABBCCDDEE.local`) dalla stessa rete > [!TIP] > Assegna un **IP statico** (prenotazione DHCP) nel tuo router per il dispositivo Shelly per evitare che l'indirizzo cambi dopo un riavvio del router. ### Passaggio 3 — Configurazione in TapHome 1. In TapHome, aggiungi un nuovo modulo **Packet Parser (HTTP)** 2. **IP Address:** inserisci l'IP dal passaggio 2 (es. `192.168.1.50`) 3. **Port:** `80` (predefinito, nessuna modifica necessaria) 4. Importa il template — TapHome interrogherà periodicamente `/status` per leggere lo stato del dispositivo > [!NOTE] > L'autenticazione HTTP è disabilitata per impostazione predefinita sui dispositivi Shelly. Se hai abilitato la protezione con accesso, TapHome attualmente non supporta HTTP Basic Auth — mantieni l'autenticazione disabilitata per l'integrazione con TapHome. ## Dispositivi disponibili 2 Questi dispositivi compaiono in TapHome dopo l'importazione. Shelly BLU TRV Modulo Attributi di servizio | | | |--------------------------------|------------------------------------------------------------------| | Intensità del segnale ricevuto | Intensità del segnale Bluetooth LE tra il gateway e il TRV (dBm) | Azioni di servizio | | | |--------------|-----------------------------------------------------------------------------------------------------------------------------------| | Riavvio | | | Calibrazione | Esegue la calibrazione del motore passo-passo (fino a 10 secondi); necessaria dopo il primo montaggio o il cambio dell'adattatore | Variabili personalizzate `ID` (numeric) = ID ID del componente BLU TRV sul gateway (assegnato durante l'accoppiamento, in genere 200+) Open the Shelly BLU Gateway Gen3 web UI → paired devices → copy the component ID assigned to this TRV Lettura (modulo) ```taphome VAR response := SENDHTTPREQUEST("/rpc/BluTrv.GetStatus?id=" + ID); IF response.IsSuccess Status := response.Content; END response := SENDHTTPREQUEST("/rpc/BluTrv.GetConfig?id=" + ID); IF response.IsSuccess Config := response.Content; END response := SENDHTTPREQUEST("/rpc/BluTrv.GetRemoteStatus?id=" + ID); IF response.IsSuccess RemoteStatus := response.Content; END response := SENDHTTPREQUEST("/rpc/BluTrv.GetRemoteConfig?id=" + ID); IF response.IsSuccess RemoteConfig := response.Content; END if(PARSEJSON(RemoteStatus, "$.trv[0].errors", true), adderror("Error: " + PARSEJSON(RemoteStatus, "$.trv[0].errors"))); if(PARSEJSON(Status, "$.update.has_update", true), addwarning("Firmware update is available")); var battery := PARSEJSON(Status, "$.battery"); if battery < 25 addwarning("Battery charge is criticaly low"); elseif battery < 50 addwarning("Low battery"); end ``` Attributi di servizio Received signal strength ```taphome PARSEJSON(Status, "$.rssi") ``` Azioni di servizio Reboot ```taphome VAR response := SENDHTTPREQUEST("rpc/BluTrv.Call?id=" + ID + "&method=\"Shelly.Reboot\"¶ms={\"id\":0}"); if(response.IsSuccess, return("OK"), return(response.Content)); ``` Calibrate ```taphome VAR response := SENDHTTPREQUEST("rpc/BluTrv.Call?id=" + ID + "&method=\"TRV.Calibrate\"¶ms={\"id\":0}"); if(response.IsSuccess, return("OK"), return(response.Content)); ``` Batteria Interruttore multivalore Solo lettura Indicatore di stato della batteria — Critico (<25%), Basso (25-50%), Normale (50-75%), Pieno (>75%), In carica numeric Unità: % numeric Valori / Stati: Critical · Low · Normal · Full · Charging Lettura stato interruttore ```taphome var battery := PARSEJSON(Status, "$.battery"); if battery > 75 return(3); elseif battery > 50 return(2); elseif battery > 25 return(1); else return(0); end ``` Attributi di servizio Value \[%] ```taphome PARSEJSON(Status, "$.battery"); ``` Termostato Termostato Lettura e scrittura Termostato della valvola termostatica — legge la temperatura corrente e scrive il setpoint target (4-31 °C) tramite il BLU Gateway Gen3 numeric Unità: °C Attributi di servizio | | | |--------------------|----------------------------------------------------------------------------------------| | Stato valvola \[%] | Posizione attuale di apertura della valvola (0% = chiusa, 100% = completamente aperta) | Lettura temperatura ```taphome PARSEJSON(RemoteStatus, "$.status.trv:0.current_C") ``` Lettura temperatura desiderata ```taphome PARSEJSON(RemoteStatus, "$.status.trv:0.target_C") ``` Scrittura temperatura desiderata ```taphome VAR response := SENDHTTPREQUEST("rpc/BluTrv.Call?id=" + ID + "&method=\"TRV.SetTarget\"¶ms={\"id\":0,\"target_C\":" + Se + "}"); IF response.IsSuccess = false ADDERROR(response.StatusCode); END ``` Attributi di servizio ${device\_variable\_valvestate} \[%] ```taphome PARSEJSON(RemoteStatus, "$.status.trv:0.pos") ``` **Connessione:** Packet Parser → HTTP • Hostname: `shellyblugwg3-{MAC}.local` Possibili miglioramenti (14) - Manual valve position — Sets the valve to a fixed opening percentage (0-100%); disables automatic regulation until TRV.SetTarget is written again. Could be added as a service action. - Boost mode — Temporarily opens the valve fully for rapid room warm-up; accepts an optional duration (seconds). Could be exposed as a service action. - Clear boost — Terminates an active boost and restores the normal target temperature. - Temporary override — Temporarily overrides the target for a given duration (seconds); auto-expires back to the scheduled target. - Clear override — Terminates an active override and restores the regular target. - External temperature input — Supplies a temperature reading from an external sensor (e.g. room sensor) to the TRV regulation loop. - TRV flags (floor\_heating, accel, auto\_calibrate, anticlog, silent\_mode, power\_save) — Toggle operating flags that affect regulation behaviour (e.g. floor-heating mode keeps valve from fully closing). - Boost / override state — Object with started\_at and duration when boost or override is active; currently not surfaced as a service attribute. - Error / state flags (not\_calibrated, not\_mounted, battery\_low, ext\_temp\_missing) — Template only forwards $.trv\[0].errors as a generic error string; individual flags are not exposed as discrete sensors. - Local schedule rules (up to 10) — Shelly Cron-formatted daily/weekly rules stored on the TRV. TapHome normally drives scheduling externally via smart rules, so this is not exposed. - Display message — Shows up to 10 characters of scrolling text on the TRV 7-segment display. - Factory reset — Resets configuration to defaults; pairing information is preserved. - System diagnostics — Uptime, RAM and clock information from the paired TRV system status; not surfaced in the template. - Humidity sensor — BLU TRV can ingest humidity from paired BLU H&T peripherals; the template contains an empty ReadHumidityScriptPacketParser so this capability is not implemented. ## Parametri di importazione Inserisci questi valori quando importi l'XML. | Richiesto nell'app | Predefinito | |--------------------|---------------| | Indirizzo IP | `192.168.0.1` | | Id | `200` | ## Fonti - Shelly Gen2+/Gen3 RPC API Reference [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/) 2026-04-15 - Shelly Gen2+ System (Sys) Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Sys/) 2026-04-15 - Shelly Gen2+ WiFi Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/WiFi/) 2026-04-15 - Shelly BLU TRV RPC API (BluTrv / TRV.* methods) [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/docs-ble/Devices/BLU_ZB/trv/) 2026-04-15 - Shelly BLU TRV Product Page [www.shelly.com](https://www.shelly.com/products/shelly-blu-trv-single-pack) 2026-04-15 - Shelly BLU Gateway Gen3 API Reference [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/Devices/Gen3/ShellyBluGwG3/) 2026-04-15 - How to pair BLU TRV with BLU Gateway Gen3 [kb.shelly.cloud](https://kb.shelly.cloud/knowledge-base/how-to-pair-blu-trv-with-blu-gateway-gen3) 2026-04-15 - Home Assistant Shelly Integration (BLU TRV support) [www.home-assistant.io](https://www.home-assistant.io/integrations/shelly/) 2026-04-15 ## Documentazione correlata - [Integrazione Packet Parser](https://taphome.com/it/compatibility/packet-parser-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/)