tuyapi

🌧 An easy-to-use API for devices that use Tuya's cloud services. Documentation: https://codetheweb.github.io/tuyapi.

codetheweb
2108
344
JavaScript

TuyAPI 🌧 🔌

XO code style
Build Status
Coverage Status
Node Version

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.

Current State & the Future of TuyAPI

The goal of this repository specifically is to provide a bit of a middle ground between implementing everything from scratch and having everything handled for you.

I realize this is a bit wishy-washy and most users would prefer one or the other. I started a new library a while ago to address this and incorporate some of the lessons we’ve learned over the years: @tuyapi/driver. The intention is that this library would be fairly low-level, and then more user-friendly libraries could be built on top of it to provide common functionality for, say, setting RGB light values (probably named @tuyapi/devices).

Unfortunately, not much progress has been made in that regard for a few reasons. First, besides the occasional coffee (thank you 😀) I don’t get paid for this. And it’s hard to be motivated to work on it when I don’t actually use it day-to-day. For lack of a beter explanation, it’s just not “fun” anymore. Also: trying to play wack-a-mole with a large corporation is kinda exhausting.

TL;DR: all that to say that I personally will not be further developing Tuya-related projects for the foreseeable future besides fixing reproducable bugs. I plan to still respond to support requests and bug reports, but please be patient. 😀

Contributing

See CONTRIBUTING.

Contributors

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

Related

Flash alternative firmware

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

Ports

Clients for Tuya’s Cloud

Projects built with TuyAPI

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

forthebadge
forthebadge