106 lines
5.9 KiB
Markdown
106 lines
5.9 KiB
Markdown
---
|
||
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 Overhead Light** | `70:89:76:07:83:e1` | `192.168.20.41` (or `.33`) | `bf10d9430854f401e7vw2w` | `!6E$CV@BAJNQ:mj*` | 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 in router settings (`192.168.20.1`).
|
||
4. Log into [Tuya IoT Portal](https://iot.tuya.com/) → **Cloud → API Explorer → Device Management → Get Device Details** using the Device ID to retrieve the **Local Key**.
|
||
5. In HA: **Settings → Devices & Services → Tuya Local → Add Device**, enter IP, Device ID, and 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`
|
||
|
||
### Retrieval Steps
|
||
1. Go to **Cloud → API Explorer → Device Management → Get Device Details** (or *Query Devices*).
|
||
2. Input Device ID and execute.
|
||
3. Copy `"local_key"` into Home Assistant Tuya Local setup form.
|