tuyaopen-embedded-cli-debug

Files (6)

• SKILL.md
• CLI_DEBUG.md · references/
• CRASH_DECODE.md · references/
• requirements.txt
• cli_debug.py · scripts/
• monitor_helper.py · scripts/

SKILL.md (first lines)

# TuyaOpen Diagnose

Covers the CLI groups `diag doctor` / `diag export` / `diag doctor` /
`firmware list-ports` / `firmware monitor`, plus three absorbed
device-debugging skills that all answer "something's wrong, now what" and
used to overlap without a clear boundary: serial log capture, sending
ad-hoc commands to the device's CLI, and decoding a crash dump. Pick
the section that matches the symptom:

| Symptom | Section |
|---|---|
| "Is my dev environment set up right?" / "which CLI am I even running?" | § 1 `diag doctor` |
| "I need to attach diagnostics to a bug report" | § 2 `diag export` |
| "I just want to watch device logs live" | § 3 Foreground |
| "I want the device's boot/runtime log without blocking my terminal" | § 3 Background / non-blocking |
| "I want to poke the running device — dump KV, check heap, force a reset" | § 4 Send commands to the device CLI |
| "The device pasted a panic/hard-fault dump with hex addresses" | § 5 Decode a crash dump |

For the CLI's envelope, exit codes, and self-discovery (`schema get`), see
skill `tuyaopen-start` — not repeated here.

## Shortcuts — `tuyaopen-cli firmware`

| Intent | Command |
|---|---|
| List serial ports (for § 2/§ 3 port selection) | `tuyaopen-cli firmware list-ports --chip <chip>` |
| Foreground serial monitor | `tuyaopen-cli firmware monitor --port <port>` |

Flags aren't listed here — run `tuyaopen-cli schema get --group <g> --command <c>`
for the current set. Resolve `tuyaopen-cli` first per skill `tuyaopen-start` § 1
(it is usually not on `PATH`).

> **Looking for `diag doctor` / `diag export` / `diag doctor`?** They moved to
> skill `tuyaopen-start` — they diagnose the CLI and the host, not the device.
>
> **No CLI?** `tos.py monitor -p <port>` covers the foreground monitor. See
> skill `tuyaopen-start` § 7 for the rest of the coverage map.

## 0. 先把设备 CLI 打开、初始化，再谈调试

设备端的串口 CLI **默认是关的**，而且"编进固件"和"跑起来"是两件事 —— 两件都做了它才应答。
本节是这个技能所有内容的前置。

### 0.1 两道独立的门，别只看一道

设备上有没有 CLI，取决于**两件互不相干的事**。调试时"没反应"先分清是哪一道没过。

#### 门 1：应用得调 `tal_cli_init()` —— 决定有没有 `tuya> ` 提示符

CLI 子系统**不会自动起来**。应用的 main 里必须有：

```c
#include "tal_cli.h"
...
tal_cli_init();          // 默认 UART0；或 tal_cli_init_with_uart(n)
```

没有这一句，串口上**一个提示符都不会有**，跟 Kconfig 怎么配没有关系。
`apps/tuya_cloud/switch_demo` 的骨架里带了这句，所以从它抄来的工程会"莫名其妙就有
CLI"；从零写的 main 则没有。

#### 门 2：`CONFIG_ENABLE_SERIAL_CLI_CMD` —— 决定有多少条命令

过了门 1 之后，**默认只有八条**：

```
help  cmd  hello  version  sys_log_enable  sys_reboot  auth  read_mac
```

`sys_log_enable` 和 `sys_reboot` 在 `cli_cmd.c` 命令表里位于
`#if defined(CLI_CMD_SYS)` **之上**，所以这两条不受 Kconfig 影响；`auth` /
`auth-read` / `read_mac` 来自 `tuya_authorize.c`，同样无条件注册。ESP32-S3 实测：
`# CONFIG_ENABLE_SERIAL_CLI_CMD is not set` 的固件上 `help` 回的正是这八条，固件自己
还打了一句
`if you want to see more commands(sys_*, fs_*, kv_*), please turn on ENABLE_SERIAL_CLI_CMD in Kconfig`。

打开总开关才有另外三组：

```
CONFIG_ENABLE_SERIAL_CLI_CMD=y     # 总开关，SDK 里 default n
CONFIG_SERIAL_CLI_STACK_SIZE=3072  # CLI 线程栈，默认 3072
CONFIG_CLI_CMD_SYS=y               # sys_* 组：状态/堆/线程/版本/IoT/WiFi，默认 y
CONFIG_CLI_CMD_FS=y                # fs_*  组：ls/cat/write/rm…，默认 y
CONFIG_CLI_CMD_KV=y                # kv_*  组：get/set/del/list，默认 y
```

三个 `CLI_CMD_*` 都 `default y`，但**只在总开关打开时才存在**（Kconfig 里它们包在
`if (ENABLE_SERIAL_CLI_CMD)` 内）。所以某条 `sys_*` 找不到有三种成因，按这个顺序查：
应用没调 `tal_cli_init()` → 总开关没开 → 那一组被单独关了。完整命令清单见
[references/CLI_DEBUG.md](references/CLI_DEBUG.md)。

**开发期两道门都打开。** 打开之后 agent 可以直接驱动设备验证功能，而不是只能
"编译→烧录→读日志猜"：`sys_iot_report_dp` 上报一个 DP 看面板反应、`sys_wifi_info`
看设备眼里的 AP、`sys_heap` / `sys_thread` 查内存和栈、`kv_list` 看持久化。量产前
关掉总开关（`tal_cli_init()` 是否保留另行决定）。

写进工程的 `app_default.config`（或 `config/<BOARD>.config`），**不要**去改 SDK 里的
`Kconfig`：那是 vendored 文件，`tuyaopen-cli sdk update` 会把你的改动冲掉。

### 0.2 初始化：Kconfig 只负责编进去，还得有人调它

**这是最容易漏的一步**，而且症状和"没开 Kconfig"一模一样：串口敲命令没有任何回应。

```c
#include "tal_cli.h"

// 在 tuya_main.c 的初始化流程里，串口可用之后
tal_cli_init();                    // 默认走 TUYA_UART_NUM_0
// 或者指定串口：
tal_cli_init_with_uart(1);
```

SDK 里的实例：`apps/tuya.ai/your_chat_bot/src/tuya_main.c`、`your_otto_robot`、
`your_desk_emoji`、`your_robot_dog`、`duo_eye_mood` 都在 `tuya_main.c` 里调了
`tal_cli_init()`。

> **反例值得记住**：`apps/tuya.ai/your_serial_chat_bot/src/tuya_main.c` 里这一行是
> **被注释掉的** —— 那个 app 把串口用作聊天通道，CLI 会和它抢同一个 UART。
> 如果你的应用也在用 UART0 做别的事，用 `tal_cli_init_with_uart(<其他串口号>)`，
> 不要两个都往 UART0 上挂。

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

More from tuya/tuyaopen-ide-manifests