网络模式切换机制

FastBee 设备支持 STA（客户端） 与 AP（热点） 两种 WiFi 工作模式，并提供启动时修正、运行时失败回退和离线恢复路径。恢复能否成功仍取决于固件、配置文件、网络和供电状态；AP回退不等于所有启动故障都有网络救援入口。

1. 模式定义

模式枚举定义于 include/network/WiFiManager.h：

枚举	值	说明
`NETWORK_STA`	0	STA 客户端模式，连接上级路由器（`network.json` 的 `mode=0`）
`NETWORK_AP`	1	AP 热点模式，设备自建热点（`network.json` 的 `mode=1`），默认 IP `192.168.4.1`

注意

mode=0 是 STA，mode=1 是 AP，配置时不要搞反。项目已移除 AP+STA 双模，STA 失败后回退为纯 AP（wifi_mode=2）。

2. 配置存储与优先级

配置持久化在 LittleFS 的 /config/network.json（字段：mode、staSSID、staPassword、apSSID、apPassword、enableMDNS、customDomain 等）。
当前实现优先加载 LittleFS 的 /config/network.json（含已有备份恢复）；加载失败或文件不存在才回退到 NVS 的 net_cfg 命名空间。 NVS中的旧值不会覆盖成功加载的JSON。排查时先核对实际读取来源、文件解析结果与备份，再检查联网参数。
mDNS是否启用以 /config/features.json 的显式 mdns 配置为准；网络文件同名字段是兼容镜像。只有功能文件没有显式设置时才迁移旧网络值。

3. 启动时智能模式修正

NetworkManager 加载配置后执行双向修正（修正后立即持久化）：

条件	修正	目的
mode=STA 但 `staSSID` 为空	改为 AP	首次启动保证用户能通过热点配网
mode=AP 但 `staSSID` 非空	改为 STA	防止配置被持久化成 AP 后设备永久卡在 192.168.4.1

第二条修正的背景：AP→STA 探测恢复只在 运行时 STA 失败自动回退 时触发；如果 network.json 被直接持久化成 AP，开机即进 AP 且不再探测 STA，设备会表现为「WiFi 凭据正确却只能 AP 访问」。因此只要存在有效凭据，开机一律优先尝试 STA；STA 失败仍会走既有回退逻辑退回 AP，回退仍受autoFailover、资源和驱动状态影响，不能保证任何故障下均可达。

推论

通过 API 切换 AP 模式时若不清空 staSSID，设备重启后会被智能修正自动改回 STA。测试 AP 模式必须同时传入 staSSID: ""。

4. 运行时切换（API）

POST /api/network/config（JSON body，需登录）：

json

{ "mode": "0", "staSSID": "MyWiFi", "staPassword": "password",
  "apSSID": "FastBee-XXXX", "apPassword": "admin123" }

页面提交使用数字文本，参数兼容按当前处理器解析；不要将示例字符串视为所有入口唯一合法表示。
保存成功后设备调度配置重启（scheduleConfigReboot），如未自动重启可手动 POST /api/system/restart。
首次配网也可使用 POST /api/wifi/config（配网接口）。

5. STA 失败 → AP 回退（failover）

STA 模式下连接失败或长时间失联时：

autoFailover允许且相关条件满足时尝试回退到纯AP（_apFallbackAuto = true），串口输出 >>> AP fallback: AP IP=... SSID=...；
自动回退状态下会周期性探测 WiFi 恢复，探测成功自动切回 STA；
STA 失联过久会调度重启以重新进入回退流程；
AP名称、密码与地址以保存配置及实际结果核对，默认地址为192.168.4.1。

远程运维提示

不要让运维电脑长期连接设备 AP——连上 AP 后电脑会失去外网/LAN 访问。设备卡 AP 时优先用下面的离线恢复方式。

6. 离线恢复卡 AP 的设备（不连 AP）

若设备卡在 AP 模式且不方便连接其热点，可通过串口离线修改 LittleFS 镜像恢复 STA：

esptool.py read_flash <fs_offset> <fs_size> backup.bin 读出文件系统分区（偏移见分片表布局约束）；

用 littlefs-python 挂载镜像，修改 /config/network.json：mode=0、staSSID、staPassword；

python

from littlefs import LittleFS, UserContext
raw = bytearray(open('backup.bin', 'rb').read())
ctx = UserContext(buffer=raw)
lfs = LittleFS(context=ctx, block_size=4096, block_count=len(raw)//4096,
               read_size=256, prog_size=256, cache_size=256, lookahead_size=128)

esptool按已安装版本的write_flash/write-flash语法写回 <fs_offset> fixed.bin 写回，设备重启后自动连接 STA。

以上离线操作须先确认设备身份、当前分区表并保全原镜像，修改后核验写入结果和其它配置。无需为“怀疑NVS旧值”直接擦除整个NVS分区：JSON加载成功时已优先使用它，整分区擦除还会影响其它命名空间。若JSON损坏导致NVS回退，应先修复并核验JSON及其备份。本文不代表已完成任何现场恢复操作。

网络模式切换机制 ​

1. 模式定义 ​

2. 配置存储与优先级 ​

3. 启动时智能模式修正 ​

4. 运行时切换（API） ​

5. STA 失败 → AP 回退（failover） ​

6. 离线恢复卡 AP 的设备（不连 AP） ​

相关文档 ​