Back to LearnTuyaOpen SDK

Build your first firmware

Configure the switch_demo project for your board and compile it into a flashable bin with tos.py — the binary the next page flashes onto the device.

Beginner8 minBuild

What you get at the end

A firmware binary — switch_demo_QIO_1.0.0.bin — sitting in your project’s .build/bin/ directory, ready to flash. The build prints the full path when it finishes.

tos.py build downloads the right toolchain into platform/ on first run, so the first build is slower than later ones.
The output bin name follows the pattern <app>_<QIO>_<version>.bin — QIO is the flash read mode.
You must build from inside the application project directory (where tos.py build is run).

Pick a project

TuyaOpen builds applications from the apps/ and examples/ directories. This page uses switch_demo — a small cloud-connected switch — as the worked example.

cd apps/tuya_cloud/switch_demo

Configure the project

Run tos.py config choice to list the verified board configurations for this project, then pick the one that matches your hardware. The choice is written to app_default.config in the project path.

❯ tos.py config choice
[INFO]: Fullclean success.
--------------------
1. LN882H.config
2. EWT103-W15.config
3. Ubuntu.config
4. ESP32-C3.config
5. ESP32-S3.config
6. ESP32.config
7. T3.config
8. T5AI.config
9. T2.config
10. BK7231X.config
--------------------
Input "q" to exit.
Choice config file:

Common board → config

Pick the config that matches your board:

Tuya T5AIT5AI.config

Tuya T3T3.config

Tuya T2T2.config

Beken BK7231XBK7231X.config

ESP32ESP32.config

ESP32-C3ESP32-C3.config

ESP32-S3ESP32-S3.config

LN882HLN882H.config

Ubuntu (Linux host)Ubuntu.config

The config operation may switch toolchain, so it runs a deep clean first. If your project has its own config/ directory, those configs take priority over the ones in boards/ — run tos.py config -d choice to force configs from boards/ only.

Build

From the project directory, run tos.py build. Add -v for verbose output if you need to diagnose a failure.

❯ tos.py build
...
[INFO]: ******************************
[INFO]: /xxx/TuyaOpen/apps/tuya_cloud/switch_demo/.build/bin/switch_demo_QIO_1.0.0.bin
[INFO]: ******************************
[INFO]: ******* Build Success ********
[INFO]: ******************************

The build downloads the toolchain, runs its prepare, creates .build/, runs ninja, and places artifacts in .build/bin.
The build ends with Build Success and prints the bin path — that path is what you flash next.
On Windows, if each file takes ~3 s to compile, see Troubleshooting below.

Clean the build

To clear the build cache, run tos.py clean. Add -f for a deep clean that also deletes the .build directory after ninja clean.

❯ tos.py clean -f
[INFO]: Running tos.py ...
[INFO]: Fullclean success.

Troubleshooting

Compilation is very slow on Windows

Open Task Manager (Ctrl+Shift+Esc), find and close the MSPCManagerService process. If that does not help, move the whole TuyaOpen directory to a non-system drive (e.g. D:) and add it to the exclusion list under Windows Security → Virus & threat protection.

config choice does not list my board

The list comes from the project’s config/ directory first, then TuyaOpen/boards/. Run tos.py config -d choice to force configs from boards/ only. If your board still is not listed, it may not have a verified config for this app yet.

Build fails after I changed config with tos.py config menu

Changing config can break a build. Re-run tos.py config choice to pick a verified config, or tos.py clean -f and rebuild. You can also ask technical support.

could not lock config file warning

A stale ~/.gitconfig.lock is left behind. Delete it manually: rm ~/.gitconfig.lock, then retry.

Next: flash and monitor →Full build docs →