TapHome

Shelly BLU TRV

Packet Parser → HTTP
Inviato da
Ultimo aggiornamento: 04. 2026

Richiede gateway esterno

Shelly BLU Gateway Gen3 — pagina prodotto

Shelly BLU TRV

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
ParametroDescrizioneCome ottenerloEsempio
IpAddressIndirizzo IP del gateway sulla rete localeApp Shelly Smart Control → Gateway → Settings → Network oppure tabella lease DHCP del router192.168.0.42
IDID del componente BluTrv di questa valvola sul gatewayWeb UI del gateway (http://<gateway-ip>) → elenco componenti → copia l’ID numerico assegnato a questo TRV200

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).

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):

StatoLivello batteriaIcona
Critico< 25 %Batteria quasi scarica
Basso25–50 %Batteria bassa
Normale50–75 %Batteria media
Pieno> 75 %Batteria piena
In caricaIn 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://<gateway-ip>/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-<MAC>.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.

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 (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

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<model>-<mac>.local (es. shelly1pm-AABBCCDDEE.local) dalla stessa rete

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

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

Shelly BLU TRV Modulo
Attributi di servizio
Intensità del segnale ricevutoIntensità del segnale Bluetooth LE tra il gateway e il TRV (dBm)
Azioni di servizio
Riavvio
CalibrazioneEsegue la calibrazione del motore passo-passo (fino a 10 secondi); necessaria dopo il primo montaggio o il cambio dell'adattatore
Variabili personalizzate
ID (numeric) = IDID 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

Shelly BLU TRV

Lettura (modulo)
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
PARSEJSON(Status, "$.rssi")
Azioni di servizio
Reboot
VAR response := SENDHTTPREQUEST("rpc/BluTrv.Call?id=" + ID + "&method=\"Shelly.Reboot\"&params={\"id\":0}");
if(response.IsSuccess, return("OK"), return(response.Content));
Calibrate
VAR response := SENDHTTPREQUEST("rpc/BluTrv.Call?id=" + ID + "&method=\"TRV.Calibrate\"&params={\"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

Batteria

Lettura stato interruttore
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 [%]
PARSEJSON(Status, "$.battery");
Termostato Termostato

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)

Termostato

Lettura temperatura
PARSEJSON(RemoteStatus, "$.status.trv:0.current_C")
Lettura temperatura desiderata
PARSEJSON(RemoteStatus, "$.status.trv:0.target_C")
Scrittura temperatura desiderata
VAR response := SENDHTTPREQUEST("rpc/BluTrv.Call?id=" + ID + "&method=\"TRV.SetTarget\"&params={\"id\":0,\"target_C\":" + Se + "}");
IF response.IsSuccess = false
  ADDERROR(response.StatusCode);
END
Attributi di servizio
${device_variable_valvestate} [%]
PARSEJSON(RemoteStatus, "$.status.trv:0.pos")
Connessione: Packet Parser → HTTP
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.

Fonti