tinytuya

TinyTuya

Python module to interface with Tuya WiFi smart devices

Description

This python module controls and reads state of Tuya compatible WiFi Smart Devices (Plugs, Switches, Lights, Window Covers, etc.) using the local area network (LAN) or the cloud (TuyaCloud API). This is a compatible replacement for the pytuya PyPI module and currently supports Tuya Protocols 3.1, 3.2, 3.3, 3.4 and 3.5.

Tuya devices are designed to communicate with the TuyaCloud but most also expose a local area network API. This allows us to directly control the devices without using the cloud. This python module provides a way to poll status and issue commands to these devices.

TinyTuya can also connect to the Tuya Cloud to poll status and issue commands to Tuya devices.

# Example Usage of TinyTuya
import tinytuya

d = tinytuya.Device('DEVICE_ID_HERE', 'IP_ADDRESS_HERE', 'LOCAL_KEY_HERE', version=3.3)  # Set version to match your device (3.1, 3.2, 3.3, 3.4, or 3.5)
data = d.status() 
print('Device status: %r' % data)

NOTE: Devices need to be activated by Smart Life App.

TinyTuya Installation

# Install TinyTuya Library
python -m pip install tinytuya

# Optional: Install Command Line Tool
pipx install tinytuya

Pip will attempt to install cryptography, requests and colorama if not already installed.

Alternate Install on Space- or Dependency-Limited Systems

On systems with limited space (such as an OpenWRT router), or if you would like to use a different cryptography library, you can install TinyTuya without automatic dependencies and manually install them yourself.

First, install a cryptography library. TinyTuya supports:

• cryptography - Newest, requires OpenSSL - python -m pip install cryptography
• PyCryptodome - Another good alternative, does not require OpenSSL, still actively developed - python -m pip install pycryptodome or python -m pip install pycryptodomex
• pyaes - Pure Python, but is abandoned and does not support v3.5+ devices - python -m pip install pyaes
• PyCrypto - Predecessor to PyCryptodome, is also abandoned and does not support v3.5+ devices - python -m pip install pycrypto

Optional: install colorama for terminal color support: python -m pip install colorama

Required for Wizard or Cloud functionality, Optional otherwise: install requests for Cloud functions to work: python -m pip install requests

Finally, install TinyTuya without dependencies: python -m pip install --no-deps tinytuya

Tuya Device Preparation

Controlling and monitoring Tuya devices on your network requires the following:

• Address - Network address (IPv4) of the device e.g. 10.0.1.100
• Device ID - Unique identifier for the Tuya device
• Version - Tuya protocol version used (3.1, 3.2, 3.3, 3.4 or 3.5)
• Local_Key - Security key needed to access the Tuya device. See Setup Wizard to get these keys.

Network Scanner

TinyTuya has a built in network scanner that can be used to find Tuya Devices on your local network. It will show Address, Device ID and Version for each device. Your LAN and firewall will need to allow UDP (6666, 6667 and 7000) and TCP (6668) traffic.

python -m tinytuya scan

Setup Wizard - Getting Local Keys

TinyTuya has a built-in setup Wizard that uses the Tuya IoT Cloud Platform to generate a JSON list (devices.json) of all your registered devices, including secret Local_Key and Name of your devices. Follow the steps below:

1. PAIR - Download the Smart Life App or Tuya Smart App, available for iPhone or Android. Set up your SmartLife account and pair all of your Tuya devices (this is important as you cannot access a device that has not been paired). Do not use a ‘guest’ account, otherwise it will get deleted without confirmation at step 3.

2. SCAN (Optional) - Run the TinyTuya scan to get a list of Tuya devices on your network. It will show device Address, Device ID and Version number (3.x):

   python -m tinytuya scan
   

   NOTE: You will need to use one of the displayed Device IDs for step 4.

3. TUYA ACCOUNT - Set up a Tuya Account (see PDF Instructions):

   • NOTE: Tuya often changes their portal and services. Please open an issue with screenshots if we need to update these instructions.
   • Create a Tuya Developer account on iot.tuya.com. When it asks for the “Account Type”, select “Skip this step…” (see screenshot).
   • Click on “Cloud” icon -> “Create Cloud Project”
     1. Pick the correct Data Center “Region” for your location (check HERE to find your Region). This will be used by TinyTuya Wizard (screenshot).
     2. Skip the configuration wizard but remember the Authorization Key: API ID and Secret for below (screenshot).
   • Click on “Cloud” icon -> Select your project -> Devices -> Link Tuya App Account (see screenshot)
   • Click Add App Account (screenshot) and it will pop-up a “Link Tuya App Account” dialog, chose “Automatic” and “Read Only Status” (it will still alow commands). Click OK and it will display a QR code. Scan the QR code with the Smart Life app on your Phone (see step 1 above) by going to the “Me” tab in the Smart Life app and clicking on the QR code button [..] in the upper right hand corner of the app. When you scan the QR code, it will link all of the devices registered in your Smart Life app into your Tuya IoT project. If the QR code will not scan then make sure to disable any browser theming plug-ins (such as Dark Reader) and try again.
   • NO DEVICES? If no devices show up after scanning the QR code, you will need to select a different data center and edit your project (or create a new one) until you see your paired devices from the Smart Life App show up. (screenshot). The data center may not be the most logical. As an example, some in the UK have reported needing to select “Central Europe” instead of “Western Europe”.
   • SERVICE API: Under “Service API” ensure these APIs are listed: IoT Core and Authorization. To be sure, click subscribe again on every service. Very important: disable popup blockers otherwise subscribing won’t work without providing any indication of a failure. Make sure you authorize your Project to use those APIs:
     • Click “Service API” tab
     • Click “Go to Authorize” button
     • Select the API Groups from the dropdown and click Subscribe (screenshot)
   • RENEWAL: The IoT Core subscription is a free trial that expires after one month. Once expired, the Setup Wizard won’t be able to communicate with your Tuya account anymore, so it needs to be renewed to fetch Local_Keys for new devices:
     1. Sign into iot.tuya.com with the credentials you used to create your Tuya project.
     2. Click Cloud in the left pane, then Project Management (screenshot).
     3. Click Upgrade IoT Core Plan, choose Trial edition ($0.00) and click Buy Now (screenshot).
     4. Tuya may warn that you cannot select the trial edition again. Dismiss the warning and look for the IoT Core button labelled Extend trial period. Tap it and fill in the short questionnaire (duration of 1, 3 or 6 months, purpose of the project, type of developer, etc.). After several minutes, refresh the page - the trial extension is usually approved by then.

4. WIZARD - Run Setup Wizard:

   • From your Linux/Mac/Win PC run the TinyTuya Setup Wizard to fetch the Local_Keys for all of your registered devices:

     python -m tinytuya wizard   # use -nocolor for non-ANSI-color terminals
     

   • The Wizard will prompt you for the API ID key, API Secret, API Region (cn, us, us-e, eu, eu-w, sg, or in) from your Tuya IoT project as set in Step 3 above.
     • To find those again, go to iot.tuya.com, choose your project and click Overview
       • API Key: Access ID/Client ID
       • API Secret: Access Secret/Client Secret
   • It will also ask for a sample Device ID. You can have the wizard scan for one (enter scan), use one from step 2 above or in the Device List on your Tuya IoT project.
   • The Wizard will poll the Tuya IoT Cloud Platform and print a JSON list of all your registered devices with the “name”, “id” and “key” of your registered device(s). The "key"s in this list are the Devices’ Local_Key you will use to access your device.
   • In addition to displaying the list of devices, Wizard will create a local file devices.json that TinyTuya will use to provide additional details for scan results from tinytuya.deviceScan() or when running python -m tinytuya scan. The wizard also creates a local file tuya-raw.json that contains the entire payload from Tuya Cloud.
   • The Wizard will ask if you want to poll all the devices. If you do, it will display the status of all devices on record and create a snapshot.json file with these results. Make sure your LAN and firewall permit UDP (6666, 6667 and 7000) and TCP (6668) traffic.

Notes:

• If you ever reset or re-pair your smart devices, the Local_Key will be reset and you will need to repeat the steps above.
• The TinyTuya Wizard was inspired by the TuyAPI CLI which is an alternative way to fetch the Local_Keys: npm i @tuyapi/cli -g and run tuya-cli wizard

Programming with TinyTuya

After importing tinytuya, you create a device handle for the device you want to read or control. Here is an example for a Tuya smart switch or plug:

import tinytuya

# Connect to Device
d = tinytuya.OutletDevice(
    dev_id='DEVICE_ID_HERE',
    address='IP_ADDRESS_HERE',      # Or set to 'Auto' to auto-discover IP address
    local_key='LOCAL_KEY_HERE', 
    version=3.3)                    # Set to your device's actual version (3.1, 3.2, 3.3, 3.4, or 3.5)

# Get Status
data = d.status() 
print('set_status() result %r' % data)

# Turn On
d.turn_on()

# Turn Off
d.turn_off()

TinyTuya Module Classes and Functions

Classes

  AESCipher - Cryptography Helpers
  XenonDevice(args...) - Base Class
    Device(args...) - Tuya Class for Devices
      OutletDevice(args...)
      CoverDevice(args...)
      BulbDevice(args...)
        Where args:
          dev_id (str): Device ID e.g. 01234567891234567890
          address (str): Device Network IP Address e.g. 10.0.1.99 or "Auto" to auto-find
          local_key (str): The encryption key
          dev_type (str): Device type for payload options (see below)
          version = 3.1 (float): Tuya Protocol (e.g. 3.1, 3.2, 3.3, 3.4, 3.5)
          persist = False (bool): Keep TCP link open
          cid = None (str): Optional sub device id
          node_id = None (str): Alias for cid
          parent = None (object): Gateway device object this is a child of
          port = TCPPORT (int): The port to connect to device
          connection_timeout = 5 (int): Timeout in seconds
          connection_retry_limit = 5 (int)
          connection_retry_delay = 5 (int)

          Total timeout = (connection_timeout * connection_retry_limit) + 
                          (connection_retry_delay * (connection_retry_limit - 1))
                          Defaults: (5 * 5) + (5 * (5 - 1)) = 45 seconds
                        
  Cloud(apiRegion, apiKey, apiSecret, apiDeviceID, new_sign_algorithm)

TinyTuya Base Functions
    devices = deviceScan()                        # Returns dictionary of devices found on local network
    scan()                                        # Interactive scan of local network
    wizard                                        # Interactive setup wizard (run via: python -m tinytuya wizard)
    set_debug(toggle, color)                      # Activate verbose debugging output
    pack_message(msg, hmac_key)                   # Packs a TuyaMessage(), encrypting or adding a CRC if required 
    unpack_message(data, hmac_key, header, 
                    no_retcode)                   # Unpacks a TuyaMessage() 
    parse_header(data)                            # Unpacks just the header part of a message into a TuyaHeader()
    find_device(dev_id, address)                  # Scans network for Tuya devices with either ID = dev_id or IP = address
    device_info(dev_id)                           # Searches DEVICEFILE (usually devices.json) for device with ID
    assign_dp_mappings(tuyadevices, mappings)     # Adds mappings to all the devices in the tuyadevices list
    decrypt_udp(msg)                              # Decrypts a UDP network broadcast packet

 Device Functions (All Devices)
    json = status()                               # returns json payload
    subdev_query(nowait)                          # query sub-device status (only for gateway devices)
    set_version(version)                          # 3.1 [default], 3.2, 3.3, 3.4 or 3.5
    set_socketPersistent(False/True)              # False [default] or True
    set_socketNODELAY(False/True)                 # False or True [default]
    set_socketRetryLimit(integer)                 # retry count limit [default 5]
    set_sendRetryLimit(integer)                  # payload resend limit after timeout [default: follows socketRetryLimit]
    set_socketRetryDelay(integer)                 # retry delay [default 5]
    set_socketTimeout(timeout)                    # set connection timeout in seconds [default 5]
    set_dpsUsed(dps_to_request)                   # add data points (DPS) to request
    add_dps_to_request(index)                     # add data point (DPS) index set to None
    set_retry(retry)                              # retry if response payload is truncated
    set_status(on, switch=1, nowait)              # Set status of switch to 'on' or 'off' (bool)
    set_value(index, value, nowait)               # Set int value of any index.
    set_multiple_values(index_value_dict, nowait) # Set multiple values with a single request
    heartbeat(nowait)                             # Send heartbeat to device
    updatedps(index=[1], nowait)                  # Send updatedps command to device
    turn_on(switch=1, nowait)                     # Turn on device / switch #
    turn_off(switch=1, nowait)                    # Turn off
    set_timer(num_secs, dps_id=0, nowait)         # Set timer for num_secs on DPS dps_id (0=detect)
    set_sendWait(num_secs)                        # Time to wait after sending commands before pulling response
    detect_available_dps()                        # Return list of DPS available from device
    generate_payload(command, data,...            # Generate TuyaMessage payload for command with data
    send(payload)                                 # Send payload to device (do not wait for response)
    receive()                                     # Receive payload from device

OutletDevice Additional Functions
    set_dimmer(percentage):

BulbDevice Additional Functions
    set_colour(r, g, b, nowait):
    set_hsv(h, s, v, nowait):
    set_white(brightness, colourtemp, nowait):
    set_white_percentage(brightness=100, colourtemp=0, nowait):
    set_brightness(brightness, nowait):
    set_brightness_percentage(brightness=100, nowait):
    set_colourtemp(colourtemp, nowait):
    set_colourtemp_percentage(colourtemp=100, nowait):
    set_scene(scene, scene_data=None, nowait):    # 1=nature, 3=rave, 4=rainbow
    set_mode(mode='white', nowait):               # white, colour, scene, music
    result = brightness():
    result = colourtemp():
    (r, g, b) = colour_rgb():
    (h,s,v) = colour_hsv()
    result = state():

CoverDevice Additional Functions
    open_cover(switch=None, nowait=False):
    close_cover(switch=None, nowait=False):
    stop_cover(switch=None, nowait=False):
    continue_cover(switch=None, nowait=False):
    set_cover_type(cover_type):                  # Manually set cover type (1-8)
    
    CoverDevice automatically detects one of 8 device types by checking status:
      Type 1: ["open", "close", "stop", "continue"] - Most curtains, blinds, roller shades (DEFAULT)
      Type 2: [true, false]                         - Simple relays, garage doors, locks
      Type 3: ["0", "1", "2"]                       - String-numeric position/state
      Type 4: ["00", "01", "02", "03"]              - Zero-prefixed numeric position/state
      Type 5: ["fopen", "fclose"]                   - Directional binary (no stop)
      Type 6: ["on", "off", "stop"]                 - Switch-lexicon open/close
      Type 7: ["up", "down", "stop"]                - Vertical-motion (lifts, hoists)
      Type 8: ["ZZ", "FZ", "STOP"]                  - Vendor-specific (Abalon-style, older standard)
    
    Detection uses priority ordering based on real-world frequency (Type 1 → Type 8 → Type 3 → others).
    Defaults to Type 1 if detection fails. Manual override: set_cover_type(type_id).
    Common DPS IDs: 1 (most common), 101 (second most common), 4 (dual-curtain second curtain).

Cloud Functions
    setregion(apiRegion)
    cloudrequest(url, action=[POST if post else GET], post={}, query={})
    getdevices(verbose=False)
    getstatus(deviceid)
    getfunctions(deviceid)
    getproperties(deviceid)
    getdps(deviceid)
    sendcommand(deviceid, commands [, uri])
    getconnectstatus(deviceid)
    getdevicelog(deviceid, start=[now - 1 day], end=[now], evtype="1,2,3,4,5,6,7,8,9,10", size=0 [all], max_fetches=50, params={})
      -> when start or end are negative, they are the number of days before "right now"
          i.e. "start=-1" is 1 day ago, "start=-7" is 7 days ago
          

TinyTuya Error Codes

Starting with v1.2.0 TinyTuya functions will return error details in the JSON data responses instead of raising exceptions. The format for this response:

{ "Error":"Invalid JSON Payload", "Err":"900", "Payload":"{Tuya Message}" }

The “Err” number will be one of these:

• 900 (ERR_JSON) - Invalid JSON Response from Device
• 901 (ERR_CONNECT) - Network Error: Unable to Connect
• 902 (ERR_TIMEOUT) - Timeout Waiting for Device
• 903 (ERR_RANGE) - Specified Value Out of Range
• 904 (ERR_PAYLOAD) - Unexpected Payload from Device
• 905 (ERR_OFFLINE) - Network Error: Device Unreachable
• 906 (ERR_STATE) - Device in Unknown State
• 907 (ERR_FUNCTION) - Function Not Supported by Device
• 908 (ERR_DEVTYPE) - Device22 Detected: Retry Command
• 909 (ERR_CLOUDKEY) - Missing Tuya Cloud Key and Secret
• 910 (ERR_CLOUDRESP) - Invalid JSON Response from Cloud
• 911 (ERR_CLOUDTOKEN) - Unable to Get Cloud Token
• 912 (ERR_PARAMS) - Missing Function Parameters
• 913 (ERR_CLOUD) - Error Response from Tuya Cloud
• 914 (ERR_KEY_OR_VER) - Check device key or version

Example Usage

See the sample python script test.py for an OutletDevice example or look in the examples directory for other scripts.

import tinytuya

"""
OUTLET Device
"""
d = tinytuya.Device('DEVICE_ID_HERE', 'IP_ADDRESS_HERE', 'LOCAL_KEY_HERE', version=3.3)  # Set version to match your device (3.1, 3.2, 3.3, 3.4, or 3.5)
data = d.status()  

# Show status and state of first controlled switch on device
print('Dictionary %r' % data)
print('State (bool, true is ON) %r' % data['dps']['1'])  

# Toggle switch state
switch_state = data['dps']['1']
data = d.set_status(not switch_state)  # This requires a valid key
if data:
    print('set_status() result %r' % data)

# On a switch that has 4 controllable ports, turn the fourth OFF (1 is the first)
data = d.set_status(False, 4)
if data:
    print('set_status() result %r' % data)

"""
RGB Bulb Device
"""
import time

d = tinytuya.BulbDevice('DEVICE_ID_HERE', 'IP_ADDRESS_HERE', 'LOCAL_KEY_HERE')
d.set_version(3.3)  # IMPORTANT: Set the correct version for your device (3.1, 3.2, 3.3, 3.4, or 3.5)
d.set_socketPersistent(True)  # Optional: Keep socket open for multiple commands
data = d.status()

# Show status of first controlled switch on device
print('Dictionary %r' % data)

# Set to RED Color - set_colour(r, g, b):
d.set_colour(255,0,0)  

# Cycle through the Rainbow
rainbow = {"red": [255, 0, 0], "orange": [255, 127, 0], "yellow": [255, 200, 0],
          "green": [0, 255, 0], "blue": [0, 0, 255], "indigo": [46, 43, 95],
          "violet": [139, 0, 255]}
for color in rainbow:
    [r, g, b] = rainbow[color]
    d.set_colour(r, g, b, nowait=True)  # nowait = Go fast don't wait for response
    time.sleep(0.25)

# Brightness: Type A devices range = 25-255 and Type B = 10-1000
d.set_brightness(1000)

# Set to White - set_white(brightness, colourtemp):
#    colourtemp: Type A devices range = 0-255 and Type B = 0-1000
d.set_white(1000,10)

# Set Bulb to Scene Mode
d.set_mode('scene')

# Scene Example: Set Color Rotation Scene
d.set_value(25, '07464602000003e803e800000000464602007803e803e80000000046460200f003e803e800000000464602003d03e803e80000000046460200ae03e803e800000000464602011303e803e800000000')

"""
Cover Device (Window Shade)
"""
c = tinytuya.CoverDevice('DEVICE_ID_HERE', 'IP_ADDRESS_HERE', 'LOCAL_KEY_HERE')
c.set_version(3.3)  # Set correct version for your device (3.1 through 3.5)
data = c.status()

# Show status
print('Dictionary %r' % data)

# CoverDevice will automatically detect the device type (1-8)
# and use the appropriate commands

# Open the cover
c.open_cover()

# Close the cover  
c.close_cover()

# Stop the cover
c.stop_cover()

# Continue cover motion (if supported by device type)
c.continue_cover()

# Manually set cover type if auto-detection doesn't work
c.set_cover_type(1)   # Force Type 1 (open/close/stop/continue)

Example Device Monitor

You can set up a persistent connection to a device and then monitor the state changes with a continual loop. This is helpful for troubleshooting and discovering DPS values.

import tinytuya

d = tinytuya.OutletDevice('DEVICEID', 'DEVICEIP', 'DEVICEKEY', version=3.3, persist=True)  # Set version to match your device (3.1, 3.2, 3.3, 3.4, or 3.5)

print(" > Send Request for Status < ")
d.status(nowait=True)

print(" > Begin Monitor Loop <")
while(True):
    # See if any data is available
    data = d.receive()
    print('Received Payload: %r' % data)

    # Send keep-alive heartbeat
    if not data:
        print(" > Send Heartbeat Ping < ")
        d.heartbeat()

    # NOTE If you are not seeing updates, you can force them - uncomment:
    # print(" > Send Request for Status < ")
    # d.status(nowait=True)

    # NOTE Some smart plugs require an UPDATEDPS command to update power data
    # print(" > Send DPS Update Request < ")
    # payload = d.generate_payload(tinytuya.UPDATEDPS)
    # d.send(payload)    

Multi-Device Monitor (Monitor Class) - ⚠️ Experimental

The Monitor class provides efficient, single-thread monitoring of multiple Tuya devices using OS-level selectors (epoll/poll/select). No asyncio, no per-device threads, no extra dependencies. It’s ideal for home automation dashboards, data loggers, or any application that needs to watch many devices simultaneously.

Key features:

• Single OS thread handles all device I/O via selectors
• Real-time status updates through callbacks (on_status, on_connect, on_disconnect)
• Thread-safe command dispatch — send commands from anywhere via proxy handles
• Built-in heartbeat management per device
• Automatic reconnection on disconnect (auto_reconnect=True)
• Optional manual poll mode for integration into existing event loops

import tinytuya

def on_status(device, result):
    dps = result.get("dps", {}) if result else {}
    name = getattr(device, "name", device.id)
    print(f"[STATUS] {name}: {dps}")

def on_connect(device, error):
    if error:
        print(f"[CONNECT FAIL] {device.id}: {error}")
    else:
        print(f"[CONNECTED] {device.id}")

def on_disconnect(device, error):
    print(f"[DISCONNECTED] {device.id}: {error}")

# Create the monitor with callbacks
mon = tinytuya.Monitor(
    on_status=on_status,
    on_connect=on_connect,
    on_disconnect=on_disconnect,
    heartbeat_interval=12,
    auto_reconnect=True,   # automatically reconnect on disconnect
)

# Register devices — add() connects and returns a proxy handle
handles = []
for cfg in devices:
    d = tinytuya.OutletDevice(cfg["id"], cfg["ip"], cfg["key"],
                              version=3.3, persist=True)
    handle = mon.add(d)
    handles.append(handle)

# Start the reactor on a background daemon thread
mon.start()

# Send commands via the proxy handle (thread-safe)
handles[0].set_value(1, True)    # turn on first device

# ... later
mon.stop()

The on_disconnect callback is opt-in — if you don’t pass it, disconnects are logged silently. When provided, you receive the device object and error string, allowing you to implement custom reconnection logic, alerts, or cleanup:

# Example: reconnect on disconnect
def on_disconnect(device, error):
    print(f"{device.id} went away: {error}")
    # Reconnect by re-adding the device
    time.sleep(5)
    mon.add(device)

mon = tinytuya.Monitor(
    on_status=on_status,
    on_disconnect=on_disconnect,
)

See examples/monitor_example.py for a complete working example, and examples/monitor_poll_example.py for manual poll mode (no background thread).

Tuya Cloud Access

You can poll and manage Tuya devices using the Cloud class and functions.

CAUTION: The free Tuya IoT Developer (Trial) account allows a very limited number of Cloud API calls. Be aware of the restrictions before enabling any automation that makes frequent calls.

import tinytuya

# Connect to Tuya Cloud
# c = tinytuya.Cloud()  # uses tinytuya.json 
c = tinytuya.Cloud(
        apiRegion="us", 
        apiKey="xxxxxxxxxxxxxxxxxxxx", 
        apiSecret="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", 
        apiDeviceID="xxxxxxxxxxxxxxxxxxID")

# Display list of devices
devices = c.getdevices()
print("Device List: %r" % devices)

# Select a Device ID to Test
id = "xxxxxxxxxxxxxxxxxxID"

# Display Properties of Device
result = c.getproperties(id)
print("Properties of device:\n", result)

# Display Status of Device
result = c.getstatus(id)
print("Status of device:\n", result)

# Send Command - Turn on switch
commands = {
    "commands": [
        {"code": "switch_1", "value": True},
        {"code": "countdown_1", "value": 0},
    ]
}
print("Sending command...")
result = c.sendcommand(id,commands)
print("Results\n:", result)

Up to one week of device logs can also be pulled from the Cloud. By default getdevicelog() will pull 1 day of logs or 5000 log entries, whichever comes first. The returned timestamps are unixtime*1000, and event_id 7 (data report) will probably be the most useful.

import tinytuya
import json

c = tinytuya.Cloud()
#r = c.getdevicelog( '00112233445566778899', start=-1, end=0, size=0, max_fetches=50 )
#r = c.getdevicelog( '00112233445566778899', start=1669990000, end=1669990300, size=20 )
r = c.getdevicelog( '00112233445566778899' )
print( json.dumps(r, indent=2) )

Encryption Notes

Tuya devices use AES encryption which is not available in the Python standard library. PyCA/cryptography is recommended and installed by default. Other options include PyCryptodome , PyCrypto and pyaes.

• Deprecation notice for pyaes: The pyaes library works for Tuya Protocol <= 3.4 but will not work for 3.5 devices. This is because pyaes does not support GCM which is required for v3.5 devices.

Command Line

TinyTuya provides a built-in command line interface to get Local key, scan, poll, list and control devices.

Installation

# Option-1: pip install tinytuya
python -m tinytuya

# Option-2: pipx install tinytuya
tinytuya 

Command Line Usage

tinytuya <command> [-debug] [-nocolor] [-h] [-yes] [-no-poll] [-device-file FILE] [-snapshot-file FILE]

  Setup & Discovery
  wizard         Launch Setup Wizard to get Tuya Local Keys from Tuya Cloud.
  scan           Scan local network for Tuya devices.
  devices        Scan all devices listed in devices.json file.
  snapshot       Scan devices listed in snapshot.json file.
  json           Scan devices listed in snapshot.json file [JSON output].
  list           List devices from devices.json as a table (or --json).

  Device Control  (require --id or --name)
  on             Turn on a device switch.
  off            Turn off a device switch.
  set            Set a DPS value on a device.
  get            Read a DPS value (or full status) from a device.
  monitor        Connect to a device and monitor for live status updates.

  Info
  version        Display the TinyTuya version.
  help           Show detailed help and usage examples.

  Wizard
      tinytuya wizard [-h] [-debug] [-force [0.0.0.0/24 ...]] [-no-broadcasts] [-nocolor] [-yes] [-no-poll] [-no-poll-configured]
                [-device-file FILE] [-raw-response-file FILE] [-snapshot-file FILE] [-credentials-file FILE]
                [-key KEY] [-secret SECRET] [-region {cn,eu,eu-w,in,sg,us,us-e}] [-device DEVICE [DEVICE ...]]
                [-dry-run] [max_time]

        Common Options
        max_time             Maximum time to find Tuya devices [Default: 18]
        -no-broadcasts       Ignore broadcast packets when force scanning
        -nocolor             Disable color text output.
        -debug               Activate debug mode.
        -h, -help            Show usage help for command.
        -yes, -y             Answer "yes" to all questions
        -no-poll, -no        Answer "no" to "Poll?" (overrides -yes)
        -no-poll-configured  Don't poll devices.json IPs that were not heard by broadcast (scan, devices, wizard)
        -device-file FILE    JSON file to load devices from [Default: devices.json]
        -snapshot-file FILE  JSON file to load/save snapshot from/to [Default: snapshot.json]
        -force [0.0.0.0/24 ...], -f [0.0.0.0/24 ...]
                             Force network scan of device IP addresses [Default: Auto-detects net/mask]
        -no-broadcasts       Ignore broadcast packets when force scanning
        -raw-response-file   JSON file to save the raw server response to [Default: tuya-raw.json]

        Wizard Cloud API Options
        -dry-run             Do not actually connect to the Cloud
        -credentials-file    JSON file to load/save Cloud credentials from/to [Default: tinytuya.json]
        -key KEY             Cloud API Key to use
        -secret SECRET       Cloud API Secret to use
        -region              Cloud API Region to use {cn,eu,eu-w,in,sg,us,us-e}
        -device DEVICE(S)    One or more Device ID(s) to use

  Scan
      tinytuya scan [-h] [-debug] [-force [0.0.0.0/24 ...]] [-no-broadcasts] [-nocolor] [-yes] 
                [-no-poll-configured] [-device-file FILE] [-snapshot-file FILE] [max_time]

  Devices
      tinytuya devices [-h] [-debug] [-force [0.0.0.0/24 ...]] [-no-broadcasts] [-nocolor] [-yes] 
                [-no-poll] [-no-poll-configured] [-device-file FILE] [-snapshot-file FILE] [max_time]

  Snapshot
      tinytuya snapshot [-h] [-debug] [-nocolor] [-yes] [-no-poll] [-device-file FILE] [-snapshot-file FILE]

  JSON
      tinytuya json [-h] [-debug] [-device-file FILE] [-snapshot-file FILE]

  List
      tinytuya list [-h] [-debug] [--json] [-device-file FILE]

        --json               Output as a JSON array instead of a table
        -device-file FILE    JSON file to load devices from [Default: devices.json]

  Device Control Options (on / off / set / get / monitor)
      --id and --name are mutually exclusive; one is required.
      --key, --ip, and --version are loaded automatically from devices.json if found.
      If --key is omitted and not in devices.json, the CLI will prompt for it interactively
      (input is hidden, avoiding shell-escaping issues with special characters like $, #, =).
      Tuya local keys are always exactly 16 characters — a wrong length usually means a
      shell-escaping problem (try wrapping with single quotes or omitting --key entirely).

  On / Off
      tinytuya on  [-h] [-debug] [--dps N] (--id ID | --name NAME) [--key KEY] [--ip IP] [--version VER] [-device-file FILE]
      tinytuya off [-h] [-debug] [--dps N] (--id ID | --name NAME) [--key KEY] [--ip IP] [--version VER] [-device-file FILE]

        --dps N              Switch DPS index [Default: 1]
        --id ID              Device ID (mutually exclusive with --name)
        --name NAME          Device name – looked up in device-file (mutually exclusive with --id)
        --key KEY            Device local encryption key (prompted if omitted and not in device-file)
        --ip IP              Device IP address (auto-discovered if omitted or set to "Auto")
        --version VER        Tuya protocol version (auto-discovered if omitted, defaults to 3.3)
        -device-file FILE    JSON file to load devices from [Default: devices.json]

  Set
      tinytuya set [-h] [-debug] --dps N --value VALUE (--id ID | --name NAME) [--key KEY] [--ip IP] [--version VER] [-device-file FILE]

        --dps N              DPS index to write (required)
        --value VALUE        Value to set – parsed as JSON if possible (true, false, 123, "text"),
                             otherwise sent as a plain string

  Get
      tinytuya get [-h] [-debug] [--dps N] (--id ID | --name NAME) [--key KEY] [--ip IP] [--version VER] [-device-file FILE]

        --dps N              DPS index to read; omit to return full device status JSON

        Output:
          No --dps  →  full status JSON, e.g. {"dps": {"1": true, "2": 500}}
          --dps N   →  plain scalar value only, e.g. true

  Monitor
      tinytuya monitor [-h] [-debug] (--id ID | --name NAME) [--key KEY] [--ip IP] [--version VER] [-device-file FILE]

        Connects to the device, prints the initial status, then enters a persistent
        loop that listens for asynchronous updates, sends a heartbeat every 12 seconds,
        and polls for a full status refresh every 30 seconds. Press Ctrl-C to exit.

        Example:
          tinytuya monitor --name "Kitchen Light"
          tinytuya monitor --id $DEVICE_ID --key $KEY --ip 192.168.1.50

  Version
      tinytuya version

        Prints the installed TinyTuya version, e.g.:  TinyTuya version: 1.19.0

  Help
      tinytuya help

        Prints a detailed usage summary with examples for all commands.

Scan Tool

The function tinytuya.scan() listens on your local network (UDP 6666, 6667 and 7000), identifies Tuya devices broadcasting their Address, Device ID, Product ID and Version, and prints them and their status to stdout. The tinytuya.deviceScan() function returns the devices it finds and their status as a dictionary.

Some devices never broadcast (seen on some v3.5 meters), and broadcasts don’t cross VLANs or reach Docker containers without host networking. To find those, the scan, devices and wizard commands also poll each devices.json device that wasn’t heard, once, at its saved IP. Those devices show up as [Configured IP], and the summary lists any that didn’t answer. Devices that don’t answer add about 3 seconds to the scan; add -no-poll-configured to skip this. In Python it’s off by default; pass poll_configured=True to turn it on:

scan(maxretry=None, color=True, forcescan=False, poll_configured=False)
deviceScan(verbose=False, maxretry=None, color=True, poll=True, forcescan=False, byID=False, poll_configured=False)

You can run the scanner from the command line using these interactive commands:

# Listen for Tuya Devices and match to devices.json if available
python -m tinytuya scan

# Broadcast only: don't poll devices.json IPs that were not heard
python -m tinytuya scan -no-poll-configured

# The above creates a snapshot.json file with IP addresses for devices
# You can use this command to get a rapid poll of status of all devices
python -m tinytuya snapshot

# The sames thing as above but with a non-interactive JSON response
python -m tinytuya json

# List all register devices discovered from Wizard and poll them
python -m tinytuya devices

# List devices from devices.json as a table
python -m tinytuya list

# Control devices by name or ID (key and IP are loaded from devices.json)
python -m tinytuya on  --name "Kitchen Light"
python -m tinytuya off --name "Kitchen Light"
python -m tinytuya set --name "Fan" --dps 3 --value 50
python -m tinytuya get --name "Sensor"

# Monitor a device for live async updates (Ctrl-C to exit)
python -m tinytuya monitor --name "Kitchen Light"

# Display version
python -m tinytuya version

By default, the scan functions will listen for about 18 seconds to find new devices. If you are not seeing all your devices, you can increase the scan time by passing an optional number of seconds (eg. 50 seconds):

# command line
python -m tinytuya scan 50

# invoke verbose interactive scan
tinytuya.scan(50)

# return payload of devices
devices = tinytuya.deviceScan(False, 50)

Troubleshooting

• Tuya devices only allow one TCP connection at a time. Make sure you close the TuyaSmart or SmartLife app before using TinyTuya to connect.
• Battery-powered devices (sensors, door/window contacts, etc.) are asleep most of the time and do not maintain a local network connection. They will not appear in scans and cannot be controlled locally — they only push data to the cloud when triggered. This is expected behaviour, not a TinyTuya bug.
• Polling too aggressively can cause devices to drop or reset their connection. Avoid polling faster than once per second for most devices. For energy-monitoring plugs and other data-heavy devices, a 5–10 second interval is safer. Use set_socketPersistent(True) with a heartbeat loop rather than opening a new connection on every poll.
• Some devices ship with older firmware that may not work with TinyTuya. If you’re experiencing issues, please try updating the device’s firmware in the official app.
• The LOCAL KEY for Tuya devices will change every time a device is removed and re-added to the TuyaSmart app. If you’re getting decrypt errors, try getting the key again as it might have changed.
• Devices running protocol version 3.1 (e.g. below Firmware 1.0.5) do not require a device Local_Key to read the status. All devices will require a device Local_Key to control the device.
• Some devices with 22 character IDs will require additional setting to poll correctly. TinyTuya will attempt to detect and accomodate for this, but it can be specified directly:

  a = tinytuya.OutletDevice('here_is_my_key', '192.168.x.x', 'secret_key_here', 'device22')
  a.set_version(3.3)  # Replace 3.3 with your device's actual version
  a.set_dpsUsed({"1": None})  # This needs to be a datapoint available on the device
  data =  a.status()
  print(data)
  

• Debugging several devices at once: log lines from device methods are prefixed with the device ID (e.g. [0123456789abcdef] sending payload) and each record carries a device_id attribute. Logger names are unchanged (tinytuya.core.XenonDevice, tinytuya.core.Device, …). device_id is only present on records emitted by device methods, so a shared formatter using %(device_id)s must add a filter that supplies a default first. Attach the filter to the handler (not the tinytuya logger): filters on a logger do not run for records propagated up from child loggers like tinytuya.core.XenonDevice, so some records would still fail to format:

  import logging
  class DeviceIdFilter(logging.Filter):
      def filter(self, record):
          if not hasattr(record, 'device_id'):
              record.device_id = '-'
          return True
  handler = logging.StreamHandler()
  handler.setFormatter(logging.Formatter('%(device_id)s %(message)s'))
  handler.addFilter(DeviceIdFilter())
  logging.getLogger('tinytuya').addHandler(handler)
  logging.getLogger('tinytuya').setLevel(logging.DEBUG)
  

• Windows 10 Users - TinyTuya wizard and scan interactive tools use ANSI color. This will work correctly in PowerShell but will show cryptic escape codes when run in Windows CMD. You can fix this by using the -nocolor option on tinytuya, or by changing the Windows CMD console registry to process ANSI escape codes by doing something like this:

  reg add HKEY_CURRENT_USER\Console /v VirtualTerminalLevel /t REG_DWORD /d 0x00000001 /f
  

User Contributed Device Modules

In addition to the built-in OutletDevice, BulbDevice and CoverDevice device support, the community is encourage to submit additional device modules which are available here: Contrib Library:

# Example usage of community contributed device modules
from tinytuya.Contrib import ThermostatDevice

thermo = ThermostatDevice( 'abcdefghijklmnop123456', '172.28.321.475', '1234567890123abc' )

Tuya Data Points - DPS Table

The Tuya devices send back data points (DPS) also called device function points, in a json string. The DPS attributes define the state of the device. Each key in the DPS dictionary refers to key value pair, the key is the DP ID and its value is the dpValue. You can refer to the Tuya developer platform for definition of function points for the products.

The following table represents several of the standard Tuya DPS values and their properties. It represents data compiled from Tuya documentation and self-discovery. Devices may vary. Feedback or additional data would would be appreciated. Please submit a Issue or Pull Request if you have additional data that would be helpful for others.

To find Tuya DPS for devices not listed below, you can discover the DPS values using the Tuya IoT platform. See this help here: Find your Data Point.

DPS Read and Set Example:

# Read Value of DPS 25
data = d.status()  
print("Value of DPS 25 is ", data['dps']['25'])

# Set Value of DPS 25
d.set_value(25, '010e0d0000000000000003e803e8')

Version 3.1 Devices

Version 3.1 (and some 3.3) - Plug or Switch Type

Version 3.1 - Light Type (RGB)

Version 3.3 Devices

Version 3.3 - Plug, Switch, Power Strip Type

Note: Some 3.3 energy management plugs use the DPS values of the 3.1 plug above.

Version 3.3 - Dimmer Switch

Version 3.3 - Light Type (RGB)

Version 3.3 - Automated Curtain Type

Version 3.3 - Fan Switch Type

Version 3.3 - Universal IR Controller with optional Temp/Humidity

# The IR Commands JSON has the following format:
command = {
    "control": "send_ir",
    "head": "",
    "key1": "[[TO_BE_REPLACED]]",
    "type": 0,
    "delay": 300,
}
# Sending the IR command:
payload = d.generate_payload(tinytuya.CONTROL, {"201": json.dumps(command)})
d.send(payload)

The key1 attribute is a base64 string that contains the IR signal. You can extract it using this procedure:

1. Register a new IR device on Tuya Smart / Smart Life app (if not registered already) and map, setup or import your buttons.
2. Tap multiple times on the button you wish to control.
3. Go to Tuya IoT Platform and select your app under Cloud > Development section.
4. Go to to the Device tab and select “Debug Device” on the parent device. Browse Device Logs section and retrieve the key1 attribute that matches your tapping timestamp from step 2 above. Use that key1 attribute in the payload example above.

You need to repeat these steps for each button (cloud logging is not always sequential).

Version 3.3 - Sensor Type

Important Note: Battery-powered Tuya sensors are usually designed to stay in sleep mode until a state change (eg.open or close alert). This means you will not be able to poll these devices except in the brief moment they awake, connect to the WiFi and send their state update payload the the Tuya Cloud. Keep in mind that if you manage to poll the device enough to keep it awake, you will likely quickly drain the battery.

NOTE (*) - The range can vary depending on the device. As an example, for dimmers, it may be 10-1000 or 25-255.

Version 3.3 - WiFi Air Quality Detector PM2.5/Formaldehyde/VOC/CO2/Temperature/Humidity

Example device: https://www.aliexpress.com/item/1005005034880204.html

Version 3.3 - Robot Mower Type

Reference pymoebot for further definition.

Version 3.3 - 24v Thermostat (i.e. PCT513-TY)

NOTE (*) - Depending on the firmware, either 18/19/20/26/27 or 108/109/110/111/x are used, not both

A user contributed module is available for this device in the Contrib library:

from tinytuya.Contrib import ThermostatDevice

thermo = ThermostatDevice( 'abcdefghijklmnop123456', '172.28.321.475', '1234567890123abc' )

For info on the Sensor Data lists, see https://github.com/jasonacox/tinytuya/discussions/139

Version 3.4 - WIFI Dual Meter (i.e. PJ1103A)

Note: (A) or (B) means channel A or channel B

A user contributed module is available for this device in the Contrib library:

from tinytuya.Contrib import WiFiDualMeterDevice

wdm = WiFiDualMeterDevice.WiFiDualMeterDevice(
    dev_id='abcdefghijklmnop123456',
    address='192.168.0.29',      # Or set to 'Auto' to auto-discover IP address
    local_key='1234567890123abc',
    version=3.4)

Tuya References

• Tuya Hardware Development - Protocol: https://developer.tuya.com/en/docs/iot/device-development/embedded-software-development/mcu-development-access/wifi-mcu-sdk-solution/tuya-cloud-universal-serial-port-access-protocol?id=K9hhi0xxtn9cb
• TuyaMCU listing of Tuya DP IDs: https://tasmota.github.io/docs/TuyaMCU/#switches-or-plugspower-strips

Credits

• TuyAPI https://github.com/codetheweb/tuyapi by codetheweb and blackrozes. Protocol reverse engineering from jepsonrob and clach04.
• PyTuya https://github.com/clach04/python-tuya by clach04. The origin of this python module (now abandoned). Thanks to nijave for pycryptodome support and testing, Exilit for unittests and docstrings, mike-gracia for improved Python version support, samuscherer for RGB Bulb support, magneticflux for improved Python version support, sean6541 for initial PyPi package and Home Assistant support https://github.com/sean6541/tuya-homeassistant, ziirish - for resolving a dependency problem related to version numbers at install time
• https://github.com/rospogrigio/localtuya-homeassistant by rospogrigio. Updated pytuya to support devices with Device IDs of 22 characters
• Thanks to @uzlonewolf, our top contributor and resident wizard, for expanding the Outlet/Cover/Bulb/Cloud modules into separate files, introducing Contrib structure for user generated device modules, making enhancements to TuyaMessage logic for multi-payload messages, rewriting the scanner and adding Tuya Protocol 3.2, 3.4 & 3.5 support to TinyTuya!
• Finally, thanks to the entire TinyTuya community for the great engagement, contributions and encouragement! See RELEASE notes for the ever growing journal of improvements and the incredible list of talent making this project possible.

Related Projects

• https://github.com/sean6541/tuyaapi Python API to the web api
• https://github.com/codetheweb/tuyapi node.js
• https://github.com/Marcus-L/m4rcus.TuyaCore - .NET
• https://github.com/SDNick484/rectec_status/ - RecTec pellet smokers control (with Alexa skill)
• https://github.com/TradeFace/tuyaface - Python Async Tuya API
• https://github.com/sjhorn/tinytuya - Dart Flutter port of TinyTuya based on this code base

TinyTuya Powered Projects

Please feel free to submit a PR or open an issue to add your project.

• https://github.com/mafrosis/tinytuya2mqtt - A bridge between TinyTuya and Home Assistant via MQTT
• https://github.com/Whytey/pymoebot - A Python library intended to monitor and control the MoeBot robotic lawn mowers.
• https://github.com/make-all/tuya-local - Local support for Tuya devices in Home Assistant
• https://github.com/teejo75/mtghs - Provides an HTTP service for Moonraker to control Tuya outlets.
• https://github.com/Xenomes/Domoticz-TinyTUYA-Plugin - Plugin for Domoticz Home Automation
• https://github.com/CmdrAvegan/AmbiTuya - Ambient lighting system for Tuya-based LED strips,

Contributors