{"id":4804,"library":"tinytuya","title":"TinyTuya: Tuya Smart Device Interface","description":"TinyTuya is a Python library that enables local and cloud-based control and monitoring of Tuya WiFi smart devices such as plugs, switches, and lights. It provides an API for direct communication over a local area network (LAN), supporting Tuya protocols from 3.1 to 3.5, and can also integrate with the Tuya Cloud API. Currently at version 1.17.6, the project is actively maintained with frequent updates and a focus on community contributions. [1, 3, 6, 9]","status":"active","version":"1.17.6","language":"en","source_language":"en","source_url":"https://github.com/jasonacox/tinytuya","tags":["IoT","smart home","Tuya","device control","local control"],"install":[{"cmd":"pip install tinytuya","lang":"bash","label":"Core library"},{"cmd":"pipx install tinytuya","lang":"bash","label":"Command-line tool (optional)"}],"dependencies":[{"reason":"Optional for colored console output; gracefully disabled if not present.","package":"colorama","optional":true}],"imports":[{"symbol":"tinytuya","correct":"import tinytuya"},{"note":"Base class for general Tuya devices","symbol":"Device","correct":"from tinytuya import Device"},{"note":"Common device-specific classes and the Cloud API interface","symbol":"OutletDevice, BulbDevice, Cloud","correct":"from tinytuya import OutletDevice, BulbDevice, Cloud"}],"quickstart":{"code":"import os\nimport tinytuya\n\n# --- Configuration (replace with your device details or environment variables) ---\nDEVICE_ID = os.environ.get('TUYA_DEVICE_ID', 'YOUR_DEVICE_ID')\nDEVICE_IP = os.environ.get('TUYA_DEVICE_IP', 'YOUR_DEVICE_IP') # Can be 'Auto' if devices.json is present\nLOCAL_KEY = os.environ.get('TUYA_LOCAL_KEY', 'YOUR_LOCAL_KEY')\nDEVICE_VERSION = float(os.environ.get('TUYA_DEVICE_VERSION', '3.3')) # e.g., 3.1, 3.3, 3.5\n\n# --- Local Control Example (OutletDevice) ---\nprint(f\"Connecting to device {DEVICE_ID} at {DEVICE_IP} (version {DEVICE_VERSION})...\")\n\ntry:\n    # Initialize the device object\n    d = tinytuya.OutletDevice(DEVICE_ID, DEVICE_IP, LOCAL_KEY, version=DEVICE_VERSION)\n    d.set_version(DEVICE_VERSION) # Ensure the correct protocol version is set\n\n    # Get current status\n    data = d.status()\n    if data and 'dps' in data:\n        print(f\"Device status: {data['dps']}\")\n        # Assuming DP '1' controls the main switch (common for outlets)\n        current_state = data['dps'].get('1')\n        print(f\"Current switch state (DP 1): {'ON' if current_state else 'OFF'}\")\n\n        # Toggle the power state\n        new_state = not current_state\n        print(f\"Setting switch state (DP 1) to: {'ON' if new_state else 'OFF'}\")\n        d.set_status(new_state)\n        print(\"Command sent. Waiting for update...\")\n\n        # Re-check status after a short delay (optional, for verification)\n        import time\n        time.sleep(2)\n        updated_data = d.status()\n        if updated_data and 'dps' in updated_data:\n            print(f\"Updated switch state (DP 1): {'ON' if updated_data['dps'].get('1') else 'OFF'}\")\n    else:\n        print(\"Failed to get device status or 'dps' key not found.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Troubleshooting tips:\")\n    print(\"- Ensure your device ID, IP, and local key are correct.\")\n    print(\"- Confirm the device is on the same local network as the script.\")\n    print(\"- Close any official Tuya/Smart Life apps to free the device's TCP connection. [11]\")\n    print(\"- Check your firewall for UDP (6666, 6667, 7000) and TCP (6668) port access. [3]\")","lang":"python","description":"This quickstart demonstrates how to establish local control over a Tuya smart device using TinyTuya. It initializes an `OutletDevice` with device credentials (ID, IP, local key, and protocol version), retrieves its current status, and then toggles the main switch (Data Point 1). Device credentials should ideally be supplied via environment variables or a configuration file. Remember to obtain your device's `LOCAL_KEY` and `DEVICE_ID` using the `tinytuya wizard` CLI tool or the Tuya IoT Platform. [3, 5, 6, 8]"},"warnings":[{"fix":"Update CLI usage from `tinytuya` to `tinytuya scan` for device discovery.","message":"Starting with v1.14.0, running the `tinytuya` command-line interface without arguments no longer initiates a scan; it now displays a 'Usage' page. Users must explicitly specify `tinytuya scan` or `python -m tinytuya scan` to discover devices.","severity":"breaking","affected_versions":">=1.14.0"},{"fix":"Re-run the `tinytuya wizard` CLI tool or use the Tuya IoT Platform to fetch the updated local key after any device re-pairing or network changes. [5, 6]","message":"The local key for Tuya devices is crucial for local control but will change if the device is re-paired with the Smart Life/Tuya Smart app or removed and re-added. If you encounter decrypt errors or loss of control, you likely need to re-obtain the local key. [1, 3, 10, 11]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Terminate any other applications or services that might be actively connected to the Tuya device via its local API.","message":"Tuya devices typically allow only one TCP connection at a time for local control. Ensure that official Tuya/Smart Life apps or other smart home integrations (like Home Assistant's native Tuya integration) are completely closed or disconnected from the device before attempting to control it with TinyTuya to avoid connection issues. [1, 10, 11]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly check your Tuya IoT Platform project's 'Service API' section to ensure required services are active and subscribed. Extend any expiring trial subscriptions if necessary.","message":"Setting up the Tuya IoT Platform project to retrieve local keys often requires subscribing to specific API services (e.g., IoT Core, Authorization, Smart Home Scene Linkage). These services may have trial periods that expire, potentially interrupting your ability to fetch keys or use cloud-dependent features. [1, 5, 8]","severity":"gotcha","affected_versions":"All versions (cloud interaction)"},{"fix":"Review the `BulbDevice` example usage in the GitHub repository and update your code to align with the latest recommended patterns for lighting control, especially if migrating from older `tinytuya` versions.","message":"The `BulbDevice` class underwent significant rewrites and fixes across multiple minor versions (v1.17.0, v1.17.1, v1.17.2). If you are using `BulbDevice` or encounter unexpected behavior with lighting controls, review the changes in these versions, as the expected interaction or internal handling might have evolved.","severity":"gotcha","affected_versions":"1.17.0-1.17.2"},{"fix":"Ensure your local network's firewall allows inbound and outbound UDP traffic on ports 6666, 6667, 7000 and TCP traffic on port 6668 from the machine running TinyTuya to your Tuya devices.","message":"Local device discovery and control require specific network ports to be open. UDP ports 6666, 6667, and 7000 are used for discovery, and TCP port 6668 is used for device communication. Firewall rules or network configurations blocking these ports will prevent TinyTuya from functioning correctly. [1, 3, 6, 11, 13]","severity":"gotcha","affected_versions":"All versions (local control)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}