tuyapi

    7.2.0 • Public • Published

    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

    Install

    npm i tuyapi

    DownloadsWeekly Downloads

    27,920

    Version

    7.2.0

    License

    MIT

    Unpacked Size

    53.3 kB

    Total Files

    9

    Last publish

    Collaborators

    • codetheweb