Please report any issues and feel free to raise pull requests.
Many others have contributed their help already.
This is a Home Assistant integration to support devices running Tuya
firmware without going via the Tuya cloud. Devices are supported
over WiFi, limited support for devices connected via hubs is available.
Note that many Tuya devices seem to support only one local connection.
If you have connection issues when using this integration, ensure that
other integrations offering local Tuya connections are not configured
to use the same device, mobile applications on devices on the local
network are closed, and no other software is trying to connect locally
to your Tuya devices.
Using this integration does not stop your devices from sending status
to the Tuya cloud, so this should not be seen as a security measure,
rather it improves speed and reliability by using local connections,
and may unlock some features of your device, or even unlock whole
devices, that are not supported by the Tuya cloud API.
A similar but unrelated integration is
rospogrigio/localtuya, if
your device is not supported by this integration, you may find it
easier to set up using that, or another more recent fork, as an alternative.
Installation
Installation is easiest via the Marketplace in Home Assistant 2026.11 or later
(HACS in earlier versions), which is the best place to get third-party
integrations for Home Assistant. Simply click the button below (requires My Homeassistant configured) or
follow the instructions for adding a custom
repository and then
the integration will be available to install like any other.
Configuration
After installing, you can easily configure your devices using the Integrations configuration UI. Go to Settings / Devices & Services and press the Add Integration button, or click the shortcut button below (requires My Homeassistant configured).
Choose your configuration path
There are two options for configuring a device:
- You can login to Tuya cloud with the Tuya or SmartLife app and retrieve a list of devices and the necessary local connection data.
- You can provide all the necessary information manually as per the instructions in DEVICES_DETAILS.md.
The first choice essentially automates all the manual steps of the second and without needing to create a Tuya IOT developer account. This is especially important now that Tuya has started time limiting access to a key data access capability in the IOT developer portal to only a month with the ability to refresh the trial of that only every 6 months.
The cloud assisted choice will guide you through authenticating, choosing a device to add from the list of devices associated with your Tuya account, locate the device on your local subnet and then drop you into Stage One with fully populated data necessary to move forward to Stage Two.
The Tuya authentication token expires after a small number of hours and so is not saved by the integration. But, as long as you don't restart Home Assistant, this allows you to add multiple devices one after another only needing to authenticate once for the first one.
Stage One
The first stage of configuration is to provide the information needed to connect to the device.
When using the cloud assisted config, the device id and local key will be pre-filled from the cloud, and the IP address will also be filled if local discovery is not blocked by other integrations or a complex network setup. Otherwise, see DEVICE_DETAILS.md for instructions on how to find the info.
host
(string) (Required) IP or hostname of the device.
device_id
(string) (Required) Device ID retrieved
local_key
(string) (Required) Local key retrieved
Note that each time you pair the device, the local key changes, so if you obtained the local key using the instructions below, then re-paired with your manufacturer's app, then the key will have changed already.
protocol_version
(string or float) (Required) Valid options are "auto", 3.1, 3.2, 3.3, 3.4, 3.5, 3.22. If you aren't sure, choose "auto", but some 3.2, 3.22 and maybe 3.4 devices may be misdetected as 3.3 (or vice-versa), so if your device does not seem to respond to commands reliably, try selecting between those protocol versions. Protocol 3.22 is a special case, that enables tinytuya's "device22" detection with protocol 3.3. Previously we let tinytuya auto-detect this, but it was found to sometimes misdetect genuine 3.3 devices as device22 which stops them receiving updates, so an explicit version was added to enable the device22 detection.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
