tuya/tuyaopen-dev-skills/device-auth

TuyaOpen Device Authorization & Provisioning

Docs: <https://tuyaopen.ai/docs/quick-start/equipment-authorization>

Authorization Overview

TuyaOpen devices need three credentials to connect to the Tuya cloud:

Credential Resolution Priority

The SDK resolves credentials in this order (first success wins):

1. KV storage — previously written via CLI auth command (keys: UUID_TUYAOPEN / AUTHKEY_TUYAOPEN)
2. OTP / module flash — tuya_iot_license_read() reads from hardware (pre-burned modules)
3. Source code macros — TUYA_OPENSDK_UUID / TUYA_OPENSDK_AUTHKEY in tuya_config.h

If none succeed, the device cannot connect to the cloud.

Configuring tuya_config.h

Each application has a tuya_config.h (in include/ or src/). Edit it with your credentials:

#define TUYA_PRODUCT_ID      "xxxxxxxxxxxxxxxx"
#define TUYA_OPENSDK_UUID    "uuidxxxxxxxxxxxxxxxx"
#define TUYA_OPENSDK_AUTHKEY "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Optional for AP provisioning with QR code:

#define TUYA_NETCFG_PINCODE  "12345678"

File locations (vary by project):

• apps/tuya_cloud/switch_demo/src/tuya_config.h
• apps/tuya.ai/your_chat_bot/include/tuya_config.h
• apps/tuya_cloud/weather_get_demo/include/tuya_config.h

Note: some README files reference TUYA_DEVICE_UUID / TUYA_DEVICE_AUTHKEY — these are outdated names. The actual macros used in source code are TUYA_OPENSDK_UUID / TUYA_OPENSDK_AUTHKEY.

Getting Credentials

Product ID (PID)

1. Log in to Tuya IoT Platform.
2. Create a product matching your device type.
3. Copy the PID from the product page.

UUID + AuthKey

TuyaOpen-specific authorization codes come in three ways:

1. Pre-burned modules — some Tuya modules ship with credentials in OTP; no manual setup needed.
2. Purchase from Tuya platform — <https://platform.tuya.com/purchase/index?type=6>
3. Free developer codes — Tuya periodically offers free authorization codes for developers; check the platform for current offers.

Important: only TuyaOpen-specific authorization codes work. Standard Tuya module authorization codes are not compatible.

Writing Auth via Serial & Network Provisioning

For CLI-based serial authorization (port selection, baud rates, commands), provisioning modes (BLE / AP), and the full provisioning flow, see references/PROVISIONING.md.

Serial port discovery (agents)

Before writing auth credentials over UART, identify the correct port:

1. List available ports:

``bash # Linux / macOS ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null # Windows PowerShell [System.IO.Ports.SerialPort]::GetPortNames() ``

1. For T5/T5AI boards (WCH dual-serial, VID 0x1a86 PID 0x55d2): the lower enumerated port is typically used for flash/auth; the higher port for monitor/log. This is not guaranteed — swap if the auth command fails.
2. Use skill tuyaopen/debug-helper to capture device logs in the background during the auth flow:

``bash $OPEN_SDK_PYTHON .agents/skills/tuyaopen/debug-helper/scripts/monitor_helper.py start -p <monitor-port> # ... run auth on auth port ... $OPEN_SDK_PYTHON .agents/skills/tuyaopen/debug-helper/scripts/monitor_helper.py tail -n 100 $OPEN_SDK_PYTHON .agents/skills/tuyaopen/debug-helper/scripts/monitor_helper.py stop ``

Agent Strategy

When generating or modifying tuya_config.h

1. Always use placeholder values in generated code:

``c #define TUYA_PRODUCT_ID "your_product_id_here" #define TUYA_OPENSDK_UUID "your_uuid_here" #define TUYA_OPENSDK_AUTHKEY "your_authkey_here" ``

1. Warn the user if credentials appear to be placeholders when they attempt to build/flash for cloud testing.
2. Never log, commit, or display real UUID/AuthKey values in output, comments, or commit messages.
3. If the user provides real credentials, write them only to tuya_config.h and remind them not to commit the file with real values.

Detecting placeholder values

Placeholder patterns to check: values containing your_, xxx, here, empty strings, or strings shorter than expected length (UUID ~20 chars, AuthKey ~32 chars).