Home Assistant Guide

LocalTuya – Complete Beginner's Setup

Many affordable smart plugs, switches, bulbs, and sensors are "Powered by Tuya". By default, these devices connect through the Tuya cloud, which works fine but can feel slower and will stop working if your internet goes down. Home Assistant also offers an official Tuya integration that uses this same cloud connection.

LocalTuya lets you control Tuya devices directly over your home network. This means faster responses, better reliability, and improved privacy. At first glance, LocalTuya can look a little intimidating - especially compared to the plug-and-play cloud integration - but don't worry. This guide is step-by-step, aimed at beginners, and requires no developer experience.

If you already use the cloud-based Tuya integration, you can keep it during setup for testing. Many users disable or remove it later to avoid duplicate entities.

Local control of Tuya devices: Tuya Local vs LocalTuya

Home Assistant has two popular community integrations for controlling Tuya devices without the cloud: Tuya Local and LocalTuya. Both keep commands on your LAN, but they take different approaches to setup and device mapping. This guide will focus on LocalTuya, since it's widely used, actively maintained, and gives you fine-grained control during setup.

What they are

• Tuya Local (make-all/tuya-local): uses a large library of device profiles. During setup you usually pick your model (or closest match) and the integration creates the correct entities for you automatically. It can optionally use a one-time cloud sign-in to prefill your device ID, local key, and IP, then runs locally.
• LocalTuya (rospogrigio/localtuya and maintained forks): talks to devices on your LAN and updates state via push notifications (fast and responsive). When adding a device, you select which DP (data point) drives each entity (switch, brightness, colour temp, etc.). It can also use the Tuya Cloud once to fetch local keys, then runs locally.

Key differences (at a glance)

• Setup experience: Tuya Local often feels simpler if your exact device profile exists (pick it and go). LocalTuya asks you to map DPs per entity, which is more manual but very transparent.
• Entity mapping: Tuya Local uses curated profiles to auto-create entities; LocalTuya lets you explicitly choose the DPIDs (and shows live DP values during setup) so you know exactly what's mapped.
• Updates & responsiveness:Both LocalTuya and Tuya Local receive status updates via push from the device, so state changes (such as pressing a physical switch) appear nearly instantly without polling.
• Cloud usage: Both can optionally use Tuya Cloud during setup to fetch local keys; day-to-day control remains local.

Which one do people prefer?

There's no single "best" for every device. If a Tuya Local profile exists for your model, setup is often smoother out of the box. If you want explicit control over every datapoint or your device isn't profiled yet, LocalTuya's DP-by-DP mapping is reliable and flexible.

This guide's choice

We'll use LocalTuya throughout this article. It's beginner-friendly once you understand what DPIDs are, and you'll learn a repeatable method to discover and map them - so even unusual Tuya devices can be integrated cleanly.

Contents

1. 1) Benefits vs Tuya Cloud
2. 2) Terminology
3. 3) Install HACS
4. 4) Add LocalTuya via HACS
5. 5) Tuya Developer Platform Setup
   1. 5.1 Before you start
   2. 5.2 Create your cloud project
   3. 5.3 Link your phone app account
   4. 5.4 Copy each device's Device ID
   5. 5.5 Get each device's Local Key (API Explorer)
   6. 5.6 Region / data-center pitfalls
   7. 5.7 Where to find your UID
   8. 5.8 Security notes
6. 6) Connect LocalTuya in Home Assistant
7. 7) Mapping entities (DPs)
8. 8) Troubleshooting
9. 9) Managing your IoT Core subscription (Extensions)
10. 10) FAQ
11. 11) Quick checklist

1) Benefits vs Tuya Cloud

• Faster - commands don't leave your house.
• Works offline - if the internet or Tuya cloud is down, your automations still work.
• More private - fewer cloud round-trips.

2) Terminology

LocalTuya uses some technical terms that might look confusing at first - don't worry if they seem offputting. We'll explain each one step by step, and you'll only need them when following the guide. You don't need to memorize or fully understand them right now.

• Device ID - a unique ID for your Tuya device (visible in your Tuya cloud project after linking your app account).
• Local Key - a per-device secret needed for local control. We fetch it via Tuya's API Explorer.
• Access ID & Access Secret - keys for your Tuya cloud project (also called Client ID and Client Secret).
• UID (User ID) - the identifier of your Smart Life / Tuya Smart app account.
• DP / DPID (Data Point) - an individual function of a device (on/off, brightness, color temperature, power readings, etc.). LocalTuya maps these to entities.

3) Install HACS (so we can install LocalTuya easily)

If you already have HACS, skip to section 4.

1. Download HACS for your installation type (OS/Supervised, Container, or Core). Follow the official "Downloading HACS" steps for your install method.
2. Restart Home Assistant, then go to Settings → Devices & Services → Add Integration and search for HACS. Complete the GitHub sign-in prompt.
3. Open HACS from the left sidebar once onboarding is complete.

4) Add LocalTuya via HACS

LocalTuya isn't part of Home Assistant by default, so we'll install it as a custom integration. There are a few forks; the one used here is xZetsubou/hass-localtuya.

1. Open HACS → Integrations, click ⋮ (top-right) → Custom repositories.
2. Paste https://github.com/xZetsubou/hass-localtuya, choose Integration, then click Add.
3. Back in HACS → Integrations, find LocalTuya and click Download/Install.
4. Restart Home Assistant.

5) Tuya Developer Platform Setup (step-by-step)

You will create a Tuya cloud project, link your phone app account so your devices appear, then retrieve each device's Device ID and Local Key. This is a one-time step to enable local control in Home Assistant.

5.1 Before you start

• Phone app set up - your devices should already be added in the Smart Life or Tuya Smart app.
• Know your app region - your app account belongs to a region (e.g., Europe, Western US). Your Tuya cloud project must use the same data center or your devices won't link.
• Tuya Developer account - sign in on the web at the Tuya IoT/Developer Platform.

5.2 Create your cloud project

1. Sign in to the Tuya IoT/Developer Platform. Go to Cloud → Development → My Cloud Projects → Create Cloud Project.
2. Fill the dialog:
   • Project Name / Description - anything you like.
   • Development Method / Industry - choose Smart Home (or "Custom" if not shown).
   • Data Center - pick the same region your app account uses (this is critical).
3. Authorize required API services. Ensure at least IoT Core is enabled. It's common to also authorize Authorization and Device Status Notification.
4. On the project overview, note your Access ID and Access Secret.

If your trial for "IoT Core" ever expires, you can request an extension from the Cloud Services page (see section 9).

5.3 Link your phone app account (so devices appear)

1. Open your project's Devices tab. Click Link Tuya App Account → Add App Account to show a QR code.
2. On your phone, open Smart Life (or Tuya Smart). Tap the + and choose Scan, then scan the QR code and confirm.
3. After a moment, your app account is linked. Your devices should now appear on the project's Devices tab.

No devices listed? It's almost always a region mismatch. Make sure the project's data center matches your app account region.

5.4 Copy each device's Device ID

In Cloud → Development → [Your Project] → Devices, click a device to view details and copy its Device ID. Repeat for each device you plan to add to LocalTuya.

5.5 Get each device's Local Key (API Explorer)

The Local Key is not shown on the device overview page. You must query it via Tuya's API Explorer.

1. Open Cloud → API Explorer. Make sure the Project and Data Center match your cloud project.
2. Select IoT Core → Device Management → Query Device Details (or Query Device Details in Bulk for multiple IDs).
3. Paste your device_id and click Submit Request. In the JSON result, copy local_key.

{
  "success": true,
  "result": {
    "id": "bf1234567890abcdxyztpq",
    "uuid": "bf1234567890abcdxyztpq",
    "name": "Living Room Plug",
    "local_key": "ab12cd34ef56gh78",  ← copy this
    "ip": "192.168.1.42",
    "online": true
  }
}

Optional - DP info: Still in API Explorer, use Device Control → Get Device Specification Attribute to see DP codes and IDs (power, brightness, color temperature, etc.). This helps when mapping entities later.

If local_key is missing or blank

• Confirm your app account is linked and the Data Center matches.
• Make sure the device is online in the phone app and on your home network, then query again.
• Check that IoT Core is authorized for the project.
• If the project's IoT Core trial expired, renew it and retry.

5.6 Region / data-center pitfalls

• "You cannot scan the QR code to add a device deployed in another data center" - your project region doesn't match your phone app's region. Edit the project and change the data center.
• No devices after linking - almost always a region mismatch. Re-check both sides.

5.7 Where to find your UID

Some guides refer to your app account's UID. You can see it in the app under Me → Settings → Account and Security → User Code, or on the project's Link Tuya App Account page once linked.

5.8 Security notes

• Treat your Access Secret and Local Keys like passwords. Do not share or publish them.
• LocalTuya uses the cloud only to fetch setup info. Day-to-day control in Home Assistant is fully local.

6) Connect LocalTuya in Home Assistant

1. Go to Settings → Devices & Services → Add Integration and search for LocalTuya.
2. Automatic discovery - LocalTuya can scan your LAN for Tuya devices. Select one and fill any missing fields (Device Name, Device ID, Local Key).
3. Manual add - if a device isn't discovered, choose "Add new device" and enter Device ID, Local Key, and the device's current IP address (from your router/DHCP list). Then add entities by mapping DPs as prompted.
4. Cloud pre-fill (optional) - some LocalTuya flows can use your Access ID/Secret and region to pre-fill devices and keys. This only fetches details - control remains local.

Before adding devices, close the Smart Life/Tuya app on your phone. Some devices allow only one local connection at a time, and the app can "occupy" it.

7) Mapping entities (DPs)

After the device connection test passes, LocalTuya will guide you to add entities based on DPs (Data Points). A plug might expose a single on/off DP; a light may expose DPs for power, brightness, color temperature, and color. If LocalTuya doesn't auto-map them, you can add them manually. Community threads often share DP examples for specific models, but you can also retrieve them directly from Tuya.

Finding DPIDs with the Tuya API

Each function your device supports (such as turning on, adjusting brightness, or changing colour) is represented by a Data Point ID, or DPID. LocalTuya requires the numeric DPIDs to know how to talk to your device. These aren't always obvious, but you can get them using the Tuya IoT Platform:

1. Log in to the Tuya IoT Platform and open your Cloud Project.
2. Go to Device Control → Query Properties.
3. Select your device and run the query. The response will include entries like this:

{
  "code": "switch_led",
  "dp_id": 20,
  "type": "bool",
  "value": true
}

In this example:

• code tells you what the function is (switch_led = main power).
• dp_id is the numeric identifier you need for LocalTuya (in this case, 20).
• type shows the data type (boolean, integer, enum, JSON, etc.).
• value is the device's current state.

Once you know the DPIDs, you can map them in LocalTuya: for example, set "Switch" to DPID 20, "Brightness" to 22, "Color Temperature" to 23, and so on. Combine this with the ranges shown in the Device Specification or Instruction Set API to know valid min/max values.

This approach means you don't need to guess or rely on community lists - you can pull the exact DPID mapping for your device straight from Tuya.

8) Troubleshooting (common beginner gotchas)

• Can't add LocalTuya to HACS? Ensure you added the repo under HACS → Integrations → ⋮ → Custom repositories, pasted the correct URL, and selected Integration. Refresh the HACS page after adding.
• LocalTuya not in "Add Integration"? Restart Home Assistant after installing via HACS and check again under Settings → Devices & Services → Add Integration.
• API Explorer errors:
  • 1004: sign invalid - Access ID/Secret incorrect. Re-copy from the project overview.
  • 1106: permission deny - App account not linked to the cloud project. Link it under Devices → Link Tuya App Account.
• Local key is empty - device offline, wrong data center, or unsupported type. Bring the device online and verify the region.
• "ip": "" and device offline in API Explorer - device is asleep, powered off, or on another network/VLAN. Wake it, power-cycle, and ensure it's on the same LAN.
• Device keeps disconnecting - assign a static IP in your router for each Tuya device. Keep the phone app closed during testing.
• Missing brightness/color entities - edit the device in LocalTuya and add the DPs for brightness, color_temp, and color. Some models use unusual DP codes.
• Energy/power values slow to update - in LocalTuya's options, reduce the scan interval (avoid <10s for stability).

9) Managing your IoT Core subscription (Extensions)

When you create a Tuya Cloud Project, the IoT Core service is activated with a 6-month free trial. You need IoT Core to use API Explorer (to retrieve Local Keys, Device IDs, and DP info).

Tuya advertises IoT Core as an enterprise paid service. For personal smart home use, you can request a free extension every 6 months with a short form.

9.1 Check your IoT Core status

1. Log in at the Tuya IoT/Developer Platform.
2. Go to Cloud → My Services (or Cloud Services).
3. Find IoT Core and note the expiry date.

9.2 Extend IoT Core for free

1. On the IoT Core entry, click Renew or Apply for Extension.
2. Fill the form:
   • Reason / Project Overview - e.g. "This project is solely for personal smart home use with Home Assistant. No commercial use."
   • Other fields - choose "Home Automation" or "Personal Use". Keep device counts realistic (dozens, not hundreds).
3. Submit. Approval typically arrives within hours to a couple of days and adds another 6 months.

9.3 Example text for the form

Project Overview:
This project is solely for personal smart home use with Home Assistant.
It is not for commercial purposes.

Set a calendar reminder to renew before it expires so you don't lose API Explorer access.

10) FAQ

• Is this permanent cloud dependence? No. The cloud is only used to fetch setup info; control is local.
• Do I need YAML? No. Everything is done through the UI. You can add devices and entities entirely from the integration's screens.
• Where do I find my UID? In your project's Devices → Link Tuya App Account page after linking, or in the app under Me → Settings → Account and Security → User Code.

11) Quick checklist

1. Install HACS → add xZetsubou/hass-localtuya as a custom repository → install LocalTuya.
2. Create a Tuya cloud project (correct data center) → copy Access ID/Secret → link your app account under Devices.
3. Get each Device ID (Devices tab) and Local Key (API Explorer → Query Device Details).
4. Add the device in LocalTuya (auto-discovery or manual) and map DPs to entities as needed.

That's it - you now have fast, reliable, and private local control of your Tuya devices in Home Assistant!