ESP32 联网设备
让连接可以恢复

12.1.1 设备联网的分层

端到端联网至少有五个事实层：无线链路是否关联，接口是否拿到 IP，DNS 是否解析，TLS/传输会话是否建立，应用服务是否接受并处理消息。ESP-NETIF 为应用提供网络接口抽象和线程安全 API，但它不会替应用判断服务器健康；每层都要有自己的状态和超时。

12.1.2 状态机而不是一个 connected

一个布尔 connected 会掩盖大量中间状态。扫描到 AP、完成 WPA 认证、收到 DHCP 地址、解析域名、完成 TLS、收到 MQTT CONNACK 或 HTTP 200 是不同证据。状态机应允许回退，例如 IP 丢失回到 DHCP、认证失败回到配网、服务拒绝回到应用退避，而不是所有错误都从头重启。

PYTHON · CONNECTION STATE复制
from enum import Enum

class State(str, Enum):
    OFFLINE = "offline"
    LINK = "link"
    IP = "ip"
    SERVICE = "service"

def can_publish(state):
    return state == State.SERVICE

状态模型区分链路、IP 和服务；目标机仍需核对 Wi‑Fi、DHCP、DNS 和服务器证据。

C · EVENT HANDOFF复制
void wifi_event(void *arg, int32_t event) {
    net_event_t message = {.id = event, .tick = xTaskGetTickCount()};
    xQueueSend(net_queue, &message, 0);
}

回调只投递事件，连接任务统一做状态转移；队列容量和上下文规则需按目标配置。

12.1.3 事件循环与回调上下文

ESP-IDF 的网络组件通过事件循环把 Wi‑Fi、IP 和接口变化通知应用；回调上下文、调用线程和生命周期必须按版本文档核对。回调里做慢 I/O、分配大缓冲或直接重连容易阻塞事件处理。更安全的结构是回调只记录事件并投递到连接任务，由任务统一执行状态转移。

12.1.4 在线、可达与服务健康

链路可达不等于业务健康。AP 关联可能仍无 DHCP，能 ping 网关可能仍 DNS 失败，TCP 建立可能 TLS 证书不匹配，MQTT 连接可能主题权限被拒绝。健康报告应分层记录 RSSI、IP、DNS、握手、服务响应和最后有效业务时间，避免用一项绿色指标覆盖其余未知。

12.1.5 断线、退避与重连预算

重连需要退避、抖动和上限。固定 100 ms 重试会让断电后的设备一起冲击 AP 和服务器；指数退避如果没有最大值又会让恢复等待过久。记录 attempt、reason、delay、random_seed、last_success 和总预算，并在认证失败、凭据错误、服务拒绝和临时断线之间使用不同策略。

12.1.6 离线队列与数据新鲜度

离线队列是产品策略而不是无限缓存。要定义元素大小、容量、时间戳、优先级、过期时间和满队列动作：拒绝、覆盖旧数据、合并、降采样或只保留告警。恢复后发送旧 telemetry 也可能过时或造成突发流量；队列水位和数据年龄应成为健康证据。

12.1.7 时间、功耗与网络协同

网络活动与功耗/实时性互相影响。扫描、TLS 握手、证书验证、射频发射和 Flash 写入都会占用 CPU、RAM 和电流；睡眠会改变连接保持和唤醒延迟。ESP-IDF 的电源管理文档说明频率切换和低功耗会影响中断延迟，因此应把连接窗口、唤醒源、功耗和任务预算一起评审。

12.1.8 本节交付：联网状态卡

联网状态卡包括 layer、state、event、owner_task、precondition、timeout、retry/backoff、socket/session、offline_policy、health_signals、power_window、trace_fields、host_result、target_result 和 unverified_scope。它是后续 Wi‑Fi、协议、安全和 OTA 单元共享的事实入口。

12.2.1 STA、AP 与 APSTA 模式

STA 是连接 AP 的客户端，SoftAP 允许手机或电脑先连接设备，APSTA 则同时承担两种角色。角色会影响信道、内存、功耗和应用路径；配网阶段可能暂时启动 SoftAP，凭据成功写入后切到 STA。切换前后要定义服务是否暂停、旧 socket 如何关闭以及失败时回到哪种角色。

12.2.2 扫描结果与网络身份

SSID 是人可读的网络名，BSSID 标识具体 AP，channel 是无线资源，RSSI 只是接收信号强度。相同 SSID 可能对应多个 AP，强 RSSI 不代表拥塞小、吞吐高或互联网可达。扫描记录要保留时间、BSSID、信道、加密能力和选择规则，避免现场只凭信号条猜原因。

C · PROVISIONING SHAPE复制
wifi_prov_mgr_config_t config = {
    .scheme = wifi_prov_scheme_ble,
    .scheme_event_handler = WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM
};
ESP_ERROR_CHECK(wifi_prov_mgr_init(config));

示例展示依赖形状；凭据、NVS 加密、超时和具体 IDF 版本必须核对。

PYTHON · RETRY BACKOFF复制
def backoff(attempt, base=1.0, maximum=60.0):
    if attempt < 0:
        raise ValueError("attempt must be non-negative")
    return min(maximum, base * (2 ** attempt))

退避模型用于主机预算；真实 RSSI、信道、认证和法规条件仍需实机验证。

12.2.3 认证、失败原因与重试

认证失败、AP 不存在、信号太弱、信道不兼容、DHCP 超时和凭据格式错误的恢复动作不同。ESP-IDF Wi‑Fi API 的 connect 调用通常只尝试一次，持续重连需要应用处理失败计数和退避。错误事件要带 reason、attempt、RSSI、AP 身份和是否可由用户修复。

12.2.4 DHCP、静态地址与 DNS

获得 IP 后仍要验证网关、DNS、时间和服务端。DHCP 租约可能变化，静态地址可能冲突，DNS 可能返回多个地址或暂时失败。应用请求应在 network_ready 条件之后，并对 DNS、TCP、TLS 和服务响应分别计时；一个成功 ping 不能覆盖证书、权限和主题错误。

12.2.5 配网会话与超时

配网会话要有开始、凭据输入、验证、提交、超时、取消和擦除。SoftAP 或 BLE 配网期间应限制尝试次数、隐藏敏感回显并在超时后关闭入口；用户按键/命令擦除凭据时要清理旧连接、缓存和状态，重启后明确进入未配网模式，而不是继续使用旧句柄。

12.2.6 NVS 中的凭据生命周期

Wi‑Fi 凭据通常写入 NVS，生产设备应结合 NVS 加密、Flash Encryption 和访问控制。更新凭据可采用新旧双槽、校验后提交和失败回滚；擦除动作应记录原因但不把密码写入日志。存储版本、加密状态和分区布局属于配置证据，不能只在代码注释里说明。

12.2.7 现场诊断与恢复按钮

现场诊断应同时服务普通用户和工程师：LED 可以表示未配网、认证失败、无地址、服务离线和恢复中，串口/远程日志则记录详细 reason。状态灯也会占 GPIO、功耗和时序预算；定义闪烁周期、优先级和安全默认态，避免诊断输出掩盖主业务。

12.2.8 本节交付：Wi‑Fi 配网卡

Wi‑Fi 配网卡包括 role、scan_policy、selection_rule、auth、dhcp/dns、credential_version、nvs_partition、encryption、provision_window、erase_trigger、diagnostic_codes、retry_policy 和 target_conditions。它将用户体验与底层网络事实连接起来。

12.3.1 GAP 角色与广播

GAP 处理发现和连接角色，GATT/ATT 描述服务、特征和属性访问，SMP 处理配对、密钥和加密。一个 BLE 外设可以广播自己的服务并等待 central 连接；手机看到设备名只证明收到了广播，不证明服务完整、权限正确或数据会话已经建立。

12.3.2 GATT 服务与特征

服务/特征表是 BLE 的应用 API。每个特征要有 UUID、长度、编码、读写/通知权限、最小/最大值、版本和错误响应。动作型特征要说明写入是否幂等、是否需要确认、执行完成如何回报；不要把一个可写字节当成没有边界的命令通道。

C · GATT CHARACTERISTIC复制
static const ble_gatt_svc_def services[] = {
    {
        .type = BLE_GATT_SVC_TYPE_PRIMARY,
        .uuid = &service_uuid.u,
        .characteristics = chars
    },
    {0}
};

服务表是 API 形状；UUID、权限、生命周期和 NimBLE/Bluedroid 版本需按目标工程确认。

PYTHON · FRAGMENT REASSEMBLY复制
def accept_fragment(parts, sequence, payload, total):
    if sequence < 0 or sequence >= total:
        raise ValueError("bad sequence")
    parts[sequence] = payload
    return len(parts) == total

主机验证长度和顺序；真实 MTU、连接中断和手机兼容仍需 BLE 设备测试。

12.3.3 ATT 权限与读写语义

ATT 的读写是事务，通知通常是不带确认的单向发送，指示需要客户端确认。通知队列满、手机后台、连接暂时拥塞时，生产者必须知道拒绝、覆盖、合并或降低频率。记录 value 序号、连接句柄、发送结果和客户端确认，才能解释‘手机偶尔少一条’。

12.3.4 通知、指示与背压

BLE 链路有 MTU 限制，应用数据超过单包后需要长度、消息 ID、分片序号、总片数/偏移、超时和重组失败动作。不要依赖手机库恰好分包；注入乱序、重复、截断和连接中断，验证重组器不会把两条消息拼接或无限等待。

12.3.5 MTU、分包与重组

配对/绑定提供链路级加密和身份关系，但不自动授权每个应用动作。设备维护命令仍可能需要应用层权限、挑战/响应和版本检查。密钥、绑定列表、删除条件和重新配对要有生命周期；恢复出厂、换用户和丢手机时不能留下无限制访问。

12.3.6 配对、绑定与密钥生命周期

连接间隔、slave latency、 supervision timeout、广播间隔和发射功率共同决定交互延迟与功耗。ESP-NimBLE 面向 BLE-only 场景更轻量，Bluedroid 覆盖 Classic + BLE；选择栈和参数要结合芯片系列、内存、手机兼容和证据，而不是只复制示例默认值。

12.3.7 连接参数与功耗

低功耗 BLE 设计要先标出必须在线的窗口和可延迟的数据。批量通知、延长连接间隔、按需广播、睡眠唤醒和断点续传都可能降低功耗，但会改变用户感知和超时。目标机测量要包含手机、天线、连接参数、屏幕/应用状态和电池电压。

12.3.8 本节交付：BLE 交互卡

BLE 交互卡包括 role、advertising、service_uuid、characteristics、permissions、encoding、mtu、fragmentation、notify_policy、pairing/bonding、app_auth、connection_params、power_window、compatibility 和 target_evidence。它为 Wi‑Fi 配网和本地维护提供可复用接口。

12.4.1 MQTT 与 HTTP 的角色

MQTT 适合发布/订阅和设备到云的异步消息，HTTP 适合资源请求和响应；两者都运行在传输和 TLS 之上。建立 TCP 连接、完成 TLS、收到 MQTT CONNACK 或 HTTP 2xx 各自只证明一层。业务完成要由消息 schema、结果码、序号和服务端处理记录共同定义。

12.4.2 消息身份与时间戳

设备消息应包含 device_id、schema_version、message_id/sequence、event_time、monotonic_age、payload、quality 和 result。云端按 sequence 去重时要处理重启和回绕；按 wall clock 排序时要说明时间同步不确定性。没有版本和身份的 JSON 看似灵活，升级后却难以解释旧数据。

C · MQTT EVENT复制
esp_mqtt_client_config_t config = {
    .broker.address.uri = "mqtts://broker.example",
    .credentials.client_id = "device-id"
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&config);

URI、证书、身份和版本不能从占位地址推出；生产配置必须脱离示例秘密。

PYTHON · IDEMPOTENT RETRY复制
def should_retry(status, idempotent, attempt, limit):
    transient = {408, 429, 500, 502, 503, 504}
    return status in transient and idempotent and attempt < limit

重试资格不等于业务已完成；要保存 message_id、原始响应和可能副作用。

12.4.3 MQTT topic、QoS 与 will

MQTT QoS 说明传输交付级别，不自动提供业务 exactly-once；retain 是保留最后消息，will 是连接异常的提示，它们都可能产生旧状态或重复消费。设备要记录 broker、topic、client_id、session、QoS、publish 返回和业务确认，不能把一次 socket 写成功当作云端已入库。

12.4.4 HTTP method、状态码与 handler

HTTP method 与状态码也需要应用合同。GET 通常读取，PUT 可设计为幂等更新，POST 可能创建新事务；服务器返回 202、409、429、5xx 和超时时，设备应知道是否可重试、是否可能已执行以及如何查询最终状态。ESP-IDF HTTP server 的 handler 线程安全由应用负责，共享状态必须显式保护。

12.4.5 TLS、证书与时间

TLS 提供加密和服务端认证，但证书验证依赖信任锚、主机名和有效时间；设备没有正确时间可能无法验证证书。证书/信任库更新要有版本、回滚和过期策略，日志不能泄露私钥。测试时可使用专用测试 CA，不应把关闭验证写成生产修复。

12.4.6 重试、去重与业务确认

超时后的重试必须考虑副作用。遥测上传通常可用 message_id 去重，开门、固件切换、计费或执行器命令则需要幂等键、状态查询或‘可能已执行’结果。每次重试记录 attempt、backoff、原始响应、业务状态和剩余预算，避免网络抖动造成重复动作。

12.4.7 背压、批量与离线恢复

背压可以通过 MQTT inflight 限制、HTTP 并发上限、应用队列、批量、降采样和过期策略实现。恢复上线时不要立刻倾倒所有离线数据；按优先级、年龄、带宽和服务器配额发送，并记录 dropped/expired/replayed。队列容量是内存、功耗和恢复时间的共同约束。

12.4.8 本节交付：应用协议卡

应用协议卡包括 transport、endpoint、schema、identity、sequence、timestamp、QoS/status、tls_scope、idempotency、retry、backpressure、offline_retention、server_ack、privacy、compatibility 和 host/target evidence。它把‘联网成功’升级为可复查业务事务。

12.5.1 安全目标四分法

安全目标要拆开：机密性防止秘密被读取，完整性防止代码/数据被篡改，身份回答‘是谁’，授权回答‘允许做什么’。TLS 可以同时提供传输机密性和服务器认证，但不自动保护 Flash 中的固件、NVS 凭据或调试口；每个目标都要有机制和证据。

12.5.2 Secure Boot 信任链

Secure Boot 形成启动信任链，验证可变软件实体的签名；Flash Encryption 保护外部 Flash 内容。Espressif 文档明确两者是不同功能，生产环境通常组合使用。签名 key、设备 key、信任锚和版本撤销列表的所有权、存储、备份和轮换必须分别定义。

C · SIGNATURE GATE复制
bool verify_image(const uint8_t *image, size_t n,
                  const uint8_t *signature) {
    return sha256_ok(image, n) &&
           verify_signature(signature, image, n);
}

完整性和签名是模型占位；密钥、芯片硬件验证和启动链必须按 ESP32 系列核对。

PYTHON · CREDENTIAL RECORD复制
def credential_record(version, identity, encrypted):
    if not version or not identity:
        raise ValueError("identity and version required")
    return {"version": version, "identity": identity,
            "encrypted": bool(encrypted)}

主机检查字段而不接触真实秘密；目标机需验证 NVS/Flash/eFuse 和权限边界。

12.5.3 Flash Encryption 与 NVS

Flash Encryption 不能替代 NVS encryption；NVS 中的 Wi‑Fi 凭据、证书和配置有自己的分区/密钥关系。分区表、bootloader、app、otadata 和 NVS key partition 要一起审查。启用加密可能改变重刷、JTAG 和 UART 下载能力，不能在不理解后果时复制 menuconfig 选项。

12.5.4 设备身份与 TLS 信任锚

设备身份最好是每台唯一的密钥或证书，而不是所有设备共用一个密码。TLS 验证要核对信任锚、主机名、时间、证书链和撤销策略；设备证书轮换时需要旧新并存、失败回滚和过期窗口。身份字段可以公开，私钥和明文凭据绝不能写日志或普通分区。

12.5.5 eFuse、调试口与不可逆操作

eFuse、关闭 JTAG、禁用 UART 下载和 Secure Boot release mode 可能是一次性或难以恢复的动作。生产前应保存芯片 ID、密钥生成环境、烧录脚本、签名摘要、分区、恢复镜像和审批记录，并先在同修订测试设备演练。开发模式的便利不能悄悄带进量产。

12.5.6 日志、权限与最小暴露

日志最小化不是不记录。公开日志可以保留阶段、错误类别、计数和哈希摘要，调试日志在授权环境保留寄存器/网络细节；私钥、Wi‑Fi 密码、token、完整证书和用户数据应脱敏或不落盘。调试命令、OTA、配置和 reset 也要按角色授权，不能仅靠隐藏 URI。

12.5.7 密钥轮换与撤销

密钥轮换需要版本、双槽、有效期、撤销和恢复策略。设备收到新证书先验证链和时间，再原子提交；失败保留旧 key。泄露或换厂时，云端拒绝旧身份，设备进入受限维护模式。轮换本身也是 OTA/存储事务，必须可重试、可回滚并留下证据。

12.5.8 本节交付：安全身份卡

安全身份卡包括 goal、trust_chain、signing_key_owner、device_identity、tls_anchor、nvs_partition、encryption、efuse_state、debug_scope、log_policy、rotation、revocation、recovery_image、host_checks、target_checks 和 irreversible_actions。它把安全声明限制在实际配置和证据内。

12.6.1 OTA 分区与镜像身份

ESP-IDF OTA 的安全应用更新通常需要至少两个 OTA app slot 和一个 OTA data 分区。新镜像写入当前未启动的槽，验证后更新 otadata；断电恢复能力取决于分区和写入过程。分区表本身、bootloader 和 NVS 等数据分区的更新风险不同，不能把‘支持 OTA’当作所有组件都安全可更新。

12.6.2 下载、完整性与签名验证

下载完成只证明字节收齐。还要检查镜像格式、摘要/签名、目标芯片、版本策略、配置兼容和依赖；验证通过后才选择启动槽。保存 URL/manifest、大小、哈希、证书、进度、重试、当前/候选槽位和错误阶段，便于断网后续传或回滚。

C · OTA SLOT CHECK复制
const esp_partition_t *running = esp_ota_get_running_partition();
const esp_partition_t *next = esp_ota_get_next_update_partition(running);
ESP_ERROR_CHECK(esp_ota_begin(next, OTA_SIZE_UNKNOWN, &handle));

分区、签名、断电和 rollback 状态必须按当前 ESP-IDF 和分区表验收。

PYTHON · POWER BUDGET复制
def energy_mwh(current_ma, voltage_v, active_minutes):
    if min(current_ma, voltage_v, active_minutes) < 0:
        raise ValueError("non-negative values required")
    return current_ma * voltage_v * active_minutes / 60.0

预算模型用于比较活动窗口；电池、射频峰值、温度和测量仪器需目标机补证。

12.6.3 首次启动与回滚确认

应用回滚需要 pending、valid、invalid 等状态和首次启动健康检查。新版本应先保持受限输出，验证时钟、存储、网络、关键任务和安全态，再标记 valid；诊断失败则标记 invalid 并重启到旧槽。不要在启动早期无条件确认，否则坏版本会被永久接受。

12.6.4 掉电、断网与更新恢复

掉电、断网、服务器返回错误、空间不足和签名失败都应进入可观察状态。测试可以在主机模型中切断下载、损坏摘要、重复写 otadata，再在目标机用受控方式做一次掉电/复位注入。若无法保证断电可控、输出安全或恢复镜像存在，应停止目标实验。

12.6.5 Light/Deep Sleep 与唤醒源

Light-sleep 通常保持更多上下文，Deep-sleep 可能关闭更多电源域并从唤醒入口重新启动；DFS 还会改变频率和延迟。ESP-IDF 文档把睡眠模式、唤醒源和 Wi‑Fi/BLE 场景分开说明。设备要记录 wake cause、睡眠时长、连接重建、时间同步和未保持的状态。

12.6.6 功耗预算与测量窗口

功耗报告要分峰值、活动窗口、睡眠电流、唤醒能量和测量条件。平均电流需绑定工作周期、信号强度、重连次数、温度、电池电压和外围负载；一次短时读数不能直接推出电池寿命。连接保持、批量发送、证书验证和 Flash 写入的峰值可能决定电源设计。

12.6.7 远程健康、日志与维护模式

远程运维最小指标包括 firmware/config version、boot/reset cause、uptime、last_success、RSSI、IP、服务错误、队列年龄、温度、电池和 OTA state。日志上传也要受背压、隐私和成本限制；维护模式应有授权、时限、退出和安全输出，不能开放一个永久远程 shell。

12.6.8 长期运行与发布责任

实时交付卡包括 partition_table、image_hash/signature、slot_state、rollback_policy、power_modes、wake_sources、energy_budget、health_schema、remote_log_policy、maintenance、fleet_compatibility、host_result、target_result、known_limits 和 stop_conditions。它把 ESP32 联网设备从一次演示推进到可长期运维产品。

资料卡（访问日期：2026-09-05）：Espressif 官方 ESP-IDF 文档覆盖 Wi‑Fi、ESP-NETIF、Bluedroid/NimBLE、配网、MQTT、HTTP server、OTA、分区、安全和低功耗。通用主机模型不能替代当前 ESP32 系列的射频、天线、供电、eFuse、证书、分区、手机/AP/服务器和现场环境。