Smart Life / Tuya

Overview

This PG3x plugin integrates compatible Smart Life / Tuya devices with Universal Devices eisy and IoX. Devices are controlled directly over the local network using TinyTuya, allowing normal operation without routing commands through the Tuya cloud.

Smart Life / Tuya Setup

Before the plugin can control a fan locally, you must obtain several pieces of information about the Tuya device: its Device ID, Local Key, local IP address, and Tuya protocol version. The easiest method is to first add the fan to Smart Life or Tuya Smart, create a Tuya developer project, and then run the TinyTuya setup wizard on the eisy.

1. Add the Fan to Smart Life or Tuya Smart

1. Install Smart Life or Tuya Smart on your phone.
2. Pair the fan/controller with the app in the normal manner.
3. Verify that the fan can be controlled successfully from the app before continuing.

2. Create a Tuya IoT Developer Project

Using a web browser, go to Tuya IoT Platform and create or sign into a Tuya IoT developer account.

1. Create a new Cloud project for Smart Home devices.
2. Select the data center/region corresponding to the Smart Life or Tuya Smart account used to pair the fan.
3. Open the project Overview page.
4. Locate the project's Access ID / Client ID and Access Secret / Client Secret. These will be used by the TinyTuya wizard.

3. Link Your Smart Life / Tuya Smart Account

1. In the Tuya IoT project, open the Devices section.
2. Select Link Tuya App Account.
3. Select Add App Account.
4. A QR code will be displayed.
5. Open Smart Life or Tuya Smart on your phone and use its QR-code scanner to scan the code.
6. Confirm the account link.
7. Verify that the fan appears in the Tuya IoT project device list.

4. Connect to the eisy Using SSH

SSH provides a command-line connection to the eisy. No additional SSH software is normally required on current versions of Windows.

Find the eisy IP Address

Find the eisy in your router's client/device list and note its local IP address. An address will typically look something like:

192.168.1.50

Your address will probably be different. Use the actual IP address assigned to your eisy.

Open a Terminal in Windows

1. Right-click the Windows Start button.
2. Select Terminal. Windows PowerShell or Command Prompt may also be used.
3. At the prompt, enter ssh admin@ followed by the eisy IP address.

For example:

ssh admin@192.168.1.50

First SSH Connection

The first time you connect to an eisy, SSH may display a message similar to:

The authenticity of host '192.168.1.50' can't be established.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Type:

yes

Log In

The default eisy SSH login is:

If the password has previously been changed, use the current password instead.

After a successful login, you should see a command prompt similar to:

[admin@eisy ~]$

You are now operating at the eisy command line.

5. Install TinyTuya and Run the Wizard

At the eisy SSH prompt, first make sure TinyTuya is installed:

python3 -m pip install --user --upgrade tinytuya

After the installation completes, run the TinyTuya setup wizard:

cd /home/admin
python3 -m tinytuya wizard

The TinyTuya wizard will ask for information from the Tuya IoT project, including the API/Access ID, API/Access Secret, Device ID, and region. If TinyTuya has been configured previously, it may display the saved settings and ask:

Use existing credentials (Y/n):

Press Enter to accept the existing credentials, or answer n if new Tuya project credentials need to be entered.

The wizard will then ask whether to download DP name mappings. Answer y. DP (Data Point) mappings provide descriptive information about the functions exposed by Tuya devices.

Download DP name mappings? (Y/n): y

When asked whether to poll local devices, answer y:

Poll local devices? (Y/n): y

TinyTuya will scan the local network for Tuya devices and attempt to communicate with them directly. A successful scan will look similar to:

Scanning local network for Tuya devices...
    2 local devices discovered

Polling local devices...
    [Patio Fan East] 192.168.1.50 - [On] - DPS: {...}
    [Patio Fan West] 192.168.1.51 - [On] - DPS: {...}

>> Saving device snapshot data to snapshot.json
>> Saving IP addresses to devices.json

Done.

The names and IP addresses shown above are only examples. Your devices and addresses will be different.

When successful, TinyTuya creates or updates:

/home/admin/devices.json

The devices.json file contains the Tuya device information needed to configure the plugin, including Device IDs, Local Keys, and discovered local IP addresses.

6. Identify the Fan Information

For each fan you intend to configure, identify:

7. Enter the Information in PG3x

Open the Tuya Fan plugin in PG3x and enter the information under Custom Configuration Parameters.

For the first fan:

Additional fans use fan2_*, fan3_*, and so forth.

8. Save and Restart the Plugin

1. Save the Custom Configuration Parameters.
2. Restart the Tuya Fan plugin.
3. Open IoX and verify that the fan node appears.
4. Test Fan On, Fan Off, and Fan Speed.

Configuration

Each fan is configured using PG3x Custom Parameters. The parameter number corresponds to the fan number.

For additional fans use fan2_*, fan3_*, and so on through fan16_*.

After changing Custom Parameters, save the changes and restart the plugin.

Smart Life / Tuya Power Switches

In addition to ceiling fans, the plugin supports compatible Smart Life / Tuya power switches. Supported switches appear as native IoX nodes and can provide local On/Off control along with electrical measurements when those values are exposed by the device.

Switch Configuration

Power switches are configured using PG3x Custom Parameters in the same manner as ceiling fans. For the first switch use:

Additional switches use switch2_*, switch3_*, and so forth through switch16_*.

IoX Switch Node

A configured power switch provides standard IoX On and Off commands. After an On or Off command is sent, the plugin queries the device to confirm its actual relay state rather than simply assuming that the command succeeded.

Energy Monitoring

When supported by the Tuya switch, the node also reports electrical measurements supplied by the device:

Metering values are refreshed approximately every 30 seconds, independently of the normal PG3x polling interval. This allows changing power consumption to be reflected in IoX without requiring frequent polling of every device by PG3x.

Switch Communication

The switch implementation opens a new local Tuya connection when communicating with the device rather than maintaining an idle persistent socket. This improves compatibility with tested Tuya 3.5 switches that may silently expire an idle persistent connection.

Ceiling Fan Nodes & Functions

Using Ceiling Fans in IoX Scenes

IoX scenes can use the fan node as a responder. Because a responder normally selects one command for the node, the Fan Speed command automatically includes Fan On behavior.

For example, four keypad buttons can provide simple preset control:

A speed command therefore works whether the fan is already running or currently off.

Tested Hardware

Other Tuya ceiling fan controllers may work if they use the same DPS mapping.

DPS Mapping

Local Operation

Once configured, normal fan control and status polling occur directly between eisy and the Tuya device over the LAN.

Internet or Tuya cloud availability is therefore not required for routine fan operation.

Troubleshooting

• If a fan's IP address changes, update the corresponding fan*_ip parameter or use a DHCP reservation.
• If a device is reset, removed, or re-paired, its Local Key may change. Run the TinyTuya wizard again to obtain the current key.
• Local communication failure: if the fan continues to work through the Smart Life/Tuya app but stops responding to the plugin, completely power-cycle the fan/controller by removing AC power and restoring it. Testing has shown that a controller can remain online and accessible through the Tuya cloud while its local Tuya protocol stops responding. A full power cycle can restore local LAN communication.
• After changing Custom Parameters, restart the plugin.

Security Notes

• The Tuya Local Key is a credential. Do not publish it or commit it to Git.
• Do not include Local Keys, Tuya API secrets, or other credentials in screenshots, logs, or public support requests.
• Configuration credentials are stored in PG3x Custom Parameters rather than in this repository.

Version

Current version: 1.2.0

Version 1.2.0 expands the plugin beyond ceiling fans with support for compatible Smart Life / Tuya power switches, including local On/Off control and energy-monitoring values where supported by the device. Ceiling fan control remains fully supported.