---
created: 2026-05-26
modified: 2026-07-02
type: note
tags: []
aliases: []
---
# Tuya Local Integration Notes

## Tuya IoT Portal

- URL: https://iot.tuya.com/
- Select the correct **Data Center** (Central Europe for EU users)
- Access ID: `pwwd8y3v7kj8j9c3nnj5`

## Renavigating After a Device is Re-Paired / Reset

When a Tuya device is reset and re-paired to WiFi, it gets a **new Device ID** and **new Local Key**. The old credentials are invalid. Steps to recover:

### 1. Check IoT Core Subscription

If API calls return `code: 28841002` / `"IoT Core service subscription has expired."`:

- Go to **iot.tuya.com** → **Cloud** → **IoT Core** (under Cloud section)
- You'll likely see an option to **extend the service trial period**
- There's a form asking for: project background, estimated lead time, relevant info
- Sample blurb: *"Personal home automation project using Home Assistant to control smart lighting. Need temporary API access to retrieve local device keys for re-paired bulbs."*
- Estimated lead time: 1–3 days
- Approval is usually quick (sometimes instant, sometimes minutes)

### 2. Get the New Device ID (Virtual ID) from the Phone App

The new Device ID is **not visible in the IoT portal's device management**. You need to get it from the app:

- Open the **Tuya Smart / Smart Life / Genio** app on your phone
- Go to the device details/settings page for the device
- Look for **Device Information** → **Device ID** (or **Virtual ID**) — this is the ID to use in the API
- Copy this ID — it looks like: `bfd8b357cc21529eb8zpbo`

### 3. Query Device Details via API Explorer

- Go to **Cloud → API Explorer** (not IoT Core → API Explorer)
- Method: `Query Device Details` under Device Management
- Enter the new Device ID from the app
- Execute
- In the response, note the `"local_key"` field

### 4. Add to Home Assistant (Tuya Local)

- In HA: **Settings → Devices & Services → Tuya Local → Add Device**
- Choose **Manually provide device connection information**
- Enter:
  - **IP Address** — from router's connected device list
  - **Device ID** — from app
  - **Local Key** — from API Explorer response
  - **Protocol** — Try 3.3 or 3.4 first, or try 3.1 if those fail
- Select device type (e.g., Simple RGBCW lightbulb for RGB+CCT bulbs)
- Submit

## Fields Required for Home Assistant (Tuya Local)

| Field | Source |
|-------|--------|
| **Device ID (Virtual ID)** | Phone app → Device Info page |
| **Local Key** | IoT Portal → Cloud → API Explorer → Query Device Details |
| **IP Address** | Router's connected device list |
| **Protocol Version** | Usually auto-detected; try 3.3, 3.4, or 3.1 |

## Steps to Add a Device

1. In HA: Settings → Devices & Services → Tuya Local → Add Device
2. Choose **Manually provide device connection information**
3. Enter IP, Device ID, Local Key, Protocol
4. Select device type (e.g., Simple RGBCW lightbulb for RGB+CCT bulbs)
5. Submit

## Notes

- Close Tuya/Smart Life app on phone before adding devices
- Genio bulbs may need the Genio app for initial WiFi setup
- Some newer bulbs use Protocol 3.5 (auto-detected by Tuya Local)
- If port 6668 is closed on the device, it may be cloud-only
- The Local Key **rotates** every time a device is re-paired — always get a fresh one via API Explorer