Adding Tuya Smart Switches to Home Assistant: Three Paths and What Breaks

Tuya is a company that provides a cloud platform, Wi-Fi firmware, and ZigBee profiles for smart devices. The type of Tuya technology a device uses determines how it can be integrated into Home Assistant and the potential challenges users may face. There are three main paths to integrate Tuya smart switches into Home Assistant.

Path 1 involves using the official Tuya cloud integration, which connects to the Tuya cloud servers rather than the device itself. This method works with most Tuya devices, including those without local access, and remains functional even without internet connectivity. However, state changes may take several seconds to minutes to appear, and if the internet is down, automations will stop working despite the switch being within range.

Physical presses are usually reported quickly, while state changes triggered from Home Assistant take longer. Free developer accounts also have a limited device count.

Path 2 entails utilizing local Tuya, a custom component that communicates with the device directly over LAN using TCP port 6668. This approach reduces latency to tens of milliseconds and allows Home Assistant to function without internet access. To set up local Tuya, users need the device ID, local IP, and local key. The local key can be acquired from the Tuya IoT developer console or extracted from an Android app backup.

However, newer firmware on the 3.5 protocol may reject local connections, and some devices may not respond on 6668. Devices functioning well locally may stop working after a firmware update, making Local Tuya a trial-and-error experience for consistent local control. Users should consider blocking the device from the internet after pairing for better reliability.

Path 3 involves reflashing the firmware of certain devices built on ESP8266 or ESP32, such as plugs and low-cost devices. This method provides MQTT control, local functionality, and eliminates cloud dependencies. However, it is not recommended for mains wall switches due to safety concerns, as the enclosure is not designed for repeated access, certification is lost, and RF calibration cannot be redone.

Tuya ZigBee devices cannot be reflashed either. If local control is essential, purchasing a device designed for it is advisable. Tuya ZigBee switches pairing with a generic coordinator using Zigbee2MQTT or ZHA expose the standard On/Off cluster, supporting basic on/off functions and multi-gang switches. However, Tuya manufacturer-specific clusters, such as scene events, button presses, backlight settings, and energy monitoring, may not integrate seamlessly with ZHA or Z2M.

Users can write automations targeting raw cluster commands for enhanced functionality. It is crucial to target switch entities rather than device entities to avoid potential issues with firmware updates breaking existing automations. Overall, purchasing a device that aligns with the existing network topology is recommended over attempting to make a Tuya device fit the desired network setup.