Skip to content

API Reference

Jump to bottom
Arunkumar Mourougappane edited this page Oct 25, 2025 · 1 revision

API Reference

Complete programming interface documentation for ESP32 WiFi Utility v4.2.0.

Table of Contents

WiFi Manager

Core WiFi functionality for network management.

Initialization

void initializeWiFi();

Initializes WiFi subsystem and loads configuration from NVS.

Returns: void

Example:

void setup() {
    Serial.begin(115200);
    initializeWiFi();
}

Mode Management

void startStationMode();

Switches ESP32 to Station (client) mode.

Parameters: None Returns: void

void startAccessPoint();

Starts Access Point with settings from NVS configuration.

Parameters: None Returns: void

void startAccessPoint(const String& ssid, const String& password);

Starts Access Point with custom credentials.

Parameters:

  • ssid - Network name (1-32 characters)
  • password - Network password (8-63 characters, or empty for open)

Returns: void

Example:

startAccessPoint("ESP32-Hotspot", "password123");
void stopWiFi();

Completely disables WiFi radio.

Parameters: None Returns: void

void setIdleMode();

Sets WiFi to idle state (radio on, not connected).

Parameters: None Returns: void

Network Connection

void connectToNetwork(String ssid, String password);

Connects to WiFi network in Station mode.

Parameters:

  • ssid - Target network name
  • password - Network password (empty for open networks)

Returns: void

Example:

connectToNetwork("HomeWiFi", "mypassword");
void disconnectFromNetwork();

Disconnects from current WiFi network.

Parameters: None Returns: void

Scanning

void performWiFiScan();

Scans for available WiFi networks and displays results.

Parameters: None Returns: void

Output: Displays scan results to Serial

void showNetworkDetails(int networkId);

Shows detailed information about a specific scanned network.

Parameters:

  • networkId - Network index from scan results (1-based)

Returns: void

Example:

performWiFiScan();
showNetworkDetails(1);  // Show details for first network

QR Code Generation

void generateAPQRCode(const String& ssid, const String& password,
                      const String& security = "WPA");

Generates QR code for AP connection (displayed on Serial).

Parameters:

  • ssid - Access Point SSID
  • password - Access Point password
  • security - Security type: "WPA", "WEP", or "nopass" (default: "WPA")

Returns: void

Example:

generateAPQRCode("ESP32-AP", "password123", "WPA");

Global State Variables

extern WiFiMode currentMode;        // Current WiFi mode
extern bool scanningEnabled;        // Continuous scanning state
extern unsigned long lastScan;      // Last scan timestamp
extern String currentAPSSID;        // Current AP SSID
extern String currentAPPassword;    // Current AP password
extern uint8_t currentAPChannel;    // Current AP channel

Web Server

HTTP server for web-based configuration interface.

Initialization & Control

void initializeWebServer();

Initializes web server subsystem.

Parameters: None Returns: void

bool startWebServer();

Starts web server on port 80.

Parameters: None Returns: true if started successfully, false otherwise

Example:

if (startWebServer()) {
    Serial.println("Web server running");
    Serial.println(getWebServerURL());
}
void stopWebServer();

Stops web server and frees resources.

Parameters: None Returns: void

void handleWebServerRequests();

Processes incoming HTTP requests. Call in loop().

Parameters: None Returns: void

Example:

void loop() {
    if (webServerEnabled) {
        handleWebServerRequests();
    }
}
void monitorWebServerState();

Auto-restarts web server based on WiFi state.

Parameters: None Returns: void

Status Functions

bool isWebServerRunning();

Checks if web server is active.

Parameters: None Returns: true if running, false otherwise

String getWebServerURL();

Gets full URL of web interface.

Parameters: None Returns: URL string (e.g., "http://192.168.1.100")

Example:

if (isWebServerRunning()) {
    Serial.println("Access web interface at: " + getWebServerURL());
}

Global Variables

extern WebServer* webServer;        // Web server instance
extern bool webServerEnabled;       // Web server state

Configuration System

NVS-based configuration persistence.

AP Configuration

void initializeAPConfig();

Initializes AP configuration from NVS.

Parameters: None Returns: void

bool loadAPConfig();

Loads AP configuration from NVS.

Parameters: None Returns: true if config loaded, false if using defaults

bool saveAPConfig(const String& ssid, const String& password,
                  uint8_t channel);

Saves AP configuration to NVS.

Parameters:

  • ssid - Access Point SSID (1-32 chars)
  • password - Password (8-63 chars, or empty for open)
  • channel - WiFi channel (1-13)

Returns: true on success, false on failure

Example:

if (saveAPConfig("MyESP32", "securepass", 6)) {
    Serial.println("AP config saved");
}
void clearAPConfig();

Clears AP configuration from NVS (resets to defaults).

Parameters: None Returns: void

void printAPConfig();

Displays current AP configuration to Serial.

Parameters: None Returns: void

Station Configuration

void initializeStationConfig();

Initializes Station configuration from NVS.

Parameters: None Returns: void

bool loadStationConfig();

Loads Station configuration from NVS.

Parameters: None Returns: true if config exists, false otherwise

bool saveStationConfig(const String& ssid, const String& password);

Saves Station credentials to NVS with base64 encoding.

Parameters:

  • ssid - Network SSID
  • password - Network password

Returns: true on success, false on failure

Example:

saveStationConfig("HomeWiFi", "mypassword");
// Password automatically base64 encoded
void clearStationConfig();

Clears Station configuration from NVS.

Parameters: None Returns: void

void printStationConfig();

Displays current Station configuration (password masked).

Parameters: None Returns: void

bool hasStationConfig();

Checks if Station configuration exists.

Parameters: None Returns: true if configured, false otherwise

Example:

if (hasStationConfig()) {
    Serial.println("Auto-connecting to saved network...");
    // Station config loaded automatically during init
}

Channel Analysis

WiFi spectrum analysis and channel recommendation.

Channel Scanning

void performChannelScan();

Performs quick channel scan (congestion only).

Parameters: None Returns: void

Output: Displays channel congestion to Serial

void performDetailedChannelScan();

Performs comprehensive channel analysis with recommendations.

Parameters: None Returns: void

Output: Displays detailed analysis and AI recommendations

Example:

performDetailedChannelScan();
// Shows:
// - Per-channel network count
// - Signal strengths
// - Congestion levels
// - Interference analysis
// - Best channel recommendations
void recommendBestChannel();

Analyzes channels and recommends optimal choice.

Parameters: None Returns: void

Output: Prints recommendations to Serial

Latency Testing

Network latency measurement and quality assessment.

Test Functions

void performLatencyTest(const String& host);

Performs TCP latency test to specified host.

Parameters:

  • host - Target hostname or IP address

Returns: void

Output: Displays test results including min/avg/max latency, jitter, packet loss

Example:

performLatencyTest("google.com");
performLatencyTest("192.168.1.1");
void startContinuousLatencyMonitoring(const String& host);

Starts continuous latency monitoring.

Parameters:

  • host - Target hostname or IP

Returns: void

Usage: Tests every 10 seconds, press any key to stop

void generateLatencyReport();

Generates summary report of recent latency tests.

Parameters: None Returns: void

Output: Historical statistics and trends

iPerf Integration

Network throughput testing using iPerf3 protocol.

Server Mode

void startIperfServer(uint16_t port = 5201);

Starts iPerf server on specified port.

Parameters:

  • port - Listen port (default: 5201)

Returns: void

Example:

startIperfServer(5201);
// Listen for incoming iPerf tests
// Clients connect: iperf3 -c <esp32-ip> -t 30

Client Mode

void startIperfClient(const String& server, uint16_t port = 5201,
                      uint8_t duration = 30);

Starts iPerf client test to server.

Parameters:

  • server - Server hostname or IP
  • port - Server port (default: 5201)
  • duration - Test duration in seconds (default: 30)

Returns: void

Example:

startIperfClient("192.168.1.100", 5201, 30);
// Run 30-second throughput test

Control Functions

void stopIperf();

Stops current iPerf test.

Parameters: None Returns: void

void getIperfStatus();

Displays current iPerf test status.

Parameters: None Returns: void

Output: Test state, elapsed time, current throughput

Performance Monitoring

System performance measurement and statistics.

Monitoring Functions

void startPerformanceMonitor(const String& operation);

Begins timing an operation.

Parameters:

  • operation - Operation name for identification

Returns: void

Example:

startPerformanceMonitor("NetworkScan");
performWiFiScan();
stopPerformanceMonitor("NetworkScan");
void stopPerformanceMonitor(const String& operation);

Ends timing and records statistics.

Parameters:

  • operation - Operation name (must match start)

Returns: void

void printAllPerformanceStats();

Displays statistics for all monitored operations.

Parameters: None Returns: void

Output: Min/avg/max times, call counts

void resetPerformanceStats();

Clears all performance statistics.

Parameters: None Returns: void

Memory Monitoring

void logMemoryStats(const String& tag);

Logs current memory usage.

Parameters:

  • tag - Log tag for identification

Returns: void

Output: Free heap, largest block, fragmentation

Example:

logMemoryStats("STARTUP");
// Later...
logMemoryStats("AFTER_SCAN");

Error Handling

Structured error handling with Result type.

Result Type

template<typename T>
class Result {
public:
    Result();                                      // Success
    Result(const T& value);                       // Success with value
    Result(ErrorCode code, const char* message);  // Error

    bool isSuccess() const;
    bool isError() const;
    operator bool() const;  // Implicit success check

    const T& getValue() const;
    ErrorCode getErrorCode() const;
    const char* getMessage() const;
};

Usage:

Result<int> getValue() {
    if (error) {
        return {ErrorCode::INVALID_PARAMETER, "Parameter out of range"};
    }
    return 42;  // Success
}

auto result = getValue();
if (result) {
    int value = result.getValue();
} else {
    Serial.println(result.getMessage());
}

Error Codes

enum class ErrorCode {
    SUCCESS = 0,
    WIFI_NOT_INITIALIZED,
    WIFI_CONNECT_FAILED,
    WIFI_INVALID_SSID,
    CONFIG_SAVE_FAILED,
    CONFIG_LOAD_FAILED,
    INVALID_PARAMETER,
    NETWORK_TIMEOUT,
    // ... more codes
};

Macros

RETURN_IF_ERROR(expr)

Propagates error if expression fails.

Example:

Result<void> doMultipleSteps() {
    RETURN_IF_ERROR(step1());
    RETURN_IF_ERROR(step2());
    return {};  // All succeeded
}

Logging System

Configurable logging with multiple levels.

Log Levels

enum class LogLevel {
    TRACE,    // Most verbose
    DEBUG,
    INFO,
    WARN,
    ERROR,
    FATAL,    // Least verbose
    NONE      // Disable logging
};

Configuration

void setLogLevel(LogLevel level);

Sets global log level.

Parameters:

  • level - Minimum level to display

Example:

setLogLevel(LogLevel::DEBUG);  // Show DEBUG and above
void setLogTimestamps(bool enabled);

Enables/disables timestamps in logs.

Parameters:

  • enabled - true to show timestamps

Example:

setLogTimestamps(true);

Logging Macros

LOG_TRACE(tag, format, ...)
LOG_DEBUG(tag, format, ...)
LOG_INFO(tag, format, ...)
LOG_WARN(tag, format, ...)
LOG_ERROR(tag, format, ...)
LOG_FATAL(tag, format, ...)

Parameters:

  • tag - Log tag (usually module name)
  • format - Printf-style format string
  • ... - Format arguments

Example:

LOG_INFO(TAG_WIFI, "Connecting to %s", ssid);
LOG_ERROR(TAG_CONFIG, "Save failed: %d", errorCode);
LOG_DEBUG(TAG_PERF, "Scan took %lu ms", duration);

Common Tags

#define TAG_WIFI "WiFi"
#define TAG_WEB "Web"
#define TAG_CONFIG "Config"
#define TAG_CHANNEL "Channel"
#define TAG_LATENCY "Latency"
#define TAG_IPERF "iPerf"
#define TAG_PERF "Performance"
#define TAG_SYSTEM "System"

LED Controller

NeoPixel RGB LED control for status indication.

Initialization

void initializeLED();

Initializes LED subsystem.

Parameters: None Returns: void

Color Control

void setLEDColor(uint8_t r, uint8_t g, uint8_t b);

Sets LED to specific RGB color.

Parameters:

  • r - Red intensity (0-255)
  • g - Green intensity (0-255)
  • b - Blue intensity (0-255)

Returns: void

Example:

setLEDColor(255, 0, 0);    // Red
setLEDColor(0, 255, 0);    // Green
setLEDColor(0, 0, 255);    // Blue
setLEDColor(255, 255, 0);  // Yellow
void setLEDOff();

Turns LED off.

Parameters: None Returns: void

Status Patterns

void updateLEDStatus();

Updates LED based on system state. Call in loop().

Parameters: None Returns: void

Behavior:

  • Idle: Cyan
  • Station Connecting: Blinking Yellow
  • Station Connected: Green
  • AP Mode: Blue
  • Error: Red

Example:

void loop() {
    updateLEDStatus();
    // ... other loop code
}

Complete Example

#include <Arduino.h>
#include "wifi_manager.h"
#include "web_server.h"
#include "config.h"
#include "logging.h"
#include "led_controller.h"

void setup() {
    Serial.begin(115200);

    // Configure logging
    setLogLevel(LogLevel::INFO);
    setLogTimestamps(true);

    // Initialize subsystems
    initializeLED();
    initializeWiFi();
    initializeWebServer();

    // Load and apply configuration
    if (hasStationConfig()) {
        LOG_INFO(TAG_MAIN, "Using saved Station config");
        startStationMode();
    } else {
        LOG_INFO(TAG_MAIN, "Starting AP mode");
        startAccessPoint();
    }

    // Start web server
    if (startWebServer()) {
        LOG_INFO(TAG_MAIN, "Web interface: %s", getWebServerURL().c_str());
    }
}

void loop() {
    // Handle web requests
    if (webServerEnabled) {
        handleWebServerRequests();
    }

    // Update LED status
    updateLEDStatus();

    // Periodic tasks
    static unsigned long lastStats = 0;
    if (millis() - lastStats > 60000) {  // Every minute
        logMemoryStats(TAG_SYSTEM);
        printAllPerformanceStats();
        lastStats = millis();
    }
}

← Back to Home | Next: Development Guide →

### 🔗 External Links

GitHub Repository • Report Issues • Discussions

ESP32 WiFi Utility v4.2.0 • MIT License • © Arunkumar Mourougappane

📡 ESP32 WiFi Utility

🏠 Main

📦 Setup

⚙️ Configuration

📊 Features

💻 Development

🆘 Support

🔗 Links

Version: 4.2.0
License: MIT

Clone this wiki locally