tuyaopen-embedded-build

Files (3)

• SKILL.md
• KCONFIG_GUIDE.md · references/
• cmake-dependencies.md · references/

SKILL.md (first lines)

# TuyaOpen Build

Docs: <https://tuyaopen.ai/docs/quick-start/project-compilation>

## Shortcuts — `tuyaopen-cli firmware` (IDE-scaffolded projects)

| Intent | Command |
|---|---|
| Compile | `tuyaopen-cli firmware build --project-root <project>` |
| Remove build artifacts | `tuyaopen-cli firmware clean --project-root <project>` |
| Full clean (deletes `.build/` entirely, `tos.py clean -f`) | `tuyaopen-cli firmware clean --project-root <project> --force` |

**首次全量编译要放宽超时。** `firmware build` 默认 300 s，而**第一次**编译还要下载平台与
工具链，正常就会超过 —— 内测第一轮就撞上了，然后被迫放弃包装层直接跑 `tos.py build`，同时
丢掉了日志捕获和类型化信封。改成：

```bash
tuyaopen-cli firmware build --timeout 1800     # 首次全量；0 = 完全不设超时
```

超时的报错现在会点名这个 flag。增量编译用默认值就够（实测约 40 s）。

> **No CLI?** `tos.py build` / `tos.py clean` (`-f` for full clean). See
> skill `tuyaopen-start` § 7.

`--project-root` is the **IDE project root** — the directory holding
`.tuyaopen/` and `source/embedded/` (see skill `tuyaopen-start` § 8) — not an
SDK `apps/`/`examples/` directory. It defaults to the current directory, so
`cd <project>` then omit the flag works too. Both commands are risk tier
**P3**: mutating, but **no** `--dry-run`/`--confirm`/`--yes` gate applies (see
skill `tuyaopen-start` § 4 — P3 is a real tier, distinct from P0/P2, for
commands the framework doesn't consider destructive).

Two things `tuyaopen-cli firmware build`/`clean` do that raw `tos.py build` does
not, verified against `src/cli/commands/firmware.ts`:

- **Self-activates the SDK env** — it calls the same bootstrap `tuyaopen-cli sdk
  env-init` would, so you don't need `. ./export.sh` first.
- **Pre-syncs the platform submodule to its pinned commit** before building,
  so the `y/n/d` "platform commit mismatch" prompt that raw `tos.py build`
  can hang on (see § *Build* below) never fires — the
  `.cache/.dont_prompt_update_platform` workaround is a `tos.py`-direct-only
  concern.

Full flags (baud, `--sdk-root`, `--stream` for ndjson progress): `tuyaopen-cli
firmware --help` / `tuyaopen-cli schema get --group firmware --command build` —
don't hardcode the flag list here, it drifts (see skill `tuyaopen-start` § 5).

**Everything below this point — Kconfig, `tos.py config`/`menu`/`choice`, and
building inside a raw SDK checkout's `apps/`/`examples/` tree — has no
`tuyaopen-cli` CLI equivalent.** `tuyaopen-cli config` is a different, unrelated
command (see the warning immediately below); use `tos.py` directly for all of
it.

## ⚠ `tuyaopen-cli config` is not Kconfig — read before touching either `config`

`tos.py config` (Kconfig/menuconfig — everything in this skill) and
`tuyaopen-cli config` (`get`/`set`/`list` over exactly three **IDE settings**:
`language`, `gitMirror`, `manifestsSource`) are two unrelated commands that
share a word. Typing `tuyaopen-cli config set` to change a build option is the
intuitive guess and the **wrong** one — it silently rejects the key instead of
touching Kconfig, since none of the three IDE settings match. Full detail:
skill `tuyaopen-start` § 7.

> **SDK root:** All `tos.py`-direct paths and commands below are relative to
> the TuyaOpen SDK root (`$OPEN_SDK_ROOT` on Linux/macOS/PowerShell,
> `%OPEN_SDK_ROOT%` on Windows CMD). Activate the environment first — see
> the `tuyaopen-start` routing table.

## Project Locations

Buildable projects live in two directories:

- `apps/` — application projects (e.g. `apps/tuya_cloud/switch_demo`, `apps/tuya.ai/your_chat_bot`)
- `examples/` — example projects (e.g. `examples/get-started/sample_project`, `examples/peripherals/gpio`)

Navigate into the target project before building:

```bash
cd apps/tuya_cloud/switch_demo
```

## Configuration

### Selecting a Verified Config

```bash
tos.py config choice                           # interactive — list and pick
tos.py config choice -c TUYA_T5AI_EVB         # non-interactive — select by name (Agent / CI)
tos.py config choice -c Linux                  # non-interactive — LINUX / Ubuntu native build
tos.py config choice -d                        # interactive — board default configs only
tos.py config choice -d -c TUYA_T5AI_EVB      # non-interactive — from board defaults
tos.py config choice -l                        # list names and exit, no clean (newer SDK — check `config choice -h`)
```

All variants trigger a full clean. The selected config is written to `app_default.config`.

Config lookup priority: project `config/` dir > `boards/` global configs.

**`-c` flag (non-interactive, preferred for Agent / CI):**  
Matches config by filename — `.config` extension is optional (`TUYA_T5AI_EVB` and `TUYA_T5AI_EVB.config` are equivalent).  
If the name is not found, the command exits with an error and prints the available config names.

Config names do not always match the platform or board directory — the LINUX / Ubuntu target is `Linux` — so list them with `-l` instead of guessing. A config file may also be legitimately **empty**: defconfig records only deviations from Kconfig defaults, so a target that already *is* the default (such as `boards/LINUX/config/Linux.config`) has nothing to record. A 0-byte config is valid, not broken.

### Fine-Tuning with Menuconfig (requires TTY)

```bash
tos.py config menu    # terminal-based Kconfig editor; resolves depends on/select automatically
tos.py config save    # interactive (requires TTY) — save current config as named preset
```

Menuconfig keys: arrows or `h`/`j`/`k`/`l`; `?` for help; write to `app_default.config` on exit.

### Writing a Custom Config (Agent / CI)

Two paths, depending on what the installed SDK supports. **Ask it — don't guess from a version number:**

```bash
tos.py config -h        # the subcommand list IS the answer; look for 'set'

From tuya/tuyaopen-ide-manifests, Apache-2.0.

More from tuya/tuyaopen-ide-manifests