Skip to main content

Kconfig and project configuration

Overviewโ€‹

TuyaOpen projects are configured with Kconfig (menu-driven options) and a small saved file, app_default.config, in each application or example directory. The tos.py config commands connect the two: you pick a board preset, optionally open a graphical menu, and the result is written back to app_default.config.

This page has two parts:

  1. Everyday use โ€” enough to select a board, toggle common features, and recover from mistakes.
  2. Deeper dive โ€” how Kconfig files are wired together and how configuration reaches the compiler (for BSP, driver, or build work).

Audience: Application developers (first sections) and BSP/driver developers (deeper section).

Prerequisitesโ€‹

Requirementsโ€‹

  • Shell in the project directory (for example TuyaOpen/apps/tuya_cloud/switch_demo or TuyaOpen/examples/peripherals/gpio).

Everyday useโ€‹

What app_default.config isโ€‹

Each app or example keeps an app_default.config file in its project root. It stores only non-default Kconfig choices (a minimal diff). Together with the Kconfig trees under the SDK, it defines platform, board, enabled components, and many feature toggles.

For a structural overview, see TuyaOpen directory walkthrough โ€” app_default.config.

Step 1: Choose a board or preset (tos.py config choice)โ€‹

From your project directory:

tos.py config choice

You get a numbered list of preset .config files. Picking one replaces app_default.config with that preset. Presets come from:

  1. A config/ folder inside the project (if it exists), or
  2. Otherwise, board bundles under TuyaOpen/boards/ (typical for examples under examples/).

To only list board presets from boards/ (ignore the project config/ folder), use:

tos.py config -d choice
note

choice and menu run a deep clean first because the toolchain or platform may change when configuration changes.

Step 2: Adjust options (tos.py config menu)โ€‹

To open the menuconfig UI and change options interactively:

tos.py config menu

Save and exit in the menu when done; the tool updates app_default.config accordingly. Use this when tutorials ask you to enable a driver, LVGL, Bluetooth role, and similar options.

Screenshots and command help: tos.py โ€” config.

Step 3 (optional): Save your own preset (tos.py config save)โ€‹

After you have a working app_default.config (often after using menu), you can snapshot it as a named preset under the project config/ directory:

tos.py config save

Enter a name when prompted. That file can be selected later with tos.py config choice. This is useful for teams or for keeping debug vs release profiles.

If configuration breaks the buildโ€‹

  • Run tos.py config choice again and re-select a known-good preset.
  • Restore app_default.config from version control if you committed a working version.
  • Ask in support channels if a menu change pulled in an incompatible combination; see the warning on tos.py config menu.

Deeper dive (for developers)โ€‹

Where Kconfig definitions liveโ€‹

Configuration options are spread across the SDK and the project:

  • Project โ€” Kconfig in the app/example root (app-specific options).
  • SDK โ€” TuyaOpen/src/Kconfig and subtrees for components (Wi-Fi, Bluetooth, display, and so on).
  • Boards โ€” TuyaOpen/boards/<platform>/... supply board and chip choices.

tos.py config aggregates these into a catalog used to resolve your selections against app_default.config.

Generated files you may inspectโ€‹

After config or build, the project .build/cache/ directory (under the project, not the SDK root) typically holds generated configuration artifacts, including a merged view of selected symbols and metadata the build needs. The exact names can vary by tool version; treat this directory as generated โ€” edit app_default.config or use menu, not these cache files by hand.

After Kconfig resolves, the build reads <project>/.build/cache/using.config and continues with platform fetch and CMake; see Compilation guide. For how libtuyaos.a, tuyaapp, and board CMakeLists.txt fit together, see CMake, Kconfig, and the component model.

CONFIG_* symbols in C codeโ€‹

Enabled options become preprocessor macros (names usually prefixed with CONFIG_) included through generated headers used during compilation. When you select or depends on options in Kconfig, you are controlling which sources and defines participate in the link.

ESP32 and IDF menuconfigโ€‹

On ESP32 targets, native ESP-IDF configuration is available via tos.py idf menuconfig when the project is already configured for ESP32. See tos.py idf reference.

Expected outcomeโ€‹

After choice or menu, app_default.config reflects your board and features, and tos.py build uses that configuration on the next compile.

Referencesโ€‹