Tuya V2 Installation and Usage Guide

Date: Tuesday, 10 August 2021Authors:

Contents

Overview...............................................................................................................................................................................3

Features.................................................................................................................................................................................................. 4

Applications.........................................................................................................................................................................5

Important Information........................................................................................................................................................6

Disclaimer.............................................................................................................................................................................7

Setting up your Tuya devices..............................................................................................................................................8

Quick Start Guide..............................................................................................................................................................17

Adding the driver to Composer........................................................................................................................................18

Adding the agent to your project....................................................................................................................................19

Setting up individual drivers............................................................................................................................................22

Additional Notes................................................................................................................................................................24

Licensing............................................................................................................................................................................25

Creating a Project on Driver Central...............................................................................................................................25

Purchasing a Driver Licence.............................................................................................................................................26

Install the driverCentral cloud driver..............................................................................................................................27

Install Chowmain driver...................................................................................................................................................28

Page 2

Overview

Tuya provides a leading global IoT platform that enables manufacturers, brands, OEMs and retail chains to

develop one-stop smart home solutions

To-date, Tuya has 180,000 clients in over 190 countries who are delivering over 90 thousand Powered by

Tuya products, covering 500 types of products, ranking the first in the industry, including lighting, appliances,

entertainment and security solutions.

The Chowmain Tuya agent integrates Tuya enabled devices into Control4 for bi-directional control and

feedback.

V2 of the Tuya Driver offers many benefits over the original driver, including access to a wider range of

functionality using variables, increased feedback performance (with the option to subscribe to TUYA Cloud

Services to further increase the performance to realtime speeds) and support using the official API which

offers long term support.

V1 and V2 drivers are NOT intercompatible. New V2 Devices will need to be reconfigured in Control4

Note This is built as a Control4 Agent and will only work on Control4 OS 3.1.3 and above.

Note This solution is cloud based and as such requires an active internet connection for operation.

Page 3

Features• Bi-directional control / feedback

• Supported Device Types Include

• CLIMATE - These are HVAC based devices which can include thermostats, split systems, wall

furnaces, portable air conditioners, oil heaters and more providing the ability to change HVAC

modes, fan speeds and setpoints with room temperature feedback.

• COVER - These are up, down, stop based devices which can include blinds, curtains,

projection screens and garage doors

• FAN - These are multi speed fan devices which can include ceiling fans, tower fans and floor

fans.

• LIGHT - These are lighting products which can include on/off lighting loads, dimmable loads

and RGB/W loads such as on-wall switches/dimmers, bulbs, strips, spotlights, garden lights,

Christmas lights and more. Setting of LED colors is also supported

• SWITCH - These are on/off devices which can include relays, on/off lighting loads, smart

plugs, power boards, air purifiers, aroma diffusers, kettles, robot vacuum cleaners and more.

• GENERIC - Support for "Utility"/Generic devices which collect information, or allow access

• The agent logs into your Tuya account scans all available devices.

• Auto polls for feedback every 5 minutes. Control is instantaneous. For faster poll rates, subscription

services are available from Tuya

Page 4

Applications

• Thousands of brands utilise Tuya's technology. Many products that you find on the shelf at bunnings,

home depot, kmart, walmart and other retailers are Tuya enabled or can be found online at Amazon,

Kogan, eBay, Aliexpress and other online marketplaces. Some of these will have a 'Powered by Tuya'

logo on it to signify that it uses Tuya. Others may hide this fact so you may need to do some research.

• Tuya brands are usually more affordable than other brands. As such it can bring down the price of

solutions for HVAC, Lighting, Power, Shading and more.

• There are alot of unique products that you can integrate including (but not limited to)

• Aroma Diffusers

• Air Purifiers

• Christmas Lights

• Kettles

• Robot vacuum cleaners

• Known Tuya brand partners include

• 3Stone

• Aldi

• Amysen

• Anko

• Avatto

• Arlec

• Best Buy

• Brilliant

• Commercial Electric

• Feit Electric

• Globe Electric

• Girien

• Gosund

• Kogan

• KMC

• Jinvoo

• LoraTap

• Mirabella

• Offong

• Teckin

Page 5

Important Information

• This is built as a Control4 Agent and will only work on Control4 OS 3.1.3 and above.

• This solution is cloud based and as such requires an active internet connection for operation.

• Feedback is polled once every 5 minutes. Control is instant. For faster poll rates, a subscription is

required to avoid hitting the rate limits.

• This will only work on wifi based Tuya devices (Zigbee based devices will not work even through a

hub)

• Not all commands are exposed. However, almost all are accessible using read/write variables via

programming or by combining drivers

Page 6

Disclaimer

This driver relies on Tuyas cloud service (homeassistant endpoint) and as such Chowmain cannot guarantee

the uptime or indefinite availability of this services. Do not utilise this driver for any safety systems or

systems that cannot handle any form of down time from this driver.

Page 7

Setting up your Tuya devices

Please complete the steps below before you start setting up the driver.

1. Download the 'TuyaSmart' app from Apple AppStore or Google Playstore or alternatively download

the 'SmartLife' app from Apple AppStore or Google Playstore

2. Launch the app and click 'Sign Up'

3. Note it is easier to sign up via an email address rather than Google or Apple so sign up via an email

address.

Page 8

4. Add devices by clicking on the '+' button.

5. Follow the prompts until all of your devices have been added in.

Page 9

6. Sign up to Tuya IOT Portal and verify the email address. Use the created login to login to the IOT

portal. Skip the wizard which pops up

7. Select Cloud-Development from the left menu. You will need to sign up for a plan. The Trial plan

safely allows Control4 to poll for feedback approximately every 300s and the trial is updated on a

yearly basis. 2,678,400 API calls allows a poll rate of up to 1s (excluding additional calls to perform

actions). The recommended formula to determine maximum poll rate is

2678400/(TOTAL_API_CALLS - API_CALLS_RESERVED_FOR_ACTIONS). We normally use 20000 for

API_CALLS_RESERVED_FOR_ACTIONS, however, if you send lots of commands, you may need more

(if you don't send many commands, you can use less, but you risk rate limiting at end of month).

Page 10

8. Return to Cloud, and Create Cloud Project. Select Development Method "Smart Home". For

Availability, pick a region which is close to you. To determine the server with best Performance, ping

the following servers, and use the server with the lowest ping:

• China - https://openapi.tuyacn.com

• Europe - https://openapi.tuyaeu.com

• India - https://openapi.tuyain.com

• America - https://openapi.tuyaus.com

• Western Europe - https://openapi-weaz.tuyaeu.com

• Eastern America - https://openapi-ueueaz.tuyaus.com

Page 11

9. The default Authorised API Products are suitable. Press Authorize

Page 12

10.Select the newly created Cloud. Record the Cloud Application Authorization Key and Access

Secret/Client Secret. These will be required by the Tuya V2 Agent Driver

Page 13

11.Go to Devices, Link Tuya App Account, and Add App Account. A QR code will show

Page 14

12.On your phone in Tuya Smart App, go to "Me", and select the barcode scanner function to link your

account. Confirm the login

13.Under Link Tuya App Account in your browser, record the UID (it will be required for the Tuya V2

Agent and ensure that the number of devices matches.

Page 15

Page 16

Quick Start Guide

IMPORTANT - Perform Licencing Steps as outlined above first

1. Install Tuya V2 Agent (Do not confuse with Tuya V1 Agent). Keep in mind, Agents are available under

the AGENT section of Composer after installing, not System Design (or System Design Search).

2. Download the 'TuyaSmart' app from Apple AppStore or Google Playstore or alternatively download

the 'SmartLife' app from Apple AppStore or Google Playstore

3. Setup all devices in the Tuya Android App. Please note, Zigbee Tuya Devices are NOT supported

4. Create a seperate account on https://iot.tuya.com

1. Create a cloud account (Trial allows a poll time of 300s and will automatically be renewed at

the end of the year)

2. Select the correct server in Tuya Agent. Then add the Access Secret and Client ID to the Tuya

Agent.

3. In the cloud settings, go to Devices, Link Tuya App Account which will create a QR code

4. Under "Me" on the mobile phone app, press the Barcode Scanner button (the square with as

line in it on the top right hand corner of the app), and scan the QR code from

https://iot.tuya.com

5. Add the newly created UID to Tuya Agent and the drivers should be listed as available

5. Ensure all C4Z files have been added to Control4 or Auto-config will fail.

6. In Tuya Agent, Press Auto Setup, and all known devices will be added.

1. Due to the complexity of the Tuya Ecosystem, in some cases, the incorrect driver may be

added. Simply add the correct one instead, and add the device ID

2. Some devices such as switch switches with multiple buttons may only be added once. To

support the additional buttons, add additional instances of the driver, and set the Code

properties as required.

7. Some devices may need codes to be manually set in their properties if they function incorrectly.

8. Refresh Navigators after everything is set up

Page 17

Adding the driver to Composer

1. The driver you have downloaded will be in a zip file. Double click on this file to open it in your

preferred zip program (WinZip, WinRar, etc.)

2. Extract the c4z file to the My Documents\Control4\Drivers directory. If you are using Windows 7 or

8 this will be extracted to the Libraries\Documents\Control4\Drivers directory.

You are now ready to add and configure the driver via the Composer Pro software.

Page 18

Adding the agent to your project

1. Launch the Composer Pro application and connect to your project

2. Select Agents view button

3. Select the Add… button

4. Search for Tuya and double click on the listed Tuya Agent V2 (Chowmain) agent

Page 19

5. Enter in your Secret and Client ID afrom the Cloud section of https://iot.tuya.com and press Set

6. Type in your User ID available from https://iot.tuya.com, Devices, Link Tuya App account and press

set

7. If you are successful at logging in the number of devices will change to show you how many devices it

discovered on your Tuya account.

8. Click on Connections and highlight the Tuya driver

Page 20

9. If it did not import all of your devices then you will need to manually add in the device via the agent's

'Add Custom Device' action

10.The 'Add Custom Device' action will prompt you for the device name (this does not have to match

what is on the Tuya app), virtual ID (This has to match what is on the tuya app) and the device type

(this will allow you to bind the correct device driver to it). If you do not know how to get the virtual ID

then please refer to the section labelled 'How to get a device's virtual ID' in this document.

11.Install the appropriate Tuya driver for each device binding.

Page 21

12.Bind each device to the appropriate binding and it will automatically rename the device. This is a

once off rename which is done on binding and can be disabled by changing the Auto Rename Device

property in the device driver's properties.

13.Some device driver has some unique setup properties which you may need to set. Please refer to this

via the sections below

14.Refresh Navigator

15.Congratulations you have successfully installed the Tuya agent for Control4

Setting up individual drivers

Certain Tuya drivers require additional setup where others have no setup at all. The drivers that require

additional setup are as follows

Page 22

Tuya Climate

Tuya Climate integration cannot detect what the capabilities are of the device you are trying to integrate. As

such you will need to set the available HVAC modes and Fan modes for the device via the driver's properties

Tuya Switch (Button / Outlet)

Switch based devices have the ability to assign an appropriate on/off icon to the experience button. Every

single power socket variant is included so if you are integrating a smart plug, power board or power outlet

please select the correct outlet type for your region.

We have also included some on/off icons for other appliances. Please select the desired button type if you

are using an appliance.

Tuya Fan

Control4 does not have the ability to dynamically set the maximum number of fan speeds. As such we have

limited fan control to off, low, medium and high speeds. You will need to map the appropriate speeds via the

driver's properties page to your desired low, medium and high speeds.

Page 23

Additional Notes

• This agent communicates via the Tuya cloud. As such if internet is disrupted the agent will lose

control over the devices.

• The agent will poll for updates once every 5 minutes by default. On the trial Tuya Cloud Trial plan, this

ensures that there are sufficient remaining calls remaining to perform other actions. It is possible to

pay for more API calls

• The recommended formula to determine maximum poll rate is 2678400/(TOTAL_API_CALLS -

API_CALLS_RESERVED_FOR_ACTIONS). We normally use 20000 for

API_CALLS_RESERVED_FOR_ACTIONS, however, if you send lots of commands, you may

need more (if you don't send many commands, you can use less, but you risk rate limiting at

end of month).

• Due to Tuya's incredibly broad device support, not all commands are exposed through the Control4

GUI. However, most commands and data are exposed via Control4 variables. To determine their

available parameters, use the "Display Variables Directory" action.

Page 24

Licensing

• How does the trial period work?

All Chowmain drivers are free to use for a set trial period. When the trial expires the driver will cease

to function until you purchase a licence and apply it to the driverCentral project.

• Where do I buy a Licence from?

This driver is developed by Chowmain software & Apps and is distributed by driverCentral, Inc

https://www.drivercentral.io/chowmain-ltd

To purchase a driver:

1) On driverCentral, purchase a license and register it to your project

1) If the driver is not already installed in your project, download it and install it

1) If necessary, use the cloud driver’s Action: “Check Drivers” to force the licence to download into

the project

Creating a Project on Driver Central

1. Visit http://www.drivercentral.io

2. Log into your driver Central dealer account

3. Click Portal

4. Click New Project

5. Enter the project name

6. Click Add Project

7. Click on the project we just created

Page 25

8. Take note of the Project Token as this will be used later when we install the Cloud Driver

9. Click Close

Purchasing a Driver Licence

1. Visit https://www.drivercentral.io/chowmain-ltd/ and find the product/driver you want to purchase a

licence for

2. Click on Add to Cart

3. Now click the shopping cart icon (top right) and click View cart

4. Confirm that your order is correct and click on Proceed to checkout

5. Choose your payment option, provide the relevent details and click Place order

Page 26

6. You will now be at a page where you can see your purchased licence

7. From here assign the licence to the project we created or if you did not follow that step create a new

project

Install the driverCentral cloud driver

1. Visit http://www.drivercentral.io

2. Log into your driver Central dealer account

3. Click Portal

4. Click Cloud Driver

Page 27

5. Copy the C4Z driver to My Documents\Control4\Drivers directory

6. Add the driver to your project

7. Click on the driver to view it’s properties

8. Type in the project token we took note of earlier

9. Click Actions tab

10.Click Check Drivers

Install Chowmain driver

1. Install the Chowmain driver

2. You will notice that the Activation Status reflects a Licence Activated state

3. Any driver that does not have a purchased licence will have a trial licence activated via the

marketplace

Note that there is no way to reactivate the trial so please use wisely

4. If you do not then press the Check Drivers action in the driverCentral Cloud driver again

Page 28