Network Mode Switching

FastBee devices work in STA (client) or AP (hotspot) WiFi mode, with boot-time smart correction, runtime failover, and offline recovery to keep the device reachable in every state.

1. Mode Definitions

Defined in include/network/WiFiManager.h:

Enum	Value	Meaning
NETWORK_STA	0	STA client, connects to your router (mode=0 in network.json)
NETWORK_AP	1	AP hotspot, default IP 192.168.4.1 (mode=1)

警告

mode=0 is STA, mode=1 is AP — don't mix them up. AP+STA dual mode has been removed; STA failure falls back to pure AP.

2. Config Storage & Priority

• Persisted at /config/network.json in LittleFS (mode, staSSID, staPassword, apSSID, apPassword, ...).
• NVS network config takes priority over LittleFS. After firmware upgrades NVS may keep stale config; erase it with esptool erase_region 0x9000 0x5000 to force a reload.

3. Boot-Time Smart Correction

After loading config, NetworkManager applies bidirectional correction (persisted immediately):

Condition	Correction	Purpose
mode=STA with empty staSSID	switch to AP	first-boot provisioning must be reachable
mode=AP with non-empty staSSID	switch to STA	prevent devices permanently stuck at 192.168.4.1

Background for the second rule: AP→STA probe recovery only triggers after a runtime STA failure fallback. If network.json is persisted as AP, the device boots into AP and never probes STA again. So whenever valid credentials exist, STA is preferred at boot; STA failure still falls back to AP via the existing failover path.

Consequence

When switching a device to AP via the API without clearing staSSID, the next reboot auto-corrects it back to STA. Testing AP mode requires staSSID: "".

4. Runtime Switching (API)

POST /api/network/config (JSON, authenticated):

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

• mode is a numeric string ("0"/"1").
• Saving schedules a config reboot; if it doesn't happen, call POST /api/system/restart.

5. STA Failure → AP Failover

On STA connect failure or prolonged loss:

1. The device falls back to pure AP (_apFallbackAuto = true), serial shows >>> AP fallback: ...;
2. In auto-fallback state it periodically probes WiFi recovery and returns to STA when possible;
3. Prolonged STA loss schedules a reboot to re-enter the fallback flow;
4. Fallback AP default password is admin123, gateway 192.168.4.1.

Ops Note

Never let an ops computer stay connected to a device AP — it loses internet/LAN access. Prefer the offline recovery below.

6. Offline Recovery of AP-Stuck Devices (no AP connection)

Via serial, edit the LittleFS image offline:

1. esptool.py read_flash <fs_offset> <fs_size> backup.bin (offsets in Partition Layout);

2. Mount with littlefs-python and set /config/network.json to mode=0 + STA credentials:

   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)

3. esptool.py write-flash <fs_offset> fixed.bin; the device boots back into STA.

Also run esptool.py erase_region 0x9000 0x5000 if stale NVS config is suspected.

Related

• Network Best Practices
• Partition Layout Constraints
• Troubleshooting