📖 Device Compatibility FAQ — Read Before Opening an Issue

[jasonacox]

🔌 Device Compatibility FAQ for TinyTuya

This FAQ covers the most common device compatibility questions and is updated regularly based on real issues reported by the community. Before opening a new issue, please check if your question is answered here!

---

1. My device is not responding / cannot be found on the network

Check these first:

• Is the device on the same local network as the machine running tinytuya? (Devices must be on the same subnet — not separated by VLANs or guest networks)
• Try python3 -m tinytuya scan — does the device appear?
• Make sure the device is not in a guest network or VLAN isolated from your machine
• Another app (Home Assistant, LocalTuya, Tuya Smart) may already hold the TCP connection — disconnect other clients first
• Some ISPs and routers block UDP multicast; try python3 -m tinytuya scan -force 192.168.x.0/24 with your actual subnet

If the scan says "DEVICE KEY required":

• The device was found but tinytuya doesn't have the local key yet — run the wizard: python3 -m tinytuya wizard

---

2. I get "permission deny" or authentication errors

This is almost always a key or version mismatch:

• Are you using the correct Device ID, Local Key, and IP address?
• Local keys change when a device is re-paired or reconnected via the Tuya app — re-fetch from Tuya IoT Platform
• Try different protocol versions: set_version(3.1), set_version(3.3), set_version(3.4)
• Run python3 -m tinytuya wizard to re-fetch all keys from the cloud

How to get your Local Key:

1. Log in to iot.tuya.com
2. Go to Cloud → Development → your project → Devices
3. Find your device and copy the Local Key

"Permission deny" from the Tuya cloud during wizard:

• Make sure you subscribed to the correct API services in your cloud project. Required services: IoT Core, Smart Home Scene Linkage, Device Status Notification
• Go to your project → Service API tab and verify all three are active
• If you paired your device using the Smart Industry app instead of Tuya Smart or Smart Life, you must re-pair it using one of the consumer apps — Smart Industry uses a different platform that blocks the standard local-key API
• The "permission deny" error is a Tuya cloud API error, not a tinytuya bug — check your project's API subscriptions first

Important: Use the Tuya Smart or Smart Life app (not Smart Industry, not Tuya IoT app) when linking your app account to the cloud project.

---

3. My Tuya IoT Cloud trial has expired / subscription issues

This is one of the most common questions. Here's the situation:

The Tuya IoT Platform requires an active subscription to use the cloud API (which the wizard uses to fetch local keys). The free trial gives you a limited usage quota.

What you can do:

• Option A — Renew for free: Log into iot.tuya.com, go to your project, and click "Renew". Individual developer projects can typically be renewed for free (the $25K figure is for commercial plans). Look for a free/trial renewal option.
• Option B — Use the local key you already have: If you already ran the wizard before your trial expired and have your local keys in devices.json or snapshot.json, you don't need the cloud anymore for local control. The local key doesn't expire on its own — only if the device is re-paired.
• Option C — Alternative key extraction: Projects like TuyaLocalKeyExtractor or tuya-cli may help extract keys without an active IoT subscription.
• Option D — Packet sniffing: Use a MITM proxy (e.g., mitmproxy) during initial device pairing to capture the local key from the Tuya app traffic.

Cloud is only needed to fetch local keys — once you have them, local device control works entirely offline without any cloud subscription.

---

4. My device is not recognized by the wizard / IP shows as 0

Battery-powered sensors and sleep-mode devices:

• Many sensors (door/window, temperature/humidity, motion, smoke detectors) are battery-powered and spend most of their time asleep to preserve battery life
• When asleep, they are not connected to WiFi — the scan will show "ip": 0 or not find them at all
• These devices typically only connect to the cloud (not local) to send data when triggered (e.g., door opens, temperature threshold crossed)
• This is by design — battery-powered Tuya sensors generally cannot be polled locally in real time
• Workaround: Use Tuya Cloud API (tinytuya.Cloud) to subscribe to device status push notifications, or use a hub/gateway that keeps a persistent local connection

Zigbee and Matter sub-devices:

• Some devices use Zigbee or Matter and communicate through a gateway — control the gateway, not the end device directly
• Check if your device is a sub-device paired to a Tuya Zigbee hub
• See Section 9 (Zigbee/Sub-devices) for details

Wi-Fi devices that still show IP=0:

• The device may have changed its IP (DHCP reassignment) — try the force scan
• Some devices require a firmware update to support local control
• A few Tuya-platform devices are "cloud-only" by design — see Section 10

---

5. What protocol version should I use? (3.1 / 3.3 / 3.4 / 3.5)

Protocol version is device-specific — it's determined by the device firmware, not your preference.

How to find the right version:

1. Run python3 -m tinytuya scan — the version is reported in the scan output
2. Look in snapshot.json after running the wizard — the "version" field per device
3. Try versions in order: 3.3 → 3.4 → 3.5 → 3.1

Version characteristics:

Version	Encryption	Notes
3.1	AES-ECB	Older devices; plaintext DPS in status response
3.3	AES-ECB	Most common; encrypted payloads
3.4	AES-GCM	Requires session key negotiation
3.5	AES-GCM	Latest; similar to 3.4 with minor differences

"v3.4 session key negotiation failed" — This usually means:

• Wrong local key (re-fetch via wizard)
• The device is actually v3.3 (try set_version(3.3))
• Another app is holding the connection — close Tuya Smart app first

"Unknown v3.4 Device" in scan — The device broadcasts as v3.4 but can't be queried until you have the local key from the wizard.

---

6. Commands are sent but nothing happens

• Try different DPS (Data Point System) values — every device type uses different DPS numbers
• Use d.status() first to see current DPS values before sending commands
• Some devices need a persistent connection: d.set_socketPersistent(True)
• For plugs/switches, dps=1 is the most common on/off DPS, but some use dps=20 or other values — check d.status() output
• Run python3 -m tinytuya scan -all to dump all available DPS values for your device

Device responds to status but ignores set commands:

• Some devices are "read-only" locally (e.g., energy sensors, some thermostats in cloud-only mode)
• Try using d.set_value(dps_id, value) with the exact DPS ID from the status output
• Make sure you're not mixing up Device ID and Local Key

---

7. Device works sometimes but drops connection

• Tuya devices have a connection limit — Tuya cloud app being connected may cause conflicts
• Set d.set_socketTimeout(5) and handle reconnection in your code
• v3.4/v3.5 devices may require session-based connect/close pattern
• Polling too frequently can cause devices to stop responding — add a delay between requests (minimum 1-2 seconds recommended)
• Some devices (especially heatpumps and thermostats) have a built-in connection limit per time window — if you exceed it, the device stops responding until rebooted. Reduce polling frequency and use set_socketPersistent(True) to reuse the connection
• Error 914 / "Check device key or version" after extended use usually means the device's session has expired — close and reopen the connection, or restart with a fresh Device() instance
• TCP keepalive can help with persistent connections: see issue #678 for the latest discussion

---

8. I have a new/unsupported device

1. Run python3 -m tinytuya scan -all to capture raw DPS data
2. Use d.status() while toggling the device manually in the Tuya app
3. Share the output in your issue — this helps add support!

---

9. Where are device-specific DPS mappings?

• The TinyTuya wiki
• Run the wizard and check devices.json — the "dps_cache" section contains all DPS for your device
• Search past issues for your device model
• The Tuya developer docs have standard DPS codes by category

Some DPS only available via cloud (not local):

• Certain data points (energy totals, historical logs, some configuration settings) are only accessible through the Tuya Cloud API, not the local protocol
• Use tinytuya.Cloud for these: c.getproperties(device_id) or c.getdevicelog(device_id)

---

10. Zigbee / Sub-devices / Gateway setup

Tuya Zigbee devices use a hub/gateway architecture:

• The Zigbee end-devices (sensors, plugs, etc.) communicate with a Zigbee gateway hub via Zigbee radio
• The gateway hub connects to your WiFi and is the device you control with tinytuya
• You do NOT connect to Zigbee end-devices directly via tinytuya

Setting up Zigbee sub-device control:

import tinytuya

# Connect to the Zigbee gateway
gw = tinytuya.Device(GATEWAY_DEVICE_ID, GATEWAY_IP, GATEWAY_LOCAL_KEY)
gw.set_version(3.3)  # or whatever version your gateway uses

# Access a sub-device via its CID (from devices.json)
child = tinytuya.OutletDevice(CHILD_DEVICE_ID, cid=CHILD_CID, parent=gw)
print(child.status())

• The child device's cid value is found in devices.json after running the wizard
• The child device uses the gateway's IP and key — not its own
• If the gateway is working but child status returns empty, check that the child's cid is correct in your devices.json
• Some newer Zigbee gateways (Matter-based) may use different protocols — see issue #592

Zigbee devices showing no payload / Unexpected Payload:

• Verify the gateway is on a supported protocol version
• Some Zigbee child devices only report status when triggered (not on poll)
• Battery-powered Zigbee sensors also sleep and won't respond to polls

---

11. BLE (Bluetooth) devices

TinyTuya does not support Bluetooth/BLE devices directly. Tuya BLE devices require:

• A BLE gateway hub that bridges BLE to WiFi — you then control the gateway via tinytuya
• The Tuya Smart or SmartLife app running on a phone acts as the BLE bridge

Fingerbot, BLE lamps, BLE sensors:

• These require a compatible Bluetooth gateway (e.g., Tuya Bluetooth gateway, wg2-type)
• Connect the BLE gateway to tinytuya; the BLE device is a sub-device of the gateway
• Direct BLE control from a Raspberry Pi or PC is not supported by tinytuya

---

12. Cloud-only devices (no local control possible)

Some Tuya devices are designed to only communicate via the Tuya cloud and do not support direct local TCP connections:

• Battery-powered devices that sleep (sensors, door contacts, smoke detectors)
• Devices using BLE-only (no WiFi module)
• Some cameras and doorbells
• Certain pet feeders, vacuum robots, and specialty devices that require cloud for DPS initialization

Signs your device is cloud-only:

• status() returns {'dps': {}} (empty) when cloud is blocked, but works when cloud is accessible
• The device doesn't respond to local TCP connections at all
• scan shows the device but status() times out

Workaround:

• Use tinytuya.Cloud to control these devices via the Tuya cloud API
• Some devices only need one initial cloud connection for setup, then work locally — try allowing internet for 10 seconds, then blocking it

---

13. IR Remote Control devices

Tuya WiFi IR blasters (S06, S16, etc.) work with tinytuya but require specific DPS handling:

Sending IR commands:

• IR commands are encoded in base64 in specific DPS fields (usually DPS 201 or similar)
• Use tinytuya.Cloud to get the IR codes for your device:

  c.cloudrequest(f"/v2.0/infrareds/{ir_device_id}/remotes")

• Or use the "Learning" feature: put the IR blaster in learning mode, point your physical remote at it, then retrieve the learned code

Cannot control my specific TV/AC brand:

• Not all IR codes are in Tuya's database — you may need to use "IR learning" mode to capture codes from your physical remote
• Check the IRDevice example in the tinytuya examples

Receiving IR signals:

• Some IR blasters support learning/receiving IR — check your device's DPS for a "receive" or "learn" DPS

---

14. Installation issues

"error: externally-managed-environment" on modern Linux/Debian/Ubuntu:

# Option A: Use a virtual environment (recommended)
python3 -m venv ~/.tinytuya-env
source ~/.tinytuya-env/bin/activate
pip install tinytuya

# Option B: Use --break-system-packages (use with caution)
pip install tinytuya --break-system-packages

# Option C: Use pipx for CLI tools
pipx install tinytuya

"cannot import name ... from cryptography" or OpenSSL errors:

• Your cryptography package is outdated: pip install --upgrade cryptography
• On Raspberry Pi or older systems: sudo apt update && sudo apt install python3-cryptography

OSError: [Errno 98] Address already in use:

• Another instance of tinytuya (or another app on ports 6666/6667) is already running
• Run lsof -i :6666 to find the conflicting process and kill it
• Or wait a minute for the OS to release the socket

Installing in Docker:

• Use a Python base image and install normally: pip install tinytuya
• Make sure the container is on the host network (--network=host) so it can reach your LAN devices via UDP broadcast

---

15. TinyTuya is local-only — it does NOT work over the internet (WAN/VPS)

TinyTuya uses the Tuya local protocol which only works on the same local network (LAN) as your devices. This is a fundamental protocol limitation, not a tinytuya limitation.

This means:

• Running tinytuya on a VPS or cloud server will not work for local device control
• Devices are not accessible via their public IP or over the internet
• There is no tunneling or relay in the local protocol

Alternatives if you need remote access:

• Use tinytuya.Cloud for full cloud-based control (requires active IoT subscription)
• Run tinytuya on a local server (Raspberry Pi, NAS, etc.) and expose it via a secure tunnel (WireGuard VPN, Tailscale, etc.)
• Run the TinyTuya server locally and access its REST API remotely through a VPN

Tuya devices use a custom binary TCP protocol (not HTTP) on port 6668. There is no REST API exposed locally — only tinytuya's protocol implementation.

---

16. Device ID differences / "Why does my scan ID differ from tuya-cli?"

Some devices report two different identifiers:

• Device ID from scan (tinytuya): The actual hardware device ID broadcast via UDP
• Virtual ID (used by tuya-cli/cloud): A Tuya cloud virtual device ID

These can be different! The wizard handles this automatically. If you're comparing IDs manually:

• Use the Device ID from the scan output with tinytuya local control
• Use the Virtual ID (from Tuya IoT platform) for cloud API calls
• The wizard merges both into devices.json

---

17. Running TinyTuya as a service / background daemon

Using systemd (Linux):

[Unit]
Description=TinyTuya Server
After=network.target

[Service]
ExecStart=/usr/bin/python3 -m tinytuya server
WorkingDirectory=/home/pi/tinytuya
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

Common issues with background/service mode:

• The tinytuya scanner uses UDP broadcast — make sure your service has network access
• If using supervisord, ensure the process has the correct working directory and network access
• Run as a user with read access to your devices.json and snapshot.json

Async/await support:

• TinyTuya does not currently have native async support
• For async applications, run tinytuya calls in a thread executor: await loop.run_in_executor(None, device.status)
• See issue #156 for the latest discussion

---

Still stuck? Please include in your issue:

• TinyTuya version (python3 -m tinytuya version)
• Python version
• Device type and model
• Protocol version (3.1 / 3.3 / 3.4 / 3.5)
• Output of python3 -m tinytuya scan (redact your local key)
• The full error message or unexpected behavior

The more detail you provide, the faster we can help! 🙏