安装固件时提示「Failed to connect with the device」

按住 BOOT 键插上板子，再点一次「连接板子」。 绝大多数情况这样就能解决。

为什么会这样

安装器通过 USB 串口和板子通信。全新的 XIAO ESP32S3 有这个串口，所以第一次安装很顺利。装上 Handsy 固件后，板子的 USB 口变成了 iPhone 的键盘和鼠标，可能不再提供安装器能用的串口，安装器就会报：

Couldn't install.
Details: Failed to connect with the device

也可能看到 Timed out waiting for packet header，或者选择框里根本没有板子。原因相同，解决方法也相同。

解决：让板子进入安装模式

1. 把板子从电脑上拔下来。
2. 按住 BOOT 键，就是 USB-C 口旁边的小按钮。
3. 按住不放，把板子插回电脑，一秒后松开。
4. 在安装页点 连接板子，选择刚出现的串口，名字一般是 USB JTAG/serial debug unit。
5. 显示「安装完成」后，拔下板子再插上，新固件就会启动。

失败不会伤到板子，重试是安全的。

还是不行？

• 换数据线。 很多 USB-C 线只能充电，试试你平时用来传文件的线。
• 直连电脑。 不要经过扩展坞或集线器，或者换一个 USB 口。
• 关掉占用板子的程序。 串口监视器、Arduino IDE、PlatformIO 或另一个安装页标签都会占住串口。
• 用电脑上的 Chrome 或 Edge。 Safari、Firefox 和手机都打不开 USB 串口。
• 确认板子型号。 安装器适用于标准版 XIAO ESP32S3（8 MB 闪存、8 MB PSRAM），见硬件。

已经能用的板子要升级

不需要电脑。板子插在 iPhone 上时，ESP32 Agent App 会通过 Wi-Fi 提示并安装固件更新。见更新 ESP32 Agent 固件。

还是卡住了？点报错下方的 下载日志，把文件发到 [email protected]。日志只保存在你的浏览器里，发送前不会离开电脑。更多：常见问题、调试与拉日志。