5.7 KiB
配网失败处理与内存恢复
更新日期：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 轮询协调器，不新增任务、定时器或上层状态镜像。
尝试被允许 → 身份检查 → 有界暂停语音 → 停止 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 即使已连接也不能直接恢复云服务。
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 时继续正常联网，不强制中断连接进入配网。
验证
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 连续块及并行负载。主机故障注入不替代这些设备证据。