93 lines
5.7 KiB
Markdown
93 lines
5.7 KiB
Markdown
# 配网失败处理与内存恢复
|
||
|
||
更新日期：2026-10-23。本文描述源码策略与主机验证，不代表新板实机验收。
|
||
|
||
## 故障背景
|
||
|
||
新板启动日志显示内部 RAM 空闲 135,167 B、最大 DMA 连续块 73,728 B，均高于
|
||
当前配网门槛 49,152 B / 12,288 B。设备身份缺失返回 `ESP_ERR_NOT_FOUND`，
|
||
发生在 BLE 初始化之前。旧控制层将所有重新配网错误送入低内存恢复重启，并将
|
||
空快照打印为三个零。恢复启动再次失败后清除恢复模式，又被运行时触发重启。
|
||
因此该样本不能证明 BLE 内存不足，也不能证明身份补齐后的 BLE 内存一定充足。
|
||
|
||
## 当前职责与流程
|
||
|
||
- `domain.h` 是配网语义及 `domain_wifi_provisioning_start_status_t` 的唯一声明点，
|
||
对应 AGENTS 所有权矩阵的“小程序 Wi-Fi 配网语义”一行。未增加新契约家族或改变所有权。
|
||
- `domain_runtime_mini_program_provisioning_preflight()` 只检查身份，无 BLE 初始化副作用。
|
||
`domain_runtime_mini_program_provisioning_start()` 同步启动，必须传入结果输出指针；
|
||
失败返回错误码及类型化原因，domain/platform 不后台重试。
|
||
- `control_plane_connectivity_runtime.c` 持有唯一配网协调策略，所有共享字段在
|
||
`s_provisioning_lock` 下访问；资源操作、通知和日志在锁外执行。
|
||
- 私有 `control_plane_provisioning_policy.h` 只实现等待、退避和恢复次数决策。
|
||
Wi-Fi worker 轮询协调器，不新增任务、定时器或上层状态镜像。
|
||
|
||
```text
|
||
尝试被允许 → 身份检查 → 有界暂停语音 → 停止 STA → 内存检查 → BLE 启动 → 配网 worker
|
||
↓ ↓ ↓
|
||
等待身份 按实际原因处理 仅内存错误允许一次恢复启动
|
||
```
|
||
|
||
| 原因 | 策略 | 如何继续 |
|
||
| --- | --- | --- |
|
||
| 身份缺失 | 等待身份，不停现有音频，不自动重试、不重启 | 成功 `save_config` 后由 Wi-Fi worker 重新检查 |
|
||
| 无效参数、不支持的配置 | 停止自动尝试 | 修正后 `retry_provisioning` |
|
||
| 明确临时超时 | 首次失败后依次等待至少 1、3、10 秒，最多三次额外尝试 | 超限后等待显式重试 |
|
||
| 未分类启动错误 | 停止自动尝试，不猜测为内存故障 | 根据日志排查后显式重试 |
|
||
| 内存门槛不满足或明确分配失败 | 本轮最多一次恢复重启 | 恢复启动仍失败则保持运行，等待排查 |
|
||
| Wi-Fi 密码错误或连接超时 | 保持 BLE，通知小程序连接失败 | 小程序重新提交凭据 |
|
||
| BLE teardown 失败 | 暂停云语音/HTTPS，保留待释放义务 | 显式重试先有界完成旧实例 teardown，成功后才能重启 BLE |
|
||
| 配网被停止或取消 | 有界释放，不自动重新进入配网 | 显式重试 |
|
||
|
||
退避由 worker 轮询驱动，1/3/10 秒是最短间隔，不是精确唤醒时间。
|
||
只有明确 `ESP_ERR_TIMEOUT` 被归为临时失败；未知错误不自动循环。
|
||
内存采样 API 本身失败属于诊断失败，不触发内存恢复重启。
|
||
|
||
## 恢复次数与日志
|
||
|
||
`recovery_boot` 表示当前采用精简启动；`recovery_attempted` 表示该恢复链已用过重启。
|
||
RTC 一次性请求在恢复启动消费后锁存 attempted。恢复失败退出精简启动时，不清除
|
||
attempted；`save_config`、显式重试及再次消费请求也不重置它。
|
||
恢复配网成功并完成 BLE teardown 后，仍按原流程重启进入完整正常运行时；
|
||
这是成功后的模式切换，不是失败重试。普通启动配网成功直接恢复运行时，无需重启。
|
||
|
||
启动失败日志包含 `stage`、`error`、`reason`、`retry_ms`、`recovery_attempted` 和
|
||
`voice_paused`。内存日志使用实际采样；采样失败明确显示 unavailable / unknown，
|
||
不能把缺少快照打印为内存零值。
|
||
|
||
## 等待期间的资源与产测命令
|
||
|
||
重新配网不再设置全局运行时停止标志，因此 Wi-Fi 协调、屏幕、电池、按键与
|
||
产测串口继续工作。身份检查在暂停资源之前完成。若已暂停语音后才失败，设备
|
||
明确进入离线等待/退避，云语音保持暂停，避免与 BLE 重试争抢内存；OTA、财运
|
||
HTTPS 和语音启动入口遵守此门禁。BLE 成功 teardown 或其他 STA 恢复路径解除门禁。
|
||
若旧 BLE 尚未成功释放，STA 即使已连接也不能直接恢复云服务。
|
||
|
||
```text
|
||
get_device_info
|
||
set_device_id <后台分配的实际设备ID>
|
||
set_serial_number <实际序列号>
|
||
save_config
|
||
get_device_info
|
||
```
|
||
|
||
`set_*` 只暂存 RAM，`save_config` 成功持久化后才发布配置通知；失败不发布。
|
||
CLI 不直接停资源或初始化 BLE。新命令 `retry_provisioning` 只请求协调器重新尝试，
|
||
不写入设备身份、不删除 Wi-Fi 凭据，也不重置内存恢复次数。Wi-Fi 已正常连接且
|
||
没有待清理 BLE 时继续正常联网，不强制中断连接进入配网。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
python3 tools/test_provisioning_recovery.py
|
||
```
|
||
|
||
该主机测试提取并编译实际领域启动、控制层协调、恢复请求消费、配网 worker 和
|
||
产测保存函数，使用 RTOS/BLE/存储故障桩及 ASan/UBSan。覆盖身份等待、失败与成功保存、
|
||
错误分类、退避与计时回绕、内存门槛边界和分配失败、恢复失败不再重启、未知快照日志、
|
||
停止超时、Wi-Fi 失败后继续接收凭据、成功恢复运行时、teardown 失败、取消和启动门超时。
|
||
|
||
固件使用 ESP-IDF 5.5.4 构建。实机仍需验证空身份持续运行、身份写入后的 BLE 广播、
|
||
错误/正确 Wi-Fi 凭据、连接后的 BLE 释放与语音恢复，并记录 BLE 真正初始化前后的
|
||
内部 RAM、最大 DMA 连续块及并行负载。主机故障注入不替代这些设备证据。
|