Skip to content

WifiStaModule

WiFi station (client) mode connection. Connects the ESP32 to an existing Wi-Fi network. Introduced in Sprint 8.

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().
  2. startConnect() calls WiFi.begin(ssid, password) and sets status to "connecting...".
  3. Each loop() tick polls WiFi.status(). On success it writes the assigned IP to ip_address. On timeout (10 s) it sets status to "failed".
  4. onUpdate("ssid") or onUpdate("password") restarts the connect cycle 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 "PC (no WiFi)".

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
ip_address display — "" Assigned IP after successful connection

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 disconnect before reconnecting and reduce TX power to 8.5 dBm — stabilises connection on this board.

PC: no WiFi driver; status is always "PC (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