From 7c5151f4bdb4be0d69a162ca9acc0cf4ba7ad416 Mon Sep 17 00:00:00 2001 From: Sam Rolfe Date: Mon, 5 Oct 2026 08:06:28 +1100 Subject: [PATCH] sam-4screen-desktop 2026-10-5:8:6:28 --- .obsidian/workspace.json | 14 +- .../Tuya Local Integration Notes.md | 142 +++++++++++------- 2 files changed, 94 insertions(+), 62 deletions(-) diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index 589bad8..5424db1 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -11,10 +11,14 @@ "id": "26813e16e829b798", "type": "leaf", "state": { - "type": "empty", - "state": {}, + "type": "markdown", + "state": { + "file": "300 areas/310 Home Assistant/Tuya Local Integration Notes.md", + "mode": "source", + "source": false + }, "icon": "lucide-file", - "title": "New tab" + "title": "Tuya Local Integration Notes" } } ] @@ -178,7 +182,9 @@ "type": "leaf", "state": { "type": "file-properties", - "state": {}, + "state": { + "file": "300 areas/310 Home Assistant/Tuya Local Integration Notes.md" + }, "icon": "lucide-info", "title": "File properties" } diff --git a/300 areas/310 Home Assistant/Tuya Local Integration Notes.md b/300 areas/310 Home Assistant/Tuya Local Integration Notes.md index 430ddda..68bb579 100644 --- a/300 areas/310 Home Assistant/Tuya Local Integration Notes.md +++ b/300 areas/310 Home Assistant/Tuya Local Integration Notes.md @@ -1,84 +1,110 @@ --- created: 2026-05-26 -modified: 2026-07-02 +modified: 2026-10-02 type: area status: active -tags: [] -aliases: [] +tags: + - homeassistant + - tuya-local + - networking + - hardware +aliases: + - Tuya Local Notes --- # Tuya Local Integration Notes -## Tuya IoT Portal +## 1. General Operating & Setup Principles -- URL: https://iot.tuya.com/ -- Select the correct **Data Center** (Central Europe for EU users) -- Access ID: `pwwd8y3v7kj8j9c3nnj5` +### Core Network Requirement: Static DHCP Reservations +Tuya Wi-Fi smart bulbs do **not** publish mDNS/NetBIOS hostnames to local DNS. Home Assistant communicates directly via local IPv4 addresses on TCP port 6668. +- **The Problem**: Whenever a router reboots or a light is turned off at the wall switch, DHCP assigns a new IP address. Home Assistant loses connection and enters a "Reloading / Initializing / Failed" loop. +- **The Solution**: Every Tuya device **must have a permanent static DHCP reservation** set in the main router (`192.168.20.1`). -## Renavigating After a Device is Re-Paired / Reset +### The Single-TCP-Connection Constraint +Tuya bulb microcontrollers only accept **one active TCP connection at a time** on port 6668. +- If the Tuya/Smart Life/Genio app is open on a mobile phone, it holds the TCP connection open. +- Any attempt by Home Assistant to connect or submit configuration will fail with `Connection refused` (Errno 111) or `Unable to connect`. +- **Rule**: Always force-close / swipe away phone apps before configuring devices in Home Assistant. -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: +### Tuya Local (`make-all/tuya-local`) vs Legacy `LocalTuya` +- **`tuya-local` (by make-all)**: Modern component that supports Tuya protocol 3.4/3.5, auto-discovers devices using linked Tuya Cloud accounts, and maps device features via standard device profiles. +- **`xZetsubou/hass-localtuya`**: Legacy fork. Requires manual datapoint (DP) mapping for every entity. -### 1. Check IoT Core Subscription +--- -If API calls return `code: 28841002` / `"IoT Core service subscription has expired."`: +## 2. Household Tuya Device Inventory & Router Reservations -- 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) +Configure these static assignments under **Router Settings (`192.168.20.1`) → DHCP Server → Static IP / Reservation**: -### 2. Get the New Device ID (Virtual ID) from the Phone App +| Device Name | MAC Address | Reserved IP | Device ID | Local Key | Protocol | +| :--- | :--- | :--- | :--- | :--- | :--- | +| **Dining Room Main Light** | `1c:69:20:a2:ce:38` | `192.168.20.10` | `bfc8b2ffde5654946dhint` | `R_>@>f&u@=?$=Jd^` | 3.3 / Auto | +| **Harry Genio Lamp (Par38)** | `c4:82:e1:0f:b6:ed` | `192.168.20.33` | `bf40c2aa1ded88033bpvm1` | `}Hl^^S=8}MgMVVj<` | Auto | +| **Sam's Bed Lamp** | `70:89:76:07:8b:bc` | `192.168.20.29` | — | — | Auto | +| **Finn Main Light** | `f8:17:2d:c5:76:79` | `192.168.20.17` | `bfc8b022833308dd52ivfh` | `xZN4VwUPbAS?8~q` | Auto | +| **Secondary Lamp / Plug** | `88:13:bf:69:a3:fc` | `192.168.20.14` | — | — | Auto | -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. Light Bulb Status Diagnostics & Recovery -### 3. Query Device Details via API Explorer +### Bulb Physical Light Modes +- **Rapid Flashing Red / Color (2x per sec)**: Device was reset (e.g., wall switch toggled 3-5 times). It is in **EZ-Mode pairing** and disconnected from Wi-Fi. +- **Slow / Regular Blinking White (1x every 2 sec)**: Device is in **AP-Mode pairing**. It is broadcasting an internal setup hotspot (`SmartLife-XXXX`) and offline from local Wi-Fi. +- **Solid White / Color**: Device is connected to Wi-Fi. +- **Pingable but Port 6668 Refuses Connection**: Device micro-controller socket lockup, or phone app is holding the connection, or HA is currently connected. -- 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 +### HA "Reloading / Initializing / Failed" Loop +If Home Assistant cycles endlessly on a device entry: +1. Verify the bulb's MAC address is actually on its assigned IP (run `ip neigh show` on local host). +2. If the IP shifted, update the IP in HA or reboot the router to enforce the DHCP reservation. +3. Power cycle the wall switch **once** (off 10s, on 1s) to clear frozen TCP sockets on the bulb. -### 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 +## 4. Dining Room Light Hardware Status & Replacement Plan -## Fields Required for Home Assistant (Tuya Local) +### Diagnostic Status +- **Current MAC**: `1c:69:20:a2:ce:38` +- **Status**: The physical bulb micro-controller was repeatedly power-cycled and exhibited rapid red/white reset states. While ICMP ping responds at `192.168.20.10`, local TCP port 6668 connection remains blocked/refused. +- **Conclusion**: If power cycling off/on once and assigning static IP `192.168.20.10` fails to restore local control, the bulb's internal Wi-Fi/MCU board has suffered hardware failure or persistent firmware corruption. -| 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 | +### Replacement Specifications +If replacing the Dining Room globe: +- **Bulb Form Factor**: Standard A60 (or ST64/Globe depending on fitting) Smart LED Bulb. +- **Base Fitting**: E27 (Edison Screw) or B22 (Bayonet) – check physical socket. +- **Channels / Color**: 5-Channel RGB+CCT (RGBCW: Red, Green, Blue + Warm White + Cool White). +- **Protocol**: Wi-Fi 2.4 GHz (Tuya / Smart Life ecosystem compatible). +- **Wattage**: 9W – 12W (800 – 1100 Lumens). -## Steps to Add a Device +### Recommended Replacement Models +1. **Mirabella Genio Smart Wi-Fi LED Bulb A60 RGB+CCT** (Available locally at Kmart / Target / Bunnings). +2. **Grid Connect / Arlec Smart RGB+CCT Wi-Fi LED Bulb** (Bunnings). +3. **Standard Tuya / Smart Life Wi-Fi 5-Channel RGB+CCT A60 E27/B22 Bulb** (AliExpress / Amazon). -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 +### New Bulb Onboarding Procedure +1. Install new globe and power on. +2. Open **Tuya Smart** app on phone (connected to 2.4 GHz Wi-Fi) and add the bulb. +3. Reserve the new bulb's MAC address to `192.168.20.10` in router settings (`192.168.20.1`). +4. Log into [Tuya IoT Portal](https://iot.tuya.com/) → **Cloud → API Explorer → Query Device Details** using the new Device ID (from app settings) to retrieve the **new Local Key**. +5. In HA: **Settings → Devices & Services → Tuya Local → Add Device**, enter IP `192.168.20.10`, new Device ID, and new Local Key. -## 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 +## 5. Tuya Cloud API & Key Retrieval Reference + +### Tuya IoT Portal Settings +- **URL**: [https://iot.tuya.com/](https://iot.tuya.com/) +- **Data Center**: Central Europe Data Center (`https://openapi.tuyaeu.com`) +- **Access ID**: `pwwd8y3v7kj8j9c3nnj5` + +### Subscription Renewal (If Error 28841002 occurs) +1. Go to **iot.tuya.com → Cloud → IoT Core**. +2. Click **Extend Trial Period**. +3. Description 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."* + +### Retrieval Steps +1. Get **Virtual Device ID** from Tuya phone app: **Device Settings → Device Information → Device ID**. +2. Go to **Cloud → API Explorer → Device Control → Query Device Details**. +3. Input Device ID and execute. +4. Copy `"local_key"` into Home Assistant Tuya Local setup form.