Skip to content

WifiStaModule

WiFi station (client) mode connection. Connects the ESP32 to an existing Wi-Fi network. Introduced in Sprint 8; reconnect retry and NetworkModule management added Sprint 10/12.

What it does

WifiStaModule stores SSID and password and initiates a non-blocking connection to a Wi-Fi access point. The connect sequence is:

  1. setup() registers controls and calls startConnect() if enabled and ssid is non-empty.
  2. startConnect() calls wifi_sta_connect(ssid, password) and sets status to "connecting...".
  3. Each loop() tick polls wifi_sta_is_connected(). On success it writes the assigned IP to ip_address. On timeout (10 s) it sets status to "failed".
  4. While enabled, not connecting, and not connected: retries startConnect() every 30 seconds. This covers router reboots and brief signal loss without any external intervention.
  5. onUpdate("ssid") or onUpdate("password") schedules a reconnect on the next loop() tick when credentials change from the UI.

The password control has sensitive: true — its value is never broadcast over WebSocket or returned in GET /api/modules. See Notes on Sensitive Controls.

On PC, startConnect() is a no-op; status is set to "no WiFi".

For how NetworkModule gates STA alongside Ethernet (disabling STA when Ethernet connects, re-enabling when it drops), see Developer Guide: Network — Management policy.

Controls

Key Type Sensitive Default Description
ssid text no "" Network SSID; editable, persisted
password password yes "" Network password; persisted, never broadcast
status display — "no credentials" Live connection status (see table below)
ip_address display — "" Assigned IP after successful connection

Status values

Value Meaning
no credentials ssid is empty
no WiFi platform has no WiFi hardware
connecting... association in progress
connected link up, IP assigned
failed connection attempt timed out
disabled enabled set to false by NetworkModule

Timers

Constant Value Purpose
CONNECT_TIMEOUT_MS 10 000 ms Per-attempt association timeout
RETRY_INTERVAL_MS 30 000 ms How often to retry while disconnected

Parent

WifiStaModule is a child of NetworkModule. Its lifecycle is managed by the ModuleManager parent-child mechanism.

Platform notes

ESP32 (Lolin S3): define WIFI_LOLIN_FIX to reduce TX power to 8.5 dBm — stabilises connection on this board.

PC: no WiFi driver; status is always "no WiFi".

Test coverage

Network and WiFi — lifecycle on PC does not crash; password control is sensitive (absent from getControlValues); SSID present in getControlValues; saveState/loadState round-trip for SSID and enabled.

Source