Skip to main content

DuckyClaw Quick Start (ESP32-S3)

This guide walks you through building and flashing the DuckyClaw firmware on an ESP32-S3 development board. It is for developers who want to run DuckyClaw 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
git clone https://github.com/tuya/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
git submodule update --init

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 1 to select ESP32S3_BREAD_COMPACT_WIFI:

--------------------
1. ESP32S3_BREAD_COMPACT_WIFI.config
2. RaspberryPi.config
3. TUYA_T5AI_BOARD_LCD_3.5_CAMERA.config
--------------------
Input "q" to exit.
Choice config file: 1

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 DuckyClaw notifications or interact via a messaging app, set the channel to feishu, telegram, or discord and fill in the corresponding credentials in tuya_app_config.h:

// IM configuration
// feishu | telegram | discord
#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.

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

du 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​