Tuya Universal v2.1 - Setup Guide

Custom Control Drivers LLC - control any Tuya / Smart Life device from RTI.

What it does

Controls your Tuya / Smart Life devices - plugs, switches, multi-gang power strips, bulbs and LED strips, curtains/shades/garage, fans, and more - from your RTI system. It runs in one of two modes, Cloud or Local. Read the next section, pick one, then follow Part 1 plus the part for your mode.

Which mode should I use?

Use Local wherever the device allows it. Cloud exists for the devices Local cannot reach, and it carries ongoing requirements that Local does not - read both before you pick.

Local (recommended). This instance talks DIRECTLY to your Wi-Fi devices over your own network - instant response, works with the internet down, and it makes no Tuya cloud calls at all, so nothing here expires or runs out. Up to 24 devices on one instance, and IR/RF blasters can learn and send locally. Wi-Fi mains-powered devices only; Zigbee, Bluetooth and battery devices have no address of their own and cannot be reached this way. Setup is per device: each needs its Device ID, Local Key and IP address, read once from the Tuya portal.

Cloud (for what Local cannot reach). One instance controls your WHOLE Tuya account over the internet and finds your devices automatically, including the Zigbee, Bluetooth and battery devices Local cannot see. Needs internet, and needs the Tuya developer project kept alive - see the two boxes below, which are not optional reading.

You can run both at once, and that is often the right answer - Local for your Wi-Fi devices and blasters, Cloud for the Zigbee and battery ones. A Local instance costs nothing against your Tuya allowance, so pairing one Local instance with one Cloud instance does not increase what Cloud uses. One License Key covers every instance on the processor.

Before you choose Cloud - two things that will bite later

1. The Tuya project's term expires, and Cloud stops when it does. Cloud mode runs on a Tuya developer project with an IoT Core subscription. That subscription has a term, and when it ends Tuya refuses every call and the driver loses the whole account until it is renewed - buttons stop working and it looks like a driver fault. Renewing is free and instant: platform.tuya.com, open the project, click the orange Subscribe to Resource Pack, choose IoT Core, pick the Trial Edition ($0.00), and Buy Now. Do NOT use the "Extend Trial Period" form - that one goes into a 1-2 working day review queue. Check the expiry date on the project's Overview page and put a reminder in the calendar before it lands. Local mode has no equivalent - there is nothing to renew.

2. Cloud spends a monthly API allowance, and ONE instance is what it is sized for. Every cloud call the driver makes is charged against your Tuya project's monthly API allowance, which it shares with your Smart Life app and anything else on that project. Here is what we control and what we measured. The driver polls one device per minute in rotation, so its call rate is fixed and does NOT rise with the number of devices you name - 24 devices cost exactly the same as 1. We measured one instance at that rate against a real Tuya account and it fitted inside the free tier, but without a lot of room to spare. Two Cloud instances on the SAME Tuya credentials do not fit. They poll independently, so the rate doubles, and in our measurements that overran the free tier - once it runs out Tuya refuses every call and the whole account goes dark until it refreshes, which reads as a driver fault. Tuya sells IoT Core only as annual editions, so there is no small pack to buy your way out. If you need more than 24 cloud devices, the two options that work are a second Tuya project with its own Access ID for the second instance, or moving devices to Local, which spends nothing.

Watch your own usage rather than trusting our numbers to stay true. The allowance and its pricing are Tuya's and they can change them. Yours is at platform.tuya.com under Cloud, then Cloud Services, then IoT Core - check it a few weeks after commissioning and you will know for certain rather than hoping.

Part 1 - Tuya account setup (BOTH modes, one time, ~10 min)

Both modes use a free Tuya developer project. Do this once; it covers all your devices.

1a. Create the account. Go to platform.tuya.com and sign up for a free developer account. This is the web portal - separate from your phone-app login.

1b. Create a project. Cloud > Development > Create Cloud Project. Set Industry = Smart Home, Development Method = Smart Home, and Data Center = your region (e.g. Western America for the US, Central Europe for the EU). Click Create. On the "Authorize API Services" pop-up, keep the defaults and Confirm.

1c. Link your phone app. Open the project > Devices tab > Link App Account > Add App Account - a QR code appears. In your Smart Life or Tuya Smart app (either works): tap Me, then the scan icon (top-right), and scan the QR. Your app's devices are now linked to the project.

1d. If it says IoT Core is expired: click the orange Subscribe to Resource Pack > IoT Core > Trial Edition (free, 1 month) > Buy Now. It re-activates instantly ($0). Do not use the slow "Extend Trial Period" form.

Now do Part 2 (Cloud) OR Part 3 (Local).

Part 2 - Cloud setup (whole account, including Zigbee and battery devices)

2a. Get your credentials. On your project's Overview tab, find the Authorization Key box. Copy the Access ID / Client ID and the Access Secret / Client Secret (click the eye icon to reveal the secret). Note the Data Center shown here (us / eu / cn / in) - that is your Region.

2b. Fill the driver settings. Set Connection Mode = Cloud (whole account). Paste Cloud Access ID and Cloud Access Secret, set Cloud Region, and leave Cloud Seed Device ID BLANK (the driver auto-discovers your account).

2c. Name your devices. Set Number of Cloud Devices to how many you want to control (1-24). For each, set Device N Name to the device's EXACT name as it appears in your Smart Life / Tuya Smart app (e.g. "Office Strip"). Save - the driver connects, discovers your account, and fills those named devices.

2d. Bind buttons and sliders. Use the Cloud functions - each has a Device parameter (1-24) that picks which device it controls (Power On/Off, Set Brightness, Set Color, etc.). Do NOT use the plain Local functions in Cloud mode (they do nothing here). Feedback variables are per device, numbered from 0: device 1 = Power0 / Brightness0 / Online0..., device 2 = Power1..., and so on.

2e. More than 24 devices? Do NOT just add a second Cloud instance on the same credentials. It will appear to work and then fail every month. Tuya's API allowance belongs to the Tuya project - the Access ID - not to the driver, and two instances sharing those credentials poll independently: together they use roughly 180 percent of the free monthly allowance and will exhaust it. When it runs out Tuya refuses every call and you lose the whole account, not one device, until the allowance refreshes. There is no small resource pack to buy as a fix - Tuya sells IoT Core only as annual editions. The two options that DO work: put the extra devices on a Local instance (which costs nothing against the allowance), or stand up a second Tuya project with its own Access ID for the second Cloud instance. Either way the single License Key still covers every instance on the processor. Check your usage at platform.tuya.com under Cloud, then Cloud Services, then IoT Core.

Cloud needs internet. Your own commands from RTI take effect instantly. Feedback works the other way round: Tuya offers no live push, so the driver polls - one device every 60 seconds, in rotation. With 4 devices named, each one is re-read about every 4 minutes; with 12, about every 12. So a change you make in the Smart Life app (or on the device itself) can take that long to show up in RTI, and readings such as energy use are only as fresh as the last poll. Name only the devices you actually use and the rotation stays quick. Then skip to Wiring color sliders below.

Part 3 - Local setup (Wi-Fi devices, direct LAN, no cloud) - START HERE

Local mode needs four things per device: Device ID, Local Key, IP address and Device Type. As of v2.1 the driver can fetch all four for you, so read the short way first and only fall back to the manual steps if you need to.

The short way - Import from Tuya Account (v2.1)

Three fields and one click sets up every device. You still need the Tuya account setup in Part 1, because local keys only exist in your Tuya project and nothing on your network will hand them out.

1. Set Connection Mode to Local.

2. Fill in Tuya Access ID, Tuya Access Secret and Tuya Region from Part 1.

3. Click Import from Tuya Account in the left-hand panel of the driver's configuration page, under Driver Configuration. Integration Designer signs in to your Tuya account and fills in the Name, Device ID, Local Key and Device Type for every device it finds.

4. Read the summary it shows you. It lists every device it set up and which slot each one landed in, and it names anything it had to skip and why.

5. Send the project. The driver finds each device's IP address on your network by itself.

Where the imported devices appear. Device 1 is under System Settings; devices 2 and up are under Additional Local Devices, which grows one device at a time - each one appears once the previous device has a Local Key. After an import they are all filled in, so they are all there. The IP Address boxes stay empty on purpose, and that is not something you need to fix.

That is the whole setup. You do not have to look up a single Device ID or Local Key by hand, and you do not have to type device names in first - the names come from your Tuya account.

Why there is nothing to fill in for the IP address. Deliberately. The driver finds each device on the network and keeps following it if your router gives it a different address later. An address typed in during setup could not do that. Leave Protocol Version on Auto for the same reason: the driver works out 3.3, 3.4 or 3.5 on its own.

What Import will and will not change. It always writes the Name, Device ID and Local Key, because those have exactly one correct value and your Tuya account is the only place they come from. A device already set up keeps the slot it is in, matched on its Device ID, so importing again is safe even if you renamed the device in the app. If a device you have since deleted leaves a slot behind, that slot is left alone rather than handed to something else, and any device that could not be given a slot is listed in the summary instead of being dropped quietly.

Device Type is set only on devices Import ADDS for you. On a device you had already set up, whatever type you picked is left exactly as it is. Anything Tuya does not give us a clear type for stays on Generic, which always works through the Data Point functions.

Devices that are offline are imported anyway, and the summary lists which ones they were. That is deliberate: a plug switched off at the wall, or a device you have unplugged for the winter, is still one you want set up and ready. A device that is offline in your Tuya account will not connect locally either, so it will simply sit there until it comes back.

You can safely leave them. An offline device never gets an IP address, so the driver never opens a connection to it, never retries, and never reports an error about it. It costs nothing at runtime. The only thing it uses up is a device slot, and one entry in the device list that will not do anything until the device returns.

Clearing one out is housekeeping, not maintenance, and only really matters if you run out of room. One instance holds 24 devices. If your Tuya account has more than that and some of them are dead, those dead ones are taking slots a working device could use, and the import will tell you it had nowhere to put the rest. That is the case worth tidying. To remove one: clear its Device ID and Local Key, and lower Number of Devices if it was at the end of the list. Otherwise there is no hurry, and a device you expect back is better left where it is, because importing again will only put it back in the same slot anyway.

Devices inside a hub or a blaster are listed as skipped. Zigbee and battery devices behind a hub, and the virtual remotes inside an IR/RF blaster, have no Local Key of their own, so nothing can address them directly over the LAN. Blaster remotes still work, sent through the blaster itself.

Importing is always your choice. Everything can be typed in by hand instead, using the manual steps below, and a system set up that way never needs the Access ID or Secret at all.

When to run Import again. Whenever you add a device, and whenever a device is removed and paired again in the app. Re-pairing gives a device a new Local Key, which is the single most common reason a device that used to work stops working. Everything else about the device stays the same, so importing again fixes it without disturbing your programming.

If your Tuya trial has expired, Import will say so. Extend it on platform.tuya.com and import again. Devices already set up keep working throughout - local control never touches Tuya.

Import runs on your computer, in Integration Designer, not on the processor. Your Access ID and Secret are used at that moment and never sent anywhere else, and the running driver never contacts Tuya at all in Local mode.

LAN discovery - the IP address looks after itself

With LAN Discovery on (the default), the driver listens for Tuya devices announcing themselves on your network. It fills in an address you have not typed, and if a device changes address it follows it instead of going offline. A DHCP reservation is still tidier, but it is no longer the difference between working and not.

Discovery matches devices by Device ID, so it helps a device once that ID is set - by hand or by Import.

Protocol 3.3 and 3.4 devices announce themselves every few seconds. Protocol 3.5 devices never announce themselves at all, so the driver asks for them: at start-up, after an import, and when a configured device has not been heard from. Discover Devices Now asks immediately.

Only one Tuya driver instance per processor can run discovery. A second instance still works normally, it just needs its addresses typed in.

The manual way (still supported)

If you would rather not put cloud credentials in the driver at all, fill the fields in yourself. Get them in this order - you need the Device ID before you can look up the Local Key.

Step 1 - Device ID. In your Smart Life / Tuya Smart app, open the device > Edit (pencil) > Device Information > Virtual ID. (Or on platform.tuya.com > your project > Devices > Device List, the Device ID column.) Copy it.

Step 2 - Local Key (needs the Device ID from Step 1). The Local Key is NOT shown on the app's device page. Two ways to get it:

- Easiest (tinytuya): on any PC with Python, run pip install tinytuya, then python -m tinytuya wizard. It first asks for an "API Key" and "API Secret" - these are just other names for your Access ID and Access Secret (get them on platform.tuya.com > your project > Overview tab > Authorization Key box; the eye icon reveals the secret). It then asks for any one Device ID (from Step 1) and your region (us / eu / cn / in). It writes a devices.json file listing EVERY device with its name, Device ID and Local Key, and scans your LAN to show each device's IP (Step 3 done too).

- No Python (API Explorer): on platform.tuya.com go to Cloud > API Explorer, check the project selector and data center at the top match your project, then in the left panel open Device Management > Query Device Details in Bulk. Paste your Device ID into device_ids and press Submit Request. In the Response panel on the right, the line reading local_key is your Local Key. That call takes several Device IDs separated by commas, so you can pull the whole project in one go.

Two gotchas here. The Local Key is 16 characters and often contains punctuation, so copy it exactly rather than retyping it. And API Explorer spends real API calls from your project's monthly allowance (Tuya says so on the page), so pull your keys BEFORE that allowance runs low, and keep a copy - the key does not change unless you re-pair the device.

Step 3 - IP address. The device's IP on your LAN (tinytuya's scan shows it, or check your router's DHCP client list). Set a DHCP reservation so it never changes.

Step 4 - Protocol Version: leave it on Auto. Tuya devices speak one of several LAN protocol versions (3.3, 3.4 or 3.5). Which one a device speaks is decided by its own firmware, so it is not really a choice you make. It is something the driver works out. On Auto it starts on 3.3 and moves through 3.4 and 3.5 until one proves itself. That covers both of the ways a wrong version shows up: a device that accepts the connection and then stays silent, and a device that accepts it and drops it again partway through. Once a version works it is remembered, so the search happens once rather than on every restart.

Forcing a version stops the search. If you pin 3.4 or 3.5 by hand, the driver keeps trying that version and does not look at the others. If it is the wrong one the device will not come online, and Last Error will say so and tell you to set it back to Auto. Only force a version if you have a specific reason to.

Step 5 - Fill in the FIRST device. Set Connection Mode = Local, then enter Device IP Address, Local Key and Device ID, leave Protocol Version on Auto, and pick the Device Type that matches (Light - color, Light - older type, Switch / Relay, Smart Plug, Cover / Shade / Garage, Fan, or multi-gang). Generic always works via the Data Point functions. This first device is always Device 1.

Step 6 - Add more devices to the SAME driver. One instance handles up to 24 local devices. As soon as Device 1 has a Local Key, an Additional Local Devices category appears with the fields for Device 2; give that one a Local Key and Device 3 appears, and so on. Only the device you are working on is ever on screen, so the page stays short however many you end up with. The Local Key is what each device is gated on because it is the one field a device cannot work without, and the one thing Import from Tuya Account always supplies.

Step 7 - Set Number of Devices. It starts at 1. Raise it to however many devices you are actually controlling. That is what gives each device its own set of variables and events in Integration Designer. Name them in the Device 1..24 Name fields; those names are what appear in the Device picker when you program a button.

Note: every setting on this page is read when the driver loads, so re-send the project after changing any of them.

Still want one device per instance? That works too, and existing installations are unaffected - add the driver again and use its Device 1 fields. But one instance with several devices is tidier and uses fewer processor resources.

Heads-up: the Local Key CHANGES if you remove and re-pair a device in the app. If you ever reset or re-add a device, open the project in Integration Designer and click Import from Tuya Account again: it writes the new key straight into Driver Settings. Pulling it by hand (Step 2) still works if you prefer. The driver names this case for you, so you are not left guessing: when it can see a device on the network and the key is the only thing being refused, it says so and tells you which button fixes it.

Roller shutters and other RF remotes

If your shutters, blinds, awning or fan are driven by a 433MHz handset that you taught into a Tuya IR+RF blaster, this is the section for you. Tuya does not expose RF handsets the way it exposes infrared ones, so the driver records the raw signal once and replays it through the blaster. You never see or type a code.

Before you start - one setting on the Tuya website. RF will not work until this is done, and it takes about a minute. It changes ONE product, so your lights and plugs are untouched. You must be signed in as the MAIN account that owns the Tuya IoT project - a sub-account cannot change it.

1. Go to platform.tuya.com and sign in.

2. Top menu: Cloud > Development. Click your project to open it.

3. Open the Devices tab, then the All Devices sub-tab.

4. Above the list, switch the view from device to product. You will see product cards instead of individual devices.

5. Find the card for your IR+RF blaster, hover over it, and click Change Control Instruction Mode.

6. Select DP Instruction - not Standard Instruction Set - then click Save Configuration.

7. Open View Details on that same product and click Refresh Configuration. Skip this and the change can take around four hours to reach servers outside China.

How to tell it worked. Load the driver and try a Learn. If the setting has not applied, the command is rejected and the driver prints these exact steps in the processor System Log. If it has applied, the learn arms the blaster and its indicator lights up.

Step 1 - name the blaster. In Driver Settings, put the blaster's name from the Smart Life app into one of the Device N Name boxes. Name the BLASTER, not the shutter remote.

Step 2 - label the buttons you are going to teach. Still in Driver Settings, fill in RF Code 01 Name, RF Code 02 Name and so on - for example "Roller 1 Open", "Roller 1 Stop", "Roller 1 Close". Naming is optional - every slot appears in the Send and Delete lists either way, shown as your label followed by its slot number - but a name is what makes the list readable a year from now.

Give the driver a moment after sending your project. At start-up it discovers your devices, scans the blaster and asks each device what it supports, all over one connection to Tuya. Teaching during those first busy seconds is the most common reason a capture fails. Wait until your device list has filled in, then teach.

Step 3 - teach each button. Put a temporary button on a page and give it Learn RF Code, with Device = the blaster and Into Slot = 1. Press that button in RTI, then WAIT FOR THE BLASTER'S LED TO LIGHT UP before you touch the handset. The learn command travels to the cloud and back down to the blaster, and a handset press sent before the LED lights is not heard at all - this is the single most common reason a learn fails. Once the LED is lit, press the matching button on your handset, held within a few inches of the blaster. The blaster normally reports the code within about 10 seconds; the driver keeps the window open for 30. The RF Learn State variable tells you what happened. Repeat with slot 2, slot 3 and so on. You can delete the temporary button afterwards.

Step 4 - use them. Bind any button to Send RF Code and pick your code by the name you gave it. That is all - no codes to copy, nothing to paste.

If a shutter responds only sometimes, raise RF Repeat Count in Driver Settings from 6 to 10-20. Some motors want the signal repeated more times. This is the first thing to try.

Delete RF Code clears a slot, and Cancel RF Learn aborts a learn you started by mistake.

What will not work: rolling-code handsets, which change their signal on every press for security (many garage and gate remotes). If your handset could be taught into the Smart Life app at all, it is a fixed-code type and it will work here. Note also that a blaster is one-way, so there is no position feedback from a shutter - the same as using the handset itself.

Multi-gang switches & power strips (Cloud)

A power strip or multi-gang switch reports one on/off point per outlet. Power On / Power Off / Toggle control outlet 1 only - that is the outlet the device's standard power command drives. To reach the others, use the Cloud Multi-Gang / Power Strip functions.

Outlet On / Outlet Off / Outlet Toggle. Pick the Device, then set Outlet to the outlet number (1-6). Outlet 1 is the same one Power controls.

All Outlets On / All Outlets Off. Switches the whole strip in a single command.

Feedback. Bind each button to that device's Outlet 1-6 variable. Outlet Count tells you how many outlets the driver found on that device, so you can hide the buttons you do not need.

Bind to the variable group named after the device. In both Cloud and Local mode that is <device name> (n) > Outlet 1-6 (gang), where n is the same device number you picked on the button. (Up to v1.8 Local mode had a second, device-less set called Multi-Gang / Power Strip > Gang 1-6; v1.9 removed it, because it silently belonged to device 1.)

Which outlet is which? Switch them one at a time and label them. Outlet 1 sends the device's own switch 1, Outlet 2 its switch 2, and so on - the same numbering the Smart Life app shows. That numbering does not have to match the physical order of the sockets on the housing, so switch each outlet on once, see which socket lights, and name the buttons to suit the install. The driver also prints the outlet list to the processor System Log at startup ("has 4 outlet(s)").

A USB bank may be one of the outlets. Some strips expose their USB ports as just another switch, in which case it appears as the next Outlet number and switches like any other - on the 4-socket strip we tested, the USB bank was Outlet 5. Outlet Count includes it.

Check the slot before you blame the driver. The Cloud Device Map variable reads like "1 = Gate Alert | 2 = LG TV | ... | 6 = Wi-Fi Power Strip" and tells you which device is in which slot. Slots are pinned by the Device Name fields, so if you rename or reorder them after binding buttons, those buttons stay on the OLD slot - the label they show changes, which is usually the first clue.

Unusual devices. The Outlet picker covers outlets named switch_1, switch_2 and so on. If a device names something differently, read its Raw (codes JSON) variable to see the real names it reports, then drive them with Set Code (advanced) (code = the name, value = true or false).

Multi-gang switches & power strips (Local)

Pick Device Type = Switch / Power Strip - multi-gang for that device. Each gang/outlet maps to a data point: Gang 1 = DP1, Gang 2 = DP2, ... Gang 6 = DP6.

Commands. Use Multi-Gang / Power Strip > Outlet On / Outlet Off / Outlet Toggle. Set Device to the strip and Outlet to that outlet's number. Local and Cloud mode use the same functions.

Feedback. Bind to that device's own group: <device name> (n) > Outlet 1-6 (gang).

If the outlets do nothing but the driver says it is connected, check the Device picker first. It defaults to 1, so a button dragged out without changing it addresses the first device in the settings. A Tuya device happily accepts a data point it does not have and reports success, so a strip's buttons aimed at, say, an IR blaster look exactly like a working button that does nothing. With more than one device configured the driver flags this in Last Error.

Programming a button - choosing WHICH device

Every control category (Power, Light, Cover / Shade / Garage, Fan, Multi-Gang / Power Strip, Timer and Data Points) has a Device parameter as its first setting. Pick the device there and that is the one the button drives. The list shows the names you typed into the Device 1..24 Name fields, so name them before you start programming and the picker reads properly.

The device numbers line up with the setup fields: Device 1 is the one in the Connection category, Device 2 is the first one under Additional Local Devices, and so on. The same numbering drives the variables and events, so Device 3's feedback is on the Device 3 variables.

There is no longer a second set of device-less functions. v1.8 kept the pre-multi-device functions under Legacy - always Device 1; they were removed in v1.9 because they looked identical to the ones above but ignored which device you meant. If a button stopped working after updating, it was using one of those - pick the same command again from the category above and set its Device.

System (all devices) > Refresh and Reconnect have no Device parameter on purpose - they act on every configured device at once.

System (all devices) > Redetect Protocol is the one to reach for when a device that used to work stops connecting after being re-paired, replaced, or moved to a different address. In Local mode the driver remembers which protocol each device actually spoke and re-uses it on every later start, which saves the search - but if the device itself changes, that memory is now wrong and picking a protocol in the settings will not override it. Redetect Protocol wipes the remembered value for the device you choose (or for all of them) and starts the search again from what Driver Settings says. It is safe to run at any time; the worst it costs is a few seconds of reconnecting.

Wiring color sliders (both modes)

For a slider you must set BOTH its Command and its Value (feedback) to the matching channel - if the Value points at the wrong variable the thumb jumps back when you release it. (In Cloud mode use the Cloud version of each command, with the Device parameter.)

Red / Green / Blue sliders: Command = Set Red / Set Green / Set Blue; Value = the matching Red / Green / Blue variable from that device's own group; range 0-255. Set the command's Device picker and take the Value from the same numbered device, or the thumb will read another device's color.

Color Brightness slider: Command = Set Color Brightness %; Value = Color Brightness %; range 0-100. Brightens/dims the current color while keeping its hue - use this if your colors look dim.

White slider: Command = Set White %; Value = Brightness %; range 0-100. By design this switches the light to white mode (replaces the color).

Devices behind an IR / RF blaster (Cloud mode)

Roller shutters, fans, air conditioners and TVs driven through a Tuya IR or IR+RF blaster are not ordinary Wi-Fi devices - the blaster just replays a remote-control signal at them. How you reach one depends on how the remote was created in the Smart Life app.

INFRARED remotes you taught yourself, button by button - these work directly. Name the remote in a Device Name field and use IR Send Key, typing the button name exactly as the Smart Life app shows it on that remote (for example Power, Volume Up). The driver lists each remote's buttons in the System Log at startup.

RADIO-FREQUENCY (RF, 433MHz) remotes - teach them to the driver. RF is common for roller shutters, blinds, awnings and some fans. Tuya does not publish RF remotes the way it publishes infrared ones, so instead of pressing the remote's buttons the driver replays the raw signal through the blaster. You teach each button once - see Roller shutters and other RF remotes below. Run Scene still works and remains a fine alternative if you already have scenes built.

Knowing what each device actually is

Every device slot carries the same full set of variables - power, brightness, color, cover position, fan speed, outlets, energy - because one driver has to cover every kind of Tuya device. That means a slot shows variables its device does not have: an IR blaster appears to have a brightness level, a light appears to have a cover position. Only the ones the device actually reports will ever change.

Each slot has a Device Type variable that tells you what it really is. In Cloud mode it reads the type Tuya reports - for example Light (dj), Power Strip (pc), IR/RF Blaster (wnykq) - with the plain-English name first and Tuya's own category code in brackets, so you always have the raw value too. A device we do not have a friendly name for shows the bare code rather than a guess. In Local mode there is nothing to ask, so it reads back the Device Type you picked for that device in the settings, for example Switch / Power Strip - multi-gang (DP 1-6). Either way it is the quickest check that a button is pointed at the device you think it is. (Local mode published no type variable at all before v1.9.)

RF Remote - not directly controllable means exactly that: Tuya publishes no way to command these, so buttons bound to them will do nothing. Drive those with Run Scene (Tap-to-Run), or with the learned RF codes above if it is a 433MHz handset.

IR Remote (behind a blaster) is a remote learned into one of your blasters. Use IR Send Key or its learned buttons rather than the normal device commands.

Data Points (advanced - control ANY device)

Every Tuya device is controlled through numbered data points (DPs). When the typed Device Type doesn't cover a control, drive any DP directly: Set Data Point - On/Off (boolean DP), Set Data Point - Number (numeric DP like brightness 0-1000), Set Data Point - Text (string/enum DP like a mode name), or Set Data Points (JSON) to set several at once, e.g. {"20":true,"22":500}. To discover what your device supports, set Debug Level = High and watch the DP1..DP30 and All Data Points (JSON) variables - they show every DP the device is reporting.

Supported devices & network notes

Cloud mode reaches everything in your account, including Zigbee / Bluetooth / battery devices behind a hub.

Local mode is for Wi-Fi, mains-powered devices only. The device and the RTI processor must reach each other on the LAN - no Wi-Fi client/AP isolation between them. Battery / deep-sleep devices are not reachable locally; use Cloud for those.

How many devices can one processor handle?

CPU is not the limit. We measured 24 local devices on a single instance at 10-15% CPU on both an XP-8s and an XP-6, with no reconnects, across four separate 67-minute runs. Memory is the thing worth a moment's thought, and mainly on the smaller processors.

What a device costs. On protocol 3.5 each local device needs roughly 145 KB of driver memory. We measured 24 devices on 3.5 using about 5.9 MB in total, and the same 24 on 3.4 using about 3.3 MB. You do not choose which of those a device speaks - its firmware does - so read this as a prediction from your device list rather than a setting you can turn down.

On an XP-6 or an XP-3, check the free memory before you commit to a large device count. These are the smaller processors in the range. On our XP-6 bench unit, 24 Tuya devices used about 5.9 MB and left roughly 12 MB free, and that ran perfectly well. A processor that is already close to full before Tuya is added is a different story, and the number of devices it will comfortably take is lower.

How to check, in under a minute. Put the processor's IP address in a browser to open XP Diagnostics. The Dashboard shows Memory Free. The Drivers page shows what each driver on that processor is using. Compare what is free against the figures above.

If memory turns out to be tight, that is the capacity of the processor rather than something the driver can tune away. We cannot make a device's protocol cost less than its firmware costs. What we can do is help you find a sensible arrangement, whether that is splitting devices across instances or across processors, so please email support@customcontroldrivers.com and we will work through it with you. We are always glad to help.

Where the driver's messages appear

When something is wrong the driver says so in two places, and it is worth knowing both before you start troubleshooting.

Last Error, a driver variable, carries the most recent problem in plain language. Put it on a panel, or watch it on XP Diagnostics > System Variables.

The System Log. Open the processor's IP address in a browser, then XP Diagnostics > System Log. The driver's running commentary goes there. It is the page you want, and it is not the same place a driver trace appears, so an empty trace does not mean the driver is quiet.

Raising Debug Level adds detail to the System Log. Leave it on Low for normal running.

What the connection messages mean

"cannot connect to this device..." - the processor tried to open a connection and the device refused it or was not there at all. Check the IP address, the device's power, and that it is on the same network as the processor.

"no response while connecting..." - the connection was started but the device never completed it. Usually the same causes. A device that has been powered off, or whose IP address has changed, behaves this way.

"has never connected since the driver started..." - this device has not come up once since the project was sent. Almost always a wrong IP address, or a device on a different network from the processor.

"could not establish a session on protocol..." - the processor reached the device but could not open a Tuya session with it. The usual cause is a Local Key that no longer matches, which happens whenever a device is removed and re-paired in the app. Run Import from Tuya Account to pick up the new key, or pull it by hand (Part 3, Step 2). If the driver can see the device on the network and the key is the only thing being refused, the message says so outright and names the button. A blaster or gateway with no readable data points can also show this even though its commands work.

"...which is FORCED for this device in Driver Settings" - the same thing, except the version was pinned by hand instead of being found automatically. Set Protocol Version back to Auto unless you know this device needs that specific version.

License

Leave License Key blank for the 2-hour trial; paste your key to license this processor. One license covers every Tuya Universal instance (local and cloud) on the same processor - buy once per processor, control as many Tuya devices as you like.

If RF Learn says "nothing captured"

"...the blaster is offline" - the blaster lost its Wi-Fi connection, so it never armed its receiver. Pressing the handset harder or closer cannot help. Check the blaster's signal and try again. Blasters often sit low or behind equipment where reception is poor; if learns fail repeatedly, move the blaster or put an access point nearer to it.

"...wait for the blaster's LED before pressing" - the blaster was reachable but reported no code. Nine times out of ten the handset was pressed before the LED lit. Press Learn, wait for the LED, then press the handset within a few inches of the blaster.

A learn that fails costs nothing - the slot keeps whatever it already held. Just try again.

Device not working? Tell us and we will add it

Tuya and Smart Life cover thousands of devices from hundreds of manufacturers, and we cannot test them all. If you have a device this driver does not control correctly, email support@customcontroldrivers.com with the make and model and we will add support for it.

To speed that up, set Debug Level = High, put the device in Cloud mode, and send us what the All Data Points (JSON) variable reports for it - that tells us exactly which data points your device uses.

Updating from an earlier version

Everything below is for installers updating an existing project. If this is a fresh install there is nothing here you need.

Renamed in v1.9 - updating a project built on v1.8 or earlier

Only projects that used the device-less Local commands and variables are affected. Cloud programming, driver settings, device IPs, Local Keys and learned RF codes are untouched, and nothing needs re-entering.

Commands. Everything that lived under Legacy - always Device 1 moved to the matching category above it, with a Device picker added as its first parameter. Set the picker to the device you meant:

Power On / Power Off / Power Toggle -> Power > Power On / Power Off / Toggle

Gang On / Off / Toggle -> Multi-Gang / Power Strip > Outlet On / Outlet Off / Outlet Toggle (the Gang parameter is now called Outlet)

All On / All Off -> Multi-Gang / Power Strip > All Outlets On / All Outlets Off

All the light commands -> Light > Set Brightness % / Set Color Temp % / Set Color (RGB) / Set Red / Set Green / Set Blue / Set White % / Set Color Brightness % / Set White Mode / Set Color Mode / Scene Mode

Open / Close / Stop / Set Position % -> Cover / Shade / Garage > Cover Open / Cover Close / Cover Stop / Cover Set Position %

Set Speed / Set Direction -> Fan > Fan Set Speed / Fan Set Direction

Set Auto-Off Countdown -> Timer > Set Auto-Off Countdown

Set Data Point - On/Off, - Number, - Text, Set Data Points (JSON) -> the same names under Data Points (advanced)

Feedback variables. The device-less names are gone; use the group named after the device instead. Device 1's variables end in 0, device 2's in 1, and so on - the same numbering Cloud mode has always used:

Power -> <device name> (1) > Power (sysvar Power0)

Gang 1-6 (on/off) -> <device name> (1) > Outlet 1-6 (gang) (sysvar Gang1_0 ... Gang6_0)

All Data Points (JSON) -> <device name> (1) > Raw (codes JSON) (sysvar Raw0)

Device Type (under Status) -> <device name> (1) > Device Type (sysvar DevType0)

Brightness, Color Temp, Mode, Color, Red, Green, Blue, Color Brightness, Position, Cover State, Fan Speed, Fan Direction, Current, Power (W), Voltage, Energy and Countdown all follow the same rule: the same name under the device's own group.

Data Point 1-30 have NOT moved. They are still under Data Points (raw) - Device 1 only, and still only cover the first device. For devices 2 and up, read that device's Raw (codes JSON) variable instead.

What's new in v2.1

Import from Tuya Account. One click in Integration Designer fills in the Name, Device ID, Local Key and Device Type for every device, instead of copying four fields per device out of the Tuya website by hand. It runs on your computer, at setup, and writes the values straight into Driver Settings where you can see them. The running driver never contacts Tuya in Local mode.

LAN discovery. The driver finds your devices on the network and fills in their addresses, and follows a device that changes address instead of going offline. It can be switched off.

A re-paired device now says so. If a device is removed and paired again in the app it gets a new Local Key, and the driver used to be unable to tell that apart from a device that was simply unreachable. When it can see the device on the network and the key is the only thing being refused, it now tells you exactly that, and which button fixes it.

Devices behind a hub are named. Zigbee and battery devices paired through a hub cannot be controlled over the LAN by anything, because a hub does not expose a local key for them. Import now says which of your devices those are instead of leaving you to work it out.

What's new in v2.0

Finds the right protocol version on its own, every time. Earlier releases could get stuck partway through the search on devices that drop the connection rather than staying silent, and sit on the wrong version indefinitely. The search now handles both behaviors and always reaches an answer, or tells you plainly that it could not.

Says something useful when a device will not connect. A device with a wrong IP address, no power, or on the wrong network now produces a clear message in Last Error instead of leaving you with a device that is simply absent. The same applies to a device that stops accepting connections while the driver is running.

Connected now means the device has actually answered. Previously a device on protocol 3.3 reported Connected the moment the network socket opened, before it had said a word. A completely unresponsive device could sit there looking healthy. Connection State and each device's Online variable now wait for the device to genuinely respond, so a macro that keys on them can trust them.

Forcing a protocol version now actually forces it. If you pin 3.4 or 3.5, the driver stays on it rather than quietly searching away from your choice, and tells you clearly if that version turns out to be wrong.

Recovers gracefully when everything drops at once. If your Wi-Fi access point reboots, every Tuya device on the instance goes offline in the same instant. The driver now paces the recovery instead of trying to reconnect all of them simultaneously: a fixed number of devices reconnect per second, each device's retry is offset from its neighbors so they do not stay in lockstep, and the periodic keepalives are spread across the interval rather than all firing on the same tick. On a large install this keeps the processor from being hit with every reconnection and every encryption handshake at once. A single-device instance behaves exactly as it did before.

What's new in v1.9

Every command and every feedback variable now names its device. v1.8 kept a second, older set of commands (grouped under Legacy - always Device 1) and a matching set of feedback variables with no device number. They looked the same as the normal ones in Integration Designer but always addressed the first device, whatever the button said. Both sets have been removed, so there is now exactly one way to drive a device and it is always the one with the Device picker.

If you are updating from v1.8 or earlier, re-point your buttons. Any button or macro that used a command from Legacy - always Device 1, or a feedback variable without a device number (Power, Gang 1-6, All Data Points), needs the equivalent picked again from the normal category with Device set. Your driver settings, device IPs, Local Keys and learned RF codes are untouched. Everything is listed under Renamed in v1.9 below.

Local mode now reports each device's type. The Device Type variable for each device shows what you picked for it in the settings, which makes it obvious at a glance when a button is aimed at the wrong device. Previously only Cloud mode filled this in.

A clearer warning when a button is aimed at the wrong device. If you send an outlet command to a device that reports no outlets at all, and you have more than one device configured, the driver now says so in Last Error instead of only in the debug log.

New: Redetect Protocol. The driver remembers which protocol each local device spoke and re-uses it, which is right until the device itself changes - re-paired onto an older protocol, replaced, or a different device given the same IP. Until now that memory could not be overridden from the settings. System (all devices) > Redetect Protocol clears it, for one device or all of them, and runs the search again.

What's new in v1.8

One driver instance now handles up to 24 local devices. Local mode used to be one Wi-Fi device per instance. Now the first device goes in the Connection category as before, and an Additional Local Devices section reveals Device 2, then Device 3, and so on as you fill them in. Existing installations are untouched: the original fields are still Device 1 and every macro you have already written keeps working exactly as it did.

Every control now takes a Device. Power, Light, Cover, Fan, Multi-Gang, Timer and Data Points each have a Device parameter, so one button can drive whichever device you choose. (v1.8 also kept the original single-device functions alongside these; v1.9 removed them, see above.)

The driver works out the protocol version by itself. Leave Protocol Version on Auto. It starts on 3.3 and, if a device accepts the connection but never answers, tries 3.4 and then 3.5, then remembers whichever worked. No more running a scan to find out.

Data points can now be written on any device, not just the first one, which matters for devices set to Generic.

The settings page is far shorter. Cloud-only sections no longer appear on a Local instance and vice versa, and device fields appear one device at a time.

What's new in v1.7

Local mode now supports protocol 3.4 and 3.5 devices. Until now Local mode only spoke Tuya protocol 3.3, so newer devices could not be controlled locally at all. Local mode now speaks 3.3, 3.4 and 3.5, selected with the new Protocol Version setting. 3.4 and 3.5 devices negotiate an encrypted session with the device on every connection, so the Local Key is never sent over your network.

Local mode picks up changes made outside RTI more reliably. A 3.4 or 3.5 device reports a change made from the Tuya app, the physical button or a countdown timer in a different format from the one it uses to answer a status request. The driver now understands both, so those changes show up in RTI instead of being missed.

What's new in v1.6

Cloud mode now fits inside Tuya's free API allowance. Tuya's free developer tier includes a monthly allowance of cloud API calls, shared by everything on your Tuya project. The driver was polling your devices often enough to use that allowance up before the month ended, and once it is gone Tuya refuses every call, so the driver loses the whole account until the allowance refreshes. Polling is now half as frequent, which brings a single instance inside the free allowance with headroom left for your own button presses. The trade is that feedback from changes made outside RTI takes longer to appear; see the polling note in the Cloud section.

The driver says so when the allowance runs out. If Tuya reports the project's API quota exhausted, Last Error now names that as the cause and points at where to check it, instead of the driver appearing to have simply stopped working. It also slows its polling right down while that lasts, so it is not spending the next month's allowance the moment it refreshes.

What's new in v1.5

The driver tells you when a command goes to a device that is offline. Previously a button press aimed at a device that had dropped off Wi-Fi did nothing and reported nothing - the driver still showed as connected, because it was: connected to the cloud, not to that device. The device is now named in Last Error and in the processor System Log, with what to check. The command is still sent, so a device that has just come back is never blocked by a stale status.

Fan speeds map to the speeds your fan actually has. On some models the speed list a fan publishes begins with an off or auto entry, or is not in slow-to-fast order. Speed 1 could therefore switch the fan off, and the top speed could select auto. The driver now reads that list, sets aside the entries that are not speeds, and puts the rest in order before choosing.

Fan Direction only goes to a real fan. On some products the setting the driver used for direction is not a fan control at all - on a camera it is the pan control. Direction is now sent only when the device genuinely exposes forward and reverse, using that device's own wording; if it does not, the driver says so instead of sending anything.

Feedback that never moved now moves. On some dimmers the brightness variable stayed put while the light itself dimmed correctly, and on shutters that use the alternate command set the Cover State variable never updated. Both now track the device - including when a shutter is moved by its own wall remote rather than by the driver.

Correct colors from bulbs in Local mode. Some bulbs report color in a longer format than others. In Local mode that format was read the wrong way round, which produced nonsense red, green and blue values and a brightness reading far above 100 percent. Cloud mode already handled it; Local mode now uses the same code.

Device names with accents or non-Latin characters. Names such as Kuche, Salon or a name in Chinese are now read correctly, so slots pin by name the way they always should have. Previously those names arrived garbled and would not match what you typed in Driver Settings.

More accurate energy readings. Wattage is now corrected on metering plugs that mis-describe their own scale even when the plug does not report current, three-phase voltages are no longer divided down as if they were a mistake, and an idle plug reading zero volts is left alone.

Startup and connection robustness. If the driver cannot finish starting it now says so in Last Error and the System Log rather than stopping silently, and Cloud mode recovers on its own if its first connection attempt is refused while the processor is busy booting.

Also new in v1.4

Every outlet of a power strip, in Cloud mode. Multi-gang switches and power strips used to answer Power On/Off on their FIRST outlet only, because that is the outlet the standard power command reaches. There are now Outlet On / Outlet Off / Outlet Toggle functions with an Outlet picker (1-6), plus All Outlets On / Off, and an Outlet 1-6 feedback variable per device. See Multi-gang switches & power strips (Cloud) below.

Power On/Off/Toggle are unchanged - they still control outlet 1, so every button you have already programmed keeps doing exactly what it did before.

Clearer IR button lists. For a remote you TAUGHT in the Smart Life app, the startup log printed each button's internal id number instead of its name. It now prints the button names as the app shows them - which is what you type into IR Send Key.

Per-device events. Each named Cloud device now raises its own Power On, Power Off, State Changed, Came Online, Went Offline events, so a macro can react to one device instead of watching the whole driver. They fire only on a real change, not on every poll.

RADIO-FREQUENCY (RF) REMOTES NOW WORK - the headline change. Roller shutters, blinds, awnings and fans driven by a 433MHz remote taught into a Tuya IR+RF blaster can now be operated button by button. Previously nothing could reach them and the only option was a Tap-to-Run scene. You teach each button to the driver once, then bind it like any other command. See Roller shutters and other RF remotes below.

Correct brightness, color and energy readings on more devices. The driver now asks each device what ranges and units it actually uses instead of assuming. Older bulbs whose brightness slider snapped to about a quarter now track properly, and energy readings on metering plugs are no longer ten times out on models that mis-declare their own scale.

Shades that ran backwards can be corrected. New Invert Cover Position setting, set to Auto by default, which reads the motor's own preference where it reports one.

Ceiling fans and dimmers. Power now finds the fan motor on a ceiling-fan light (it used to only ever switch the lamp), and Tuya dimmers are now driveable at all.

Quieter, leaner polling. Devices that expose no status at all - blaster remotes and similar - were being polled on every cycle and failing every time. They are now detected and skipped, which frees those polling turns for devices that actually report something.

Also new in v1.2

Run Scene (Tap-to-Run). Trigger any Tap-to-Run you have built in the Smart Life app, by name. This is the way to control anything the driver cannot address directly - most importantly the devices operated through an IR or RF blaster, such as roller shutters, fans and air conditioners. See Devices behind an IR / RF blaster below.

Remotes from Tuya's code library. For blaster remotes chosen from Tuya's brand list, Open / Close / Stop and Power look up the matching button automatically, and IR Send Key presses any other button by name. The driver lists each remote's buttons in the processor System Log at startup.

Fixed: device names typed into slots 9 to 24 were ignored, so those devices never bound. All 24 slots now work. If you had typed names into slots 9 or higher, they now take effect - check your device slots after updating and confirm each button still points at the right one.

More resilient startup. If the processor boots before the internet is up - after a power cut, for example - the driver now keeps retrying the cloud connection on its own instead of sitting idle until someone reloads it. Its internal timers also recover if the processor is busy at the moment the driver starts.

Support

support@customcontroldrivers.com - customcontroldrivers.com