WiFi Connection Management

Kinematrix provides three WiFi connection handlers with increasing levels of functionality, from basic connectivity to full web-based configuration portals.

Module Overview

WiFiModule

Basic WiFi connectivity with auto-reconnection and static IP support

WiFiHandlerV2

Advanced handler with AP mode, scanning, and power management

WiFiManager

Web-based configuration portal with async server and mDNS

WiFiModule (Basic)

Features

Basic WiFi connection management
Auto-reconnection with configurable intervals
Static IP configuration
Connection status tracking
Event callbacks

Enable Module

#define ENABLE_MODULE_WIFI_MODULE
#include "Kinematrix.h"

Basic Usage

WiFiModule wifi;

void onWiFiEvent(wifi_module_status_t status) {
  Serial.print("WiFi Status: ");
  Serial.println(wifi.getStatusString());
}

void setup() {
  Serial.begin(115200);
  
  wifi.begin();
  wifi.setAutoReconnect(true);
  wifi.setReconnectInterval(30000); // 30 seconds
  wifi.onEvent(onWiFiEvent);
  
  if (wifi.connect("MySSID", "MyPassword")) {
    Serial.println("Connected!");
    Serial.println(wifi.getIP());
  }
}

void loop() {
  // Check connection periodically
  if (!wifi.checkConnection()) {
    Serial.println("Connection lost");
  }
}

Static IP Configuration

IPAddress staticIP(192, 168, 1, 100);
IPAddress gateway(192, 168, 1, 1);
IPAddress subnet(255, 255, 255, 0);
IPAddress dns1(8, 8, 8, 8);
IPAddress dns2(8, 8, 4, 4);

wifi.setStaticIP(staticIP, gateway, subnet, dns1, dns2);
wifi.useStaticIP(true);
wifi.connect("MySSID", "MyPassword");

Status Types

typedef enum {
    WIFI_MODULE_IDLE,              // Not started
    WIFI_MODULE_CONNECTING,        // Connection in progress
    WIFI_MODULE_CONNECTED,         // Successfully connected
    WIFI_MODULE_DISCONNECTED,      // Manually disconnected
    WIFI_MODULE_CONNECTION_LOST,   // Connection lost
    WIFI_MODULE_CONNECTION_FAILED  // Connection failed
} wifi_module_status_t;

API Reference

begin

bool()

Initialize WiFi in station mode

connect

bool(ssid, password)

Connect to WiFi network with default timeout

connectWithTimeout

bool(ssid, password, timeout)

Connect with custom timeout in milliseconds

checkConnection

bool()

Check connection status and auto-reconnect if enabled

reconnect

bool()

Attempt to reconnect to saved network

disconnect

void()

Disconnect from WiFi network

getStatus

wifi_module_status_t()

Get current connection status enum

getStatusString

const char*()

Get human-readable status string

getIP

IPAddress()

Get assigned IP address

getSSID

String()

Get connected network SSID

getRSSI

int32_t()

Get signal strength in dBm

WiFiHandlerV2 (Advanced)

Features

All WiFiModule features plus:
Access Point (AP) mode
Dual mode (STA + AP simultaneously)
Network scanning
Signal quality calculation
Power save mode
Connection watchdog
Custom hostname

Enable Module

#define ENABLE_MODULE_WIFI_HANDLER_V2
#include "Kinematrix.h"

Basic Connection

WiFiHandlerV2 wifi;

void onConnect() {
  Serial.println("WiFi Connected!");
  Serial.println(wifi.getIP());
}

void onDisconnect() {
  Serial.println("WiFi Disconnected!");
}

void setup() {
  Serial.begin(115200);
  
  wifi.setOnConnectCallback(onConnect);
  wifi.setOnDisconnectCallback(onDisconnect);
  
  if (wifi.connect("MySSID", "MyPassword", 30000)) {
    Serial.print("Signal Quality: ");
    Serial.print(wifi.getSignalQuality());
    Serial.println("%");
  }
}

void loop() {
  wifi.loop(); // Handle watchdog
}

Access Point Mode

// Start AP mode
wifi.startAP("ESP32-Config", "password123", 1, false);

Serial.print("AP IP: ");
Serial.println(wifi.getAPIP());

// Client can connect to ESP32-Config network
// Default AP IP: 192.168.4.1

Dual Mode (STA + AP)

// Connect to WiFi AND provide AP simultaneously
wifi.startDualMode(
  "HomeNetwork", "wifi_password",  // Station credentials
  "ESP32-Setup", "setup_password"  // AP credentials
);

if (wifi.isConnected()) {
  Serial.print("Internet IP: ");
  Serial.println(wifi.getIP());
}

if (wifi.isAPActive()) {
  Serial.print("Setup IP: ");
  Serial.println(wifi.getAPIP());
}

Network Scanning

int numNetworks = wifi.scanNetworks();

Serial.println("Available Networks:");
for (int i = 0; i < numNetworks; i++) {
  Serial.print(wifi.getScannedSSID(i));
  Serial.print(" (");
  Serial.print(wifi.getScannedRSSI(i));
  Serial.print(" dBm, ");
  Serial.print(wifi.getScannedEncryption(i));
  Serial.println(")");
}

Connection Watchdog

// Enable watchdog to check connection every 30 seconds
wifi.enableWatchdog(30000);

void loop() {
  wifi.loop(); // Watchdog runs automatically
  
  // Your code here
}

Power Management

// Enable WiFi sleep mode to save power
wifi.enablePowerSave();

// Disable for maximum performance
wifi.disablePowerSave();

API Reference

connect

bool(ssid, password, timeout)

Connect to WiFi with timeout (default 30s)

startAP

bool(ssid, password, channel, hidden)

Start Access Point mode. Password must be 8+ characters or NULL for open network

startDualMode

bool(staSSID, staPassword, apSSID, apPassword)

Enable station and AP mode simultaneously

stopAP

bool()

Stop Access Point mode

isConnected

bool()

Check if connected to WiFi as station

isAPActive

bool()

Check if Access Point is active

getSignalStrength

int()

Get RSSI in dBm (-100 to 0)

getSignalQuality

int()

Get signal quality as percentage (0-100%)

getAPIP

IPAddress()

Get Access Point IP address

getMacAddress

String()

Get device MAC address

setStaticIP

bool(ip, gateway, subnet, dns1)

Configure static IP address

setDHCP

bool()

Switch back to DHCP (requires reconnection)

setHostname

bool(hostname)

Set device hostname for network identification

scanNetworks

int()

Scan for available WiFi networks, returns count

enableWatchdog

void(interval)

Enable connection monitoring with interval in milliseconds

disableWatchdog

void()

Disable connection watchdog

loop

void()

Must be called regularly to handle watchdog

WiFiManager (Web Configuration)

Features

Web-based WiFi configuration portal
Async web server with non-blocking operation
Automatic AP mode on connection failure
Network scanning and selection
Static IP configuration via web UI
Persistent configuration storage (LittleFS)
mDNS for easy access (http://esp32.local)
Custom timeout and retry settings
Signal quality filtering

Enable Module

#define ENABLE_MODULE_WIFI_MANAGER
#include "Kinematrix.h"

Basic Usage

WiFiManager wm;

void onConnected() {
  Serial.println("Connected to WiFi!");
  Serial.println(wm.getIP());
}

void onConfigMode() {
  Serial.println("Entering config mode");
  Serial.println("Connect to: ESP-Config");
  Serial.println("Open: http://192.168.4.1");
}

void setup() {
  Serial.begin(115200);
  
  wm.onConnected(onConnected);
  wm.onConfigMode(onConfigMode);
  
  // Set custom AP name
  wm.setAPCredentials("MyDevice-Setup", "password123");
  
  // Set timeouts
  wm.setTimeout(30000);        // 30s connection timeout
  wm.setConfigTimeout(300000); // 5min config portal timeout
  
  // Enable mDNS
  wm.enableMDNS(true);
  wm.setMDNSName("mydevice");
  
  wm.begin();
  wm.autoConnect(); // Try to connect or start config portal
}

void loop() {
  wm.loop(); // Handle web server and reconnection
}

Manual Configuration Portal

void setup() {
  Serial.begin(115200);
  
  wm.begin();
  
  // Start config portal on button press
  pinMode(BUTTON_PIN, INPUT_PULLUP);
  if (digitalRead(BUTTON_PIN) == LOW) {
    wm.startConfig();
  } else {
    wm.autoConnect();
  }
}

Custom Settings

// Minimum signal quality (0-100%)
wm.setMinSignalQuality(25); // Only show networks > 25%

// Reconnection interval
wm.setReconnectInterval(60000); // Try every 60 seconds

// Retry delay after failed connection
wm.setRetryDelay(5000); // Wait 5 seconds before retry

// Enable auto-reconnect
wm.enableAutoReconnect(true);

Configuration Portal Features

When in config mode, users can:

Scan Networks: View all available WiFi networks with signal strength
Select Network: Click to auto-fill SSID
Enter Credentials: Provide WiFi password
Static IP: Optionally configure static IP settings
Connect: Save and connect to network
Reset: Clear saved credentials

mDNS Access

wm.enableMDNS(true);
wm.setMDNSName("sensor");

// Device accessible at:
// http://sensor.local (instead of IP address)

Reset Configuration

// Reset WiFi credentials only
wm.reset();

// Reset all settings including IP configuration
wm.resetAll();

// Restart device
wm.restart();

State Management

WiFiManagerState state = wm.getState();

switch(state) {
  case WM_IDLE:
    Serial.println("Idle");
    break;
  case WM_CONNECTING:
    Serial.println("Connecting...");
    break;
  case WM_CONNECTED:
    Serial.println("Connected");
    break;
  case WM_CONFIG_MODE:
    Serial.println("Config Mode");
    break;
  case WM_RETRY:
    Serial.println("Retrying...");
    break;
}

Time Queries

// Get various timeout values
unsigned long connTimeout = wm.getConnectionTimeoutMs();
unsigned long configTimeout = wm.getConfigTimeoutMs();
unsigned long retryDelay = wm.getRetryDelayMs();
unsigned long reconnectInterval = wm.getReconnectIntervalMs();

// Get remaining time in current state
unsigned long remaining = wm.getRemainingTimeoutMs();

API Reference

begin

bool()

Initialize WiFiManager and load saved configuration

autoConnect

bool()

Try to connect with saved credentials, start config portal if failed

startConfig

void()

Manually start configuration portal

stopConfig

void()

Stop configuration portal

loop

void()

Must be called regularly to handle web server and state machine

isConnected

bool()

Check if connected to WiFi

isConfigMode

bool()

Check if in configuration mode

getState

WiFiManagerState()

Get current state

setAPCredentials

void(apSsid, apPass)

Set Access Point SSID and password for config portal

setTimeout

void(timeout)

Set connection timeout in milliseconds

setConfigTimeout

void(timeout)

Set config portal timeout in milliseconds

setRetryDelay

void(delay)

Set delay between connection retry attempts

setReconnectInterval

void(interval)

Set interval for reconnection checks

setMinSignalQuality

void(quality)

Set minimum signal quality (0-100) for network list

enableMDNS

void(enable)

Enable/disable mDNS

setMDNSName

void(name)

Set mDNS hostname (accessible at http://name.local)

reset

void()

Clear saved WiFi credentials

resetAll

void()

Clear all saved settings including IP configuration

Comparison

Feature	WiFiModule	WiFiHandlerV2	WiFiManager
Basic Connection	✅	✅	✅
Auto-Reconnect	✅	✅	✅
Static IP	✅	✅	✅
Event Callbacks	✅	✅	✅
AP Mode	❌	✅	✅
Dual Mode	❌	✅	❌
Scanning	❌	✅	✅
Power Management	❌	✅	❌
Web Config Portal	❌	❌	✅
mDNS	❌	❌	✅
Persistent Storage	❌	❌	✅
Complexity	Low	Medium	High
Memory Usage	Low	Medium	High

Best Practices

Never hardcode credentials in production code. Use WiFiManager or environment variables.

Always call loop() regularly for WiFiHandlerV2 and WiFiManager to maintain connections and handle web requests.

Signal Quality Interpretation:

90-100%: Excellent
70-90%: Good
50-70%: Fair
30-50%: Weak
0-30%: Very weak

Troubleshooting

Connection Issues

if (!wifi.connect("SSID", "password", 30000)) {
  Serial.print("Failed to connect: ");
  Serial.println(wifi.getStatusString());
  
  // Check signal strength
  int rssi = wifi.getRSSI();
  if (rssi < -80) {
    Serial.println("Signal too weak");
  }
}

WiFiManager Not Starting

void setup() {
  // Ensure LittleFS is mounted for config storage
  if (!LittleFS.begin()) {
    Serial.println("LittleFS Mount Failed");
    // Format if needed
    LittleFS.format();
    LittleFS.begin();
  }
  
  wm.begin();
  wm.autoConnect();
}

Memory Issues (ESP8266)

// Reduce buffer sizes for ESP8266
#ifdef ESP8266
  // WiFiManager automatically adjusts buffer sizes
  // But you can limit network scan results
  wm.setMinSignalQuality(40); // Higher threshold
#endif

Getting Started

Core Concepts

Sensor Framework

Communication

Control Algorithms

WiFi & Cloud Services

AutoLight System

Guides

​Module Overview

WiFiModule

WiFiHandlerV2

WiFiManager

​WiFiModule (Basic)

​Features

​Enable Module

​Basic Usage

​Static IP Configuration

​Status Types

​API Reference

​WiFiHandlerV2 (Advanced)

​Features

​Enable Module

​Basic Connection

​Access Point Mode

​Dual Mode (STA + AP)

​Network Scanning

​Connection Watchdog

​Power Management

​API Reference

​WiFiManager (Web Configuration)

​Features

​Enable Module

​Basic Usage

​Manual Configuration Portal

​Custom Settings

​Configuration Portal Features

​mDNS Access

​Reset Configuration

​State Management

​Time Queries

​API Reference

​Comparison

​Best Practices

​Troubleshooting

​Connection Issues

​WiFiManager Not Starting

​Memory Issues (ESP8266)

​Next Steps

Firebase Integration

MQTT Communication

Build docs developers (and LLMs) love

Module Overview

WiFiModule (Basic)

Features

Enable Module

Basic Usage

Static IP Configuration

Status Types

API Reference

WiFiHandlerV2 (Advanced)

Features

Enable Module

Basic Connection

Access Point Mode

Dual Mode (STA + AP)

Network Scanning

Connection Watchdog

Power Management

API Reference

WiFiManager (Web Configuration)

Features

Enable Module

Basic Usage

Manual Configuration Portal

Custom Settings

Configuration Portal Features

mDNS Access

Reset Configuration

State Management

Time Queries

API Reference

Comparison

Best Practices

Troubleshooting

Connection Issues

WiFiManager Not Starting

Memory Issues (ESP8266)

Next Steps