sam/obsidian-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2dfb72767903f23c2698689a6a3d49f555e6fd8e
obsidian-vault/300 areas/310 Home Assistant/Tuya Local Integration Notes.md

5.9 KiB
Raw Blame History

created, modified, type, status, tags, aliases
created modified type status tags aliases
2026-05-26 2026-10-02 area active
homeassistant
tuya-local
networking
hardware
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 → 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/
  • 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.
Reference in New Issue View Git Blame Copy Permalink