--- title: "Shelly BLU TRV" description: "Shelly BLU TRV radiator valve in TapHome over HTTP via the Shelly BLU Gateway Gen3, several TRVs per gateway: setpoint, valve position, 2x AA battery." url: "https://taphome.com/en/compatibility/shelly-blu-trv/" language: en lastmod: 2026-04-15 generator: hugo ai: topics: ["http","thermostat","ble","gateway","battery-powered","heating"] questions: ["How to integrate Shelly BLU TRV with TapHome?","How does TapHome communicate with the Shelly BLU TRV through the Gateway Gen3?","How many Shelly BLU TRVs can be paired with one BLU Gateway Gen3?","How to find the Shelly BLU TRV component ID on the gateway?","When does the Shelly BLU TRV need to be calibrated?","Why does the Shelly BLU TRV report a low-battery warning in TapHome?"] --- # Shelly BLU TRV Communication: Packet Parser → HTTP - [Shelly BLU TRV Product Page](https://www.shelly.com/products/shelly-blu-trv-single-pack) - [Shelly BLU Gateway Gen3 Product Page](https://www.shelly.com/products/shelly-blu-gateway-gen3) > Network address > > TapHome reaches this device at the address entered on import. Give the device a fixed address — an IP reservation in the router, or its mDNS name if it supports one — otherwise the integration stops working when the router changes the address. > > [Network Preparation](https://taphome.com/en/docs/setup/network-preparation/) ## Integration guide The Shelly BLU TRV (model SBTR-001AEU) is a battery-powered thermostatic radiator valve with Bluetooth LE 5 and Zigbee 802.15.4 connectivity. It does not speak Wi-Fi or HTTP directly — TapHome reaches the TRV by talking HTTP to a **Shelly BLU Gateway Gen3**, which proxies JSON-RPC calls from the `BluTrv` namespace to the paired TRV over BLE. A single Shelly BLU Gateway Gen3 can host **multiple BLU TRVs** as component peripherals (Shelly sells single-, two- and three-packs with one gateway). Each TRV is identified by its component ID on the gateway (typically 200, 201, 202). The TapHome template is imported once per TRV with the same gateway IP and a different component ID. ## What you need - **Shelly BLU TRV** (SBTR-001AEU) — the valve head, includes 2× AA 1.5 V batteries and a mounting adapter for M28 × 1.5 threads - **Shelly BLU Gateway Gen3** (SBGT-3B-001) — USB-A powered Wi-Fi gateway that bridges BLE peripherals to HTTP RPC; also sold in starter kits with the TRV - **Power** — the TRV runs on 2× AA 1.5 V (up to 2 years typical battery life); the gateway plugs into any USB-A port (phone charger, router, powered hub) - **Network** — LAN / Wi-Fi connectivity for the gateway; the TRV itself does not join the Wi-Fi network - **Valve thread** — direct mount on M30 × 1.5 valves, or use the supplied adapter for Danfoss RA/RAV/RAVL, Caleffi, Giacomini, and M28 × 1.5 threads ## Pairing the TRV with the gateway Pair each TRV to the gateway **before** importing the template in TapHome — the component ID is only assigned after pairing succeeds. 1. Plug the Shelly BLU Gateway Gen3 into a USB-A port and wait for it to join the local network 2. Press the **Pairing button** on the gateway — the LED indicates pairing mode is active for 30 seconds 3. Within 30 seconds, either remove the battery isolation tab from a brand-new TRV, or single-press the **Reset button** on an already-running TRV 4. The TRV display flashes and shows a confirmation animation once pairing succeeds 5. Add the gateway to the Shelly Smart Control app — the newly paired TRV appears as a child component of the gateway with an assigned component ID Repeat steps 2–4 for each additional TRV. Each pairing produces a new component ID (200, 201, 202…). ## Configuration The TapHome template connects to the **gateway IP** (not the TRV itself) and targets a single TRV by its component ID on the gateway. ### Import parameters | Parameter | Description | How to obtain | Example | |-----------|-------------|---------------|---------| | `IpAddress` | Gateway IP address on the local network | Shelly Smart Control app → Gateway → Settings → Network, or your router's DHCP lease table | `192.168.0.42` | | `ID` | BluTrv component ID of this TRV on the gateway | Gateway web UI (`http://`) → Components list → copy the numeric ID assigned to this TRV | `200` | Each TRV requires its own template import. For three TRVs paired to the same gateway, import the template three times with the same `IpAddress` and `ID` values of `200`, `201`, and `202` (IDs are visible in the gateway web UI). > [!WARNING] > HTTP Digest Authentication on the gateway must be **disabled** for TapHome to reach the `/rpc/*` endpoints — the same constraint as for other Shelly Gen2+/Gen3 devices. ## Device capabilities ### Thermostat The template exposes the TRV as a thermostat device. The current temperature is read from `$.status.trv:0.current_C` and the target setpoint from `$.status.trv:0.target_C` (both polled from `BluTrv.GetRemoteStatus`). Writing a new setpoint sends `TRV.SetTarget` through `BluTrv.Call` in the 4–31 °C range supported by the device. A **valve state** service attribute reports the current valve opening as a percentage (`$.status.trv:0.pos`), where 0 % is fully closed and 100 % is fully open. The valve position is controlled by the TRV's internal regulation loop — the template only reads it. ### Battery Battery charge is exposed as a 5-state indicator mapped from the raw percentage (`$.battery`): | State | Battery level | Icon | |-------|---------------|------| | **Critical** | < 25 % | Battery almost empty | | **Low** | 25–50 % | Battery low | | **Normal** | 50–75 % | Battery medium | | **Full** | > 75 % | Battery full | | **Charging** | Charging (not typical for AA cells) | Charging icon | A **Value [%]** service attribute exposes the raw 0–100 % battery reading. Module-level warnings are emitted automatically when the battery drops below 50 % (Low battery) and below 25 % (Critically low battery). ### Diagnostics and actions Module-level signals: - **Received signal strength** — BLE link RSSI (dBm) between the gateway and the TRV (`$.rssi`) - Automatic warning when `$.update.has_update` is set (firmware update available through Shelly Smart Control) - Automatic error emitting the content of `$.trv[0].errors` when the TRV reports a problem Two module-level service actions are available: - **Reboot** — reboots the paired TRV via `Shelly.Reboot` proxied through `BluTrv.Call` - **Calibrate** — runs the stepper motor calibration (`TRV.Calibrate`) through the gateway. Calibration takes up to 10 seconds during which the TRV is unresponsive. Required after first mounting or after changing the valve adapter. ## Troubleshooting ### Gateway not reachable 1. Verify the gateway is powered (USB-A LED lit) and has joined Wi-Fi / LAN (visible in the Shelly Smart Control app) 2. Open `http:///rpc/Shelly.GetDeviceInfo` in a browser — a JSON response confirms the gateway is reachable 3. If the IP has changed after a DHCP lease renewal, try the mDNS hostname `shellyblugwg3-.local` (the gateway advertises `_http._tcp.local.`) 4. Confirm HTTP Digest Auth is disabled on the gateway (`Settings → Authentication`) ### TRV errors reported in TapHome The template surfaces `$.trv[0].errors` as a generic error string. Common flags and fixes: - `not_calibrated` — run the **Calibrate** service action; calibration must complete within 10 seconds without manual valve interference - `not_mounted` — the back cover of the TRV is open or the valve body is not properly seated; reseat the TRV on the valve and close the battery compartment - `battery_low` — replace the 2× AA cells; battery warnings are also emitted automatically when the level drops below 50 % / 25 % - `ext_temp_missing` — an external sensor was configured on the TRV but is no longer reporting; either pair the sensor again or clear the external reading ### Target temperature change is not applied 1. Check the valve state service attribute — if it is at 0 % with a target set above current temperature, the valve may need recalibration 2. Verify that a manual override (via the rotating ring, Shelly app, or `TRV.SetPosition` from another client) is not active — writing a target via the TapHome thermostat re-enables automatic regulation, but any local ring rotation on the TRV immediately takes priority 3. Confirm BLE link quality — RSSI below −85 dBm often causes 1–3 s additional latency and occasional dropped commands; consider placing the gateway closer to the TRV (indoor range ≤ 10 m) ### Firmware update warning The template emits a firmware update warning when `$.update.has_update` is `true`. Firmware updates for the BLU TRV must be performed through the **Shelly Smart Control** app — they are not exposed over the local RPC. > [!TIP] > BLE round-trip latency between the gateway and the TRV is typically 1–3 seconds. The template polls at 3000 ms, which is already close to the practical minimum — lowering this further increases BLE collisions without improving responsiveness. ## How to install in TapHome ### Prerequisites - Shelly device installed and powered on - Local Wi-Fi network (2.4 GHz) - TapHome CCU on the same network ### Step 1 — Connect Shelly to Wi-Fi **Option A — Shelly app (recommended):** 1. Download the [Shelly app](https://www.shelly.com/en/support/shelly-app) (iOS / Android) 2. Tap **+** → **Add Device** and follow the Bluetooth pairing wizard 3. Enter your Wi-Fi credentials when prompted **Option B — AP mode (no app):** 1. On first power-up the device creates a hotspot: `ShellyXXX-AABBCCDDEE` 2. Connect your phone/PC to that hotspot 3. Open `http://192.168.33.1` → **Internet & Security** → **Wi-Fi Mode - Client** 4. Enter SSID and password → **Save** > [!NOTE] > Shelly only supports **2.4 GHz** networks. 5 GHz networks will not appear in the scan. ### Step 2 — Find the device address Shelly Gen1 devices support **mDNS** (Zeroconf). You can reach the device using a hostname instead of an IP address: ``` shelly-.local ``` For example: `shelly1pm-AABBCCDDEE.local` (MAC address in uppercase hex, no colons). > [!TIP] > **Recommended: use the TapHome IP Scanner.** Open the TapHome app and use the **IP Scanner** (Settings → Network → Scan). The scanner will discover devices on your network and show both the IP address and the mDNS hostname. Use the **hostname** instead of the IP address for a more reliable connection — it stays the same even if the device's IP changes after a router reboot. **Alternative methods** to find the IP address: - **Shelly app:** Device detail → **Device info** → IP address - **Shelly web UI:** Connect to the device AP before Wi-Fi setup — the IP is shown after saving - **Router DHCP table:** Look for a hostname like `shelly1pm-AABBCCDDEE` ### Step 3 — Configure in TapHome 1. In TapHome, add a new **Packet Parser (HTTP)** module 2. **Address:** enter the mDNS hostname (e.g., `shelly1pm-AABBCCDDEE.local`) or IP address from Step 2 3. **Port:** `80` (default, no change needed) 4. Import the template — TapHome will poll `/status` to read device state > [!NOTE] > HTTP authentication is disabled by default on Shelly devices. If you have enabled login protection, TapHome does not support HTTP Basic Auth at this time — keep auth disabled for TapHome integration. ## Available devices 2 These devices appear in TapHome after import. Shelly BLU TRV Module Service Attributes | | | |--------------------------|-------------------------------------------------------------------------| | Received signal strength | Bluetooth LE link signal strength between the gateway and the TRV (dBm) | Service Actions | | | |-----------|--------------------------------------------------------------------------------------------------------| | Reboot | | | Calibrate | Runs the stepper motor calibration (up to 10 seconds); required after first mounting or adapter change | Custom Variables `ID` (numeric) = ID Component ID of the BLU TRV on the gateway (set during pairing, typically 200+) Open the Shelly BLU Gateway Gen3 web UI → paired devices → copy the component ID assigned to this TRV Read (module) ```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 ``` Service Attributes Received signal strength ```taphome PARSEJSON(Status, "$.rssi") ``` Service Actions 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)); ``` Battery Multi-value Switch Read-only Battery state indicator — Critical (<25%), Low (25-50%), Normal (50-75%), Full (>75%), Charging numeric Unit: % numeric Values / States: Critical · Low · Normal · Full · Charging Read switch state ```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 ``` Service Attributes Value \[%] ```taphome PARSEJSON(Status, "$.battery"); ``` Thermostat Thermostat Read and write Radiator valve thermostat — reads current temperature and writes target setpoint (4-31 °C) through the BLU Gateway Gen3 numeric Unit: °C Service Attributes | | | |------------------|-------------------------------------------------------------| | Valve state \[%] | Current valve opening position (0%=closed, 100%=fully open) | Read temperature ```taphome PARSEJSON(RemoteStatus, "$.status.trv:0.current_C") ``` Read desired temperature ```taphome PARSEJSON(RemoteStatus, "$.status.trv:0.target_C") ``` Write desired temperature ```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 ``` Service Attributes ${device\_variable\_valvestate} \[%] ```taphome PARSEJSON(RemoteStatus, "$.status.trv:0.pos") ``` **Connection:** Packet Parser → HTTP • Hostname: `shellyblugwg3-{MAC}.local` Possible improvements (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. ## Import parameters Enter these values when you import the XML. | Asked in the app | Default | |------------------|---------------| | IP address | `192.168.0.1` | | Id | `200` | ## Sources - 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 ## Related Documentation - [Packet Parser Integration](https://taphome.com/en/compatibility/packet-parser-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/) - [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/) - [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/)