Tuya devices

Experimental

Tuya devices in Homer 1.0 are an experiment: the tuya_bridge bridge is set up and tested in one home, and device keys are taken from the Tuya cloud integration in a way the vendor never promised and may close. Yours may need some tuning.

Tuya Wi-Fi devices — outlets, relays, lights and sensors — join the home directly, through localtuya. The regular Tuya integration sends every press through the cloud: no internet — the outlet doesn't switch. With localtuya the command goes over the home network.

Where it is

	Where
App	Settings → Devices → Tuya devices → “Add devices”
Web	Settings → Tuya devices, the same block on the “Home” page (owner only)

Preparing the home for Tuya and signing in to the Tuya cloud are only in the app.

What the home needs

• The tuya_bridge bridge — a Homer component for Home Assistant, enabled with the line tuya_bridge: in configuration.yaml. It matches keys and protocol versions to the found addresses and writes the devices to localtuya.
• localtuya — devices are added to it. A pinned version is needed: other versions lack what the bridge relies on.
• The Tuya cloud integration in Home Assistant, with the usual QR sign-in. Don't remove it: device keys (local_key) come from it. You don't need a project on iot.tuya.com.
• An HA admin token — bridge commands are for administrators only.

A new home installs all of this by itself — see below.

Prepare the home for Tuya

At the top of the “Tuya devices” screen in the app there's the “Prepare the home for Tuya” card. It lists the steps and the state of each: the tuya_bridge bridge, localtuya, the tuya_bridge line in the HA config, the Home Assistant restart, a localtuya entry without cloud, the Tuya cloud. What's already there is ticked, what the Homer server can do itself it will do, and what needs your hands is explained.

1. “Prepare”. The Homer server installs the bridge and localtuya, adds the config line and creates a localtuya entry without cloud.
2. HA picks up new components only at startup, so the app asks “Restart Home Assistant?” — the home can't be controlled for about a minute. “Not now” postpones the restart.
3. If something fails, everything goes back to how it was: “Failed: …” and a “Try again” button.
4. Cloud sign-in. Enter the “User code” from Smart Life (“Me” → settings → “Account and security”) and tap “Sign in to Tuya”. Scan the QR with the Smart Life (or Tuya Smart) app, confirm the sign-in and tap “Done”.

localtuya is downloaded from GitHub: the Homer server needs internet access during preparation.

Add in the app

1. Connect the phone to the home Wi-Fi: the local Tuya protocol doesn't reach beyond its own network.
2. Open the screen — the search starts by itself: “Looking for outlets on the network…”, then “Matching keys…”. The phone listens for broadcasts and walks its subnet to find the silent ones too. Each found device says what it is: outlet or switch, light, sensor.
3. On a found device — “add”. Once it's added, the app offers a room right away.
4. For a light in a room that already has a light group, the app offers “Add to “…”” — into the group, “Replace “…”” — in place of a group light, or “No group”. On replace, the new light takes the old one's place and its body; the old one leaves the plan and all groups of the room.
5. Added devices are in the “Added devices” list; ones not yet placed have “place”, the rest say “on the plan”.

The search runs only while the screen is open. “Search again” repeats it.

Add on the web

A browser can't hear broadcasts, so the Homer server walks the subnet.

1. Enter the home subnet — the first three numbers of the address, for example 192.168.1. The web fills in the subnet if opened by a local address, and remembers what you enter.
2. “Find devices”. The server walks addresses .1–254 on Tuya port 6668, then the bridge matches keys — up to a minute.
3. On a found one — “Add”. Done — “entities: N — place them on the plan”.
4. Place the device on the plan in home editing.

The line at the top is “In the Tuya cloud: N, with a key: M”. “Reload from cloud” refreshes the list.

The entity_id stays

After moving from the cloud to localtuya a device keeps its entity_id: the bridge renames the cloud entity to …_cloud and gives the local one the old id, so the plan, groups, automations and Alice don't notice the move. The app shows “Kept existing ids: …”. The cloud entities are disabled at the same time so they don't duplicate the local ones.

Cloud and local entities are paired by data point code. If a pair is ambiguous, the bridge leaves it alone: the local entity gets a suffix _2, like sensor.monitor_1_voltage_2 next to the disabled sensor.monitor_1_voltage. If that bothers you, rename the entity in HA by hand.

Devices added before the bridge learned this get their old ids back with the bridge command adopt_ids. Running it again is harmless: the bridge skips what's already been handed over.

Address change

The router gave a device a new IP — localtuya loses it. During a search the app checks the addresses of added devices and updates the address in localtuya without adding the device again: “Address updated: …”.

If it didn't work

Message	What to do
“Nothing ready to add was found”	The device is not on this network or already added — the bridge skips added ones on purpose
“Nothing in this subnet answers on the Tuya port (6668)”	Check the subnet
“the device is not in the cloud — the key may have expired after re-pairing”	The key changes every time the device is re-paired in the Tuya app. “Reload from cloud” and try again
“Couldn't add: …”	“retry”
“the user code was not accepted”	The code is in Smart Life: “Me” → settings → “Account and security”. Check it and enter it again
“sign-in not confirmed in the app yet”	Scan the QR in Smart Life and confirm the sign-in, then “Done”
“preparation failed, everything rolled back: …”	The home is back to its previous state. Read the reason and tap “Try again”
“localtuya … could not be downloaded from GitHub”	The Homer server needs access to github.com. Try again when the network is back

Tuya gateways

The cloud doesn't give out the key of a Tuya gateway (Multimode gateway). Its child Zigbee devices share the gateway's key, so they aren't available directly either. Better move such devices to your own Zigbee network.