---
title: "SmartThings Switch/Plug with Power Metering"
description: "SmartThings Switch/Plug with power metering via SmartThings Cloud API. Control on/off and monitor energy consumption from TapHome over HTTPS."
url: "https://taphome.com/en/compatibility/smartthings-switch-plug/"
language: en
lastmod: 2026-03-28
generator: hugo
ai:
  topics: ["http","smart-plug","cloud-api","power-metering","smartthings"]
  questions: ["How to integrate a SmartThings switch or plug with TapHome?","What does the SmartThings Switch/Plug TapHome template measure?","How to generate a SmartThings Personal Access Token for TapHome?","Why does the SmartThings integration stop working after 24 hours?","How to find the SmartThings Device ID for TapHome?","Can I control multiple SmartThings devices from TapHome?"]
---

# SmartThings Switch/Plug with Power Metering

Communication: Packet Parser → HTTP

- [SmartThings Developer Portal](https://developer.smartthings.com/)

## Integration guide

This template integrates any SmartThings-compatible switch or plug with power metering into TapHome. Communication goes through the SmartThings Cloud REST API v1 at `api.smartthings.com` over HTTPS — the template does not communicate with the physical device directly. The device can be ZigBee, Z-Wave, or Matter — as long as it is connected to a SmartThings account and exposes switch, powerMeter, and energyMeter capabilities, the template will work.

The template was contributed by Csongor Varga and demonstrated with a BlitzWolf BW-SHP15 ZigBee plug, but it is not limited to that model.

## Configuration

The template requires two variables configured in TapHome after import:

- **Token** — a SmartThings Personal Access Token (PAT) used for Bearer authentication
- **DeviceId** — the UUID of the target device in the SmartThings platform

### Generating a Personal Access Token

1. Go to [account.smartthings.com/tokens](https://account.smartthings.com/tokens) and sign in with a Samsung account
2. Click **Generate new token** and name it (e.g., "TapHome Integration")
3. Select the **Devices** permission scope — this is required for reading status and sending commands
4. Click **Generate Token** and copy the token immediately — this is the only opportunity to retrieve the value

> [!WARNING]
> Standard Personal Access Tokens (created after December 30, 2024) are valid for **24 hours only**. The token must be regenerated and updated in TapHome before it expires, otherwise the integration will stop working. Legacy tokens created before that date may have longer validity periods.

### Finding the Device ID

1. Log in to [my.smartthings.com](https://my.smartthings.com/)
2. Locate the target device in the device list
3. Copy the **Device ID** from the device details page — it is a UUID string (e.g., `47eff6bf-83c9-4374-a367-b254759b486d`)

### Adding multiple devices

Each SmartThings device requires its own module instance. To add another device, import the template again and configure a new DeviceId. The same Token can be reused across all modules.

## Device capabilities

### Switch control

The template exposes the device as a switch. The state is read from the SmartThings status response (`components.main.switch.switch.value` — `"on"` or `"off"`, mapped to 1/0). Switch commands are sent via `POST /v1/devices/{DeviceId}/commands` with the `switch` capability.

After sending a switch command, the template waits 500 ms and re-reads the device status to prevent state shuffle between the command and the next poll cycle. The switch is polled every 2.5 seconds.

### Power metering

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

- **Real-time power** — `components.main.powerMeter.power.value` reported in watts, converted to kW by the template (÷ 1000)
- **Total consumption** — `components.main.energyMeter.energy.value` reported directly in kWh

The meter is read-only and polled every 15 seconds.

### Additional capabilities

The SmartThings API also exposes power and energy unit strings, device health status, and a refresh capability for forcing an immediate state update. These can be added in a future template update.

## Troubleshooting

### Integration stops working after 24 hours

Standard SmartThings PAT tokens expire after 24 hours. Generate a new token at [account.smartthings.com/tokens](https://account.smartthings.com/tokens) and update the Token variable in the TapHome module. If frequent token renewal is impractical, check whether a legacy token with longer validity is available on the account.

### Device not responding

1. Verify the SmartThings device is online — check its status in the SmartThings app
2. Confirm the DeviceId variable matches the correct device UUID
3. Test the API manually: `GET https://api.smartthings.com/v1/devices/{DeviceId}/status` with the `Authorization: Bearer {Token}` header — it should return a JSON response with the device state
4. Ensure the Token has the correct permission scope (Devices — read and execute)

### Power readings show zero

1. Confirm the device is actually consuming power — turn on a connected load
2. Check that the SmartThings device supports the `powerMeter` and `energyMeter` capabilities — not all switches report power
3. Poll the status API manually and verify `components.main.powerMeter.power.value` returns a non-zero value

> [!NOTE]
> This is a cloud-based integration — it requires an active internet connection on the TapHome CCU. The template communicates with Samsung's servers, not with the physical device on the local network.

## Available devices 2

These devices appear in TapHome after import.

SmartThings Switch/Plug Module

Custom Variables

|                                                            |                                                                                                       |
|------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| `Token` (string) = 0ead2552-e331-4355-b483-81d3898eb5ba    | SmartThings Personal Access Token for API authentication (generate at account.smartthings.com/tokens) |
| `DeviceId` (string) = 47eff6bf-83c9-4374-a367-b254759b486d | SmartThings device UUID — identifies the target switch or plug                                        |

Read (module)

```taphome
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization: Bearer "+Token);
IF response.IsSuccess
 StatusJson := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
```

Electric Meter Electricity Meter Read-only

Power consumption and energy metering — instantaneous power (kW) and cumulative energy (kWh) via SmartThings Cloud API

numeric Unit: kW / kWh JSON

Variable: `DeviceId`

Read total consumption

```taphome
VAR value := PARSEJSON(StatusJson, "components.main.energyMeter.energy.value", 1);
IF(ISNULL(value), NaN, value);
```

Read demand

```taphome
VAR value := PARSEJSON(StatusJson, "components.main.powerMeter.power.value", 1);
IF(ISNULL(value), NaN, value / 1000);
```

Switch Switch Read and write

boolean JSON

Values / States: ON · OFF

Read switch state

```taphome
VAR value := PARSEJSON(StatusJson, "components.main.switch.switch.value", 1);
IF(ISNULL(value), NaN, if(value="on", 1, 0));
```

Write switch state

```taphome
# Set Http request method, body and headers
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", 
"POST", 
"{\"commands\": [ { \"component\": \"main\", \"capability\": \"switch\", \"command\": \""+IF(St=1, "on", "off")+"\", \"arguments\": [] } ] }",
"Authorization: Bearer "+Token);


# Wait a little an read the state again to prevent state shuffle
SLEEP(500);
response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization: Bearer "+Token);
IF response.IsSuccess
 StatusJson := response.Content;
 # ADDINFO("StatusJson refreshed");
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
```

**Connection:** Packet Parser → HTTP

Possible improvements (4)

- Power Unit — Unit string for power reading (W), available in status response
- Energy Unit — Unit string for energy reading (kWh), available in status response
- Health Check — Device health/online status, available via SmartThings Health API
- Refresh — Force refresh device state via SmartThings refresh capability command

## Sources

- TapHome Wiki — SmartThings Integration Guide
  
  [github.com](https://github.com/nygma2004/km/wiki/TapHome-Examples#integrating-smartthings-switch-or-plug-with-power-metering) 2026-03-28
- SmartThings API — Quick Start Guide
  
  [developer.smartthings.com](https://developer.smartthings.com/docs/getting-started/quickstart) 2026-03-28
- SmartThings Authorization and Permissions
  
  [developer.smartthings.com](https://developer.smartthings.com/docs/getting-started/authorization-and-permissions) 2026-03-28
- SmartThings Capabilities Reference (switch, powerMeter, energyMeter)
  
  [github.com](https://github.com/erikwilson/SmartThings-Documentation/blob/master/capabilities-reference.rst) 2026-03-28

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