TuyAPI 🌧 🔌

A library for communicating with devices that use the Tuya cloud network. These devices are branded under many different names, but if your device works with the TuyaSmart app or port 6668 is open on your device chances are this library will work.

Installation

npm install codetheweb/tuyapi

Basic Usage

See the setup instructions for how to find the needed parameters.

These examples should report the current status, set the default property to the opposite of what it currently is, then report the changed status. They will need to be adapted if your device does not have a boolean property at index 1 (i.e. it doesn't have an on/off property). Index 20 seems to be another somewhat common on/off property.

Asynchronous (event based, recommended)

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);

Synchronous

const TuyAPI = require('tuyapi');

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

(async () => {
  await device.find();

  await device.connect();

  let status = await device.get();

  console.log(`Current status: ${status}.`);

  await device.set({set: !status});

  status = await device.get();

  console.log(`New status: ${status}.`);

  device.disconnect();
})();

Data not updating?

Some new devices don't send data updates if the app isn't open.

These devices need to be "forced" to send updates. You can do so by calling refresh() (see docs), which will emit a dp-refresh event.

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(() => {
    // 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('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);

📝 Notes

Only one TCP connection can be in use with a device at once. If using this, do not have the app on your phone open.
Some devices ship with older firmware that may not work with tuyapi. If you're experiencing issues, please try updating the device's firmware in the official app.
Newer firmware may use protocol 3.3. If you are not using find(), you will need to manually pass version: 3.3 to the constructor.
TuyAPI does not support sensors due to the fact that they only connect to the network when their state changes. There are no plans to add support as it's out of scope to intercept network requests.
The key parameter for devices changes every time a device is removed and re-added to the TuyaSmart app. If you're getting decrypt errors, try getting the key again - it might have changed.

📓 Documentation

See the docs.

Contributing

See CONTRIBUTING.

Contributors

(If you're not on the above list, open a PR.)

Flash alternative firmware

tuya-convert a project that allows you to flash custom firmware OTA on devices

Ports

python-tuya a Python port by clach04
aiotuya a Python port by frawau
m4rcus.TuyaCore a .NET port by Marcus-L
TuyaKit a .NET port by eppz
py60800/tuya a Go port by py60800
rust-tuyapi a Rust port by EmilSodergren

Clients for Tuya's Cloud

cloudtuya by unparagoned

Projects built with TuyAPI

tuya-cli: a CLI interface for Tuya devices
homebridge-tuya: a Homebridge plugin for Tuya devices
tuyaweb: a web interface for controlling devices by bmachek
homebridge-igenix-air-conditioner: a Homebridge plugin for the Igenix IG9901WIFI air conditioner
magichome-led-controller: a node to use magichome led RGB controller in node-red
ioBroker.tuya: an ioBroker (http://iobroker.net/) adapter to get data and control devices incl. schema parsing
node-red-contrib-tuya-smart: A NodeRED input node utilizing tuyapi to connect the smart home
tuyadump a Go project to decode device traffic in real time
tuya-mqtt a simple MQTT interface for TuyAPI

To add your project to either of the above lists, please open a pull request.

oliveiraallex/tuyapi