Event Handling
Several ESP-IDF components use events to inform application about state changes,
such as connection or disconnection. This document gives an overview of these
event mechanisms.
Wi-Fi, Ethernet, and IP Events
Before the introduction of esp_event library, events from Wi-Fi driver, Ethernet
driver, and TCP/IP stack were dispatched using the so-called legacy event loop.
The following sections explain each of the methods.
esp_event Library Event Loop
esp_event library is designed to supersede the legacy event loop for the
purposes of event handling in ESP-IDF. In the legacy event loop, all possible
event types and event data structures had to be defined in system_event_id_t
enumeration and system_event_info_t union, which made it impossible to send
custom events to the event loop, and use the event loop for other kinds of
events (e.g. Mesh). Legacy event loop also supported only one event handler
function, therefore application components could not handle some of Wi-Fi or IP
events themselves, and required application to forward these events from its
event handler function.
See esp_event library API reference for general information on using this
library. Wi-Fi, Ethernet, and IP events are sent to the default event loop
provided by this library.
Legacy Event Loop
This event loop implementation is started using esp_event_loop_init() function.
Application typically supplies an event handler, a function with the following
signature:
/*F********************************************************************
*
**********************************************************************/
esp_err_t event_handler( void *ctx, system_event_t *event)
{
}
Both the pointer to event handler function, and an arbitrary context pointer are
passed to esp_event_loop_init().
When Wi-Fi, Ethernet, or IP stack generate an event, this event is sent to a
high-priority event task via a queue. Application-provided event handler
function is called in the context of this task. Event task stack size and event
queue size can be adjusted using CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE and
CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE options, respectively.
Event handler receives a pointer to the event structure (system_event_t) which
describes current event. This structure follows a tagged union pattern: event_id
member indicates the type of event, and event_info member is a union of
description structures. Application event handler will typically use
switch( event->event_id) to handle different kinds of events.
If application event handler needs to relay the event to some other task, it is
important to note that event pointer passed to the event handler is a pointer to
temporary structure. To pass the event to another task, application has to make
a copy of the entire structure.
Event IDs and Corresponding Data Structures
| Event ID (legacy event ID) | Event data structure
|
| Wi-Fi
|
| WIFI_EVENT_WIFI_READY (SYSTEM_EVENT_WIFI_READY) | n/a
|
| WIFI_EVENT_SCAN_DONE (SYSTEM_EVENT_SCAN_DONE) | wifi_event_sta_scan_done_t
|
| WIFI_EVENT_STA_START (SYSTEM_EVENT_STA_START) | n/a
|
| WIFI_EVENT_STA_STOP (SYSTEM_EVENT_STA_STOP) | n/a
|
| WIFI_EVENT_STA_CONNECTED (SYSTEM_EVENT_STA_CONNECTED) | wifi_event_sta_connected_t
|
| WIFI_EVENT_STA_DISCONNECTED (SYSTEM_EVENT_STA_DISCONNECTED) | wifi_event_sta_disconnected_t
|
| WIFI_EVENT_STA_AUTHMODE_CHANGE (SYSTEM_EVENT_STA_AUTHMODE_CHANGE) | wifi_event_sta_authmode_change_t
|
| WIFI_EVENT_STA_WPS_ER_SUCCESS (SYSTEM_EVENT_STA_WPS_ER_SUCCESS) | n/a
|
| WIFI_EVENT_STA_WPS_ER_FAILED (SYSTEM_EVENT_STA_WPS_ER_FAILED) | wifi_event_sta_wps_fail_reason_t
|
| WIFI_EVENT_STA_WPS_ER_TIMEOUT (SYSTEM_EVENT_STA_WPS_ER_TIMEOUT) | n/a
|
| WIFI_EVENT_STA_WPS_ER_PIN (SYSTEM_EVENT_STA_WPS_ER_PIN) | wifi_event_sta_wps_er_pin_t
|
| WIFI_EVENT_AP_START (SYSTEM_EVENT_AP_START) | n/a
|
| WIFI_EVENT_AP_STOP (SYSTEM_EVENT_AP_STOP) | n/a
|
| WIFI_EVENT_AP_STACONNECTED (SYSTEM_EVENT_AP_STACONNECTED) | wifi_event_ap_staconnected_t
|
| WIFI_EVENT_AP_STADISCONNECTED (SYSTEM_EVENT_AP_STADISCONNECTED) | wifi_event_ap_stadisconnected_t
|
| WIFI_EVENT_AP_PROBEREQRECVED (SYSTEM_EVENT_AP_PROBEREQRECVED) | wifi_event_ap_probe_req_rx_t
|
| Ethernet
|
| ETHERNET_EVENT_START (SYSTEM_EVENT_ETH_START) | n/a
|
| ETHERNET_EVENT_STOP (SYSTEM_EVENT_ETH_STOP) | n/a
|
| ETHERNET_EVENT_CONNECTED (SYSTEM_EVENT_ETH_CONNECTED) | n/a
|
| ETHERNET_EVENT_DISCONNECTED (SYSTEM_EVENT_ETH_DISCONNECTED) | n/a
|
| IP
|
| IP_EVENT_STA_GOT_IP (SYSTEM_EVENT_STA_GOT_IP) | ip_event_got_ip_t
|
| IP_EVENT_STA_LOST_IP (SYSTEM_EVENT_STA_LOST_IP) | n/a
|
| IP_EVENT_AP_STAIPASSIGNED (SYSTEM_EVENT_AP_STAIPASSIGNED) | n/a
|
| IP_EVENT_GOT_IP6 (SYSTEM_EVENT_GOT_IP6) | ip_event_got_ip6_t
|
| IP_EVENT_ETH_GOT_IP (SYSTEM_EVENT_ETH_GOT_IP) | ip_event_got_ip_t
|
| IP_EVENT_ETH_LOST_IP (SYSTEM_EVENT_ETH_LOST_IP) | n/a
|
| | |
|
| BLE GAP:
| esp_ble_gap_register_callback(),
| esp_gap_ble_cb_event_t,
| esp_ble_gap_cb_param_t.
|
| BT GAP:
| esp_bt_gap_register_callback(),
| esp_bt_gap_cb_event_t,
| esp_bt_gap_cb_param_t.
|
| GATTC:
| esp_ble_gattc_register_callback(),
| esp_ble_gattc_cb_event_t,
| esp_ble_gattc_cb_param_t.
|
| GATTS:
| esp_ble_gatts_register_callback(),
| esp_ble_gatts_cb_event_t,
| esp_ble_gatts_cb_param_t.
|
| SPP:
| esp_spp_register_callback(),
| esp_spp_cb_event_t,
| esp_spp_cb_param_t.
|
| Blufi:
| esp_blufi_register_callbacks(),
| esp_blufi_cb_event_t,
| esp_blufi_cb_param_t.
|
| A2DP:
| esp_a2d_register_callback(),
| esp_a2d_cb_event_t,
| esp_a2d_cb_param_t.
|
| AVRC:
| esp_avrc_ct_register_callback(),
| esp_avrc_ct_cb_event_t,
| esp_avrc_ct_cb_param_t.
|
| HFP Client:
| esp_hf_client_register_callback(),
| esp_hf_client_cb_event_t,
| esp_hf_client_cb_param_t.
|
| HFP AG:
| esp_bt_hf_register_callback(),
| esp_hf_cb_event_t,
| esp_hf_cb_param_t.
|