TapHome

Shelly BLU TRV

Packet Parser → HTTP
Eingereicht von
Zuletzt aktualisiert: 04. 2026

Erfordert externes Gateway

Shelly BLU Gateway Gen3 — Produktseite

Shelly BLU TRV

Der Shelly BLU TRV (Modell SBTR-001AEU) ist ein batteriebetriebenes Thermostatventil für Heizkörper mit Bluetooth LE 5 und Zigbee 802.15.4. Er unterstützt weder Wi-Fi noch HTTP direkt — TapHome erreicht das Ventil per HTTP über ein Shelly BLU Gateway Gen3, das JSON-RPC-Aufrufe aus dem BluTrv-Namespace per BLE an das gekoppelte Ventil weiterleitet.

Ein einzelnes Shelly BLU Gateway Gen3 kann mehrere BLU TRVs als Peripheriekomponenten verwalten (Shelly verkauft Einzel-, Doppel- und Dreierpacks zusammen mit einem Gateway). Jedes Ventil ist über seine Komponenten-ID im Gateway identifiziert (typisch 200, 201, 202). Die TapHome-Vorlage wird einmal pro Ventil importiert — mit derselben Gateway-IP und einer unterschiedlichen Komponenten-ID.

Was Sie benötigen

  • Shelly BLU TRV (SBTR-001AEU) — der Ventilkopf, enthält 2× AA 1,5 V Batterien sowie einen Montageadapter für M28 × 1,5-Gewinde
  • Shelly BLU Gateway Gen3 (SBGT-3B-001) — ein USB-A-versorgtes Wi-Fi-Gateway, das BLE-Peripheriegeräte als HTTP-RPC bereitstellt; auch in Starter-Paketen mit dem TRV erhältlich
  • Stromversorgung — der TRV läuft mit 2× AA 1,5 V (typische Batterielaufzeit bis zu 2 Jahre); das Gateway wird an jede USB-A-Buchse angeschlossen (Handyladegerät, Router, Stromhub)
  • Netzwerk — LAN/Wi-Fi-Anbindung für das Gateway; der TRV selbst verbindet sich nicht mit dem Wi-Fi
  • Ventilgewinde — Direktmontage auf M30 × 1,5-Ventilen oder Verwendung des mitgelieferten Adapters für Danfoss RA/RAV/RAVL, Caleffi, Giacomini und M28 × 1,5

Den TRV mit dem Gateway koppeln

Jeder TRV muss mit dem Gateway vor dem Import der Vorlage in TapHome gekoppelt werden — die Komponenten-ID wird erst nach erfolgreicher Kopplung vergeben.

  1. Stecken Sie das Shelly BLU Gateway Gen3 in eine USB-A-Buchse und warten Sie, bis es sich mit dem lokalen Netzwerk verbunden hat
  2. Drücken Sie die Pairing-Taste am Gateway — die LED zeigt 30 Sekunden lang den aktiven Pairing-Modus an
  3. Entfernen Sie innerhalb von 30 Sekunden entweder die Batterie-Isolierlasche eines brandneuen TRV oder drücken Sie kurz die Reset-Taste an einem bereits laufenden TRV
  4. Das TRV-Display blinkt und zeigt nach erfolgreicher Kopplung eine Bestätigungsanimation
  5. Fügen Sie das Gateway in der Shelly Smart Control App hinzu — der neu gekoppelte TRV erscheint als untergeordnete Komponente des Gateways mit einer zugewiesenen Komponenten-ID

Wiederholen Sie die Schritte 2–4 für jeden weiteren TRV. Jede Kopplung erzeugt eine neue Komponenten-ID (200, 201, 202…).

Konfiguration

Die TapHome-Vorlage verbindet sich mit der Gateway-IP (nicht mit dem TRV selbst) und adressiert einen einzelnen TRV über dessen Komponenten-ID am Gateway.

Import-Parameter
ParameterBeschreibungSo ermittelnBeispiel
IpAddressIP-Adresse des Gateways im lokalen NetzwerkShelly Smart Control App → Gateway → Settings → Network oder DHCP-Lease-Liste im Router192.168.0.42
IDBluTrv-Komponenten-ID dieses TRV am GatewayGateway-Web-UI (http://<gateway-ip>) → Komponentenliste → numerische ID dieses TRV kopieren200

Jeder TRV benötigt seinen eigenen Vorlagenimport. Für drei TRVs an demselben Gateway importieren Sie die Vorlage dreimal mit derselben IpAddress und ID-Werten 200, 201 und 202 (die IDs sind im Gateway-Web-UI sichtbar).

Die HTTP Digest Authentication muss am Gateway deaktiviert sein, damit TapHome die /rpc/*-Endpunkte erreichen kann — dieselbe Einschränkung wie bei anderen Shelly Gen2+/Gen3-Geräten.

Gerätefunktionen

Thermostat

Die Vorlage stellt das Ventil als Thermostatgerät bereit. Die Ist-Temperatur wird aus $.status.trv:0.current_C gelesen und der Sollwert aus $.status.trv:0.target_C (beide werden über BluTrv.GetRemoteStatus abgefragt). Das Schreiben eines neuen Sollwerts sendet TRV.SetTarget über BluTrv.Call im vom Gerät unterstützten Bereich 4–31 °C.

Ein Service-Attribut Ventilstellung meldet die aktuelle Ventilöffnung in Prozent ($.status.trv:0.pos), wobei 0 % geschlossen und 100 % vollständig geöffnet bedeutet. Die Ventilposition wird vom internen Regelkreis des TRV gesteuert — die Vorlage liest sie nur aus.

Batterie

Der Batterieladezustand wird als 5-stufiger Indikator auf Basis des rohen Prozentwerts ($.battery) bereitgestellt:

ZustandBatteriestandSymbol
Kritisch< 25 %Batterie fast leer
Niedrig25–50 %Batterie niedrig
Normal50–75 %Batterie mittel
Voll> 75 %Batterie voll
LadenLädt (bei AA-Zellen untypisch)Ladesymbol

Ein Service-Attribut Wert [%] liefert den rohen Batteriewert von 0–100 %. Auf Modulebene werden automatisch Warnungen ausgegeben, wenn der Ladestand unter 50 % (Niedrige Batterie) bzw. unter 25 % (Kritisch niedriger Batteriestand) fällt.

Diagnose und Aktionen

Signale auf Modulebene:

  • Empfangssignalstärke — RSSI der BLE-Verbindung (dBm) zwischen Gateway und TRV ($.rssi)
  • Automatische Warnung bei $.update.has_update (Firmware-Update über Shelly Smart Control verfügbar)
  • Automatischer Fehler mit dem Inhalt von $.trv[0].errors, wenn der TRV ein Problem meldet

Zwei Service-Aktionen auf Modulebene sind verfügbar:

  • Neustart — startet den gekoppelten TRV per Shelly.Reboot über BluTrv.Call neu
  • Kalibrieren — startet die Schrittmotor-Kalibrierung (TRV.Calibrate) über das Gateway. Die Kalibrierung dauert bis zu 10 Sekunden, in denen der TRV nicht reagiert. Erforderlich nach Erstmontage oder Adapterwechsel.

Fehlerbehebung

Gateway nicht erreichbar
  1. Prüfen Sie, ob das Gateway mit Strom versorgt ist (USB-A-LED leuchtet) und sich mit Wi-Fi/LAN verbunden hat (in der Shelly Smart Control App sichtbar)
  2. Öffnen Sie http://<gateway-ip>/rpc/Shelly.GetDeviceInfo im Browser — eine JSON-Antwort bestätigt die Erreichbarkeit des Gateways
  3. Wenn sich die IP nach einer DHCP-Lease-Erneuerung geändert hat, versuchen Sie den mDNS-Hostname shellyblugwg3-<MAC>.local (das Gateway kündigt _http._tcp.local. an)
  4. Stellen Sie sicher, dass HTTP Digest Auth am Gateway deaktiviert ist (Settings → Authentication)
TRV-Fehler in TapHome

Die Vorlage leitet $.trv[0].errors als generischen Fehlerstring weiter. Häufige Flags und Abhilfen:

  • not_calibrated — führen Sie die Aktion Kalibrieren aus; die Kalibrierung muss innerhalb von 10 Sekunden ohne manuellen Eingriff in das Ventil abgeschlossen sein
  • not_mounted — die Rückwand des TRV ist geöffnet oder der Ventilkörper sitzt nicht korrekt; TRV erneut auf das Ventil aufsetzen und Batteriefach schließen
  • battery_low — die 2× AA-Zellen ersetzen; Batteriewarnungen werden außerdem automatisch bei Unterschreiten von 50 % / 25 % ausgegeben
  • ext_temp_missing — ein externer Sensor wurde im TRV konfiguriert, meldet aber keine Werte mehr; entweder den Sensor erneut koppeln oder den externen Messwert zurücksetzen
Zieltemperatur wird nicht übernommen
  1. Prüfen Sie das Service-Attribut der Ventilstellung — bei 0 % mit einer über der Ist-Temperatur liegenden Zieltemperatur benötigt das Ventil möglicherweise eine erneute Kalibrierung
  2. Stellen Sie sicher, dass kein manueller Override aktiv ist (über den Drehring, die Shelly-App oder TRV.SetPosition aus einem anderen Client) — ein Sollwertbefehl aus dem TapHome-Thermostat reaktiviert die automatische Regelung, jede lokale Ringdrehung am TRV hat jedoch sofort Vorrang
  3. Bestätigen Sie die BLE-Linkqualität — RSSI unter −85 dBm verursacht häufig 1–3 s zusätzliche Latenz und gelegentlich verworfene Befehle; platzieren Sie das Gateway gegebenenfalls näher am TRV (Innenraumreichweite ≤ 10 m)
Firmware-Update-Warnung

Die Vorlage gibt eine Firmware-Update-Warnung aus, wenn $.update.has_update auf true steht. Firmware-Updates für den BLU TRV müssen über die Shelly Smart Control-App erfolgen — sie werden nicht über die lokale RPC bereitgestellt.

Die BLE-Round-Trip-Latenz zwischen Gateway und TRV beträgt typischerweise 1–3 Sekunden. Die Vorlage pollt alle 3000 ms, was bereits nahe am praktischen Minimum liegt — eine weitere Verkleinerung erhöht BLE-Kollisionen ohne die Reaktionsfähigkeit zu verbessern.

Installation in TapHome

Voraussetzungen

  • Shelly-Gerät installiert und eingeschaltet
  • Lokales Wi-Fi-Netzwerk (2,4 GHz)
  • TapHome CCU im selben Netzwerk

Schritt 1 — Shelly mit Wi-Fi verbinden

Option A — Shelly-App (empfohlen):

  1. Laden Sie die Shelly-App herunter (iOS / Android)
  2. Tippen Sie auf + → Add Device und folgen Sie dem Bluetooth-Kopplungsassistenten
  3. Geben Sie Ihre Wi-Fi-Zugangsdaten ein, wenn Sie dazu aufgefordert werden

Option B — AP-Modus (ohne App):

  1. Beim ersten Einschalten erstellt das Gerät einen Hotspot: ShellyXXX-AABBCCDDEE
  2. Verbinden Sie Ihr Telefon/PC mit diesem Hotspot
  3. Öffnen Sie http://192.168.33.1 → Internet & Security → Wi-Fi Mode - Client
  4. Geben Sie SSID und Passwort ein → Save

Shelly unterstützt nur 2,4 GHz-Netzwerke. 5 GHz-Netzwerke werden beim Scannen nicht angezeigt.

Schritt 2 — IP-Adresse ermitteln

Nach der Verbindung mit Wi-Fi ermitteln Sie die zugewiesene IP-Adresse auf eine der folgenden Arten:

  • Shelly-App: Gerätedetail → Device info → IP-Adresse
  • Shelly-Weboberfläche: Verbinden Sie sich mit dem Geräte-AP vor der Wi-Fi-Einrichtung — die IP wird nach dem Speichern angezeigt
  • Router-DHCP-Tabelle: Suchen Sie nach einem Hostnamen wie shelly1pm-AABBCCDDEE
  • mDNS: Pingen Sie shelly<model>-<mac>.local (z. B. shelly1pm-AABBCCDDEE.local) aus dem selben Netzwerk

Weisen Sie dem Shelly-Gerät eine statische IP (DHCP-Reservierung) in Ihrem Router zu, damit sich die Adresse nach einem Router-Neustart nicht ändert.

Schritt 3 — Konfiguration in TapHome

  1. Fügen Sie in TapHome ein neues Modul Packet Parser (HTTP) hinzu
  2. IP Address: Geben Sie die IP aus Schritt 2 ein (z. B. 192.168.1.50)
  3. Port: 80 (Standard, keine Änderung erforderlich)
  4. Importieren Sie die Vorlage — TapHome fragt regelmäßig /status ab, um den Gerätestatus zu lesen

Die HTTP-Authentifizierung ist auf Shelly-Geräten standardmäßig deaktiviert. Wenn Sie den Anmeldeschutz aktiviert haben, unterstützt TapHome derzeit kein HTTP Basic Auth — lassen Sie die Authentifizierung für die TapHome-Integration deaktiviert.

Verfügbare Geräte

Shelly BLU TRV Modul
Serviceattribute
EmpfangssignalstärkeBluetooth-LE-Signalstärke zwischen Gateway und TRV (dBm)
Serviceaktionen
Neustart
KalibrierenStartet die Schrittmotor-Kalibrierung (bis zu 10 Sekunden); erforderlich nach Erstmontage oder Adapterwechsel
Benutzerdefinierte Variablen
ID (numeric) = IDKomponenten-ID des BLU TRV im Gateway (beim Pairing zugewiesen, typisch 200+)
Open the Shelly BLU Gateway Gen3 web UI → paired devices → copy the component ID assigned to this TRV

Shelly BLU TRV

Lesen (Modul)
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
Serviceattribute
Received signal strength
PARSEJSON(Status, "$.rssi")
Serviceaktionen
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));
Batterie Mehrwertschalter Nur lesen

Batteriestandsanzeige — Kritisch (<25 %), Niedrig (25–50 %), Normal (50–75 %), Voll (>75 %), Laden

numeric Einheit: % numeric
Werte / Zustände: Critical · Low · Normal · Full · Charging

Batterie

Schaltzustand lesen
var battery := PARSEJSON(Status, "$.battery");
if battery > 75
    return(3);
elseif battery > 50
    return(2);
elseif battery > 25
    return(1);
else
    return(0);
end
Serviceattribute
Value [%]
PARSEJSON(Status, "$.battery");
Thermostat Thermostat

Heizkörperventil-Thermostat — liest die aktuelle Temperatur und schreibt den Zielwert (4–31 °C) über das BLU Gateway Gen3

numeric Einheit: °C
Serviceattribute
Ventilstellung [%]Aktuelle Ventilöffnungsstellung (0 % = geschlossen, 100 % = vollständig geöffnet)

Thermostat

Temperatur lesen
PARSEJSON(RemoteStatus, "$.status.trv:0.current_C")
Solltemperatur lesen
PARSEJSON(RemoteStatus, "$.status.trv:0.target_C")
Solltemperatur schreiben
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
Serviceattribute
${device_variable_valvestate} [%]
PARSEJSON(RemoteStatus, "$.status.trv:0.pos")
Verbindung: Packet Parser → HTTP
Mögliche Verbesserungen (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.

Quellen