Wi-Fi Management
Relevant source files
The following files were used as context for generating this wiki page:
Wi-Fi Management in FlxOS provides a centralized interface for handling wireless connectivity, including Station (STA) mode for connecting to external networks and Soft Access Point (SoftAP) mode for hosting a hotspot. The system is built on top of the ESP-IDF Wi-Fi driver and integrates with the project's observable-based UI system to provide real-time status updates to the user interface.
The management layer is divided into specialized modules coordinated by the ConnectivityManager. These modules handle low-level event handling, network scanning, credential persistence, and network address translation (NAT) for hotspot functionality.
Architecture and Core Components
The Wi-Fi subsystem follows a singleton pattern for its core managers to ensure consistent state across the operating system.
Connectivity Hierarchy
The ConnectivityManager acts as a facade, orchestrating the WiFiManager (Station mode) and HotspotManager (AP mode). It manages a recursive mutex to synchronize access to the underlying ESP-WiFi driver, which is a shared resource between both modes.
Component Descriptions
| Component | Responsibility | Relevant Files |
|---|---|---|
ConnectivityManager | Top-level facade; handles initialization, mode switching, and GUI bridges. | ConnectivityManager.cpp |
WiFiManager | Manages Station mode: scanning, connecting, and IP event handling. | WiFiManager.cpp |
HotspotManager | Manages Access Point mode: SSID config, client tracking, and NAT. | HotspotManager.cpp |
SettingsManager | Provides persistence for SSIDs and passwords via NVS/JSON. | ConnectivityManager.cpp |
Sources: main/core/connectivity/ConnectivityManager.cpp:48-60, main/core/connectivity/wifi/WiFiManager.cpp:24-46, main/core/connectivity/hotspot/HotspotManager.cpp:115-135
Station Mode (STA)
The Station mode allows FlxOS to connect to external Access Points. It supports background scanning, automatic reconnection with a retry limit, and time synchronization via SNTP once a connection is established.
Connection Flow
When a connection is initiated, the WiFiManager sets the Wi-Fi storage to RAM (handling persistence manually via SettingsManager) and configures the wifi_config_t structure.
Status States
The system tracks the Wi-Fi state through a WiFiStatus enum, which is pushed to the UI via observables.
- DISCONNECTED: Initial state or manual disconnect.
- SCANNING: Active site survey in progress.
- CONNECTING: Attempting to associate and authenticate.
- CONNECTED: Associated and obtained an IP address.
- AUTH_FAILED: Connection failed due to incorrect credentials.
- NOT_FOUND: Specified SSID was not found after retries.
Sources: main/core/connectivity/wifi/WiFiManager.cpp:234-265, main/core/connectivity/wifi/WiFiManager.hpp:15-25
Hotspot and SoftAP (AP)
The HotspotManager allows the device to act as an Access Point. It includes advanced features such as DHCP lease tracking, client hostname resolution, and NAT (Network Address Translation) to share the Station's internet connection with connected clients.
NAT and Traffic Tracking
If NAT is enabled, the HotspotManager enables NAPT (Network Address Translation) and hooks into the lwIP netif input/link-output functions to track data usage (bytes sent/received).
Client Management
The manager tracks connected stations and retrieves their details, including MAC address, IP, RSSI, and duration of connection.
| Field | Description | Source |
|---|---|---|
| MAC | Unique hardware address of the client. | HotspotManager.cpp |
| IP | Assigned IP via DHCP (queried from dhcps_get_active_leases). | HotspotManager.cpp |
| Hostname | Resolved device name from DHCP options. | HotspotManager.cpp |
| RSSI | Signal strength of the connected client. | HotspotManager.cpp |
Sources: main/core/connectivity/hotspot/HotspotManager.cpp:88-113
CLI Management Interface
The CliService provides a terminal-based interface for managing Wi-Fi without the GUI. This is critical for headless mode operations.
WiFi Commands
wifi status: Displays current state, SSID, IP, and signal strength.wifi scan: Triggers an asynchronous scan and prints results in a table.wifi connect <ssid> <pass>: Connects to a network.wifi on/off: Enables or disables the Wi-Fi radio.
Hotspot Commands
hotspot status: Shows if the hotspot is active and if NAT is enabled.hotspot on: Starts the hotspot using stored configuration.hotspot off: Stops the hotspot.
Sources: main/core/services/cli/CliService.cpp:160-235, main/core/services/cli/CliService.cpp:238-275
Configuration and Persistence
Connectivity settings are registered with the SettingsManager for persistence across reboots. The following keys are used:
| Key | Purpose |
|---|---|
wifi_ssid | Saved Station SSID. |
wifi_pass | Saved Station password. |
wifi_autostart | Boolean to enable Wi-Fi on boot. |
hs_ssid | Hotspot SSID. |
hs_pass | Hotspot password. |
hs_auth | Hotspot authentication mode (e.g., WPA2). |
Sources: main/core/connectivity/ConnectivityManager.cpp:36-44
Summary
The Wi-Fi Management system in FlxOS provides a robust, multi-mode networking stack. By abstracting the ESP-IDF complexities into the WiFiManager and HotspotManager, and providing a unified control point via the ConnectivityManager, the system supports seamless transitions between Station and Access Point modes. The inclusion of NAT and real-time usage monitoring via lwIP hooks ensures that the device can function as a capable portable router, while the CLI integration allows for full management in both GUI and headless environments.