网络发现与设备验证

本文说明如何在不改变电脑网络连接的情况下，验证同一局域网内的 FastBee 设备。完整的构建、烧录和测试矩阵见烧录与测试。

验证边界

• 自动测试只使用设备的 STA 地址，测试电脑不要连接设备 AP。
• STA 未连接时，记录串口和路由器 DHCP 信息并跳过 HTTP 测试，不切换电脑网络。
• IP 地址可能因 DHCP 续租而变化；长期部署建议在路由器中按设备 MAC 保留地址。
• /api/health 和 /api/system/capabilities 可直接探测；其他设备 API 通常需要先登录并复用设备下发的会话 Cookie。
• 401 表示设备可达但请求未认证，不能据此判断 Web 或网络故障。

多设备测试清单

仓库不保存实验室 DHCP 地址。先从串口启动日志或路由器 DHCP 客户端表取得每台设备的当前 STA 地址，再在本地配置中用实际值替换 <device-ip>。配置来源位于 FastBee-Arduino 源码仓库，各套配置不能互换。

串口	PlatformIO 环境	STA 地址	配置来源
COM4	esp32c3-F4R0	<device-ip>	docs/device-test-configs/com4-esp32c3-f4r0/
COM11	esp32c6-F4R0	<device-ip>	docs/c6-rgb-led-f4r0/
COM15	esp32s3-F16R8	<device-ip>	docs/ecm50a-s3-f16r8/
COM16	esp32-F4R0	<device-ip>	docs/device-test-configs/com16-esp32-f4r0/
COM7	esp32s3-F8R0	<device-ip>	docs/waveshare-esp32s3-relay6ch/

公开配置必须使用占位凭据。真实 WiFi、MQTT 密码和设备身份只在受控部署时注入，不应写入文档或提交到 Git。

先确认地址

优先从以下位置确认 STA 地址：

1. 设备串口启动日志中的 Access URL 或 STA IP。
2. 路由器 DHCP 客户端列表。
3. 已维护的本地舰队配置文件。

源码仓库的 scripts/net-discovery.ps1 仅扫描其脚本内定义的网段和地址范围，可作为辅助诊断，不能代替串口或 DHCP 台账，也不能证明配置已正确烧录。

单机验证

在 FastBee-Arduino 源码仓库执行：

cd D:\project\gitee\FastBee-Arduino

# 公共健康端点，不修改设备状态
curl.exe --noproxy "*" --max-time 10 http://<device-ip>/api/health

# 登录、能力、网络、MQTT、外设和外设执行等 API 冒烟
powershell -ExecutionPolicy Bypass -File scripts\smoke-test-device.ps1 `
  -BaseUrl http://<device-ip> -Profile unified -RequireNetworkConnected

# 16 个 Web 页面，两轮请求；4MB 设备保留 1 秒间隔
powershell -ExecutionPolicy Bypass -File scripts\device-web-smoke.ps1 `
  -BaseUrl http://<device-ip> -Rounds 2 -DelayMs 1000 `
  -TimeoutSec 15 -MaxElapsedMs 5000 `
  -ReportPath test\reports\c3-web-smoke.csv

将示例地址替换为目标设备的当前 STA 地址。不要把 192.168.4.1 传给真机测试入口。

五机验证

scripts/device-fleet.example.json 只用于展示字段结构。使用前先复制为本地配置，按当前串口和 DHCP 地址修改，不要把现场信息提交到公共仓库。

cd D:\project\gitee\FastBee-Arduino

# 先跑 STA、登录和设备 API；暂不启动浏览器用例
powershell -ExecutionPolicy Bypass -File scripts\run-device-fleet-tests.ps1 `
  -DeviceConfig scripts\device-fleet.example.json `
  -Ssid <expected-ssid> -BrowserTests:$false

# 需要页面交互回归时再开启浏览器测试
powershell -ExecutionPolicy Bypass -File scripts\run-device-fleet-tests.ps1 `
  -DeviceConfig scripts\device-fleet.example.json `
  -Ssid <expected-ssid> -BrowserTests:$true

脚本输出保存在 .pio/test-results/fleet/。执行结束码为非零时，必须根据报告定位到具体设备和阶段，不能用其他设备通过来覆盖失败。

结果判定

检查	通过条件	常见失败含义
/api/health	HTTP 200 且返回 JSON	设备未上线、地址变化或 Web 服务未就绪
登录	返回成功并建立会话 Cookie	凭据错误、内存繁忙或固件/网页版本不匹配
STA	网络状态为 STA 且连接目标 SSID	凭据、信号、DHCP 或路由器接入限制
API 冒烟	目标能力对应接口通过	配置、功能开关、认证或具体模块异常
页面巡检	16 个资源均为 HTTP 200 且耗时达标	LittleFS 不完整、低内存门控或网络抖动
观察窗口	未安排重启时uptime不回退，内部DRAM/连续块及业务持续有效	异常复位、资源下降或降级；计划重启另记新启动会话

4MB 无 PSRAM 设备出现 503 时，先停止并发请求并查看 /api/system/metrics 或串口日志。页面连续出现 401 时先重新登录，避免把认证失效误判为内存不足。

失败处理

1. STA 地址不可达：查看串口和 DHCP 列表，确认地址是否变化；保持电脑当前网络不变。
2. 首页可达但 API 为 401：使用项目脚本登录，或在浏览器重新登录。
3. 页面资源超时或 503：降低并发、保留请求间隔，记录可用 Heap、最大连续内存块和 WebGuard 指标。
4. 设备回退到 AP：记录 STA 失败原因并跳过该设备的 HTTP 验收；修正网络配置后再从 STA 重测。
5. 某项功能页面缺失：先查看“功能配置”和 /api/features/status，区分未编译、未启用、预算拒绝和运行期禁用。

长稳测试

短时冒烟通过不等于长期稳定。需要正式验收时，再按稳定性与发布检查清单执行规定时长的监测并保存报告。仅启动命令或获得少量样本不能记录为长稳通过。

相关文档

• 网络验证快速开始
• 烧录与测试
• 网络配置
• 故障排查
• API 参考