网络配置最佳实践
本文说明 FastBee-Arduino 固件的网络自愈机制与配置建议，帮助你把设备部署到长期无人值守的现场。
一、联网方式选择
| 方式 | 适用场景 | 说明 |
|---|---|---|
| WiFi STA | 室内节点、有路由器的现场 | 默认方式，配置 SSID/密码后自动连接 |
| 以太网（W5500） | 工业现场、信号干扰大 | 部分环境编译，运行时默认关闭；启用后核对SPI/控制脚、供电及IP |
| 4G（EC801E） | 无 WiFi 的户外场景 | 部分环境编译，运行时默认关闭；需SIM/APN、供电与UART资源 |
当前以 networkType 选择适配器（0 WiFi、1 W5500、2蜂窝），不承诺以太网/WiFi/4G固定优先级自动切换。切换需核对编译能力、功能选择、引脚与资源。
二、WiFi 自愈机制（内建）
固件包含以下恢复路径，实际行为取决于已部署版本、网络配置和驱动状态：
- 自动重连：WiFi 断开后自动重试，日志会记录断开原因码（reason code）便于排查。
- AP 回退：首次配网或允许回退的连接失败路径可尝试启动设备AP；名称和地址按实际配置与日志确认。有STA凭据且
autoFailover=false时，相关重试路径继续STA恢复，不一定创建热点。另有最后保障AP路径，但AP本身也可能启动失败，不能承诺任何启动故障都能通过Web恢复。 - 配置持久化：网络JSON通过临时文件校验及主/备份代提交，降低写入中断风险。主文件不可用时可尝试备份，之后才是部分NVS配置回退；这不保证任何掉电、存储故障或跨文件修改都无损。维护前仍须保留独立备份，保存完成和运行生效分别核验。
最后保障AP也启动失败时，源码会尝试递增网络专用NVS的失败计数；达到3时清理net_cfg后安排重启。该分支不删除LittleFS中的network.json及.bak，也不是全设备恢复出厂。计数/清理写入结果未逐项确认，不能以日志意图证明NVS已保存；有效JSON下次仍可能优先加载。它不构成所有启动阶段的通用失败计数或坏配置隔离。
WiFi 配置建议
- 固定 SSID/密码：避免使用中文 SSID 和特殊字符，部分路由器兼容性差。
- 2.4GHz 频段：ESP32 全系列不支持 5GHz。
- 信道 1/6/11：现场干扰大时固定信道比自动信道更稳定。
- DHCP 保留：在路由器为设备 MAC 保留固定 IP，方便访问 Web 界面。
三、MQTT 断线恢复（内建）
- 指数退避重连：断线后按退避间隔自动重连，避免风暴式重试。
- 僵尸连接检测：长时间无收发时主动检测并重建连接。
- 平台重连：重连成功后自动重新订阅主题。
MQTT 配置建议
- keepAlive 建议 30-60s：过短费流量，过长断线发现慢。
- clientId 唯一：多设备部署时确保 clientId 不冲突（固件默认按设备标识生成）。
- 上报确认：当前PubSubClient发布路径使用QoS 0；主题配置中的QoS不使发布自动变成QoS 1。订阅QoS与发布不同，业务送达需核对平台回执及数据有效性。
四、OTA 升级与自动回滚
固件支持通过 Web 界面或平台下发 OTA 升级，并内建两级保护：
- 上传停滞清理：上传型会话的相关检查入口发现60秒无新块后，尝试结束Update并记录失败、清理会话标记。升级分区可能已有部分写入，不能据此认定从未修改Flash或整机已经恢复；应核验当前运行及启动镜像，并保留本次失败记录。
- 应用确认与有条件回滚：2026-10-04后继开发代码对NEW/PENDING_VERIFY状态保留既有90秒应用运行窗口；到期确认最多3次、间隔5秒，仅SDK成功才认为已确认，耗尽仍保留未确认状态。关键初始化失败先保全诊断，再尝试标无效；SDK失败不自动重启，成功后才明确重启。90秒不是全硬件自检，实际回滚仍依赖bootloader、分区及有效旧镜像；该修复及22个主机场景仍UNTESTED，待统一候选和设备验收，未部署。
启用 bootloader 级回滚（可选增强）
实际bootloader是否开启回滚是必要核对项，对应SDK配置名称如下；本节不是现场修改或重新刷写bootloader的操作指令：
ini
CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE=y应用代码、实际bootloader和分区必须一起核验。仅在应用配置中加入该宏不证明设备bootloader已经改变；未启用、缺少可用分区或旧镜像无效时，相关API可能失败或不适用。不得把任何SDK错误一概解释为安全空转，也不得为获得回滚能力直接改变现场分区。
五、长期运行排查建议
| 现象 | 排查方向 |
|---|---|
| 设备周期性重启 | 串口日志看是否 OOM/看门狗；检查供电能力（见硬件选型指南） |
| WiFi 反复断开 | 日志中的 reason= 码：需结合SDK、SSID、认证与路由器日志分析，不能单凭原因码归因 |
| MQTT 时断时连 | 检查 clientId 是否冲突、broker 连接数上限、keepAlive 设置 |
| OTA 后行为异常 | 先核对运行/启动镜像、OTA状态、bootloader和配置保全证据；自动回滚并非必然。任何重刷须先明确目标身份、稳定候选、保留分区及恢复方案 |
| 配置缺失或回到旧值 | 区分未提交缓存、主/备份损坏、挂载失败、网络NVS回退/清理和迁移终态；保全原件后选择对应恢复路径，不默认格式化或全擦 |
串口日志默认包含模块名与关键上下文（网络事件、MQTT 状态、文件系统操作），115200 波特率即可抓取。