Chapter 31: WiFi Access Point Mode Configuration

Chapter Objectives

By the end of this chapter, you will be able to:

• Explain the purpose and common use cases of WiFi Access Point (AP) mode on the ESP32.
• Configure the ESP32 to operate as a WiFi AP using ESP-IDF.
• Set essential AP parameters like SSID, password, channel, authentication mode, and maximum connections.
• Understand the role of the DHCP server in AP mode.
• Register and interpret events specific to AP mode (WIFI_EVENT_AP_START, WIFI_EVENT_AP_STACONNECTED, WIFI_EVENT_AP_STADISCONNECTED).
• Create a simple WiFi network hosted by the ESP32 that other devices can connect to.

Introduction

So far in this volume, we’ve focused exclusively on connecting the ESP32 to existing WiFi networks as a station (STA). However, the ESP32 is also capable of creating its own WiFi network, acting as an Access Point (AP). In this mode, other WiFi-enabled devices (like smartphones, laptops, or other ESP32s) can connect to the ESP32.

AP mode is incredibly useful for various scenarios, most notably:

• Device Provisioning: Allowing a user to connect directly to the ESP32 via a temporary network to configure its main WiFi credentials (SSID/password for the home network).
• Local Control Interfaces: Hosting a web server on the ESP32 that users can access directly without needing an external router, useful for configuration or direct device control.
• Simple Local Networks: Creating isolated networks for direct device-to-device communication when an external infrastructure network is unavailable or undesirable.

This chapter covers the fundamentals of configuring and running the ESP32 in AP mode using ESP-IDF. We’ll learn how to set up the network parameters, handle relevant events, and enable other devices to connect.

Theory

What is Access Point (AP) Mode?

In AP mode, the ESP32 reverses its role compared to Station mode. Instead of searching for and joining a network, it advertises its own network and allows other devices (stations) to connect to it.

Key characteristics of AP mode:

• Network Creation: The ESP32 defines and broadcasts a WiFi network with a specific Service Set Identifier (SSID).
• Client Connections: It accepts connection requests from other WiFi stations.
• Local Communication: Connected stations can communicate directly with the ESP32 (and potentially with each other, depending on configuration).
• DHCP Server: Typically, the ESP32 running in AP mode also runs a DHCP (Dynamic Host Configuration Protocol) server to automatically assign IP addresses to connecting clients, simplifying network setup for those clients.

Configuration Steps

Setting up AP mode involves a sequence similar to Station mode but targets the AP interface and uses AP-specific configurations and events.

%%{ init: { 'flowchart': { 'curve': 'basis' } } }%%
graph TD
    %% Node Styles
    classDef primary fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef config fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E; %% For config steps
    classDef event fill:#FEE2E2,stroke:#DC2626,stroke-width:1px,color:#991B1B; %% For event triggers
    classDef success fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46;

    A[<b>Start</b>: Initialize System]:::primary
    B["<code class="code-like">esp_netif_init()</code><br>Initialize TCP/IP Stack"]:::process
    C["<code class="code-like">esp_event_loop_create_default()</code><br>Create Default Event Loop"]:::process
    D["<code class="code-like">esp_netif_create_default_wifi_ap()</code><br>Create AP Netif & Start DHCP Server"]:::process
    E["<code class="code-like">wifi_init_config_default()</code> & <code class="code-like">esp_wifi_init()</code><br>Initialize WiFi Driver"]:::process
    F["Register Event Handlers<br>(e.g., for <code class="code-like">WIFI_EVENT</code>)"]:::config
    G["<code class="code-like">esp_wifi_set_mode(WIFI_MODE_AP)</code><br>Set WiFi Mode to AP"]:::config
    H["Define <code class="code-like">wifi_config_t.ap</code> parameters<br>(SSID, Password, Channel, Auth, etc.)"]:::config
    I["<code class="code-like">esp_wifi_set_config(WIFI_IF_AP, &wifi_config)</code><br>Apply AP Configuration"]:::config
    J["<code class="code-like">esp_wifi_start()</code><br>Start WiFi Driver in AP Mode"]:::process
    K{"<code class="code-like">WIFI_EVENT_AP_START</code><br>Event Received"}:::event
    L["<b>ESP32 AP Active</b><br>Broadcasting SSID, Ready for Clients"]:::success
    M["Handle <code class="code-like">WIFI_EVENT_AP_STACONNECTED</code><br>When a client connects"]:::event
    N["Handle <code class="code-like">WIFI_EVENT_AP_STADISCONNECTED</code><br>When a client disconnects"]:::event

    A --> B;
    B --> C;
    C --> D;
    D --> E;
    E --> F;
    F --> G;
    G --> H;
    H --> I;
    I --> J;
    J --> K;
    K --> L;
    L --> M;
    L --> N;

Initialize TCP/IP Stack and Event Loop:

Just like STA mode, you need the underlying network stack and event system.

• esp_netif_init()
• esp_event_loop_create_default()

Create Default WiFi AP Network Interface:

Instead of esp_netif_create_default_wifi_sta(), you use: esp_netif_t* ap_netif = esp_netif_create_default_wifi_ap();

This function creates the network interface specifically for AP mode and, importantly, initializes and starts the default DHCP server associated with this interface. This means connecting clients will automatically receive IP addresses (typically in the 192.168.4.x range by default).

Initialize WiFi:

Initialize the WiFi driver with default settings.

• wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
• ESP_ERROR_CHECK(esp_wifi_init(&cfg));

Register Event Handlers:

You need to handle events relevant to the AP lifecycle. While you can register a single handler for WIFI_EVENT and IP_EVENT (as IP events might be relevant if the AP also connects as a station in APSTA mode), the key AP-specific events under WIFI_EVENT are:

• WIFI_EVENT_AP_START: Posted when the AP has successfully started after esp_wifi_start(). The AP is now broadcasting its SSID.
• WIFI_EVENT_AP_STACONNECTED: Posted when a station successfully connects to the ESP32 AP. The event data (wifi_event_ap_staconnected_t) contains the MAC address of the connecting station and an “association ID” (aid).
• WIFI_EVENT_AP_STADISCONNECTED: Posted when a station disconnects from the ESP32 AP. The event data (wifi_event_ap_stadisconnected_t) contains the MAC address of the disconnecting station and the aid.
• WIFI_EVENT_AP_PROBEREQRECVED: Posted when the AP receives a probe request frame from a station scanning for networks. Contains the MAC address of the probing station. (Less commonly handled).

You’ll typically register a handler for WIFI_EVENT to catch these AP-specific events.

ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT,
                                                    ESP_EVENT_ANY_ID,
                                                    &wifi_event_handler, // Your handler function
                                                    NULL,
                                                    &instance_any_wifi));

Configure WiFi Mode:

Set the mode explicitly to AP.

ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_AP));

Configure AP Parameters:

This is where you define your network’s properties using the wifi_config_t structure, specifically accessing the .ap member.

wifi_config_t wifi_config = {
    .ap = {
        .ssid = "MyESP32Network",         // Network Name (Max 32 chars)
        .ssid_len = 0,                     // Length of SSID (0 = auto-calculate)
        .password = "password123",         // Password (8-63 chars for WPA2)
        .channel = 1,                      // WiFi Channel (1-13)
        .authmode = WIFI_AUTH_WPA2_PSK,    // Authentication Mode
        .ssid_hidden = 0,                  // Broadcast SSID (0=No, 1=Yes)
        .max_connection = 4,               // Max clients (1-10)
        .beacon_interval = 100,            // Beacon interval (ms, 100-60000)
        // .pairwise_cipher = WIFI_CIPHER_TYPE_CCMP, // Optional: Specific cipher for WPA2/WPA3
        // .pmf_cfg = { .required = false }, // Optional: Protected Management Frames
    },
};

// Special case: For OPEN networks, clear the password and set authmode
if (strlen((char*)wifi_config.ap.password) == 0) {
     wifi_config.ap.authmode = WIFI_AUTH_OPEN;
     memset(wifi_config.ap.password, 0, sizeof(wifi_config.ap.password)); // Ensure password field is zeroed
}

// If ssid_len is 0, ESP-IDF calculates it from the null-terminated string
// If password is set for WPA/WPA2, it must be 8-63 characters.

ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_AP, &wifi_config));

• ssid: The name of the network your ESP32 will broadcast. Must be 1-32 characters.
• ssid_len: Length of the SSID. If 0, the length is determined automatically from the null-terminated string.
• password: The password for your network. For WIFI_AUTH_WPA_PSK, WIFI_AUTH_WPA2_PSK, or WIFI_AUTH_WPA_WPA2_PSK, it must be 8-63 ASCII characters. For WIFI_AUTH_OPEN, this field should be empty (or ignored). For WPA3 (WIFI_AUTH_WPA3_PSK), specific requirements apply.
• channel: The WiFi channel (1-13, check local regulations). Choosing a less congested channel can improve performance.
• authmode: Security type. Common options:
  • WIFI_AUTH_OPEN: No password required (insecure).
  • WIFI_AUTH_WPA_PSK: WPA security.
  • WIFI_AUTH_WPA2_PSK: WPA2 security (recommended for compatibility).
  • WIFI_AUTH_WPA_WPA2_PSK: Allows both WPA and WPA2 clients.
  • WIFI_AUTH_WPA3_PSK: WPA3 security (more secure, less compatible).
  • WIFI_AUTH_WPA2_WPA3_PSK: Allows both WPA2 and WPA3 clients.
• ssid_hidden: If set to 1, the ESP32 won’t broadcast its SSID. Clients need to know the SSID explicitly to connect (minor security obscurity, not strong protection).
• max_connection: The maximum number of stations allowed to connect simultaneously (default is 4, max is usually 10, check CONFIG_ESP_WIFI_SOFTAP_MAX_CONN).
• beacon_interval: How often the AP sends beacon frames (in milliseconds). Default is 100ms.

Start WiFi Driver:

ESP_ERROR_CHECK(esp_wifi_start());

This triggers the WiFi hardware to start operating in AP mode according to the configuration. The WIFI_EVENT_AP_START event should be posted shortly after this.

DHCP Server Operation

When esp_netif_create_default_wifi_ap() is called, it sets up the necessary infrastructure for a DHCP server on the AP’s network interface. By default:

• The DHCP server is enabled.
• The AP itself gets a static IP address, usually 192.168.4.1.
• The DHCP server leases IP addresses to connecting clients from a predefined pool (e.g., 192.168.4.2 to 192.168.4.x).

This means you generally don’t need to manually configure or start the DHCP server for basic AP operation. Clients connecting will automatically obtain an IP address, subnet mask, and gateway address (pointing to the ESP32 AP’s IP).

You can customize the DHCP server settings (IP range, lease time) or the AP’s static IP using the esp_netif API after creating the default AP netif but before starting WiFi, but this is an advanced topic beyond the scope of this introductory chapter.

Practical Examples

Let’s create a simple project where the ESP32 starts an Access Point. We’ll use Kconfig to set the SSID and password.

Prerequisites:

• ESP-IDF v5.x environment with VS Code.
• A new ESP-IDF project or modify an existing one.

Example 1: Basic WPA2-PSK Access Point

1. Create main/Kconfig.projbuild (or add to existing):

menu "Example Access Point Configuration"

    config EXAMPLE_ESP_WIFI_SSID
        string "AP SSID"
        default "ESP32-AP"
        help
            SSID (Network Name) for the ESP32 Access Point. (1-32 chars)

    config EXAMPLE_ESP_WIFI_PASSWORD
        string "AP Password"
        default "esp-password"
        help
            Password for the ESP32 Access Point. (Min 8 chars for WPA2-PSK)

    config EXAMPLE_ESP_WIFI_CHANNEL
        int "AP WiFi Channel"
        range 1 13
        default 1
        help
            WiFi Channel for the AP (1-13).

    config EXAMPLE_MAX_STA_CONN
        int "Max Stations Connected"
        range 1 10
        default 4
        help
            Maximum number of stations that can connect to the AP.

endmenu

2. Configure Project:

• Run idf.py menuconfig.
• Navigate to Example Access Point Configuration.
• Set your desired SSID, Password (ensure >= 8 chars), Channel, and Max Connections.
• Save and Exit.

3. Write main/main.c:

#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_mac.h" // Required for esp_read_mac
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_log.h"
#include "nvs_flash.h"

#include "lwip/err.h" // Required for LWIP errors (although not directly used here)
#include "lwip/sys.h" // Required for LWIP system functions (although not directly used here)
#include "esp_netif.h" // Required for esp_netif functions

/* --- Configuration --- */
// Values will be taken from Kconfig
#define EXAMPLE_ESP_WIFI_SSID      CONFIG_EXAMPLE_ESP_WIFI_SSID
#define EXAMPLE_ESP_WIFI_PASS      CONFIG_EXAMPLE_ESP_WIFI_PASSWORD
#define EXAMPLE_ESP_WIFI_CHANNEL   CONFIG_EXAMPLE_ESP_WIFI_CHANNEL
#define EXAMPLE_MAX_STA_CONN       CONFIG_EXAMPLE_MAX_STA_CONN

/* --- Globals --- */
static const char *TAG = "WIFI_AP";

/* --- Event Handler --- */
static void wifi_event_handler(void* arg, esp_event_base_t event_base,
                                    int32_t event_id, void* event_data)
{
    // Handle WIFI_EVENT specifically
    if (event_base == WIFI_EVENT) {
        switch (event_id) {
            case WIFI_EVENT_AP_STACONNECTED: {
                wifi_event_ap_staconnected_t* event = (wifi_event_ap_staconnected_t*) event_data;
                ESP_LOGI(TAG, "Station "MACSTR" joined, AID=%d",
                         MAC2STR(event->mac), event->aid);
                break;
            }
            case WIFI_EVENT_AP_STADISCONNECTED: {
                wifi_event_ap_stadisconnected_t* event = (wifi_event_ap_stadisconnected_t*) event_data;
                ESP_LOGI(TAG, "Station "MACSTR" left, AID=%d",
                         MAC2STR(event->mac), event->aid);
                break;
            }
            case WIFI_EVENT_AP_START:
                ESP_LOGI(TAG, "Access Point Started. SSID: %s Password: %s Channel: %d",
                         EXAMPLE_ESP_WIFI_SSID, EXAMPLE_ESP_WIFI_PASS, EXAMPLE_ESP_WIFI_CHANNEL);
                // You could potentially start other services here (like a web server)
                break;
            case WIFI_EVENT_AP_STOP:
                ESP_LOGI(TAG, "Access Point Stopped.");
                break;
            // Add cases for other WIFI_EVENTs if needed
            default:
                ESP_LOGD(TAG, "Unhandled WIFI_EVENT: %ld", event_id);
                break;
        }
    }
    // Handle other event bases if necessary (e.g., IP_EVENT if using APSTA mode)
    // else if (event_base == IP_EVENT) { ... }
}

/* --- WiFi Initialization Function --- */
void wifi_init_softap(void)
{
    // 1. Initialize TCP/IP stack
    ESP_ERROR_CHECK(esp_netif_init());

    // 2. Create default event loop
    ESP_ERROR_CHECK(esp_event_loop_create_default());

    // 3. Create default WiFi AP network interface
    // This also initializes the DHCP server for the AP mode
    esp_netif_t* ap_netif = esp_netif_create_default_wifi_ap();
    assert(ap_netif); // Ensure netif creation was successful

    // 4. Initialize WiFi with default configuration
    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    ESP_ERROR_CHECK(esp_wifi_init(&cfg));

    // 5. Register event handlers
    ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT,
                                                        ESP_EVENT_ANY_ID, // Catch all WiFi events
                                                        &wifi_event_handler,
                                                        NULL,
                                                        NULL)); // We don't need the instance handle here

    // 6. Configure WiFi Mode to AP
    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_AP));

    // 7. Configure AP Parameters
    wifi_config_t wifi_config = {
        .ap = {
            // Use Kconfig values
            .ssid = EXAMPLE_ESP_WIFI_SSID,
            .password = EXAMPLE_ESP_WIFI_PASS,
            .channel = EXAMPLE_ESP_WIFI_CHANNEL,
            .max_connection = EXAMPLE_MAX_STA_CONN,
            .authmode = WIFI_AUTH_WPA2_PSK, // Explicitly WPA2-PSK
            .ssid_len = strlen(EXAMPLE_ESP_WIFI_SSID), // Calculate SSID length
            // Optional: PMF settings if needed
            // .pmf_cfg = {
            //         .required = false,
            // },
        },
    };

    // Handle Open Authentication if password is empty in Kconfig
    if (strlen(EXAMPLE_ESP_WIFI_PASS) == 0) {
        wifi_config.ap.authmode = WIFI_AUTH_OPEN;
         // Ensure password field is clear if OPEN - safety measure
        memset(wifi_config.ap.password, 0, sizeof(wifi_config.ap.password));
        ESP_LOGW(TAG, "Password is empty. Setting AP AuthMode to OPEN.");
    }

    // 8. Set WiFi Configuration for AP Interface
    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_AP, &wifi_config));


    // 9. Start WiFi Driver
    ESP_LOGI(TAG, "Starting WiFi AP...");
    ESP_ERROR_CHECK(esp_wifi_start());

    ESP_LOGI(TAG, "wifi_init_softap finished.");

    // Optional: Log the AP's IP address (usually 192.168.4.1 by default)
    esp_netif_ip_info_t ip_info;
    esp_netif_get_ip_info(ap_netif, &ip_info);
    ESP_LOGI(TAG, "AP IP Address: " IPSTR, IP2STR(&ip_info.ip));
}

/* --- Main Application --- */
void app_main(void)
{
    ESP_LOGI(TAG, "Starting ESP32 SoftAP Example...");

    // Initialize NVS - Required for WiFi driver
    esp_err_t ret = nvs_flash_init();
    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
      ESP_ERROR_CHECK(nvs_flash_erase());
      ret = nvs_flash_init();
    }
    ESP_ERROR_CHECK(ret);

    // Initialize WiFi in AP mode
    wifi_init_softap();

    ESP_LOGI(TAG, "ESP32 SoftAP Initialized.");
    // The main task can now do other things or just idle.
    // The WiFi AP runs in the background managed by ESP-IDF tasks.
    while(1) {
        vTaskDelay(pdMS_TO_TICKS(10000));
    }
}

4. Build, Flash, Monitor:

• idf.py build
• idf.py flash
• idf.py monitor

Expected Output:

You should see logs indicating the AP is starting and then confirming it has started, along with its configuration and IP address.

I (XXX) main: Starting ESP32 SoftAP Example...
I (XXX) main: Initializing NVS
I (XXX) WIFI_AP: Starting WiFi AP...
I (XXX) WIFI_AP: wifi_init_softap finished.
I (XXX) WIFI_AP: AP IP Address: 192.168.4.1 // Default AP IP
I (XXX) WIFI_AP: Access Point Started. SSID: ESP32-AP Password: esp-password Channel: 1 // Or your Kconfig values
I (XXX) WIFI_AP: ESP32 SoftAP Initialized.

5. Test Connection:

• Take your smartphone or laptop.
• Scan for WiFi networks. You should see the SSID you configured (e.g., “ESP32-AP”).
• Connect to it using the password you set (e.g., “esp-password”).
• Observe the ESP32’s serial monitor output. You should see a WIFI_EVENT_AP_STACONNECTED log message including the MAC address of your phone/laptop.I (XXX) WIFI_AP: Station xx:xx:xx:xx:xx:xx joined, AID=1 // MAC of connected device
• Disconnect your device. You should see a WIFI_EVENT_AP_STADISCONNECTED log message.I (XXX) WIFI_AP: Station xx:xx:xx:xx:xx:xx left, AID=1
• Your device should have received an IP address from the ESP32’s DHCP server (likely 192.168.4.2 for the first client).

Variant Notes

• ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6: All these variants fully support WiFi AP mode as described in this chapter. The configuration process, APIs (esp_wifi_set_mode, esp_netif_create_default_wifi_ap, wifi_config_t, etc.), and event handling (WIFI_EVENT_AP_*) are consistent across these chips when using ESP-IDF v5.x. Performance characteristics (e.g., maximum throughput, number of clients handled reliably) might vary slightly based on the specific chip’s radio and processing power.
• ESP32-H2: This chapter is not applicable to the ESP32-H2, as it lacks the necessary 802.11 WiFi hardware required to function as an Access Point.

Common Mistakes & Troubleshooting Tips

Exercises

1. Open Network: Modify the Kconfig and main.c code to create an open Access Point (no password required). Ensure you set the authmode correctly to WIFI_AUTH_OPEN and leave the password empty in Kconfig. Test connecting from a device without needing a password.
2. Hidden SSID: Configure the AP to have a hidden SSID by setting wifi_config.ap.ssid_hidden = 1;. Verify that the network name doesn’t appear in standard WiFi scans on your phone/laptop, but you can still connect if you manually add the network with the correct SSID and password.
3. Change AP IP Address: After esp_netif_create_default_wifi_ap() but before esp_wifi_start(), use esp_netif_dhcps_stop() to stop the default DHCP server, then use esp_netif_set_ip_info() to assign a different static IP address to the AP interface (e.g., 10.0.0.1). Finally, use esp_netif_dhcps_start() to restart the DHCP server (it should adapt to the new IP range). Verify the AP starts with the new IP and clients receive IPs in the corresponding range (e.g., 10.0.0.x). (Requires including "esp_netif_defaults.h" for DHCP functions).
4. Limit Connections: Configure the AP using max_connection in wifi_config.ap to allow only one client (max_connection = 1). Try connecting a second device and observe that it fails to connect while the first one is active. Check the ESP32 logs for any relevant messages.

Summary

• ESP32 can create its own WiFi network using Access Point (AP) mode.
• AP mode is configured using esp_wifi_set_mode(WIFI_MODE_AP) and setting parameters in wifi_config.ap.
• Key AP parameters include SSID, password, channel, authentication mode (authmode), and maximum connections (max_connection).
• esp_netif_create_default_wifi_ap() creates the AP network interface and starts a DHCP server by default, typically assigning 192.168.4.1 to the ESP32 and leasing IPs like 192.168.4.x to clients.
• Relevant events for AP mode are WIFI_EVENT_AP_START, WIFI_EVENT_AP_STACONNECTED, and WIFI_EVENT_AP_STADISCONNECTED.
• AP mode is commonly used for device provisioning and creating local control networks.

Further Reading

• ESP-IDF Programming Guide – WiFi SoftAP: https://docs.espressif.com/projects/esp-idf/en/v5.4/esp32/api-reference/network/esp_wifi.html#wi-fi-softap-mode
• ESP-IDF Programming Guide – esp_netif: https://docs.espressif.com/projects/esp-idf/en/v5.4/esp32/api-reference/network/esp_netif.html (For details on network interfaces and DHCP server control)
• ESP-IDF WiFi SoftAP Example: https://github.com/espressif/esp-idf/tree/v5.4/examples/wifi/getting_started/softAP
• ESP-IDF Header File – esp_wifi_types.h: (Located in components/esp_wifi/include/esp_wifi_types.h) – Contains definitions for wifi_config_t, wifi_auth_mode_t, AP event structures, etc.