TuyAPI

To construct a TuyAPI instance, you need three specific parameters: id (uuid), uid (productId), and key (localKey). You can intercept the HTTPS traffic from your device's official app using Charles Proxy on macOS to find these values.

Steps:

1. Setup Charles Proxy: Download Charles and turn off the local proxy for your computer and disable recording temporarily.
2. SSL Certificate: Install the Charles SSL certificate on your phone. On iOS, you may need to navigate to Settings > General > About > Certificate Trust Settings to fully trust it.
3. Proxy Traffic: Configure your phone to proxy its traffic through your computer's IP address.
4. Capture Data:
   • Open the device's official app and remove the existing device if it's already added.
   • Add the device in the app.
   • Crucial: Pause and turn recording back on in Charles right after entering your Wi-Fi password, then turn it off once the device is successfully added.
5. Identify Request: Look for the HTTPS request where the parameter a=s.m.dev.list is present.
6. Extract Parameters: From the response body, extract the following mapping:
   • id: uuid
   • uid: productId
   • key: localKey

{
  id: uuid,
  uid: productId,
  key: localKey
}

If you have a rooted Android device, you can bypass network sniffing by reading the app's shared preferences directly.

Smart Life App

Locate the settings at: /data/data/com.tuya.smartlife/shared_prefs/dev_data_storage.xml

Inside this file, look for the tuya_data string. This string is HTML entity encoded; you must decode it to reveal a JSON string containing your device keys.

Jinvoo Smart App

Locate the settings at: /data/data/com.xenon.jinvoo/shared_prefs/gw_storage.xml

You can use a Python script to parse this XML and extract the device metadata, including localKey, uuid, and the device schema.

#!/usr/bin/env python
# -*- coding: us-ascii -*-
# vim:ts=4:sw=4:softtabstop=4:smarttab:expandtab
#

import codecs
import os
import json
import xml.etree.ElementTree as ET

try:
    # Python 2.6-2.7 
    from HTMLParser import HTMLParser
except ImportError:
    # Python 3
    from html.parser import HTMLParser  ## FIXME use html.unescape()


xml_in_filename = 'com.xenon.jinvoo/shared_prefs/gw_storage.xml'
h = open(xml_in_filename, 'r')
xml = h.read()
h.close()

builder = ET.XMLTreeBuilder()
builder.feed(xml)
tree = builder.close()


h = HTMLParser()
for entry in tree.findall('string'):
    if entry.get('name') == 'gw_dev':
        # found it, need content
        config = entry.text
        s = h.unescape(config)
        config_dict = json.loads(s)
        #print(config_dict)
        print(len(config_dict))
        for device in config_dict:
            #print(device)
            for key in ['name', 'localKey', 'uuid', 'gwType', 'verSw', 'iconUrl']:  # and/or 'gwId', 'devId'
                print('%s = %r' % (key, device[key]))
            # there is a bunch of interesting meta data about the device
            print('schema =\')
            schema = device['devices'][0]['schema']  # NOTE I've only seen single entries
            schema = h.unescape(schema)
            schema_dict = json.loads(schema)
            print(json.dumps(schema_dict, indent=4))
            print('')
        print(json.dumps(config_dict, indent=4))

The recommended way to use TuyAPI is through an asynchronous, event-based approach. This allows you to listen for connection changes, errors, and incoming data updates from the device.

Key events:

• connected: Emitted when the connection to the device is established.
• disconnected: Emitted when the connection is lost.
• error: Emitted when an error occurs.
• data: Emitted when the device sends data updates. The data object contains a dps property with device parameters (e.g., data.dps['1']).
• dp-refresh: Emitted when a manual refresh is triggered on certain devices.

const TuyAPI = require('tuyapi');

const device = new TuyAPI({
  id: 'xxxxxxxxxxxxxxxxxxxx',
  key: 'xxxxxxxxxxxxxxxx'});

let stateHasChanged = false;

// Find device on network
device.find().then(() => {
  // Connect to device
  device.connect();
});

// Add event listeners
device.on('connected', () => {
  console.log('Connected to device!');
});

device.on('disconnected', () => {
  console.log('Disconnected from device.');
});

device.on('error', error => {
  console.log('Error!', error);
});

device.on('data', data => {
  console.log('Data from device:', data);

  console.log(`Boolean status of default property: ${data.dps['1']}.`);

  // Set default property to opposite
  if (!stateHasChanged) {
    device.set({set: !(data.dps['1'])});

    // Otherwise we'll be stuck in an endless
    // loop of toggling the state.
    stateHasChanged = true;
  }
});

// Disconnect after 10 seconds
setTimeout(() => { device.disconnect(); }, 10000);

Use this method if you want to link devices regardless of whether they are currently in a Tuya app. This requires a developer account at iot.tuya.com.

1. Create a Developer Project

• Sign up at iot.tuya.com (Select United States as your country to skip verification).
• Go to Cloud -> Development and create a project.
• Important: Select Smart Home for both Industry and Development Method.
• Note your Access ID/Client ID and Access Secret/Client Secret.

2. Authorize API Services

• Go to Cloud -> Development -> [Your Project] -> Service API -> Go to authorize.
• Subscribe to the following services (use the basic edition which is free):
  • IoT Core
  • Authorization
  • Smart Home Scene Linkage
• Verify they are listed under Cloud -> Projects -> [Your Project] -> API.

3. Create an App SDK

• Go to App -> App SDK -> Development.
• Click Create. Enter a package name (Android must start with com.) and a Channel ID.
• The Channel ID is your schema value for the CLI command.

4. Link the App to the Project

• Go to Cloud -> Development -> [Your Project] -> Link Device.
• Click Link devices by Apps -> Add Apps and select the app you just created.

5. Run the Link Command

• Put your physical device into pairing mode (refer to your device's manual).
• Ensure any Tuya apps on your phone are completely closed.
• Run the following command:

tuya-cli link --api-key <your api key> --api-secret <your api secret> --schema <your schema/Channel ID> --ssid <your WiFi name> --password <your WiFi password> --region <us|eu|cn>

Note: For --region, use the two-letter code (us, eu, or cn) geographically closest to you.

tuya-cli link --api-key <your api key> --api-secret <your api secret> --schema <your schema/Channel ID> --ssid <your WiFi name> --password <your WiFi password> --region us

Some newer devices do not send data updates unless the official app is open. To receive updates from these devices, you must "force" them by calling refresh().

When using this method, you should listen for the dp-refresh event. You can also use the issueRefreshOnConnect: true option in the constructor to attempt this on connection.

const TuyAPI = require('tuyapi');

const device = new TuyAPI({
    id: 'xxxxxxxxxxxxxxxxxxxx',
    key: 'xxxxxxxxxxxxxxxx',
    ip: 'xxx.xxx.xxx.xxx',
    version: '3.3',
    issueRefreshOnConnect: true});

// Find device on network
device.find().then(() => {
    device.connect();
});

// Add event listeners
device.on('connected', () => {
    console.log('Connected to device!');
});

device.on('disconnected', () => {
    console.log('Disconnected from device.');
});

device.on('error', error => {
    console.log('Error!', error);
});

device.on('dp-refresh', data => {
    console.log('DP_REFRESH data from device: ', data);
});

device.on('data', data => {
    console.log('DATA from device: ', data);
});

// Disconnect after 10 seconds
setTimeout(() => { device.disconnect(); }, 1000);