Home Assistant Guide

Simple tutorials for powerful automations

Getting Started with Tuya Local

Many smart plugs, lights, and switches are "Powered by Tuya". By default, Home Assistant's official Tuya integration talks to Tuya's cloud servers. This works, but it depends on the internet and can feel a bit sluggish. Tuya Local is a community integration that controls your devices directly over your home Wi-Fi - faster, and it keeps working even if your internet is down.

Why Choose Tuya Local?

  • Speed: Commands and updates go directly to your device on your local network.
  • Reliability: Devices can still be controlled even if your internet connection drops.
  • No Tuya developer account needed: Unlike LocalTuya, Tuya Local can fetch keys automatically using your Tuya or Smart Life app login.

Tuya Local vs. LocalTuya

These two integrations often get confused, but they're different projects:

  • Tuya Local: Easier setup. Can log in with your Tuya/Smart Life account to automatically grab device IDs and local keys. Great for beginners.
  • LocalTuya: Manual setup - you need to extract keys and enter them yourself. But if Tuya Local doesn't support a device, LocalTuya might.

Tip: It is possible use Tuya Local for devices it supports, and LocalTuya for the rest.

Step 1: Install HACS

Tuya Local isn't included with Home Assistant by default. You'll first need HACS (Home Assistant Community Store). Our Introduction to HACS article covers installation of HACS. Once HACS is set up, continue below.

Step 2: Add Tuya Local via HACS

  1. In Home Assistant, open HACS → Integrations.
  2. Click the ⋮ menu (top-right) → Custom repositories.
  3. Paste the repository URL: https://github.com/make-all/tuya-local.
  4. Choose Integration from the category dropdown, then click Add.
  5. Now, back in the HACS "Integrations" tab, search for Tuya Local and install it.
  6. Restart Home Assistant.

Step 3: Add the Integration

After restart, go to Settings → Devices & Services → Add Integration and choose Tuya Local. You'll now be guided through configuration. There are two ways to add devices:

  • Cloud-assisted method (recommended): Log in with your Tuya/Smart Life app account. Tuya Local will fetch device IDs and local keys automatically. No developer account needed, and no time-limited trial like the IoT developer portal. You'll be shown your list of devices and can add them one by one.
  • Manual method: Enter the device_id, local_key, and IP address yourself. These values can be retrieved with tools like tinytuya. See the Tuya Local documentation's DEVICE_DETAILS.md for step-by-step instructions.

Note: The cloud login token only lasts a few hours, but you can add multiple devices in one session without re-logging in. If you restart Home Assistant, you'll need to log in again when adding more devices.

Step 4: The Three Stages of Device Setup

Each device you add goes through three stages:

Stage One - Connection Details

  • Host: The device's IP address (often auto-discovered).
  • Device ID: Unique identifier, retrieved automatically in cloud-assisted mode.
  • Local key: Security key needed for control. This changes if you re-pair the device with the Tuya app.
  • Protocol version: Normally leave as "auto". If commands don't work reliably, try 3.2, 3.3, or 3.22 manually.

The integration will test the connection at this stage. If the local key is wrong, setup will fail (except on very old 3.1 devices, where failure only shows up when you try to control the device).

Stage Two - Select Device Type

You'll be shown a filtered list of possible device types based on what Tuya Local detected. Choose the correct type (e.g. light, switch, climate device). If you pick the wrong type, you'll need to delete and re-add the device, so take care here.

Stage Three - Naming

Finally, give the device a friendly name. This name will become the base for your entity IDs in Home Assistant, so pick something descriptive like "Living Room Lamp" or "Heater Plug".

Important Notes

  • Offline behaviour: Some Tuya devices misbehave if they can't reach the Tuya servers for a long time. Blocking DNS queries sometimes helps, but results vary.
  • Command timing: Many Tuya devices can't handle rapid-fire commands. If your automations send several changes at once, add small delays between them.
  • Hubs and sub-devices: For devices that connect via a Tuya hub (like some water timers), you must add the hub's device ID, IP, and key - plus the sub-device's node_id.

Wrap-Up

Tuya Local is a great way to speed up your Tuya devices and make them less cloud-dependent. Setup is straightforward thanks to the cloud-assisted option, and for more advanced cases you can still fall back on manual entry. If a device isn't supported or gives trouble, try LocalTuya as a backup - between the two, most Tuya gear can be controlled locally in Home Assistant.