dog_dance 程序下载

目标芯片：**esp32s3** · 板型：**dog_dance**

本文含 **Linux** 与 **Windows** 两套完整流程，按你的系统看对应章节即可。

Linux

环境准备

- 已安装 ESP-IDF（版本与本仓库要求一致）

- 烧录线：USB‑TTL（CH340/CP2102）或板载 USB‑C（需支持数据）

每个新开的终端先加载 IDF（路径按本机修改）：

```bash

. ~/esp/esp-idf/export.sh

idf.py --version

```

编译

```bash

cd /path/to/dog_xiaozhi

# 换板型或构建异常时可清理：

# rm -rf build sdkconfig sdkconfig.old

idf.py set-target esp32s3

idf.py menuconfig

```

menuconfig 路径：`Xiaozhi Assistant` → `Board Type` → **dog_dance**

按 `/` 可搜索 `DOG_DANCE`。列表没有该项时，多半是 target 不是 `esp32s3`。

```bash

idf.py build

```

### 查看串口

```bash

ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

```

下面命令里的端口请换成你机器上实际出现的节点。

手动进入下载模式

多数 USB‑TTL 只有 TX/RX、没有自动 DTR/RTS，需要手动：

1. **按住 BOOT**

2. **点按 RST**

3. **先松 RST，再松 BOOT**

4. 1～2 秒内执行下面的 `flash` 命令（可加 `-b 115200`）

仍失败时，在出现 `Connecting....` 时继续按住 BOOT，直到开始写入。

接线：**模组 TX → 转换器 RX，模组 RX → 转换器 TX，GND 共地**。怀疑接反就对调 TX/RX 再试。

烧录

```bash

idf.py -p /dev/ttyUSB0 flash

idf.py -p /dev/ttyACM0 flash

首次或分区异常

idf.py -p /dev/ttyUSB0 erase-flash flash

# 编译 + 烧录 + 监视（退出监视：Ctrl+]）

idf.py -p /dev/ttyUSB0 flash monitor

```

请用 `-p` 或 `--port`，**不要**写 `-port`。若误设过环境变量：

```bash

unset ESPPORT

```

串口权限与干扰

**报错：`Path '/dev/ttyUSB0' is not readable`**

不要长期用 `sudo idf.py`。把用户加入 `dialout`：

```bash

sudo usermod -aG dialout $USER

# 注销并重新登录后：

groups # 必须含 dialout

```

当前终端临时生效：

```bash

newgrp dialout

idf.py -p /dev/ttyUSB0 flash monitor

```

**ttyUSB 一闪即失（CH341 + brltty）**

```bash

sudo apt remove brltty

# 拔插 USB 后再看

ls -l /dev/ttyUSB*

```

**设备不存在**

```bash

ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

dmesg | tail -n 30

```

换能传数据的线、换 USB 口，确认驱动已加载。

烧录失败排查

**`Invalid head of packet`**

1. 关掉占用串口的 `idf.py monitor`、minicom、串口助手

2. 手动进下载模式

3. 降波特率：

```bash

idf.py -p /dev/ttyUSB0 -b 115200 flash

idf.py -p /dev/ttyUSB0 -b 57600 flash

```

4. 对调 TX/RX；确认 3.3V 供电稳定

5. 手动进下载后避免自动复位打乱时序：

```bash

idf.py -p /dev/ttyUSB0 -b 115200 flash --extra-args="--before=no_reset"

```

**monitor 刷 `invalid header: 0xffffffff`**

Flash 无合法固件。先不要开 monitor，整片擦除再烧：

```bash

idf.py -p /dev/ttyUSB0 -b 115200 erase-flash flash

```

成功时应看到 `cpu_start` / `app_main`，以及：

```text

固件标识: board_type=dog_dance | 编译时间 ...

```

预编译固件（可选）

```bash

esptool.py -p /dev/ttyUSB0 -b 460800 write_flash 0x0 dog_dance_merged.bin

```

文件名与偏移以发布说明为准。日常开发仍推荐 `idf.py flash`。

屏 / 声软件开关

程序已跑但屏黑：查背光与排线，必要时改 `config.h` 后重编——`DISPLAY_BACKLIGHT_OUTPUT_INVERT`、`DISPLAY_SPI_MODE`（默认 3）、`DISPLAY_LCD_PCLK_HZ`、`DISPLAY_INVERT_COLOR` / `OFFSET_X`。

喇叭无声、麦正常：试 `AUDIO_I2S_SPK_SLOT_MASK`（LEFT/RIGHT/BOTH），再试 WS/BCLK 极性项；硬件确认 MAX98357 **SD_MODE=高**。

Windows

环境准备

- 安装 **ESP-IDF Windows Installer**（或 VS Code + Espressif 插件）

- 安装 CH340 / CP210x 等 USB 转串口驱动

- 打开开始菜单里的 **「ESP-IDF PowerShell」** 或 **「ESP-IDF CMD」**

（不要用未加载 IDF 的普通 PowerShell，否则找不到 `idf.py`）

```bat

idf.py --version

```

编译

路径尽量避免中文和空格，例如：

```bat

cd D:\work\dog_xiaozhi

idf.py set-target esp32s3

idf.py menuconfig

```

menuconfig：`Xiaozhi Assistant` → `Board Type` → **dog_dance**

按 `/` 搜索 `DOG_DANCE`。没有该项时先确认已 `set-target esp32s3`。

```bat

idf.py build

```

换板型异常时可删除 `build`、`sdkconfig`、`sdkconfig.old` 后重编。

查看串口（COM 号）

1. 插入板子或 USB‑TTL

2. 打开 **设备管理器** → **端口 (COM 和 LPT)**

3. 记下口号，例如 `COM3`、`COM5`、`COM7`

也可在 PowerShell：

```powershell

Get-PnpDevice -Class Ports | Where-Object { $_.Status -eq 'OK' }

```

下面示例一律用 **`COM3`**，请改成你的实际口号。

手动进入下载模式

多数 USB‑TTL 只有 TX/RX、没有自动 DTR/RTS，需要手动：

1. **按住 BOOT**

2. **点按 RST**

3. **先松 RST，再松 BOOT**

4. 1～2 秒内执行下面的 `flash` 命令（可加 `-b 115200`）

仍失败时，在出现 `Connecting....` 时继续按住 BOOT，直到开始写入。

接线：**模组 TX → 转换器 RX，模组 RX → 转换器 TX，GND 共地**。怀疑接反就对调 TX/RX 再试。

烧录

```bat

idf.py -p COM3 flash

idf.py -p COM3 erase-flash flash

idf.py -p COM3 flash monitor

```

退出监视器：`Ctrl+]`。

请用 `-p COM3` 或 `--port COM3`，**不要**写 `-port`。清除错误端口变量：

```bat

REM CMD

set ESPPORT=

```

```powershell

# PowerShell

Remove-Item Env:ESPPORT -ErrorAction SilentlyContinue

```

部分环境对 `COM10` 及以上可写成 `\\.\COM10`；一般先直接试 `COM10`。

串口常见问题

**设备管理器没有 COM 口**

- 换能传数据的 USB 线（纯充电线不行）

- 重装 CH340 / CP210x 驱动

- 看「其他设备」是否有黄色感叹号

- 换主机 USB 口，少用劣质 Hub

**`Could not open COM3` / Access denied**

- 关掉串口助手、Arduino IDE、另一份 `idf.py monitor`、部分手机助手

- 设备管理器中禁用再启用该 COM

- 拔插后 COM 号可能变化，以设备管理器为准

**乱码 / 连错口**

- 选数据 COM，不要选蓝牙虚拟串口

- 换电脑或换线对比排查

烧录失败排查

**`Invalid head of packet` / Failed to connect**

1. 关闭所有占用 COM 的软件

2. 手动进下载模式

3. 降波特率：

```bat

idf.py -p COM3 -b 115200 flash

idf.py -p COM3 -b 57600 flash

```

4. 对调 TX/RX；用稳定 3.3V 供电（勿仅靠弱 USB‑TTL 供电硬扛）

5. 可试：

```bat

idf.py -p COM3 -b 115200 flash --extra-args="--before=no_reset"

```

**monitor 刷 `invalid header: 0xffffffff`**

```bat

idf.py -p COM3 -b 115200 erase-flash flash

```

成功时应看到 `cpu_start` / `app_main`，以及：

```text

固件标识: board_type=dog_dance | 编译时间 ...

```

预编译固件（可选）

```bat

esptool.py -p COM3 -b 460800 write_flash 0x0 dog_dance_merged.bin

```

也可用 Flash Download Tool，按发布说明填 COM、波特率、偏移。日常开发仍推荐 `idf.py flash`。

### VS Code（可选）

1. 安装扩展 **Espressif IDF**

2. 配置 IDF 路径

3. 打开本仓库，目标选 `esp32s3`，板型选 **dog_dance**

4. 选择正确 COM 后 Flash / Monitor

### 屏 / 声软件开关

程序已跑但屏黑：查背光与排线，必要时改 `config.h` 后重编——`DISPLAY_BACKLIGHT_OUTPUT_INVERT`、`DISPLAY_SPI_MODE`（默认 3）、`DISPLAY_LCD_PCLK_HZ`、`DISPLAY_INVERT_COLOR` / `OFFSET_X`。

喇叭无声、麦正常：试 `AUDIO_I2S_SPK_SLOT_MASK`（LEFT/RIGHT/BOTH），再试 WS/BCLK 极性项；硬件确认 MAX98357 **SD_MODE=高**。