SoftAP Example

[中文]

Note

This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.

Example Description

SoftAP (Software-enabled Access Point) is a Wi-Fi operating mode of ESP32, allowing the device itself to create a wireless hotspot for other terminals (such as mobile phones, computers) to connect. However, it should be noted that enabling SoftAP mode alone cannot access the external Internet. ESP32 only serves as a hotspot to provide connection services. After the terminal device is connected, it can only obtain an IP address and communicate within the local area network, and cannot access external network resources through this network.

This example demonstrates how to configure the ESP32 device as a Wi-Fi SoftAP mode, creating a wireless hotspot without relying on an external router, for other devices to connect and communicate locally.

Running Method

The complete code of the example can be found at softAP Example. For configuration instructions, build and burn process before running, please refer to the README.md file in the example directory.

For custom configuration items and viewing default values, refer to the Macro Definition Description section.

Header File Description

The header files used in this example cover basic modules such as FreeRTOS task management, Wi-Fi protocol stack, system event mechanism, log output, NVS non-volatile storage, and TCP/IP protocol stack interface. It builds core functions such as task creation, Wi-Fi initialization, event registration and response, log printing, and network communication.

The header files are classified by function as follows:

  1. FreeRTOS Task Scheduling: Provides task management, delay control interface.

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

  1. System Tools: Used for device MAC address acquisition, log printing, and initialization of non-volatile storage.

#include "esp_mac.h"
#include "esp_log.h"
#include "nvs_flash.h"

  1. Wi-Fi and Event Mechanism: Includes Wi-Fi startup and connection configuration, event loop registration and processing functions.

#include "esp_wifi.h"
#include "esp_event.h"

  1. Network Protocol Stack: Includes commonly used error code definitions and underlying system abstraction interfaces in the TCP/IP protocol stack, used to handle the status during the network connection process.

#include "lwip/err.h"
#include "lwip/sys.h"

Macro Definition Description

The macro definitions involved in this example are mainly used to configure the operating parameters of ESP32 SoftAP mode and security-related GTK key rotation.

Macro definitions are classified by function as follows:

  1. Wi-Fi Parameter Configuration: Used to set Wi-Fi SSID, password, channel, and maximum number of connected devices, in order to correctly identify and connect to the specified access point.

  • SSID (Service Set Identifier) is a network name used to identify a wireless local area network, that is, the name of Wi-Fi. In SoftAP mode, the SSID and password broadcast by ESP32 can be customized.

  • The channel parameter is used to specify the Wi-Fi channel number used by ESP32 SoftAP, that is, the sub-channel of the wireless communication frequency band, the default configuration is 1. If the terminal device cannot scan the ESP32 hotspot, it may be due to channel incompatibility, it is recommended to try switching channels.

  • The maximum number of connections is used to limit the number of terminal devices that can connect to the ESP32 SoftAP at the same time, the default value is 4.

  • The parameter macros in the example actually refer to the configuration macros starting with CONFIG_, which are automatically generated by the ESP-IDF build system based on the menuconfig settings and saved in the sdkconfig file.

  1. GTK Key Rotation: Depending on the user’s configuration in menuconfig, conditional compilation is used to select whether to enable GTK key rotation and its rotation cycle setting. It is enabled by default, with a rotation cycle of 600 seconds.

  • GTK (Group Temporal Key) is a key used in the WPA/WPA2 wireless security protocol to encrypt multicast and broadcast data. It is generated and distributed by the Access Point (AP) to all connected devices to ensure the security of broadcast communication in the LAN.

  • Modern WPA2 and WPA3 standards recommend or require regular rotation of GTK to prevent key leakage, replay attacks, and other security risks, thereby improving the overall security level of wireless communication.

  • The macro EXAMPLE_GTK_REKEY_INTERVAL in the example corresponds to the configuration item CONFIG_ESP_GTK_REKEY_INTERVAL, which is used to set the time interval for GTK key rotation.

  • It is recommended to enable GTK key rotation in public or multi-user connection scenarios to enhance security.

  • Set the rotation cycle reasonably. Too short a cycle may lead to frequent key updates and performance overhead, while too long a cycle may reduce the security effect.

Note

  • The above macro definitions will be automatically updated after modifying menuconfig and rebuilding/compiling the example, no need to manually change the code.

  • You can directly edit these macros for quick testing, but configuring through menuconfig is more standard and suitable for the standard development process.

Function Description

This example completes the initialization of ESP32’s SoftAP mode through the wifi_init_softap() function, and monitors and responds to the connection status of terminal devices by registering the callback function wifi_event_handler().

Among them, wifi_init_softap() is responsible for initializing network-related components and Wi-Fi drivers, configuring parameters, and starting Wi-Fi hotspot functions, while wifi_event_handler() is used to listen to Wi-Fi events and output corresponding log information when terminal devices are connected or disconnected, which is convenient for debugging and status monitoring.

The two work together to build the initialization and operation logic under SoftAP mode, completing the entire process of hotspot creation and connection status management.

wifi_event_handler()

This function is an event response function. For a detailed introduction, please refer to Event Callback Function.

In this example, this function is used to handle the following two types of events based on different event_id inputs:

Event Category

event_id Setting

Execution Logic

Successful Connection

WIFI_EVENT_AP_STACONNECTED

A terminal device is connected to ESP32, print its related information.

Disconnection

WIFI_EVENT_AP_STADISCONNECTED

The terminal device is disconnected, print its related information.

The event_data parameter of the event handling function is a general void* pointer, and the actual type depends on the specific event.

In SoftAP mode, the connection or disconnection events of the terminal correspond to the wifi_event_ap_staconnected_t and wifi_event_ap_stadisconnected_t structures, respectively. Before use, specific fields such as the MAC address and AID of the terminal device need to be extracted through forced type conversion.

To facilitate the output of MAC addresses in logs, ESP-IDF provides two auxiliary macros:

  • MACSTA: Defines a formatted string %02x:%02x:%02x:%02x:%02x:%02x for printing the standard MAC address format.

  • MAC2STA(): Expands uint8_t mac[6] into 6 hexadecimal parameters, used in conjunction with MACSTR for convenient output.

wifi_init_softap()

This function is used to initialize Wi-Fi SoftAP mode, complete the creation of network interface and event loop, event callback registration, SoftAP parameter configuration and Wi-Fi startup, and finally wait for the terminal device to connect.

The following are the main implementation steps of the function. Since most of the steps in the process have been detailed in general steps, repeated content will not be repeated here, only the key implementation and differences in this example are highlighted.

  1. Initialization stage

  2. Event callback function:

The events involved in this example are as follows:

event_base

event_id

Event description

WIFI_EVENT

WIFI_EVENT_AP_STACONNECTED

Wi-Fi configuration completed

WIFI_EVENT

WIFI_EVENT_AP_STADISCONNECTED

Wi-Fi connection failed

  1. Configuration stage:

  • The wifi_config_t structure uses the .ap member, that is, the SoftAP mode configuration, and other members are set through macro definitions. For details, refer to Macro definition description :

    Configuration item

    Description

    Configuration in the example

    .ssid

    The SSID of the created Wi-Fi hotspot

    EXAMPLE_ESP_WIFI_SSID

    .ssid_len

    Length of the SSID

    Obtained by calling strlen()

    .channel

    Wi-Fi channel, determining the frequency band of the hotspot

    EXAMPLE_ESP_WIFI_CHANNEL

    .password

    Hotspot connection password

    EXAMPLE_ESP_WIFI_PASS

    .max_connection

    Maximum number of clients allowed to connect

    EXAMPLE_MAX_STA_CONN

    .authmode

    Choose authentication mode, control the security level of the hotspot

    If CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT is enabled, choose WIFI_AUTH_WPA3_PSK, otherwise choose WIFI_AUTH_WPA2_PSK.

    .sae_pwe_h2e

    Set the PWE generation mode of WPA3 SAE to enhance security. Only configured when CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT is enabled.

    WPA3_SAE_PWE_BOTH

    .pmf_cfg.required

    Choose whether to enable Protected Management Frames (PMF)

    true

    .bss_max_idle_cfg.period

    Set the BSS maximum idle time, after which the client may be disconnected. Only effective when CONFIG_ESP_WIFI_BSS_MAX_IDLE_SUPPORT is enabled.

    1

    .bss_max_idle_cfg.protected_keep_alive

    Choose whether to protect the keep-alive frames sent by the client to avoid disconnection. Only effective when CONFIG_ESP_WIFI_BSS_MAX_IDLE_SUPPORT is enabled.

    1

    .gtk_rekey_interval

    Key rotation period

    EXAMPLE_GTK_REKEY_INTERVAL

    • CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT: Enable SAE (Simultaneous Authentication of Equals) mechanism support for WPA3-Personal security protocol in SoftAP mode. SAE provides stronger security than traditional WPA2, suitable for scenarios requiring higher wireless encryption strength. This option is enabled by default.

    • CONFIG_ESP_WIFI_BSS_MAX_IDLE_SUPPORT: Enable support for BSS Max Idle feature, allowing ESP32 SoftAP to notify connected devices of their maximum allowed idle time, thus helping terminals decide whether to maintain connection or disconnect. This mechanism can be used to optimize resource management and reduce system overhead of idle connections. This option is disabled by default.

    Note

    Unexplicitly assigned .sta structure members will be automatically initialized to zero (or the corresponding default value), indicating the use of default behavior or disabling the corresponding feature, so only key fields need to be manually defined.

  • Judge password length, when the password length is 0, set the authentication mode to open (WIFI_AUTH_OPEN), to avoid configuration errors due to empty password.

  • Set Wi-Fi mode to WIFI_MODE_AP, i.e., SoftAP mode.

  1. Startup phase:

  1. Connection phase:

  • In SoftAP mode, the connection phase does not need to explicitly call the API to complete.

  • Specific events generated during the connection phase can be referred to ESP32 Wi-Fi AP General Situation.

Main Function Description

This function serves as the program entry function, used to complete the initialization of non-volatile storage (NVS), and start the Wi-Fi SoftAP mode, providing a basic environment for the device to establish a wireless access point.

The implementation steps within the function are as follows:

  1. Initialize NVS

  2. Print startup information: Use log to output Wi-Fi mode information.

  3. Start Wi-Fi initialization: Call the wifi_init_softap() function to complete network interface configuration, event registration, Wi-Fi parameter setting, and driver startup, making ESP32 a connectable wireless access point.