跳到主要内容

eHome App 端详细需求设计文档

M03 设备配网模块（对应需求：FR-0301~0307）​

项目内容
所属项目eHome 智能家居硬件配套 APP + 云端后台定制开发项目
设计依据《eHome智能家居项目需求文档（PRD V1.1）》设备添加与配网章节；ESP-IDF v6.1 统一配网协议规范（Unified Provisioning）；Apple CoreBluetooth / Android BLE 平台规范
范围说明本模块覆盖 Wi-Fi 设备与 Thread/Zigbee 网关设备的配网全流程（BLE配网、AP配网、扫码发现、配网状态反馈、失败重试与降级）；不包含设备配网后的业务控制（属M04）、Mesh网络拓扑管理（属M09）
优先级P0（MVP核心阻断项，配网成功率直接决定用户激活率）
里程碑M1 基础功能期开发（依赖 M01 账号、M02 家庭就绪；固件端 ESP-IDF 配网协议就绪）

1. 模块概述与设计原则​

1.1 模块范围​

序号页面/功能项需求编号类型优先级
1扫码/手动发现设备页 W01FR-0301APP(Flutter)P0
2配网引导与权限授权页 W02FR-0302APP(Flutter)P0
3BLE 配网执行与进度页 W03FR-0303APP(Flutter)+原生P0
4AP 配网执行与进度页 W04FR-0304APP(Flutter)+原生P0
5配网结果与设备命名页 W05FR-0305APP(Flutter)+云端P0
6配网失败排查与重试页 W06FR-0306APP(Flutter)P1
7批量配网进度页 W07FR-0307APP(Flutter)P2

1.2 设计原则​

  • ESP-IDF 统一配网协议对齐：全面采用 ESP-IDF v6.1 官方 Unified Provisioning 架构，基于 protocomm 基础层，支持 BLE GATT 与 Wi-Fi SoftAP+HTTP 双传输通道，强制使用 Security 1/2 安全方案，数据格式统一采用 Protobufs。
  • 高成功率优先：提供 BLE 配网为主、AP 配网为备的自动降级策略；提供详细的失败排查引导。
  • 权限最小化与透明化：仅在必要环节（如连接 Wi-Fi、开启蓝牙）请求系统权限，并提供清晰的拒绝后引导。

1.3 边界与衔接说明​

  • 入口：M02 家庭详情页 [+添加设备] / 首页 [+添加设备] -> W01。
  • 出口：配网成功 -> W05 设备命名 -> 跳转 M04-R01 设备详情页。

1.4 ESP-IDF 统一配网协议参考 (v6.1)​

本模块底层实现严格遵循 ESP-IDF v6.1 统一配网协议，确保与固件端无缝对接。

1.4.1 架构概述​

配网过程基于 protocomm (Protocol Communication) 基础层，提供统一的 API 接口，底层支持多种传输方式和安全方案。

  • 核心特性：独立于传输层、支持多种安全方案、使用 Protobufs 定义数据结构、支持设备发现机制。

1.4.2 传输方式对比​

传输方式协议栈适用场景eHome 采用策略
BLE GATTBluetooth LE + GATT首选方案，用户体验好，无需切换 Wi-Fi默认首选，支持后台静默扫描
SoftAP + HTTPWi-Fi AP + TCP/IP + HTTP备用方案，兼容无蓝牙或蓝牙故障设备BLE 失败时自动降级触发

1.4.3 安全方案 (Security Schemes)​

安全方案加密算法适用场景eHome 采用策略
Security 0无加密仅用于测试或已加密通道禁止在生产环境使用
Security 1Curve25519 密钥交换 + AES256-CTR兼容旧设备，无需 SRP6a备用方案，需配合 PoP (Proof of Possession)
Security 2SRP6a (基于密码的认证) + AES256-GCM首选方案，防中间人攻击，安全性最高默认强制使用，PoP 作为 SRP6a 密码

1.4.4 设备发现机制​

  • BLE 发现：通过广播特定的 Primary Service UUID (如 0xFFFF) 和 Device Name 前缀 (如 eHome_) 进行过滤。
  • SoftAP 发现：设备开启 AP 模式，SSID 命名为 eHome_Prov_XXXX，App 扫描 Wi-Fi 列表进行匹配。

2. 页面结构与流程图​

2.1 页面导航结构​

首页/家庭页 [+添加设备]
 └─► W01 扫码/手动发现设备页
      ├─ 扫码发现 ──► W02 配网引导与权限授权页
      └─ 手动选择 ──► W02
           └─► W03 BLE配网执行页 (主流程)
                ├─ 成功 ──► W05 配网结果与设备命名页 ──► M04-R01
                └─ 失败/超时 ──► W06 失败排查页 ──► 降级 W04 AP配网页

2.2 配网核心交互时序图（完整版）​

2.2.0 扫码/手动发现设备时序图（新增）​

2.2.0.1 QR Code 扫码发现设备时序​

QR Code 扫码发现设备时序

2.2.0.2 手动选择设备时序​

手动选择设备时序

2.2.0.3 扫码与手动发现的统一收敛流程​

扫码与手动发现的统一收敛流程

2.2.1 BLE 配网完整时序（Security 2 / SRP6a + Protocomm）​

BLE 配网完整时序

2.2.2 AP 配网完整时序（SoftAP + HTTP + Security 1）​

AP 配网完整时序

2.2.3 配网失败重试与降级完整时序​

配网失败重试与降级完整时序

2.2.4 配网成功后状态同步完整时序​

配网成功后状态同步完整时序

3. 页面级详细需求​

3.1 W01 扫码/手动发现设备页 (FR-0301)​

  • 扫码发现：调用相机扫描设备机身/包装二维码（包含 SN/MAC/品类ID/PoP）。解析后调用 /devices/provision/verify 校验设备合法性，根据返回策略预加载安全模块后跳转 W02。
  • 手动选择：按品类（照明/电工/传感/网关）展示设备列表，选择后调用 /devices/provision/verify 查询协议版本与安全方案，预加载后跳转 W02。
  • 自动发现：后台静默扫描 BLE 广播（需蓝牙权限），发现未配网设备时在页面顶部提示发现附近的新设备 [去添加]。

3.2 W02 配网引导与权限授权页 (FR-0302)​

  • 权限检测：检测 蓝牙、定位（Android BLE 扫描需要）、本地网络（iOS 需要）权限。未授权则弹窗引导。
  • 网络选择：自动获取手机当前连接的 Wi-Fi SSID（仅支持 2.4GHz）。提供 [切换 Wi-Fi] 入口。
  • PoP 码输入：若设备采用 Security 2，需提供 PoP (Proof of Possession) 输入框（通常印在设备机身上，8位字符）。若扫码已包含 PoP 则自动填充。

3.3 W03 BLE 配网执行与进度页 (FR-0303)​

  • 进度展示：雷达扫描动画 -> 连接设备 -> 安全握手 -> 发送凭证 -> 等待设备连网。
  • 超时机制：整体超时 60s。任一环节超时进入 W06。

3.4 W04 AP 配网执行与进度页 (FR-0304)​

  • 引导切换：明确图文引导用户去系统设置连接 eHome_Prov_XXXX 热点。
  • 自动回切：配网成功后，利用 Android/iOS 原生能力自动将手机切回原 Wi-Fi（iOS 需用户手动确认切回）。

3.5 W05 配网结果与设备命名页 (FR-0305)​

  • 成功反馈：展示设备渲染图与添加成功动画。
  • 设备命名：默认名称为品类+MAC后4位（如智能插座-A1B2），支持修改。
  • 房间分配：下拉选择所属房间（依赖 M02），支持跳过。

3.6 W06 配网失败排查与重试页 (FR-0306)​

  • 错误诊断：根据固件返回的错误码（如：密码错误、找不到路由器、DHCP失败、SRP6a验证失败）展示对应排查建议。
  • 操作选项：[重新输入Wi-Fi密码]、[切换AP配网模式]、[查看视频教程]、[放弃并退出]。

4. 客户端技术要求​

4.1 Flutter 与原生桥接 (MethodChannel)​

  • BLE 封装层：原生实现 protocomm 协议栈。iOS 使用 CoreBluetooth，Android 使用 FastBle 或原生 BluetoothGatt。严格对齐 ESP-IDF 的 Security 1/2 加密算法与 Protobufs 数据格式。
  • Wi-Fi 切换：Android 使用 WifiManager 切换网络；iOS 由于系统限制，使用 NEHotspotConfiguration 申请连接，配网完成后调用 removeConfiguration 引导用户切回。
  • 状态管理：使用 Riverpod 管理配网状态机（Scanning -> Connecting -> Handshaking -> Provisioning -> Polling -> Success/Fail）。

4.2 Protobufs 集成​

  • 引入 ESP-IDF 官方提供的 wifi_provisioning.proto、sec1.proto、sec2.proto、constants.proto。
  • Flutter 端使用 protobuf dart 包进行序列化/反序列化，确保与固件端数据结构字节级一致。

5. 云端需求​

5.1 接口清单​

接口方法说明备注
/devices/provision/verifyPOST校验设备 SN/MAC 合法性，返回设备品类与配网协议版本预留需求
/devices/provision/bindPOST配网成功后绑定设备与用户/家庭，下发 Device ID 与 Token必须
/devices/provision/ticketGET获取设备配网凭证（用于 Security 1 的 PoP 校验，若机身未印）预留需求
/analytics/provision-logPOST接收配网结果埋点数据预留需求

5.2 关键策略​

  • 防暴力破解：同一设备 1 小时内配网失败超过 5 次，云端锁定该设备 15 分钟。
  • 配网日志：记录每次配网的传输方式、安全方案、耗时、失败原因，用于云端生成配网成功率看板。

6. 验收标准与 QA 测试要点​

  1. 协议一致性：抓包验证 BLE/AP 配网过程中的 Protobufs 字段与 ESP-IDF v6.1 官方文档完全一致；验证 Security 2 握手过程无明文密钥泄露。
  2. 多机型兼容：覆盖 iOS 15-17 (iPhone 12-15) 与 Android 10-14 (华米OV主流机型) 的 BLE 扫描与 Wi-Fi 切换成功率。
  3. 异常注入：在握手阶段、传输凭证阶段、设备连路由器阶段分别注入断网、断电、密码错误、PoP错误，验证 W06 的错误提示准确性与降级逻辑。
  4. 弱网测试：在 2.4G Wi-Fi 信道拥挤（RSSI < -75dBm）环境下，验证配网超时重试机制。
  5. 时序验证：对照 PlantUML 时序图逐步骤验证消息顺序、加密状态、超时阈值是否与文档一致。

7. 依赖与风险​

风险项说明应对策略
iOS Wi-Fi 切换限制iOS 不允许 App 静默切换 Wi-Fi，AP 配网体验受损AP 配网仅作为 BLE 失败后的降级方案；UI 上强化引导文案
Android 后台蓝牙扫描限制高版本 Android 对后台 BLE 扫描有严格限制配网过程强制要求 App 保持在前台；开启前台服务 (Foreground Service)
固件协议版本碎片化旧批次固件可能仅支持 Security 1 或旧版 protocommW01 扫码后云端接口返回协议版本号，App 动态切换安全方案与 Proto 文件
SRP6a 计算性能低端手机 SRP6a 密钥派生耗时较长原生层实现 SRP6a 计算，避免 Dart 层性能瓶颈；设置合理超时