--- created: 2026-05-26 modified: 2026-10-02 type: area status: active tags: - homeassistant - tuya-local - networking - hardware aliases: - Tuya Local Notes --- # Tuya Local Integration Notes ## 1. General Operating & Setup Principles ### 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`). ### 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. ### 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. --- ## 2. Household Tuya Device Inventory & Router Reservations Configure these static assignments under **Router Settings (`192.168.20.1`) → DHCP Server → Static IP / Reservation**: | 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 | --- ## 3. Light Bulb Status Diagnostics & Recovery ### 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. ### 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. Dining Room Light Hardware Status & Replacement Plan ### 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. ### 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). ### 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). ### 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. --- ## 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.