Releases: bingkina/FoloToy-Codex-Buddy
Release list
FoloToy Codex Buddy v1.0.1
FoloToy Codex Buddy：从零开始刷机
本流程面向普通用户，不需要下载源码或安装 ESP-IDF。完成后，FoloToy AI Passport 会运行
Codex Buddy 固件。
0. 开始前确认
准备以下物品：
- FoloToy AI Passport（ESP32-C3、8 MB Flash）；
- 一根支持数据传输的 USB 线；
- Windows、macOS 或 Linux 电脑；
- Python 3.10 或更高版本及网络连接。
**重要：**公开版是从
0x0写入的完整固件，会清除设备原有设置和 BLE 绑定。只在
首次安装或确定要恢复设备时继续。固件不能用于其他型号。
可选：交给 Agent 自动刷机
如果 Codex 或其他编码 Agent 能访问本机终端和 USB 串口，可以让它自动完成文件下载、
隔离 Python 环境创建、esptool 安装、SHA-256 校验、串口识别、ESP32-C3 核验、刷写和
结果检查。普通网页聊天不能访问本机 USB，无法代替本地 Agent 执行。
将设备通过 USB 连接后，把本发布页面链接和下面的指令一起发送给 Agent：
请阅读这个 GitHub Release 页面的完整刷机说明，并按照其中流程自动下载和刷入当前版本。
设备已经通过支持数据传输的 USB 线连接到电脑。
我允许你在隔离的 Python 虚拟环境中安装 esptool，也已知晓并同意完整固件会清除设备设置
和 BLE 绑定。请自动完成以下工作：
1. 下载 FoloToy-Codex-Buddy-merged.bin 和 SHA256SUMS.txt；
2. 校验 SHA-256，失败时立即停止；
3. 探测串口；只有一个明确匹配的端口时自动选择，无法唯一确定时询问我；
4. 使用 chip-id 核验设备确实是 ESP32-C3，型号不符时立即停止；
5. 从 0x0 写入完整固件，并检查写入校验结果；
6. 确认设备正常重启；无法读取启动状态时明确标记 NOT RUN。
不要执行 erase-flash，不要使用 --force，也不要在校验失败或芯片型号不符时继续。
只有需要连接设备、选择多个候选串口或操作 BOOT/RESET 键时再询问我。
Agent 可以自动处理软件步骤，但以下情况仍需要用户配合：设备尚未连接、存在多个无法区分
的串口、USB 线仅能供电，或设备必须手动按 BOOT/RESET 进入下载模式。
1. 下载两个文件
展开本发布页面底部的 Assets，把下面两个文件下载到同一个文件夹：
FoloToy-Codex-Buddy-merged.bin：完整固件；SHA256SUMS.txt：固件校验值。
后续命令都要在这个下载文件夹中运行。可以在终端中使用 cd 进入该文件夹，例如：
cd ~/DownloadsWindows 用户可在文件夹空白处右键选择“在终端中打开”。
2. 安装 Python 和 esptool
如果尚未安装 Python，请从 Python 官网安装
Python 3.10 或更高版本。Windows 安装时勾选 Add python.exe to PATH。
Windows PowerShell：
py --version
py -m pip install --upgrade esptool
py -m esptool versionmacOS 或 Linux：
python3 --version
python3 -m pip install --upgrade esptool
python3 -m esptool version如果最后一条命令能显示 esptool 版本，即表示工具安装成功。
3. 校验下载的固件
Windows PowerShell：
$expected = (Get-Content .\SHA256SUMS.txt).Split()[0]
$actual = (Get-FileHash .\FoloToy-Codex-Buddy-merged.bin -Algorithm SHA256).Hash.ToLower()
if ($actual -eq $expected) { "OK" } else { "FAILED: 请重新下载两个文件" }macOS：
shasum -a 256 -c SHA256SUMS.txtLinux：
sha256sum -c SHA256SUMS.txt只有结果为 OK 时才继续。出现 FAILED 时不要刷机，请删除文件并重新下载。
4. 连接设备并找到串口
使用数据线把 AI Passport 直接连接到电脑。关闭可能占用串口的 Arduino IDE、串口监视器
或其他刷机程序。
Windows PowerShell：
[System.IO.Ports.SerialPort]::GetPortNames()常见结果为 COM5。也可以在“设备管理器 → 端口”中查看。
macOS：
ls /dev/cu.usbmodem* /dev/cu.usbserial* 2>/dev/null常见结果为 /dev/cu.usbmodem101。
Linux：
ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null常见结果为 /dev/ttyACM0。如果有多个端口，可拔下设备、再次执行命令，再插回设备比较
新增的端口。记住实际端口，下面用 PORT 表示它。
5. 核验芯片型号
先确认连接的是 ESP32-C3，避免刷错设备。把命令中的 PORT 换成上一步的实际端口。
Windows 示例：
py -m esptool --chip esp32c3 --port COM5 chip-idmacOS 示例：
python3 -m esptool --chip esp32c3 --port /dev/cu.usbmodem101 chip-idLinux 示例：
python3 -m esptool --chip esp32c3 --port /dev/ttyACM0 chip-id输出必须确认芯片是 ESP32-C3。型号不符时立即停止。
6. 写入固件
确认终端仍位于两个下载文件所在的文件夹，然后执行对应命令。
Windows PowerShell：
py -m esptool --chip esp32c3 --port COM5 --baud 460800 --before default-reset --after hard-reset write-flash 0x0 .\FoloToy-Codex-Buddy-merged.binmacOS：
python3 -m esptool --chip esp32c3 --port /dev/cu.usbmodem101 --baud 460800 \
--before default-reset --after hard-reset write-flash \
0x0 FoloToy-Codex-Buddy-merged.binLinux：
python3 -m esptool --chip esp32c3 --port /dev/ttyACM0 --baud 460800 \
--before default-reset --after hard-reset write-flash \
0x0 FoloToy-Codex-Buddy-merged.bin刷写期间不要拔线、关闭终端或让电脑休眠。看到数据写入完成、校验成功和硬复位信息，才算
写入完成。
7. 确认启动成功
刷写完成后设备通常会自动重启。确认：
- 屏幕点亮并出现 Codex Buddy 界面或
CODEX宠物； - 设备没有持续黑屏或反复重启；
- 电脑蓝牙附近可发现名称以
Codex-开头的设备。
如果刷写成功但设备仍停留在下载模式，按一下 RESET；没有 RESET 键时，拔下 USB 后重新
插入。首次连接桌面桥接器时，设备会显示六位配对码，需要在 macOS 配对窗口中输入。
8. 常见问题
- **找不到串口：**确认 USB 线支持数据传输，换一个 USB 口，避免只供电的线和不稳定的
扩展坞。 - **
No module named esptool：**安装与运行必须使用同一个命令；Windows 都使用py -m，
macOS/Linux 都使用python3 -m。 - **
Permission denied（Linux）：**确认当前用户有串口权限，并关闭占用端口的程序。 - **
Failed to connect或一直Connecting...：**重新确认端口；仍失败时，按住 BOOT，
按一下 RESET 后松开 BOOT，再重新执行刷机命令。 - **端口被占用：**关闭串口监视器、Arduino IDE 和其他刷机工具后重试。
- **写入中途失败：**更换数据线或 USB 口，并把命令中的
--baud 460800改为
--baud 115200后重试。 - **校验失败：**不要继续刷机，重新下载固件和
SHA256SUMS.txt。 - **刷完黑屏：**重新插拔设备；如果仍无显示，保留完整终端输出并提交 Issue。
不要自行执行 erase-flash。完整固件已经包含所需引导程序和分区表，无需额外擦除。