1. 课程导入
在物联网产品从样机走向量产的过程中，“设备如何安全入网”与“设备出问题后如何远程定位”是两条贯穿始终的主线。ESP32 作为集成 Wi-Fi 与蓝牙的高性价比 MCU，被大量用于智能家居、工业采集、商用设备等场景。但很多开发者在项目后期才发现：配网体验差、现场无法调试、日志拿不到、固件升级失败，这些问题往往比业务逻辑本身更消耗时间。本课程围绕 ESP32 的配网与远程诊断展开，帮助你建立一套可落地、可复用的工程方法。
一、学习目标：从“能连上”到“可运维”
本课程不是简单地讲“如何连接 Wi-Fi”，而是把设备从出厂到长期运行的全生命周期纳入视野。学完本课程，你应当能够达成以下目标：
- 掌握多种配网方式：理解 SoftAP 热点配网、BLE 蓝牙配网、SmartConfig 一键配网、二维码配网等方案的原理与适用边界。
- 设计配网状态机：能够用状态机描述“未配网—配网中—已配网—重连—恢复出厂”的完整流程，避免逻辑混乱。
- 实现远程诊断通道：通过 MQTT、HTTP、WebSocket 或自定义协议，把设备日志、异常码、运行指标回传到云端或本地工具。
- 构建可观测性：掌握日志分级、环形缓冲、崩溃回溯、看门狗与心跳机制，让“黑盒设备”变得可观测。
- 完成实战闭环：从需求分析、方案选型、代码实现到现场排障，形成一套可交付的工程路线。
核心判断：配网解决“设备如何进入网络”，远程诊断解决“设备进入网络后如何被看见”。两者共同构成 ESP32 物联网设备的可运维基础。
二、核心概念：配网、诊断与设备生命周期
在展开具体技术之前，需要先厘清几个关键概念。它们会在后续章节反复出现，也是理解整体框架的基础。
| 概念 | 含义 | 典型技术/对象 |
|---|---|---|
| 配网（Provisioning） | 将 Wi-Fi 凭证、设备身份、服务器地址等信息安全地写入设备，使其接入目标网络 | SoftAP、BLE、SmartConfig、二维码 |
| 设备身份 | 设备在云端的唯一标识与认证凭据 | DeviceID、ProductKey、证书、Token |
| 远程诊断 | 在设备运行期间，远程获取状态、日志、异常与性能数据 | MQTT 日志、HTTP 上报、OTA 诊断 |
| 可观测性 | 通过日志、指标、追踪三类数据理解设备内部状态 | Log、Metrics、Trace |
| 状态机 | 用有限状态描述设备配网与运行阶段，保证逻辑可控 | UNPROVISIONED、CONNECTING、ONLINE |
其中，配网状态机是连接“用户操作”与“设备行为”的桥梁。一个清晰的配网状态机通常包含：未配网、配网中、已配网、连接中、在线、重连、恢复出厂等状态。状态之间的迁移条件必须明确，例如“收到正确 Wi-Fi 密码后进入连接中”“连续失败 3 次后回到未配网”。
三、整体框架：从设备端到云端的四层结构
为了把配网与远程诊断放在同一张图上理解，我们可以将其抽象为四层结构：设备端、通信层、云端服务、运维工具。设备端负责采集与执行；通信层负责协议与安全；云端负责存储、分析与下发；运维工具负责展示与交互。下图展示了这一整体框架及关键数据流。
从图中可以看到，配网主要发生在“设备端—通信层—云端”的凭证传递阶段，而远程诊断则贯穿“设备端—通信层—云端—运维工具”的完整链路。理解这张图，后续每一章的技术点都能找到自己的位置。
四、实战路线图：从零到可运维设备
本课程按照“先配网、后诊断、再闭环”的顺序推进。你可以把它当作一条工程路线，而不是孤立的知识点集合。
- 需求与选型：明确产品是否需要屏幕、是否支持蓝牙、是否要求一键配网，据此选择 SoftAP、BLE 或 SmartConfig。
- 配网状态机实现：用代码定义状态与迁移条件，保证异常情况下可恢复。
- 凭证安全存储：使用 NVS 加密分区保存 Wi-Fi 密码与设备密钥，避免明文泄露。
- 远程诊断通道搭建：接入 MQTT，定义日志主题与上报格式，实现分级日志。
- 可观测性增强：加入心跳、看门狗、崩溃回溯与环形缓冲，保证断网后日志不丢。
- OTA 与回滚：把固件升级纳入诊断体系，升级失败可自动回滚。
- 现场排障演练：模拟弱网、密码错误、云端拒连等场景，验证整套机制。
建议：在动手写业务代码之前，先画出你自己的配网状态机和诊断数据流图。图能画清楚，代码通常不会太乱。
五、常见误区与复盘
初学者最容易踩的坑，往往不是技术难度，而是设计顺序。以下误区值得提前警惕：
- 把配网当成一次性动作：实际设备可能因路由器更换、密码修改而需要重新配网，必须保留恢复出厂入口。
- 日志只打串口：设备部署到现场后，串口不可达，必须提前设计远程日志通道。
- 忽略断网缓存：网络抖动时日志直接丢弃，导致关键故障无法回溯。
- 状态机缺少超时：配网过程中用户放弃操作，设备应能自动回到可配网状态。
- 安全后置：凭证明文存储、MQTT 不使用 TLS，都会在量产阶段带来风险。
// 配网状态机伪代码示例
typedef enum {
STATE_UNPROVISIONED,
STATE_PROVISIONING,
STATE_CONNECTING,
STATE_ONLINE,
STATE_RECONNECTING,
STATE_FACTORY_RESET
} prov_state_t;
// 迁移条件示例：
// UNPROVISIONED -> PROVISIONING : 用户触发配网
// PROVISIONING -> CONNECTING : 收到有效 Wi-Fi 凭证
// CONNECTING -> ONLINE : 获取 IP 且云端认证成功
// CONNECTING -> UNPROVISIONED: 连续失败 3 次
// ONLINE -> RECONNECTING : 心跳超时
// 任意状态 -> FACTORY_RESET: 长按复位键 5 秒