Tuya Local Integration: A Hands-On Implementation Guide

Tuya devices can often be controlled directly over your home network with Tuya Local. The integration uses each device’s local protocol, so Home Assistant commands do not need to travel through the Tuya cloud. A cloud-assisted setup still uses your Tuya or Smart Life account briefly to identify devices and retrieve connection details.

This implementation guide follows a completed migration of four Wi-Fi devices: two Arlec PC191HA Series 3 metering plugs and two Tuya power meters. It describes an incremental migration that preserves dashboards and automations. Device models and firmware vary, so confirm support and entity behaviour on your own installation.

This is the practical follow-up to why Wi-Fi smart devices can still depend on the cloud.

What local control changes

Tuya Local communicates with supported devices over the LAN. The cloud-assisted setup is a convenience for discovery and key retrieval; it does not make normal local control cloud-dependent. Keep the Tuya or Smart Life app and account available for setup. Once configured, the integration connects directly to each device.

Local control does not itself prevent a device from contacting Tuya servers. This migration did not include a WAN-blocked test, so do not treat it as proof that devices work indefinitely without internet access. The device, Home Assistant host and network must still be powered and reachable.

Before you start

  1. Check support and compatibility. Search Tuya Local’s current supported-device list for your model, then check recent issues or device configuration details for firmware differences. A model name alone is not a guarantee. Check the integration’s current Home Assistant minimum version and release notes against your installed Home Assistant version. Older Home Assistant installations may need a compatible older integration release and, for some meters, a backported device profile. That profile may need to be reapplied when changing integration versions. Current users should check compatibility before choosing a release.
  2. Make a recoverable backup. Create a Home Assistant backup and capture your current automation, dashboard, Energy dashboard and entity-registry state. Confirm you know how to restore it.
  3. Inventory dependencies. Record entity IDs, device-based automation actions, startup behaviour, units, helper formulas, dashboard cards and which integrations are enabled. Identify a convenient device to migrate first.
  4. Stabilise the network. Ensure Home Assistant and the devices can communicate on the same routed network. DHCP reservations help keep local addresses stable. Avoid running a second local Tuya integration or another client that competes for the device’s often-limited local connection.

For routed networks, permit the required LAN connection from HA to the device on TCP 6668. Tuya discovery uses UDP 6666, 6667 and 7000 and may not cross subnet boundaries; use the confirmed device address when discovery cannot find it. An existing Wi-Fi AP can carry these connections; no replacement AP or firmware flashing is required.

Install and add one device

  1. Install a Tuya Local release that supports your Home Assistant version using the project instructions. Depending on your Home Assistant version, the recommended installation route may be Marketplace or HACS. Restart if the installation instructions require it.
  2. In Home Assistant, open Settings → Devices & services → Add integration and select Tuya Local. Choose its cloud-assisted configuration path.
  3. Follow the prompts to authenticate with the Tuya or Smart Life account associated with the device. The flow may ask you to enter the user code shown in the phone app, then scan a QR code to link the session. The app’s user code is an account-authentication step; it is not the device’s local key.
  4. Select the intended device from the returned list, then let the integration locate it on your LAN. Review the host, device identity and protocol information it fills in. Treat the local key as a secret: do not paste it into public tickets, screenshots or article content.
  5. Choose the matching device type/profile and a clear name. Check that the resulting entities represent the functions you expect: switch, voltage, current, power and energy where applicable. If the device does not respond, stop and re-check compatibility, network reachability, protocol selection and whether another client is connected.

The cloud-assisted flow automates obtaining the local key and other connection details. Keep a current backup and avoid re-pairing the device in its manufacturer app during migration: pairing can change its local key and make the saved configuration stale.

Preserve automations and entity IDs

Home Assistant automations may target a device ID or registry entry rather than an entity. Adding a local integration creates a new device entry, so device-targeted actions can keep referring to the old cloud device. Review every automation, script, scene and blueprint that uses the device.

  1. Temporarily disable the original Tuya cloud integration while configuring the local device. Keep the original entry and its entities available for rollback.
  2. In the entity registry, rename each original cloud entity to a temporary ID ending in _cloud, freeing its original ID. Keep the cloud integration entry disabled and available for rollback.
  3. Rename each equivalent local entity from its temporary ID (for example, one ending in _local) to the freed original entity ID. Transfer the original ID only when the local entity has the same meaning and compatible units.
  4. Explicitly replace device-based automation actions with actions targeting the intended entity IDs, such as switch.turn_on or switch.turn_off. Check startup behaviour and each automation’s enabled/disabled state. Update dashboards and Energy sources, then search for remaining references to cloud-suffixed entities.

Names alone do not prove that references migrated. Review automation traces and the final entity registry before proceeding to the next device.

Check power units and energy totals

Compare readings at the source. A meter may report watts (W), while an existing template or solar calculation expects kilowatts (kW). Confirm unit and scale before reconnecting templates. Converting watts to kilowatts requires dividing by 1,000; if the integration profile already applies that scale, do not convert again.

Distinguish an incremental energy reading from a cumulative total. Some plugs expose energy used since the last report or interval, not a lifetime or daily counter. Do not feed an incremental datapoint directly to the Energy dashboard as if it were cumulative.

For a plug that exposes power in watts but no suitable cumulative energy sensor, create an Integration (Riemann sum integral) helper. Select the local power sensor as the source. If that sensor reports W, choose metric prefix k, time unit hours, method left and a maximum sub-interval of five minutes. The helper converts W over hours to kWh; do not divide the source by 1,000 as well. Confirm the helper reports kWh with an energy device class and a suitable state class. It starts accumulating at migration and does not recreate historical cloud totals. Validate the result over time.

Migrate incrementally and validate

  1. Finish one device and confirm its local config entry loads and its entities update before moving to the next.
  2. Compare local readings with the manufacturer app or another trusted meter. Check plausible voltage, current, power and energy values, including units and sign conventions for import/export meters.
  3. Test an ordinary switch action only when safe for the connected load. Confirm the physical device changes state and Home Assistant reflects it. A successful sensor read alone does not prove relay control.
  4. Reload affected templates and helpers, review automation traces, and confirm dashboards and Energy sources reference the intended local entities. Check Home Assistant logs for setup or connection errors.
  5. After validation, keep the old cloud integration disabled and retain it for rollback. Check that cloud entities are no longer the active source and automations remain in their intended enabled state.

In the migration documented here, all four local entries loaded, authenticated LAN reads and live meter values were observed, preserved entities mapped to the local platform, and the old cloud integration was disabled. Automation states were unchanged and references were reviewed. No WAN-isolated operation or relay-actuation test was recorded; those results should not be inferred from the checks above.

Implementation examples: names and inputs

The following names are examples, not values from our network. Replace them with your own values before using a snippet. The address 192.0.2.10 is a documentation address and will not reach your plug.

Input Example Where to get it
Device address 192.0.2.10 Router DHCP lease or reservation
Device ID YOUR_DEVICE_ID Tuya Local cloud-assisted setup
Local key Prompted privately Tuya Local setup or an authorised Tuya account query
Protocol 3.4 or 3.5 LAN discovery; use the detected version
Stable switch ID switch.garden_lights Your original HA entity registry

1. Verify a device with a read-only Python query

This optional diagnostic is separate from HA. Run it from another computer on a network that can reach the device. Use a virtual environment so the diagnostic dependencies do not replace other Python packages. On Linux/macOS:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install tinytuya
python -m tinytuya scan

On Windows PowerShell, use:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install tinytuya
python -m tinytuya scan

Discovery should show the device address, ID and protocol version. It does not recover the individual local key. If broadcast discovery is blocked across a VLAN, use the confirmed address and details from the cloud-assisted setup.

Save this as read_tuya_status.py. Enter the local key at the prompt; it is not stored in the source file.

from getpass import getpass
import json
import tinytuya

DEVICE_ID = "YOUR_DEVICE_ID"
DEVICE_IP = "192.0.2.10"  # Replace with the confirmed LAN address.
PROTOCOL = 3.4           # Use 3.5 if discovery reports 3.5.

key = getpass("Local key: ")
device = tinytuya.Device(
    DEVICE_ID, DEVICE_IP, key, version=PROTOCOL
)
device.set_socketTimeout(5)
device.set_socketRetryLimit(1)
result = device.status()
print(json.dumps(result, indent=2))
if "dps" not in result:
    raise SystemExit("No valid status: check key, IP, version and reachability.")
python read_tuya_status.py

An illustrative response for a plug could look like this. Datapoints vary by model; do not copy these IDs into a meter profile without confirming the device schema.

{
  "dps": {
    "1": false,
    "18": 0,
    "19": 0,
    "20": 2301
  }
}

The status request does not turn the relay on or off. Stop the diagnostic client before HA connects; some devices allow only one local connection. In Tuya Local manual setup, enter the same address, device ID, local key and confirmed protocol, then choose the matching device profile.

2. Replace cloud device actions with stable entity targets

In an automation editor, a legacy device action may resemble this example:

actions:
  - type: turn_on
    device_id: OLD_CLOUD_DEVICE_ID
    entity_id: OLD_ENTITY_REGISTRY_ID
    domain: switch

After assigning the original entity ID to the local switch, replace the action with:

actions:
  - action: switch.turn_on
    target:
      entity_id: switch.garden_lights
  - delay: "00:03:00"
  - action: switch.turn_off
    target:
      entity_id: switch.garden_lights

This is an actions section, not a complete automation. Keep your original triggers, conditions, delays and mode; the three-minute delay above is illustrative. If editing automations.yaml directly, validate the file and reload automations afterwards. Do not trigger it merely to validate its syntax.

3. Convert meter watts to kilowatts once

If the source really reports W but existing formulas require kW, add a template such as the following under template: in configuration.yaml. Merge it into any existing template list rather than creating a duplicate top-level key.

template:
  - sensor:
      - name: Grid power kW
        unique_id: grid_power_kw_local
        device_class: power
        state_class: measurement
        unit_of_measurement: kW
        availability: >-
          {{ is_number(states('sensor.meter_power_w')) }}
        state: >-
          {{ (states('sensor.meter_power_w') | float(0) / 1000) | round(3) }}

Expected arithmetic: a source value of 2450 W becomes 2.45 kW. The availability guard keeps a missing source unavailable. If the integration already reports kW, use that reading directly. Verify import/export sign separately; this template preserves the sign.

4. Build cumulative plug energy from local power

Use either the Helpers UI described above or the YAML below, not both for the same total. This example belongs under sensor: in configuration.yaml; merge with any existing sensor list. Its source must report W.

sensor:
  - platform: integration
    source: sensor.garden_lights_power
    name: Garden lights local energy
    unit_prefix: k
    unit_time: h
    method: left
    round: 4
    max_sub_interval:
      minutes: 5

The expected unit is kWh: a constant 100 W over one hour corresponds to approximately 0.1 kWh. This is an arithmetic example, not a measured result from our migration. The helper starts accumulating when created and retains its value across HA restarts. Sampling and outages affect accuracy. Do not label an incremental device report as a cumulative total or manufacture an offset from an unknown historical value.

5. Validate and inspect the resulting state

On a Home Assistant OS installation with the HA CLI available, run:

ha core check

Expected result: successful configuration validation with no reported configuration errors. Then use Developer Tools → YAML to reload supported YAML integrations, or restart HA if the change requires it. Integration files added to custom_components require a restart.

For a read-only API check, supply your HA URL and a long-lived access token in your local shell environment, then request one state:

# Bash: enter the token without including it in shell history.
HA_URL="http://homeassistant.local:8123"
read -r -s -p "HA access token: " HA_TOKEN
printf '\n'
curl --fail --silent --show-error \
  -H "Authorization: Bearer ${HA_TOKEN}" \
  "${HA_URL}/api/states/sensor.grid_power_kw" \
  | python -m json.tool
unset HA_TOKEN

Look for a numeric state, the expected unit_of_measurement, and fresh last_updated values when readings change. For a steady sensor, use the integration status and repeated successful polls rather than expecting the value to change on every poll. In Settings → Devices & services, confirm the local entries are loaded and the old cloud entry is disabled. Read-only checks do not establish that relay actuation or indefinite WAN-isolated operation works.

6. Troubleshoot by symptom

Symptom Check Next action
No LAN discovery Subnet, broadcast routing and Wi-Fi client isolation Confirm the DHCP lease and enter its address manually.
Authentication or payload error Correct device ID, key and protocol Re-check the version; obtain a new key if the device was re-paired.
Connection works intermittently Other local clients or duplicate integrations Close the phone app and stop the diagnostic client.
No matching profile Model, firmware and returned datapoints Use a supported release/profile; do not guess datapoint meanings.
Power is wrong by 1,000 Raw scale and W versus kW Apply one conversion and check downstream formulas.
Dashboard works but automation fails Old device ID or registry ID in the action Replace it with a stable entity target and inspect a normal execution trace.
Energy resets or jumps Incremental versus cumulative source and unit Use a suitable cumulative meter or an integral of local power.

Rollback

If a device is unreliable or an important automation fails, stop or remove its local entry, restore the previous entity references if you changed them, and re-enable the original cloud integration. Restore configuration and registry backups using Home Assistant’s supported recovery process. Do not edit Home Assistant’s internal storage files while it is running. Verify the old entities update and critical automations work before considering the rollback complete.

What about ESPHome?

Tuya Local keeps the original Tuya firmware and uses its LAN protocol. Replacing firmware is a separate project. The ESPHome Arlec PC191HA guide documents an ESPHome route for compatible hardware, but firmware revisions and hardware series matter. Some patched Series 3 firmware may not be compatible with Cloudcutter’s documented path. Check the current device guide and compatibility information before attempting conversion; do not assume every plug sold under the same model name can be flashed. This implementation guide does not require firmware flashing.

Syntax references: HA Integral configuration and HA template sensors.

Further reading

Re-check project documentation when upgrading Home Assistant or Tuya Local. Integration requirements and supported profiles change over time.

Leave a Reply

Your email address will not be published. Required fields are marked *