TapHome

Shelly 2.5

Packet Parser → HTTP
Submitted by
Last updated: 03. 2026
Shelly 2.5

The Shelly 2.5 is a compact dual-channel Wi-Fi relay with built-in power metering on both channels. It fits behind a standard wall switch and can control two independent circuits, each rated up to 10 A (2300 W at 230 V), with a combined maximum of 20 A. The device supports two operating modes — relay (two independent switches) and roller shutter (coordinated motor control) — but the TapHome template implements relay mode only. TapHome communicates with the device over HTTP on the local network — no cloud connection is required.

The template provides two relay switches and two energy meters (one per channel), plus a service action to switch between relay and roller mode.

Configuration

The Shelly 2.5 connects over Wi-Fi. During TapHome template import, enter the device’s IP address (default placeholder 192.168.0.1).

The current operating mode is exposed as a module-level service attribute (“Mode”) and can be changed via the “Mode” service action. Switching between relay and roller mode requires a device reboot to take effect.

Device capabilities

Relay control

The template exposes two independent relay channels. Each relay state is read from its respective /relay/ endpoint (ison field) and controlled via turn=on or turn=off.

  • Channel 1 — reads and controls /relay/0
  • Channel 2 — reads and controls /relay/1

Each relay has three service attributes:

  • Overpower — whether an overpower condition has been detected on the channel
  • Overtemperature — whether the device has exceeded its safe operating temperature
  • Power Meter — measurement validity (OK or Fault)
Power metering

Each channel has a dedicated energy meter that reads two values from its /meter/ endpoint:

  • Real-time power — power reported in watts, converted to kW by the template
  • Total consumption — total reported in watt-minutes, converted to kWh by the template

Each energy meter exposes an “Overpower” service attribute showing the overpower threshold value (in watts, divided by 1000).

The meters are read-only — they update automatically with every poll cycle (15-second interval).

Known issue — channel 1 energy reading is 10x too high. The template divides total by 6000 for channel 1 instead of 60000 (which channel 2 uses correctly). This means the cumulative energy value for channel 1 will be approximately 10 times higher than the actual consumption. This is a bug in the template’s conversion formula.

Additional capabilities

The Shelly 2.5 natively supports full roller shutter control (open/close/stop with 0-100% position after calibration), rolling one-minute power averages per channel, physical switch input states, internal device temperature, WiFi signal strength, and per-channel auto-off timers. The device can also store up to four favorite roller positions. These capabilities can be added in a future template update.

Compared to the Shelly 1PM template, the Shelly 2.5 template does not expose device diagnostics such as hostname, MAC address, uptime, RAM usage, cloud/MQTT status, firmware update availability, or internal temperature. It also lacks the power protection (max power limit) service action and the reboot action.

Troubleshooting

Device not responding
  1. Verify the Shelly is connected to Wi-Fi and has a valid IP address
  2. Try using the mDNS hostname (shellyswitch25-AABBCCDDEE.local) instead of the IP address — the IP may have changed after a DHCP renewal
  3. Open http://{device-ip}/shelly in a browser — if it responds, the device is reachable
  4. Check that TapHome CCU and Shelly are on the same network / VLAN
Power readings show zero
  1. Confirm the load is connected through the Shelly relay (not bypassed)
  2. Check that the relay is turned on — the meter only reads when current flows through the relay
  3. Poll /meter/0 or /meter/1 manually and verify power returns a non-zero value
Channel 1 energy total seems incorrect

The template divides channel 1 total by 6000 instead of the correct 60000 (which channel 2 uses). As a result, the cumulative energy value for channel 1 is 10x higher than actual. There is currently no workaround within the template — the conversion factor is embedded in the polling script.

Gen1 Shelly devices support only 2 concurrent HTTP connections. If TapHome and another system (e.g., Home Assistant) poll the same device simultaneously, communication may become unreliable. The relay endpoints poll every 2.5 seconds and the meter endpoints every 15 seconds.

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

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:

1

shelly<model>-<MAC>.local

For example: shelly1pm-AABBCCDDEE.local (MAC address in uppercase hex, no colons).

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

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

Shelly 2.5 Module
Service Attributes
Mode
Service Actions
Mode

Shelly2.5

Service Attributes
Mode
 VAR response := SENDHTTPREQUEST("/settings");
 IF response.IsSuccess
  VAR content := response.Content;
  VAR responseHeaders := response.Headers;
  RETURN(PARSEJSON(content, "mode"));
 END
Service Actions
Mode
Parameters: Mode
var St := SWITCH(mo, 1, "roller", "relay");
 VAR response := SENDHTTPREQUEST("/settings?mode=" + St);
Electric Meter — Channel 1 Electricity Meter Read-only

Power consumption and energy metering for channel 1 — instantaneous power (kW) and cumulative energy (kWh). Note: energy reading is 10x too high due to a template divisor bug (/6000 instead of /60000)

numeric Unit: W / kWh
Service Attributes
Overpower

Electric Meter — Channel 1

Read total consumption
VAR response := SENDHTTPREQUEST("/meter/0");
 IF response.IsSuccess
  VAR content := response.Content;
 VAR responseHeaders := response.Headers;
 RETURN(PARSEJSON(content, "total")/6000);
 ELSE 
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
Read demand
VAR response := SENDHTTPREQUEST("/meter/0");
 IF response.IsSuccess
  VAR content := response.Content;
 VAR responseHeaders := response.Headers;
 RETURN(PARSEJSON(content, "power")/1000);
 ELSE 
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
Service Attributes
Overpower
 VAR response := SENDHTTPREQUEST("/meter/0");
 IF response.IsSuccess
  VAR content := response.Content;
 RETURN((PARSEJSON(content, "overpower")/1000) + " W");
 END
Electric Meter — Channel 2 Electricity Meter Read-only

Power consumption and energy metering for channel 2 — instantaneous power (kW) and cumulative energy (kWh)

numeric Unit: W / kWh
Service Attributes
Overpower

Electric Meter — Channel 2

Read total consumption
VAR response := SENDHTTPREQUEST("/meter/1");
 IF response.IsSuccess
  VAR content := response.Content;
 VAR responseHeaders := response.Headers;
 RETURN(PARSEJSON(content, "total")/60000);
 ELSE 
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
Read demand
VAR response := SENDHTTPREQUEST("/meter/1");
 IF response.IsSuccess
  VAR content := response.Content;
 VAR responseHeaders := response.Headers;
 RETURN(PARSEJSON(content, "power")/1000);
 ELSE 
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
Service Attributes
Overpower
 VAR response := SENDHTTPREQUEST("/meter/1");
 IF response.IsSuccess
  VAR content := response.Content;
 VAR responseHeaders := response.Headers;
 RETURN((PARSEJSON(content, "overpower")/1000) + " W");
 END
Relay — Channel 1 Switch
boolean
Values / States: ON · OFF

Relay — Channel 1

Read switch state
VAR response := SENDHTTPREQUEST("/relay/0");
 IF response.IsSuccess
  VAR content := response.Content;
  VAR responseHeaders := response.Headers;
  RETURN(PARSEJSON(content, "ison"));
 ELSE
  ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
Write switch state
var turn := Switch(St, 1, "on", "off");
 VAR response := SENDHTTPREQUEST("/relay/0?turn=" + turn);
 IF response.IsSuccess = false
  ADDERROR(response.StatusCode);
 END
Service Attributes
Overpower
 VAR response := SENDHTTPREQUEST("/relay/0");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(IF(PARSEJSON(content, "overpower"),"Yes", "No"));
 END
Overtemperature
 VAR response := SENDHTTPREQUEST("/relay/0");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(IF(PARSEJSON(content, "overtemperature"),"Yes", "No"));
 END
Power Meter
 VAR response := SENDHTTPREQUEST("/relay/0");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(IF(PARSEJSON(content, "is_valid"),"OK","Fault"));
 END
Relay — Channel 2 Switch
boolean
Values / States: ON · OFF

Relay — Channel 2

Read switch state
VAR response := SENDHTTPREQUEST("/relay/1");
 IF response.IsSuccess
  VAR content := response.Content;
  VAR responseHeaders := response.Headers;
  RETURN(PARSEJSON(content, "ison"));
 ELSE
  ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
Write switch state
var turn := Switch(St, 1, "on", "off");
 VAR response := SENDHTTPREQUEST("/relay/1?turn=" + turn);
 IF response.IsSuccess = false
  ADDERROR(response.StatusCode);
 END
Service Attributes
Overpower
 VAR response := SENDHTTPREQUEST("/relay/1");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(IF(PARSEJSON(content, "overpower"),"Yes", "No"));
 END
Overtemperature
 VAR response := SENDHTTPREQUEST("/relay/1");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(IF(PARSEJSON(content, "overtemperature"),"Yes", "No"));
 END
Power Meter
 VAR response := SENDHTTPREQUEST("/relay/1");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(IF(PARSEJSON(content, "is_valid"),"OK","Fault"));
 END
Connection: Packet Parser → HTTP
Possible improvements (9)
  • Roller Shutter Control — Full roller shutter control (open/close/stop/position 0-100%) — the Shelly 2.5's key dual-mode feature. Template only implements relay mode.
  • Roller Position — Current roller position 0-100% (requires calibration). Not available without /roller/ endpoint.
  • Roller Calibration — Initiates travel-time calibration procedure for position control.
  • Rolling Power Averages — 3 rolling one-minute power averages per channel, available in /meter/ response
  • Input States — Physical switch input states (0/1) for both channels, available in /status response
  • Internal Device Temperature — Internal temperature in C available in /status response (not exposed as a device, only as relay SA)
  • Auto-off Timer — Per-channel auto-off timer in seconds, could be added as service action parameter
  • WiFi Signal Strength — WiFi RSSI in dBm, available in /status response
  • Favorite Positions (Roller Mode) — Up to 4 saved roller shutter positions — only relevant if roller mode is implemented

Sources