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

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

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.