xiao-webcam-sta

XIAO ESP32S3 摄像头 Web 应用 — STA（路由器）模式

开发板连接到用户的 WiFi 路由器。PC/手机保持在常用网络中（互联网仍可正常使用），并通过 http://<mdns-name>.local 或其 DHCP IP 访问开发板。

请先阅读（同一仓库中的）xiao-esp32s3 技能，了解基本工作流程和注意事项 （尤其是：PSRAM 标志为必需项、DTR 复位卡住后的恢复方法，以及演示必须持续运行时不要读取串口）。

第 1 步 — 务必先询问用户

切勿编造、猜测或默默复用 WiFi 凭据。请向用户询问：

1. 路由器 SSID — 必须是 2.4 GHz 网络（ESP32 无法检测到 5 GHz 网络； 如果用户提供的是 something_5G，请询问 2.4 GHz 频段的网络名称）。
2. 路由器密码。
3. mDNS 名称（可选，默认为 xiao）— 页面地址将变为 http://<name>.local。同一局域网中的每块开发板都必须使用唯一名称。
4. 需要哪种应用：采集器、推理查看器，或两者都要。

第 2 步 — 根据模板生成草图

assets/ 中的模板是经过验证的可用代码 — 不要重写：

• assets/web_collect.ino.tpl — 数据集采集器（图库 + 删除 + ZIP 下载）
• assets/web_infer.ino.tpl — 实时推理查看器（需要在 sketchbook 中安装 <project>_inferencing Edge Impulse 库）

将模板复制到 <workspace>\<NN>_<name>\<NN>_<name>.ino（文件夹名 = ino 名称），然后按字面替换占位符：

占位符	含义	示例
__WIFI_SSID__	2.4 GHz 路由器 SSID	myhome
__WIFI_PASS__	路由器密码	pass1234
__MDNS_NAME__	主机名（小写，不含空格）	xiao
__EI_PROJECT__	仅推理应用 — Edge Impulse 项目名称，需与已安装的 <name>_inferencing 库文件夹匹配	clfc

如果 15 秒内无法连接到路由器，模板会自动回退到 XIAO_CAM 热点，因此密码错误时也能正常降级运行。

第 3 步 — 编译并上传

arduino-cli compile --fqbn esp32:esp32:XIAO_ESP32S3 --board-options PSRAM=opi <SKETCH_DIR>
arduino-cli upload -p COM4 --fqbn esp32:esp32:XIAO_ESP32S3 --board-options PSRAM=opi <SKETCH_DIR>

PSRAM=opi 为必需项（摄像头 + 模型需要 PSRAM）。如果刚刚更换了 Edge Impulse 库，推理版本的构建需要使用 --clean。

第 4 步 — 端到端验证

PC 与开发板位于同一局域网，因此 HTTP 是验证整个链路是否正常的最快方式：

Start-Sleep -Seconds 20   # boot + WiFi join
curl.exe -s -m 15 http://<mdns-name>.local/ -o "$env:TEMP\page.html"
(Get-Item "$env:TEMP\page.html").Length     # > 1000 bytes = page served
# inference app only:
curl.exe -s -m 15 http://<mdns-name>.local/classify   # JSON with scores

如果 mDNS 解析不稳定，查询一次 IP（使用 ping <name>.local 或路由器 DHCP 列表），然后直接使用该 IP — 将这两个地址都告知用户。

通过串口查看开发板状态

HTTP 可以证明页面已启动，但无法显示开发板未能连接路由器的原因。串口可以：草图会打印尝试连接的 SSID、获取到的 IP 和 mDNS 名称。请使用 xiao-serial-monitor 技能查看。

mon                      # interactive, port auto-detected
.\scripts\mon.ps1 -Seconds 15    # bounded, for your own debugging

成功时应显示：

Connecting to WiFi ... IP: 192.168.0.179
mDNS: http://<mdns-name>.local
Collector ready

有两点值得了解，不必刻意避免：

• 打开端口会通过 DTR 复位开发板，因此日志会从启动开始重新输出。 这通常正是你想要的效果 — WiFi 连接消息只会打印一次。
• 如果开发板之后卡住，只显示 ROM 横幅 （xiao-esp32s3 的注意事项 8），重新运行 arduino-cli upload 即可清除该状态。

如果用户想自行查看，请将命令交给他们，而不要通过工具调用启动交互式监视器 — 它不会返回。在 Claude Code 中，! 前缀会在用户的会话中运行命令：

! <path>\mon.ps1

备注

• 采集器页面：采集结果会进入浏览器内的图库（标签徽标、逐张删除，“整体 ZIP 下载”会生成可直接用于 Edge Impulse 的 label.N.jpg 文件）。刷新页面会清空图库 — 请先下载 ZIP。
• 推理页面：整帧彩色框 + 顶部标签 + 按类别显示的置信度条（分类模型 — 按对象位置显示框需要使用 FOMO 模型）。
• 摄像头画面会旋转 90°；推理模板已进行补偿（顺时针旋转特征，已通过实测验证）。