Hotspot & DHCP Server
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Hotspot and DHCP Server module in FlxOS provides the capability to transform the ESP32 microcontroller into a wireless Access Point (SoftAP). This system enables other devices to connect to the FlxOS hardware, receive IP addresses via an integrated DHCP server, and optionally share an existing station (STA) internet connection through Network Address Translation (NAT).
The module is managed primarily by the HotspotManager, which handles the low-level WiFi event lifecycle, client tracking, and traffic accounting. It integrates with the ConnectivityManager for higher-level orchestration and provides a user-facing configuration interface through the HotspotSettings application.
Sources: main/core/connectivity/hotspot/HotspotManager.cpp:113-115, main/core/connectivity/ConnectivityManager.cpp:32-34
System Architecture
The hotspot system is built as a multi-layered service that interacts with the ESP-IDF WiFi driver and the lwIP network stack.
Connectivity Stack
The following diagram illustrates the relationship between the hardware abstraction, management logic, and the user interface.
Component Responsibilities
| Component | Primary Responsibility |
|---|---|
| HotspotManager | Singleton class managing AP lifecycle, client lists, and traffic hooks. |
| ConnectivityManager | Orchestrates WiFi modes (AP/STA/APSTA) and persistence via SettingsManager. |
| HotspotSettings | GUI application for configuring SSID, password, and advanced AP parameters. |
| DHCP Server | Custom component providing IP lease management and hostname capture. |
| NAPT Engine | lwIP module used for routing traffic between Hotspot clients and Station interface. |
Sources: main/core/connectivity/hotspot/HotspotManager.hpp:16-55, main/core/connectivity/ConnectivityManager.cpp:131-140, main/core/apps/settings/hotspot/HotspotSettings.cpp:12-25
Hotspot Management Lifecycle
The HotspotManager handles the transition between states and ensures network parameters are applied correctly.
Start Sequence
When starting the hotspot, the system must determine the correct WiFi mode to avoid disrupting existing connections. If the device is already connected to a WiFi network as a station, it enters WIFI_MODE_APSTA (dual mode); otherwise, it uses WIFI_MODE_AP.
Traffic Hooking & Usage Monitoring
To monitor data usage, the HotspotManager installs hooks into the lwIP netif input and output functions for the station interface. This allows it to count every byte sent and received.
- Input Hook: Captures incoming packets from the internet to the hotspot.
- Output Hook: Captures outgoing packets from the hotspot to the internet.
- Usage Timer: An
esp_timerruns every 2 seconds to calculate speeds (KB/s) and update system observables.
Sources: main/core/connectivity/hotspot/HotspotManager.cpp:28-56, main/core/connectivity/hotspot/HotspotManager.cpp:192-210
DHCP & Client Tracking
The system tracks connected clients by combining data from the WiFi driver (for RSSI and MAC) and the custom DHCP server (for hostnames and IP addresses).
Client Information Structure
| Field | Description | Source |
|---|---|---|
mac | Hardware address of the client device | WiFi Driver |
aid | Association ID assigned by the AP | WiFi Driver |
hostname | Friendly name provided by the device | DHCP Lease |
ip | Assigned IP address | DHCP Lease |
rssi | Signal strength in dBm | WiFi Driver |
connected_duration | Time since initial connection | HotspotManager |
Sources: main/core/connectivity/hotspot/HotspotManager.hpp:72-80, main/core/connectivity/hotspot/HotspotManager.cpp:113-145
Connection Flow Diagram
Advanced Features & Configuration
Network Address Translation (NAT)
FlxOS supports "Internet Sharing" via NAPT. When enabled, the HotspotManager configures the DHCP server to provide DNS information (synced from the Station interface) and enables the lwIP NAPT module on the AP's IP address. It also disables WiFi Power Save (WIFI_PS_NONE) to ensure stable routing performance.
Sources: main/core/connectivity/hotspot/HotspotManager.cpp:371-410
Auto-Shutdown
To conserve power, the system includes an auto-shutdown mechanism. If no clients are connected for a specified timeout (default 300 seconds), the HotspotManager automatically stops the AP.
Sources: main/core/connectivity/hotspot/HotspotManager.cpp:241-249, main/core/connectivity/hotspot/HotspotManager.hpp:94-96
Configuration Parameters
These settings are configurable via HotspotSettings and persisted using SettingsManager.
| Setting | Range/Options | Description |
|---|---|---|
| SSID | 1-32 chars | The wireless network name. |
| Password | 8-64 chars | WPA2/WPA3 security key. |
| Channel | 1-13 | Wireless frequency channel. |
| Max Connections | 1-10 | Maximum simultaneous clients. |
| Security | Open, WPA2, WPA3, WPA2/3 | Authentication protocol. |
| TX Power | 8-80 | WiFi transmit power setting. |
Sources: main/core/apps/settings/hotspot/HotspotSettings.cpp:334-450, main/core/connectivity/ConnectivityManager.cpp:40-45
CLI Interface
The Hotspot system can be managed via the serial console using the hotspot command.
# Check current status and NAT state
hotspot status
# Enable hotspot using saved settings
hotspot on
# Disable hotspot
hotspot off
Sources: main/core/services/cli/CliService.cpp:261-294
Summary
The Hotspot & DHCP Server module provides a robust networking gateway for FlxOS. By integrating traffic monitoring, DHCP lease management, and NAT capabilities, it allows the ESP32 to act as a functional router for small groups of devices. The architecture ensures that these services can be managed seamlessly through both the graphical user interface and the command-line service.