首次启动：配网、激活与绑定

小智设备第一次通电后，依次完成三件事：连上 Wi‑Fi、向服务器报到并检查版本、用激活码绑定到你的账号。本页按固件 v2.5.2 的实际代码，说明每一步设备在做什么、你会看到什么，以及卡住时怎么处理。

流程总览

1. 上电后，设备检查是否保存过 Wi‑Fi：没有就进入配网模式；有则尝试连接，60 秒内没连上同样回到配网模式。
2. 联网后设备进入「激活设备」状态，向 OTA 地址请求版本信息。
3. 服务器返回新固件则先升级；返回激活码则显示并朗读激活码。
4. 你在控制台输入激活码完成绑定。设备随后加载通信协议配置，进入待机并播放成功提示音。

第一步：配网

什么时候进入配网模式

• 设备没有保存任何 Wi‑Fi（首次启动）；
• 已保存的 Wi‑Fi 在 60 秒内没有连上；
• 在启动阶段按下开发板上的配网按键。按键因板而异：例如 bread-compact-wifi 在启动阶段单击 BOOT 键进入配网，其他开发板请查看 main/boards/ 下对应目录的 README。

热点配网（默认）

固件默认使用热点配网（menuconfig 中 WiFi Configuration Method → Hotspot，默认开启）。

1. 屏幕和语音提示「配网模式」，内容形如“手机连接热点 Xiaozhi-XXXX，浏览器访问 192.168.4.1”。热点名称以 Xiaozhi- 开头，后接设备 MAC 地址末两个字节，以屏幕显示为准。
2. 手机连接该热点，在浏览器中打开 192.168.4.1。热点是开放网络，没有密码，最多同时连接 4 台设备，请在可信环境中尽快完成配网。
3. 在配网页选择路由器并输入密码。多数芯片只支持 2.4 GHz；ESP32-C5 另支持 5 GHz。
4. 保存后设备退出配网模式，并用新的 Wi‑Fi 凭据重新连接。

配网页的「高级」选项卡提供 OTA 地址、Wi‑Fi 发射功率和 Wi‑Fi 休眠模式（OTA 地址与休眠两项由固件决定是否显示，v2.5.2 均已显示）。在这里填写的 OTA 地址会替代默认值，设备此后向该地址请求版本与激活信息，请只填写你信任的服务器。

BluFi 配网

BluFi 在构建固件时选择，不能与热点配网同时启用。启用后设备的蓝牙名称为 Xiaozhi-Blufi，用 EspBlufi 等客户端发送 Wi‑Fi 凭据即可。配置方法见 BluFi 配网指南。

第二步：检查版本

联网后，固件向 OTA 地址发起请求。地址取自配网页的设置，没有设置时使用 menuconfig 中 Default OTA URL（CONFIG_OTA_URL）的值。请求头带有设备标识：Device-Id（MAC 地址）、Client-Id（设备 UUID）、Activation-Version、User-Agent、Accept-Language；读到有效 eFuse 序列号的设备还会带上 Serial-Number。

服务器返回的 JSON 可以包含：

没有 activation 字段时，设备视为无需激活，直接继续启动。

第三步：激活与绑定

1. 响应带有激活码时，设备在屏幕上显示服务器给出的提示文字，播放提示音，再逐位朗读激活码中的数字。
2. 登录官方控制台，按页面指引输入激活码，把设备绑定到你的账号。
3. 在你操作期间，设备持续向 <OTA 地址>/activate 提交应答：读到 eFuse 序列号的设备提交 hmac-sha256 结果（用 eFuse 中的 HMAC 密钥对 challenge 签名），其他设备提交空对象。服务器返回 200 表示激活成功，返回 202 表示还没绑定（设备等 3 秒再试），其他状态则等 10 秒再试。
4. 一轮最多尝试 10 次；仍未完成时设备回到「检查版本」再来一轮，请以屏幕上最新显示的激活码为准。
5. 激活成功后，设备按服务器下发的配置初始化通信协议（响应里没有任何协议配置时默认使用 MQTT），显示版本号并播放成功提示音，随后即可开始对话。

常见问题排查

相关阅读

• 固件下载与烧录
• 网络配置说明
• 常见问题
• BluFi 配网指南

来源：78/xiaozhi-esp32 v2.5.2 的 wifi_board.cc、ota.cc、application.cc、Kconfig.projbuild，以及配网组件 78/esp-wifi-connect 的 README。