Home Assistant has several ways to control Tuya-based and Smart Life devices. Some keep control on your local network. Others still depend on the Tuya cloud. This guide compares the options and shows what each one needs. For the HACS install steps used by LocalTuya and Tuya Local, see our HACS guide.
The short answer
- To add Smart Life devices with the official integration, use the Tuya integration. It is cloud-based.
- To control Tuya devices locally, use LocalTuya or Tuya Local, both installed through HACS.
- To control ESP-based devices flashed with Tasmota, use the Tasmota integration with an MQTT broker.
Add Smart Life devices with the official Tuya integration
The official Tuya integration is part of Home Assistant core. It is cloud-based, so it needs an internet connection to update device states. It does not give you local control.
- Go to Settings > Devices & services, select Add integration, and search for Tuya.
- Log in by scanning the QR code with the Tuya Smart or Smart Life app. You don’t need a developer account for this login.
- Depending on the login flow, Home Assistant may ask for your user code. You can find it in the app under Me > Settings > Account and Security.
Devices and scenes sync automatically. When you add a new device in the app, reload the Tuya integration in Home Assistant so it appears.
LocalTuya and Tuya Local: local control
LocalTuya and Tuya Local are two separate custom integrations. They are not the same project, so check which one you have installed.
| Project | How devices are set up | Where the local key comes from |
|---|---|---|
| LocalTuya (rospogrigio/localtuya) | Manual datapoint (DP) mapping | Usually iot.tuya.com or tinytuya |
| Tuya Local (make-all/tuya-local) | Per-device config files that map entities automatically | Can be fetched through a Smart Life login |
Both need the same basic details for each device:
- The device’s IP address
- Its device ID
- Its local key
- Its protocol version
Setup steps
- Add the custom repository in HACS if needed, download the integration, and restart Home Assistant.
- Gather each device’s details. Give Tuya devices DHCP reservations so their IP addresses don’t change.
- Go to Settings > Devices & services, select Add integration, and choose the local Tuya integration you installed.
Protocol versions and keys
Tuya protocol versions include 3.1, 3.3, 3.4 and 3.5. A wrong version is a common cause of failure, and support varies by integration. If you are unsure, try the automatic option first.
A local key changes whenever a device is re-paired in the Smart Life app. If a device that worked stops responding, check its key first.
Retrieving keys through iot.tuya.com usually requires a Tuya IoT developer project. Trial subscriptions expire and need renewing, and an expired trial can stop key lookups.
Network notes
- Many Tuya devices accept only one local connection at a time. Close the Tuya or Smart Life app while you test, so the app doesn’t lock the device.
- Isolating devices from the internet can cause problems. Local DNS requests that aren’t handled properly can make devices appear unavailable. Test before you rely on isolation.
- Devices that connect through a hub or gateway have limited support. Standalone battery sensors without a hub are generally unsupported.
- Ports to know: TCP 6668 for local control, and UDP 6666 and 6667 for discovery.
Tasmota: local control through MQTT
Tasmota is open-source firmware for ESP8266 and ESP32 chips. It replaces the vendor firmware on a device you flash yourself. It is not a Tuya integration.
Tasmota connects to Home Assistant over MQTT:
- Install an MQTT broker, such as the Mosquitto add-on, and set up the MQTT integration. Do you need MQTT for Home Assistant? explains each step.
- In the Tasmota web interface, enter your Wi-Fi details and the broker’s host, port, username and password.
- In the Tasmota console, run
SetOption19 0on recent firmware. This turns on Tasmota’s native discovery, so Home Assistant finds the device. The olderSetOption19 1setting selects the legacy MQTT discovery. - Add the Tasmota integration under Settings > Devices & services.
Not every Tuya device can run Tasmota. Many newer Tuya devices use Beken or Realtek chips, such as CB2S and WB2S, which Tasmota cannot run. Alternatives for these chips include OpenBeken, LibreTiny and tuya-cloudcutter. The older Tuya-Convert method fails on most firmware released since about 2020.
Which option should you choose?
- Smart Life devices, and you don’t need local control: the official Tuya integration.
- Tuya devices, and you want the integration to map entities for you: Tuya Local.
- Tuya devices that Tuya Local doesn’t handle well: try LocalTuya. Some users switch between the two depending on the device.
- ESP-based devices that can run Tasmota and you already use MQTT: Tasmota.
If you are choosing between Tasmota and ESPHome for your own hardware, our comparison covers the trade-offs.
Safety
- Never open a mains-powered device for flashing while it is plugged in.
- Treat local keys like passwords. Don’t post them in forums or screenshots.