Network Best Practices

This page explains the built-in network self-healing mechanisms and configuration advice for long-running, unattended deployments.

1. Choosing a Network Type

Type	Use Case	Notes
WiFi STA	Indoor nodes, sites with a router	Default; auto-connects after SSID/password is saved
Ethernet (W5500)	Industrial sites, heavy RF interference	Requires a supported build, active feature and configured SPI hardware
4G (EC801E)	Outdoor sites without WiFi	Requires a supported build, active feature, SIM, antenna and stable power

Priority when multiple are available: Ethernet > WiFi > 4G, switched automatically.

2. WiFi Self-Healing (Built-in)

No extra configuration needed:

1. Auto reconnect after disconnection; the disconnect reason code is logged for troubleshooting.
2. AP fallback to the provisioning hotspot fastbee-ap when:
   • First boot with no saved WiFi;
   • STA fails to connect repeatedly;
   • Critical init fails repeatedly (boot failure counter protection).
3. Atomic config persistence: network.json is written via a temp file + rename, so a power loss cannot leave a corrupted config.

WiFi Configuration Advice

• Use plain ASCII SSID/password — Chinese SSIDs and special characters cause compatibility issues on some routers.
• ESP32 chips are 2.4GHz only — no 5GHz support.
• On congested sites, fix the router channel to 1/6/11 instead of auto.
• Reserve a fixed IP for the device MAC via router DHCP reservation.

3. MQTT Recovery (Built-in)

1. Exponential backoff reconnect — avoids retry storms.
2. Zombie connection detection — stale connections are probed and rebuilt.
3. Automatic re-subscribe after a successful reconnect.

MQTT Configuration Advice

• keepAlive 30-60s: shorter wastes traffic, longer delays outage detection.
• Unique clientId across devices (generated from the device identity by default).
• QoS 1 for property reports.

4. OTA Upgrade and Auto Rollback

Two layers of protection are built in:

1. Upload stall recovery: if no chunk arrives for 60s during an OTA upload, the session is aborted and the device returns to normal operation — no half-written firmware.
2. New firmware self-check: after an OTA, the new firmware enters a 90-second self-check window. If critical initialization fails within the window, the image is marked invalid and the device rolls back to the previous stable version; otherwise the new image is confirmed.

Optional: Bootloader-Level Rollback

The application self-check is most effective when the bootloader enables rollback support. For production firmware, enable in sdkconfig:

CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE=y

Without it, the self-check still runs safely but cannot actually switch back to the old partition.

5. Long-Running Troubleshooting

Symptom	Where to Look
Periodic reboots	Serial log for OOM/watchdog; check power budget (see Hardware Selection Guide)
WiFi flapping	reason= codes in the log: 201/202 usually weak signal or router kicking clients
MQTT drops	clientId conflicts, broker connection limits, keepAlive settings
Misbehaves after OTA	Self-check failure auto-rolls back; otherwise re-flash the previous version
Lost configuration	Extremely unlikely with atomic writes; check for power loss during writes

Serial logs include module names and context (network events, MQTT state, filesystem operations) at 115200 baud.

6. Related Docs

• Hardware Selection Guide
• Flashing Tutorial
• Network Settings UI
• MQTT Protocol Config