---
title: "Shelly Dimmer 2"
description: "Brightness control, on/off switching and energy metering via local HTTP. TapHome integration template for Shelly Dimmer 2 Wi-Fi dimmer."
url: "https://taphome.com/en/compatibility/shelly-dimmer2/"
language: en
lastmod: 2026-03-29
generator: hugo
ai:
  topics: ["http","lighting","wifi","dimmer","power-metering"]
  questions: ["How to integrate Shelly Dimmer 2 with TapHome?","What does the Shelly Dimmer 2 TapHome template control?","How to connect Shelly Dimmer 2 via HTTP to TapHome?","How to set a smooth brightness transition on Shelly Dimmer 2?","What is the minimum load for Shelly Dimmer 2?","Why does Shelly Dimmer 2 flicker at low brightness?"]
---

# Shelly Dimmer 2

Communication: Packet Parser → HTTP

- [Shelly Dimmer 2 Product Page](https://kb.shelly.cloud/knowledge-base/shelly-dimmer-2)

> 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 Dimmer 2 is a compact Wi-Fi dimmer module designed for behind-the-wall installation. It supports dimmable LEDs (10--200 W), incandescent/halogen bulbs (10--220 W) and ferromagnetic transformers. TapHome communicates with the device over HTTP on the local network -- no cloud connection is required.

The template provides brightness control with configurable fade transitions, an on/off light switch and an energy meter that reads real-time power consumption and cumulative energy usage.

## Configuration

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

The device supports four wiring configurations:

- **With neutral wire** -- standard installation using N, L, SW1, SW2, O terminals
- **Without neutral, minimum 10 W load** -- no neutral connection, requires at least 10 W load
- **Without neutral + Shelly Bypass** -- for loads under 10 W, the Shelly Bypass accessory is required
- **Switched neutral** -- alternative wiring with switched neutral line

> [!WARNING]
> Below the minimum load (10 W with neutral, 20 W without neutral), the dimmer may flicker or fail to turn on. Use the Shelly Bypass accessory for low-wattage loads without a neutral wire.

## Device capabilities

### Brightness control

The template exposes a dimmer device that reads the brightness level from `/light/0` (`brightness` field, 0--100 %) and sets it via `/light/0?brightness={value}`. The value is normalized internally -- the API uses 0--100 % while TapHome works with a 0.0--1.0 range.

A **Transition** service attribute shows the current fade duration in milliseconds. The **Transition** service action allows setting a smooth brightness fade (0--5000 ms) for individual commands via `/light/0?transition={ms}`.

### Light switch

The light on/off state is controlled independently from the brightness level. The template reads `ison` from `/light/0` and writes via `/light/0?turn=on` or `/light/0?turn=off`. The device has the `lighting` capability flag -- it appears as a light switch in TapHome, not a generic relay.

### Power metering

The built-in energy meter reads two values from the `/status` response:

- **Real-time power** -- `meters[0].power` reported in watts, converted to kW by the template
- **Total consumption** -- `meters[0].total` reported in watt-minutes, converted to kWh by the template

The meter is read-only and updates automatically with every poll cycle (15-second interval).

### Service diagnostics

The module-level **WiFi** service attribute reads the connected SSID from `/settings`.

### Additional capabilities

The Shelly Dimmer 2 also exposes internal temperature, overtemperature protection status, meter validity, WiFi signal strength and two physical switch inputs (SW1, SW2) in its `/status` response. A night mode with scheduled brightness limiting and incremental step-based dimming are available via the API. An auto-off timer can be set per command. These capabilities can be added in a future template update.

## 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 (`shellydimmer2-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

### Flickering or unstable dimming

1. Confirm the connected load meets the minimum wattage requirement (10 W with neutral, 20 W without)
2. Check that the load type is supported -- not all LED drivers are compatible with trailing-edge dimmers
3. Adjust the `min_brightness` setting via `/settings/light/0` if the light flickers at low levels
4. Increase the `warm_up` time (0--1000 ms) in `/settings/light/0` for loads that need a ramp-up period

### Power readings show zero

1. Confirm the load is connected through the dimmer (not bypassed)
2. Check that the light is turned on -- the meter only reads when current flows
3. Poll `/status` manually and verify `meters[0].power` returns a non-zero value

> [!WARNING]
> 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. Use a poll interval of 10--30 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](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<model>-<MAC>.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 3

These devices appear in TapHome after import.

Shelly Dimmer2 Module

Service Attributes

|      |
|------|
| WiFi |

Service Attributes

Wifi

```taphome
 VAR response := SENDHTTPREQUEST("/settings");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(PARSEJSON(content, "$.wifi_sta.ssid"));
  End
```

Brightness Dimmer Read and write

Dimmer level 0-100% with configurable fade transition (0-5000 ms)

numeric Unit: %

Service Attributes

|            |
|------------|
| Transition |

Service Actions

|            |
|------------|
| Transition |

Read level

```taphome
VAR response := SENDHTTPREQUEST("/light/0");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(PARSEJSON(content, "brightness")/100);
 ELSE
  ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
```

Write level

```taphome
VAR response := SENDHTTPREQUEST("/light/0?brightness=" + Le*100);
IF response.IsSuccess = false
 ADDERROR(response.StatusCode);
 END
```

Service Attributes

Transition

```taphome
 VAR response := SENDHTTPREQUEST("/light/0");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(PARSEJSON(content, "transition") + " ms");
 END
```

Service Actions

Transition

Parameters: Transition time \[ms] (0–5000 G)

```taphome
 VAR response := SENDHTTPREQUEST("/light/0?transition=" + G);
```

Electric Meter Electricity Meter Read-only

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

numeric Unit: W / kWh

Read total consumption

```taphome
VAR response := SENDHTTPREQUEST("/status");
 IF response.IsSuccess
  VAR content := response.Content;
 VAR responseHeaders := response.Headers;
 RETURN(PARSEJSON(content, "$..meters..total")/60000);
 ELSE 
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
```

Read demand

```taphome
VAR response := SENDHTTPREQUEST("/status");
 IF response.IsSuccess
  VAR content := response.Content;
 VAR responseHeaders := response.Headers;
 RETURN(PARSEJSON(content, "$..meters..power")/1000);
 ELSE 
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
```

Light Switch Read and write

boolean

Values / States: ON · OFF

Read switch state

```taphome
VAR response := SENDHTTPREQUEST("/light/0");
 IF response.IsSuccess
  VAR content := response.Content;
  RETURN(PARSEJSON(content, "ison"));
 ELSE
  ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
  RETURN(NaN);
 END
```

Write switch state

```taphome
var Ru := Switch(St, 1, "on", "off");
 VAR response := SENDHTTPREQUEST("/light/0?turn=" + Ru);
 IF response.IsSuccess = false
  ADDERROR(response.StatusCode);
 END
```

**Connection:** Packet Parser → HTTP • Hostname: `shellydimmer2-{MAC}.local`

Possible improvements (9)

- Brightness (via /status) — Current brightness also available in /status → lights\[0].brightness; template uses /light/0 instead
- Meter Validity — Measurement validity flag, available in /status response
- Internal Temperature — Internal device temperature in °C, available in /status response
- Overtemperature Protection — Overtemperature protection triggered flag, threshold 95°C
- Night Mode — Night mode with start/end time and max brightness — configurable via /settings/night\_mode
- Switch Inputs (SW1, SW2) — Two physical switch inputs available in /status → inputs\[0].input and inputs\[1].input
- WiFi Signal Strength — WiFi RSSI in dBm, available in /status response
- Auto-off Timer — Auto-off timer in seconds, could be added as service action parameter
- Incremental Dimming — Step-based dimming (dim up/down/stop with configurable step size 1-100)

## Import parameters

Enter these values when you import the XML.

| Asked in the app | Default       |
|------------------|---------------|
| IP address       | `192.168.0.1` |

## Sources

- Shelly Gen1 API Reference
  
  [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen1/) 2026-03-12
- Home Assistant Shelly Integration
  
  [www.home-assistant.io](https://www.home-assistant.io/integrations/shelly/) 2026-03-12
- Shelly Dimmer 2 Knowledge Base
  
  [kb.shelly.cloud](https://kb.shelly.cloud/knowledge-base/shelly-dimmer-2) 2026-03-29
- Shelly Dimmer 2 API Reference (Gen1)
  
  [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen1/#shelly-dimmer-dimmer2) 2026-03-29

## 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/)