ESP-IDF 环境安装与 Party Games 编译烧录指南

1前置条件检查

在开始之前，确认你的系统满足以下条件：

项目	要求	你的系统状态
操作系统	Windows 10/11 x64	Windows 11 64位
磁盘空间	至少 3GB 可用空间	需自行确认
USB 接口	可用 USB-C 数据线（注意不是纯充电线）	需自行确认
Python	ESP-IDF 安装器会自带，无需预装	已有 3.10.11
Git	ESP-IDF 安装器会自带，无需预装	已有 2.52.0
CMake / Ninja	ESP-IDF 安装器会自带	未安装（安装器会装）
浏览器	Chrome 或 Edge（Web Flasher 需要）	需自行确认

提示

ESP-IDF 官方安装器（ESP-IDF Tools Installer）会自动安装 Python、Git、CMake、Ninja 等所有依赖工具，你不需要手动安装这些。上面表格里已有的是你系统里碰巧装过的，不影响安装器使用。

2安装 ESP-IDF 5.5.3

方法 A：图形化安装器（推荐新手）

下载安装器

打开浏览器，访问 ESP-IDF 官方下载页面：

# 在浏览器地址栏输入：
https://dl.espressif.com/dl/esp-idf-tools/ESP-IDF-tools-setup-online-4.x.exe

或者访问官方页面选择版本：

https://docs.espressif.com/projects/esp-idf/zh_CN/v5.5.3/esp32c3/get-started/

运行安装器

双击下载的 ESP-IDF-tools-setup-online-4.x.exe，按以下步骤操作：

许可协议：同意
安装模式：选择 "Install ESP-IDF and ESP-IDF Tools"（完整安装）
ESP-IDF 版本：选择 v5.5.3（如果没有精确版本，选 5.x 最新版）
目标芯片：勾选 ESP32-C3
安装路径：建议默认 C:\Espressif\，不要有中文和空格
点击 Install，等待下载完成（约 10-30 分钟，取决于网速）

验证安装

安装完成后，桌面/开始菜单会出现 "ESP-IDF 5 PowerShell" 快捷方式。打开它，在 PowerShell 窗口中执行：

PS> idf.py --version
# 应该输出类似: ESP-IDF v5.5.3

PS> python --version
# 应该输出: Python 3.x.x

PS> idf.py --list-targets
# 列出所有支持的芯片，确认 esp32c3 在列表中

如果 idf.py --version 能正常输出版本号，说明安装成功。

注意：必须用 ESP-IDF PowerShell

后续所有编译命令都必须在 "ESP-IDF 5 PowerShell" 窗口中运行，不能用普通 PowerShell 或 CMD。ESP-IDF 快捷方式会自动设置所有需要的环境变量（IDF_PATH 等）。

方法 B：命令行手动安装（高级用户）

如果你不想用图形化安装器，也可以手动安装：

克隆 ESP-IDF 仓库（需要已安装 Git）：

mkdir C:\Espressif
cd C:\Espressif
git clone --recursive https://github.com/espressif/esp-idf.git -b v5.5.3
cd esp-idf
.\install.bat esp32c3

每次打开新的终端窗口时，先激活环境：

cd C:\Espressif\esp-idf
.\export.bat
# 或者用 PowerShell:
. \export.ps1

3克隆 AI Passport 仓库并集成 Party Games

克隆 FoloToy AI Passport 仓库

# 在 ESP-IDF PowerShell 中执行：
cd C:\Espressif
git clone https://github.com/FoloToy/ai-passport.git
cd ai-passport
git checkout main
git switch -c feature/party-games

如果 GitHub 连接不稳定，可以使用镜像：

# Gitee 镜像（如果有的话），或者用代理：
git clone https://ghproxy.com/https://github.com/FoloToy/ai-passport.git

复制 Party Games 源文件

把 Party Games 项目中的文件复制到 ai-passport 仓库的对应位置：

# 假设 Party Games 文件在：
# C:\...\party-games\

# 复制 main/ 下的所有 .c 和 .h 文件：
Copy-Item "C:\path\to\party-games\main\*.c" "C:\Espressif\ai-passport\main\" -Force
Copy-Item "C:\path\to\party-games\main\*.h" "C:\Espressif\ai-passport\main\" -Force

# 覆盖 main/CMakeLists.txt：
Copy-Item "C:\path\to\party-games\main\CMakeLists.txt" "C:\Espressif\ai-passport\main\CMakeLists.txt" -Force

# 覆盖顶层配置文件：
Copy-Item "C:\path\to\party-games\CMakeLists.txt" "C:\Espressif\ai-passport\CMakeLists.txt" -Force
Copy-Item "C:\path\to\party-games\partitions.csv" "C:\Espressif\ai-passport\partitions.csv" -Force
Copy-Item "C:\path\to\party-games\sdkconfig.defaults" "C:\Espressif\ai-passport\sdkconfig.defaults" -Force

请把 C:\path\to\party-games\ 替换为实际的 Party Games 项目路径。

确认文件结构

复制完成后，ai-passport 仓库的 main 目录应该包含这些文件：

ai-passport/
├── CMakeLists.txt          ← 已覆盖（顶层配置）
├── partitions.csv          ← 已覆盖
├── sdkconfig.defaults      ← 已覆盖
├── components/bsp/         ← 官方 BSP（不动）
└── main/
    ├── CMakeLists.txt      ← 已覆盖（注册了20个游戏源文件）
    ├── main.c              ← 已替换（菜单系统）
    ├── games.h             ← 新增
    ├── game_common.h       ← 新增
    ├── game_common.c       ← 新增
    ├── game_dice.c         ← 新增
    ├── game_rps.c          ← 新增
    ├── game_coin.c         ← 新增
    ├── game_guess.c        ← 新增
    ├── game_bomb.c         ← 新增
    ├── game_roulette.c     ← 新增
    ├── game_truth.c        ← 新增
    ├── game_penalty.c      ← 新增
    ├── game_never.c        ← 新增
    ├── game_king.c         ← 新增
    ├── game_react.c        ← 新增
    ├── game_twotruth.c     ← 新增
    ├── game_drawcard.c     ← 新增
    ├── game_picktwo.c      ← 新增
    ├── game_likely.c       ← 新增
    ├── game_wordbomb.c     ← 新增
    ├── game_simon.c        ← 新增
    ├── game_telepathy.c    ← 新增
    ├── game_story.c        ← 新增
    └── game_spy.c          ← 新增

注意：原来 main 目录下的 demo_*.c 和 ui_pixel.* 文件可以保留不动，它们不会被编译（因为新的 CMakeLists.txt 没有引用它们）。

4编译固件

设置目标芯片

PS C:\Espressif\ai-passport> idf.py set-target esp32c3

这会在项目目录下生成 build/ 文件夹和 sdkconfig 文件。首次运行需要 1-2 分钟。

开始编译

PS C:\Espressif\ai-passport> idf.py build

首次编译大约需要 5-15 分钟（取决于电脑性能），后续增量编译只需几十秒。

编译过程中会看到大量输出。如果看到类似下面的内容，说明编译成功：

Project build complete. To flash, run:
 idf.py flash
or
 idf.py -p (PORT) flash

Generating binary image files from the built executables.
...
Generated C:\Espressif\ai-passport\build\firmware.bin

# 看到这些就说明成功了！

确认固件文件已生成

PS> ls .\build\firmware.bin
# 应该能看到 firmware.bin 文件，大小约 500KB-1.5MB

PS> ls .\build\flasher_args.json
# 这个文件也是烧录时需要的

编译失败排查

如果编译报错，请看后面的常见问题排查章节。最常见的几个原因：

没用 ESP-IDF PowerShell（环境变量没设置）
BSP 组件缺失（components/bsp 目录不完整）
网络问题导致依赖没下载完

5烧录到 AI Passport

方法 A：ESP-IDF 命令行烧录

连接设备

用 USB-C 数据线（注意必须是数据线，不是纯充电线）连接 AI Passport 和电脑
AI Passport 不需要额外供电，USB 供电即可
连接后设备可能亮屏，这是正常的

确认串口编号

ESP32-C3 使用原生 USB Serial/JTAG，设备管理器中通常显示为 "USB Serial Port (COMx)"。打开 Windows 设备管理器查看端口号：

# 在 ESP-IDF PowerShell 中用以下命令列出可用端口：
PS> idf.py -p COM? monitor
# 或者直接试常见端口：
PS> idf.py -p COM3 flash    # 试 COM3
PS> idf.py -p COM4 flash    # 试 COM4

# 也可以用 mode 命令查看所有 COM 口：
PS> mode

ESP32-C3 的 USB 端口通常不需要驱动，如果设备管理器里有黄色感叹号，需要安装 Silicon Labs CP210x 驱动或 WCH CH340 驱动（取决于你的线缆/转接器）。

但如果你的 USB-C 线是直连 ESP32-C3 原生 USB（GPIO18/19），则不需要任何驱动，Windows 10/11 会自动识别。

执行烧录

# 把 COM3 替换为你的实际端口号：
PS C:\Espressif\ai-passport> idf.py -p COM3 flash

# 烧录过程会输出类似：
# Connecting...
# Chip is ESP32-C3 (RISC-V)
# Flashing...
# Hash of data verified.
# Writing at 0x00010000... (100%)
# ...
# Hard resetting via RTS pin...
# Done.

烧录过程大约 30-60 秒。烧录完成后设备会自动重启，你应该能看到屏幕显示 Party Games 菜单。

同时烧录并打开串口监视器（可选）

# 烧录后自动打开串口监视器，可以看到日志输出：
PS> idf.py -p COM3 flash monitor

# 按 Ctrl+] 退出监视器

恭喜！

如果屏幕上出现了 Party Games 菜单界面，用 UP/DOWN 键可以滚动浏览 20 款游戏，OK 键进入，长按 OK 返回——说明你已经成功把聚会游戏盒装进了 AI Passport！

方法 B：Web Flasher 烧录（推荐不想装 ESP-IDF 的用户）

前提条件

你需要先在一台装了 ESP-IDF 的电脑上完成编译，拿到 firmware.bin 文件。然后可以在这台电脑或另一台电脑上用浏览器烧录。

找到固件文件

编译完成后，固件文件在：

C:\Espressif\ai-passport\build\firmware.bin

把这个文件复制到方便找到的位置。

打开 Web Flasher

用 Chrome 或 Edge 浏览器打开：

https://ai-passport.folotoy.cn/tools/web-flasher/

这是 FoloToy 官方提供的浏览器串口烧录工具，文件完全在本地读取，不上传服务器。

连接并烧录

用 USB-C 线连接 AI Passport
在网页中点击 "连接" 按钮，浏览器会弹出串口选择窗口
选择对应的 COM 端口，点击 "连接"
选择 firmware.bin 文件
点击 "烧录" / "Flash"，等待进度条走完
烧录完成后设备会自动重启

如果 Web Flasher 连不上

浏览器串口权限

Web Flasher 依赖浏览器的 Web Serial API。如果浏览器不弹窗或连接失败：

确保用的是 Chrome 89+ 或 Edge 89+
Windows 设置 > 隐私和安全 > 串口设备，确认浏览器有权限访问
如果端口被其他程序占用（如串口调试工具），先关闭它们
试试拔掉 USB 重新插上，再刷新页面重试

6常见问题排查

问题 1：idf.py 不是可识别的命令

原因：没有使用 ESP-IDF PowerShell，或者环境变量没有正确设置。

解决：

从开始菜单打开 "ESP-IDF 5 PowerShell" 快捷方式
或者手动激活：cd C:\Espressif\esp-idf; .\export.ps1

问题 2：编译报错 "bsp_pins.h: No such file or directory"

原因：BSP 组件不完整，或者 CMakeLists.txt 中 REQUIRES 缺少 bsp。

解决：

# 确认 components/bsp 目录存在且完整：
PS> ls .\components\bsp\include\bsp_pins.h
# 如果不存在，说明仓库克隆不完整：
PS> git submodule update --init --recursive

问题 3：编译报错 "lvgl.h: No such file or directory"

原因：LVGL 依赖未正确安装。

解决：

# 删除 build 目录重新编译：
PS> rm -r -force .\build
PS> idf.py set-target esp32c3
PS> idf.py build

问题 4：烧录失败 "Failed to connect to ESP32-C3"

原因：USB 线问题、端口选错、或设备未进入下载模式。

解决：

换一根 USB-C 数据线（很多 USB-C 线只供电不传数据）
确认设备管理器中有对应的 COM 端口
手动进入下载模式：按住设备的 OK 键（或 BOOT），然后按下 RESET，松开 RESET，再松开 OK 键
尝试不同的波特率：idf.py -p COM3 -b 115200 flash

问题 5：编译时下载依赖卡住/失败

原因：ESP-IDF 的 managed components 从 GitHub 下载，网络不稳定。

解决：

# 设置 GitHub 镜像加速：
PS> $env:IDF_COMPONENT_REGISTRY_URL = "https://components-file.espressif.cn"

# 或者设置代理：
PS> $env:HTTP_PROXY = "http://127.0.0.1:7890"
PS> $env:HTTPS_PROXY = "http://127.0.0.1:7890"
PS> idf.py build

问题 6：烧录成功但屏幕不亮/花屏

原因：固件和硬件版本不匹配，或背光未正确初始化。

解决：

先尝试恢复官方固件，确认硬件本身没问题
用串口监视器查看日志：idf.py -p COM3 monitor
如果日志显示 "Display/LVGL init failed"，检查 SPI 接线
确认 sdkconfig.defaults 中的 CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y

问题 7：git clone GitHub 失败

原因：国内网络访问 GitHub 不稳定。

解决：

# 方法 1：用 GitHub 镜像代理：
git clone https://ghfast.top/https://github.com/FoloToy/ai-passport.git

# 方法 2：配置 Git 代理：
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
git clone https://github.com/FoloToy/ai-passport.git
# 完成后取消代理：
git config --global --unset http.proxy
git config --global --unset https.proxy

问题 8：屏幕显示了但中文乱码/方块

原因：LVGL 默认 Montserrat 字体不支持中文。

解决：这是已知限制。当前代码使用 Montserrat 14/20 字体，中文字符可能显示为方块或空白。解决方案：

方案一：在 sdkconfig.defaults 中启用 LVGL 的中文字体支持（会增加固件体积约 200KB-1MB）
方案二：将游戏中的中文文本改为英文/拼音（代码已预留了英文接口）
方案三：使用 LVGL 的离线字体工具生成中文子集字体文件

不过——AI Passport 的官方玩法库中的大量游戏都显示中文，说明设备本身就支持中文字体渲染。如果你克隆的 ai-passport 仓库中 main/ 目录下有中文字体文件（如 ui_pixel.c 中可能引用了自定义字体），请保留那些文件不要删除。

7验证清单

烧录完成后，按以下清单逐项验证：

检查项	操作	预期结果
开机显示	烧录完成后自动重启	屏幕亮起，显示深色背景 + "PARTY GAMES" 标题
菜单浏览	短按 UP / DOWN	选中项高亮移动，底部页码 1/3 变化
进入游戏	选中任意游戏，短按 OK	进入游戏界面，显示游戏标题和提示
游戏操作	在游戏中按 UP/DOWN/OK	游戏内有对应反应（掷骰/选择/确认等）
返回菜单	在游戏中长按 OK（约 2 秒）	返回 Party Games 主菜单
骰子游戏	进入"骰子比大小"，按 OK	显示 1-6 的随机点数，切换玩家
真心话	进入"真心话大冒险"，按 OK	随机选玩家 + 随机出真心话或大冒险题目
反应速度	进入"反应速度战"	显示 WAIT... 后随机延时变为 GO!，按 UP/DOWN 测试
词语炸弹	进入"词语炸弹"	倒计时运行，到 0 显示 BOMB!
串口日志	`idf.py -p COM3 monitor`	看到启动日志和 "20 games loaded"

全部通过？

如果你的设备通过了以上所有检查项，说明 Party Games Box 已经成功运行在你的 AI Passport 上了！拿去和朋友聚会玩吧。

恢复官方固件

如果你想恢复 AI Passport 的出厂固件：

访问官方恢复出厂固件指南
扫描设备背面的二维码获取你的专属恢复链接
在电脑上用 Chrome/Edge 打开链接，用 USB 线连接设备烧录即可

ESP-IDF 环境安装与编译烧录指南

目录