Skip to main content

TuyaOpenClaw Quick Start (ESP32-S3)

This guide walks you through building and flashing the TuyaOpenClaw (formerly DuckyClaw) firmware on an ESP32-S3 development board. It is for developers who want to run TuyaOpenClaw on ESP32-S3 with Wiโ€‘Fi.

Requirementsโ€‹

  • ESP32-S3 development board with PSRAM 8 MB and FLASH 16 MB.
  • USB data cable to connect the board to your computer.
  • Computer running Windows 10/11, Linux (e.g. Ubuntu 20/22/24 LTS), or macOS.
  • Tuya Cloud: This demo uses Tuya Cloud services. You need a valid license key (authorization code) and correct PID, UUID, and AuthKey in tuya_app_config.h for cloud and LLM features.
note

If your development board has microphone and speaker support, ASR (Automatic Speech Recognition) is enabled as the default input method and can coexist with IM (messaging apps).

Stepsโ€‹

1. Install build tools (Python, Make, Git)โ€‹

Install the required tools on your host machine.

info

We recommend Ubuntu 20, 22, or 24 LTS.

Install the required packages:

sudo apt-get install lcov cmake-curses-gui build-essential ninja-build wget git python3 python3-pip python3-venv libc6-i386 libsystemd-dev

2. Clone the repoโ€‹

info

You can increase Git buffer size for large clones:

git config --global http.postBuffer 524288000

# Github repo
git clone https://github.com/tuya/DuckyClaw.git

# Gitee repo
git clone https://gitee.com/tuya-open/DuckyClaw.git
warning

Use a project path without spaces or non-ASCII characters. On Windows, avoid using the C: drive root.

3. Activate the build environmentโ€‹

cd DuckyClaw

# update from github
git submodule update --init

# update from gitee
git config --global url."https://gitee.com/tuya-open/".insteadOf "https://github.com/tuya/"
git submodule update --init
note

If you need to switch back to pulling code from Github, run:

git config --global url."https://github.com/tuya/".insteadOf "https://gitee.com/tuya/"

Activate the TuyaOpen build environment so tos.py is available:

warning

You must run the activation command again in each new terminal session.

. ./TuyaOpen/export.sh

Verify the environment:

tos.py version
tos.py check

You should see version output (e.g. v1.3.0) and a list of tools (git, cmake, make, ninja) with OK status. Submodules will be downloaded if needed.

4. Select the board configurationโ€‹

Run the config chooser from the project root:

cd ..
tos.py config choice

Enter 3 to select ESP32S3_BREAD_COMPACT_WIFI:

--------------------
1. ATK_T5AI_MINI_BOARD_2.4LCD_CAMERA.config
2. DshanPi_A1.config
3. ESP32S3_BREAD_COMPACT_WIFI.config
4. RaspberryPi.config
5. TUYA_T5AI_BOARD_LCD_3.5_CAMERA.config
6. WAVESHARE_T5AI_TOUCH_AMOLED_1_75.config
--------------------
Input "q" to exit.
Choice config file: 3

5. Edit application configurationโ€‹

Open DuckyClaw/include/tuya_app_config.h and set the following.

LLM / Tuya Cloud (required for cloud and AI):

  • TUYA_PRODUCT_ID โ€” your product ID (PID); this is the binding key between the device and cloud configurations.
  • TUYA_OPENSDK_UUID โ€” Open SDK UUID.
  • TUYA_OPENSDK_AUTHKEY โ€” Open SDK AuthKey.

Replace the placeholder values. Obtain:

IM configuration (optional): To receive TuyaOpenClaw notifications or interact via a messaging app, set the channel to weixin, feishu, telegram, or discord and fill in the corresponding credentials in tuya_app_config.h:

// IM configuration
// feishu | telegram | discord | weixin
#define IM_SECRET_CHANNEL_MODE      "feishu"

#define IM_SECRET_FS_APP_ID         ""
#define IM_SECRET_FS_APP_SECRET     ""

#define IM_SECRET_DC_TOKEN          ""
#define IM_SECRET_DC_CHANNEL_ID     ""

#define IM_SECRET_TG_TOKEN          ""
  • For Feishu: set IM_SECRET_CHANNEL_MODE to "feishu" and fill IM_SECRET_FS_APP_ID and IM_SECRET_FS_APP_SECRET.
  • For Discord: set IM_SECRET_CHANNEL_MODE to "discord" and fill IM_SECRET_DC_TOKEN and IM_SECRET_DC_CHANNEL_ID.
  • For Telegram: set IM_SECRET_CHANNEL_MODE to "telegram" and fill IM_SECRET_TG_TOKEN.
  • For Weixin: set IM_SECRET_CHANNEL_MODE to "weixin". On first login, open the link printed in the log and scan the QR code with WeChat to bind. Press the reset button three times to clear Wi-Fi provisioning data and the Weixin binding.
[weixin] =========================================================
[weixin]   Weixin QR Login
[weixin]   Open this URL in your PC browser, then scan with WeChat:
[weixin]   https://open.weixin.qq.com/connect/qrconnect?...
[weixin] =========================================================

6. Build and flashโ€‹

Build the project:

tos.py build

After a successful build, flash the firmware to the board:

tos.py flash

Connect to the serial console to view logs:

tos.py monitor

Expected outcome: The firmware builds without errors, flashes to the ESP32-S3, and the device boots. Use the serial monitor to confirm startup and, if configured, cloud connectivity.

7. Device activation and network setupโ€‹

To use Tuya Cloud features, add the device in the Smart Life app and complete Wiโ€‘Fi provisioning.

Download the Smart Life appโ€‹

Install Smart Life (ๆ™บ่ƒฝ็”Ÿๆดป) from the Apple App Store or your Android app store, or scan the QR code on the Tuya Smart Life app page.

Confirm device is in provisioning modeโ€‹

Before adding the device in the app, ensure it is in activation (provisioning) mode. In the serial log you should see lines similar to (TuyaOpen):

[01-01 00:00:01 ty D][tuya_iot.c:774] STATE_START
[01-01 00:00:01 ty I][tuya_iot.c:792] Activation data read fail, go activation mode...
[01-01 00:00:01 ty D][tuya_main.c:143] Tuya Event ID:1(TUYA_EVENT_BIND_START)

Add the device in the appโ€‹

  1. In the Smart Life app, tap Add device (or the + button) to open the add-device flow.
  2. Grant the app Wiโ€‘Fi and Bluetooth permissions when prompted; otherwise the app cannot discover the device.
  3. Follow the in-app steps to connect the device to your Wiโ€‘Fi network.
  4. On the Home or Add device screen, when the device appears, tap Add and complete the guided setup.
warning

TuyaOpen-supported modules connect only to 2.4 GHz Wiโ€‘Fi. Using a 5 GHz network will cause provisioning to fail.

Troubleshootingโ€‹

Device not discovered or provisioning fails due to invalid authorizationโ€‹

If authorization data was not written correctly, the device may log errors such as:

[01-01 00:00:00 ty E][tal_kv.c:269] lfs open UUID_TUYAOPEN -2 err
[01-01 00:00:00 ty E][tuya_authorize.c:107] Authorization read failure.
[01-01 00:00:00 ty W][tuya_main.c:288] Replace the TUYA_OPENSDK_UUID and TUYA_OPENSDK_AUTHKEY contents...

If the log shows uuid and authkey as placeholder values (e.g. uuidxxxxxxxxxxxxxxxx), the license (UUID and AuthKey) was not applied correctly. Obtain or purchase a TuyaOpen license at Tuya IoT Platform โ€“ Open SDK and set TUYA_OPENSDK_UUID and TUYA_OPENSDK_AUTHKEY in tuya_app_config.h, then rebuild and reflash.

If productkey (PID) appears as placeholders, the product ID was not set. Copy or create a product and get your PID from the Tuya product link, then set TUYA_PRODUCT_ID in tuya_app_config.h, rebuild, and reflash.

Referencesโ€‹