Documentation for IDF v5.2.2 is available at https://docs.espressif.com/projects/esp-idf/en/v5.2.2/

ESP-IDF v5.2.2 is a bugfix update for ESP-IDF v5.2.1.

Obtaining v5.2.2

For full installation instructions, see the ESP-IDF Programming Guide.

The source files attached to this release will not work due to our use of git submodules. Use one of the following methods instead:

Using git

To get this release, use the following commands:

git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git esp-idf-v5.2.2
cd esp-idf-v5.2.2/

This is the recommended way of obtaining v5.2.2 of ESP-IDF.

Download an archive with submodules included

Attached to this release is an esp-idf-v5.2.2.zip archive. It includes .git directory and all the submodules, so can be used out of the box. This archive is provided for users who have connectivity issues preventing them from cloning from GitHub.

This archive can also be downloaded from Espressif's download server: https://dl.espressif.com/github_assets/espressif/esp-idf/releases/download/v5.2.2/esp-idf-v5.2.2.zip

Major changes

This is the list of changes since release v5.2.1:

Changelog

802.15.4

802.15.4 MAC

Fixed

Fixed ieee802154 include header file issue and unused value issue (8531594)

Thread

Added

Added max csmabackoffs numbers for transmission via spinel (1b9597f)
Added cli support in openthread sleep example (9607a11)
Added state indicator in Thread examples (fd4b09f)
Added events for meshcop-e service publish and remove (66c164b)
Supported openthread ephemeral key feature (66c164b)

Changed

Moved some lwip api to lwip task (66c164b)
Enabled RCP uart configuration for BR by default (fd4b09f)

Fixed

Fixed dead lock issue related to mdns (66c164b)
Fixed the race condition in rx buffer count operation (fd4b09f)
Fixed openthread alarm timer calculation remaining_us overflow issue (6c1542e)

Removed

Removed the range for some configurations (70fc0e3)

Bluetooth Low Energy (BLE)

Bluetooth Low Energy Controller

Added

Supported sending disconnection command if the disconnection procedure is on-going on ESP32 (8c52152)
Supported ESP32-C2 light sleep using external 32.768 kHz oscillator at pin0 as slow clock source. (4c96e52)
Added CCA related config option on ESP32-C6, ESP32-H2 and ESP32-C2 (4c96e52)
Added API to get low power clock source on ESP32C3 and ESP32S3 (228f922)
Added BLE scan backoff config option in menuconfig on ESP32 (8c52152)
Added config for channel assessment and ping procedure on ESP32-C3 and ESP32-S3. (8c52152)

Changed

Expanded the scan period to the maximum of 0xffff on ESP32-C6, ESP32-H2, and ESP32-C2. (4c96e52)

Fixed

Fixed BLE ASSERT_PARAM(0,0) in rwble.c in coexistence scenarios on ESP32 (408294a)
Register coexist functions into Bluetooth controller on ESP32-C3/ESP32-S3 (8c52152)
Fixed BLE DTM status and TX count error on ESP32 (408294a)
Reduced the usage of flash and RAM when only legacy adv and peripheral are enabled on ESP32-C2. (5fa3428)
Fixed BLE light sleep issue which will randomly cause task watchdog upon power up on ESP32-H2. (5aad850)
Fixed an occasional assertion issue during slave connection in coexistence scenarios on ESP32-C2. (b19e27d)
Use embedded assembly to get access to DPORT registers on ESP32 (8c52152)
Fixed BLE scan assert(10,0) on ESP32(#8532) (8c52152)
Fixed BLE assert when receiving packet on ESP32 (8c52152)
Fixed extended uncoded and coded scan scheduling on ESP32-C3 and ESP32-S3. (8c52152)
Cleared random address for extended advertising on ESP32-C3 and ESP32-S3. (8c52152)
Fixed periodic advertising data setting with zero length on ESP32-C3 and ESP32-S3. (8c52152)
Fixed an issue of occasional ACL data loss under multiple BLE connections on ESP32-C2. (4c96e52)
Fixed occasional assert issue in modem sleep mode on ESP32-C6 and ESP32-H2. (1097ed0)
Fixed issue of slave latency applied when not receiving valid PDU on ESP32-C6 and ESP32-H2. (1097ed0)
Fixed HCI command status event send when LLCP is busy on ESP32 (daa6a0d)
Fixed HCI command status event sending for disconnection command on ESP32 (daa6a0d)
Fixed LE transmitter test command parameters check error on ESP32 (daa6a0d)
Fixed an occasional assertion issue when enabling multiple periodic adv on ESP32-C2. (c630c04)
Fixed adv interval range limit error issue on ESP32-C2，ESP32-C6 and ESP32-H2. (c630c04)
Fixed an occasional assertion issue when disable controller on ESP32-C2. (c630c04)

ESP Bluedroid Host

Added

Added bluerooth hci layer data stream record (40d3981)
Added API to send vendor hci command (40d3981)

Changed

Updated maximum BLE reconnection attempts configuration (35630f5)

Fixed

Fixed BLE appearance category ranges (#13626) (e362358)
Fixed ADV do not restart due to disconnection reason 0x3e (40d3981)
Fixed crash when calculating GATTS database hash (daa6a0d)
Fixed "report" typo in esp_ble_gap_ext_adv_reprot_t (daa6a0d)
Fixed BLE crash when repeatedly iniitialize and deinitialize host (8def30a)
Fixed BLE periodic advertising create sync parameters check error (8def30a)
Example: Use correct struct type in discover service complete event (daa6a0d)

Removed

Removed BLE functions discard declaration (2a9108f)

ESP NimBLE Host

Added

Added usage of esp_timer_get_expiry_time to get current remaining ticks (d9be451)
Added the check to prevent address resolution in case of identity addr for esp32 (391c3a1)
Added support for data length change event in host (abd2184)
Added support for deleting the oldest bonded device across reboot (a6895ce)
Added documentation for ESP32-P4 gpio pins configuration (a253028)
Added ble_host_rpa_enabled flag for address resoultion for esp32 (69dc6f3)
Added support to send and receive read multiple variable length characteristic request and response. (61f8f19)

Changed

Increased range of reattempt connection count in menuconfig (94bec84)
Simplify reconnection code (8599ec3)
Improved documentation for bleprph_host_only example. (909e7fc)
Updated help sections for BLE_RPA_TIMEOUT config. (1f8e365)

Fixed

Expose API to set RPA timeout in stack. (2ba5320)
Fixed aggressive termination in signed write procedure (0190214)
Fixed unpair API ignoring devices bonded with CSRK (0190214)
Fixed compilation issues when CCCD is set to 0 (f9163c6)
Fixed for CVE-2024-24746 vulnerability (709b74c)
Fixed the size of number packets in dtm event (33c6315)
Set correct peer_addr during reattempt connection (3d0682d)
Handled missing free in ble spp example (6020d08)
Handled auto connection flag in extended connect (064df2a)
Fixed call to ble_hid_task_startup and compilation issues due to incorrect prototypes (962d9de)
Fixed compilation issue occurring after disabling security. (ec7e307)
Fixed type in blehr/README (#13034) (374a03f)
Fixed compilation error for strict-prototype enabled (464a62b)
Exposed baud rate in the menuconfig. (259e2ba)
Handled memory leak in callout deinit (deacd79)
Changed 'move_count' to uint8_t type to fix compilation issue in nimble for -O2 flag. (c0faa8f)

BluFi

Fixed

Fixed BluFi module link error(C++ hybrid compilation) (daa6a0d)

Classic Bluetooth

Classic Bluetooth Bluedroid Host

Fixed

Fixed the HID Host inner error state caused by repeat connection of the same device (d4e3253)
Fixed inconsistency of connection initiator state for HID Host open event (d4e3253)
Allocate memory for control block of HFP Audio Gateway in its initialization when dynamic memory is enabled (1c09bc1)
Fixed SPP crash due to the connection not being disconnected before esp_spp_deinit was called (8096a16)
Fixed the crash caused by using illegal pointers during SDP deinit (a70bb45)
Fixed missing of callback event when removing an invalid SDP record (a70bb45)

Classic Bluetooth Controller

Fixed

Fixed the incorrect timing in reporting HCI_Link_Key_Type_Changed event on ESP32 (d34b024)
Fixed the incorrect initialization vector during resuming encryption on ESP32 (d34b024)
Fixed incorrect link key returned from HCI command HCI_READ_STORED_LINK_KEY (d34b024)
Fixed crash during Bluetooth deinitialization in coexistence scenario on ESP32 (f2e1c06)
Fixed invalid transmission of LMP_MAX_POWER PDU in case that peer device is expected peer to increase TX power to maximum on ESP32 (f2e1c06)
Fixed the loss of coexistence request event during sniff transition process due to insufficient of message queue length, which causes Bluetooth link disconnection in case of wireless coexistence on ESP32 (daa6a0d)
Clear sniff state in coexistence scheme when no connections exist (daa6a0d)

Bluetooth Common

Added

Added an option to make alarm number configurable (cc5101f)

Fixed

Fixed error in CMakeLists on ESP32-C2 (#13451) (7646dd5)
Fixed missing linker generated symbols in using esp_bt_mem_release when ESP_ALLOW_BSS_SEG_EXTERNAL_MEMORY is enabled (#10427, #11377) (dc3e953)

Bluedroid

Fixed

Fixed controller using null pointer after bluedroid deinitialization (b0eef7f)

Controller

Changed

Use compile options -ffunction-sections and -fdata-sections when building libbtdm_app.a, to allow to reduce code and data from executable on ESP32 (dd70bf2)

Fixed

Apply only necessary patches for Bluetooth controller ROM code according to Bluetooth mode on ESP32 in order to reduce IRAM consumption and binary size (dd70bf2)

PHY

Changed

Updated ESP32-C3 PHY version to 1170, f4aea9b, Apr 30 2024 (55ea18d)
Updated ESP32-S3 PHY version to 670, b7bc9b9, Apr 30 2024 (55ea18d)
Updated ESP32-C6 PHY version to 290, 81efd96, May 8 2024 (55ea18d)

Fixed

Fixed BLE coded PHY s8 packet TX issue in coexistence scenarios on ESP32-C3, ESP32-S3, ESP32-C2 and ESP32-C6. (5f1187d)
Fixed PLL track when enabling and disabling PHY frequently. (bc26c82)

Wi-Fi

Changed

Updated the LMK description in ESP-NOW documentation (#12976) (06733dc)

Fixed

Fixed crash when associate request is processed before processing of SAE confirm is completed (2c4128b)
Fixed crash occurred due to concurrency in WPA3 soft-AP (7e36e97)
Fixed the SPIRAM malloc issue in wifi mesh (#13285) (bd55386)
Fixed the issue that Wi-Fi TBTT interrupt missed after BLE deinit on ESP32-C6 ECO1 chip, which may cause Wi-Fi difficult to receive packets (5ff245f)

Wi-Fi MAC

Added

Merged SAE Extended Key auth modes into WIFI_AUTH_WPA3_PSK as per WPA3 Specification v3.3, do not suggest to use WIFI_AUTH_WPA3_EXT_PSK and WIFI_AUTH_WPA3_EXT_PSK_MIXED_MODE anymore(afa39b0)

Changed

Refactor FTM code and add calibration for FTM in 40MHz Bandwidth (9da552c)
Improved Wi-Fi connecting success rate at coexist scenario. (ed57048)
Updated FTM PHY Compensation values (0b633e8)

Fixed

Fixed FTM failures with external AP while connected in 40MHz (3b15317)
Fixed AMPDU compatibility issue for some APs (5ec5168)
Fixed the issue that inactive time not reset when iTWT tear down via STA disassociate (5ec5168)
Fixed TWT request is not sent out when exponent is 0 (5ec5168)
Fixed GCMP encryption for management packets. (8b4177f)
Fixed decryption of deauth/diassoc packets when Management Frame Protection enabled (8b4177f)
Fixed sporadic crash arising out of concurrency issues in functioning of DPP module (ac44663)
Fixed multicast address QoS frames issue (22fbaf6)
Fixed task watchdog got triggered by esp_wifi_stop (22fbaf6)
Limited the number of sub frames for TX AMSDU (fc56156)
Fixed crash issue during WiFi connect when AMSDU TX enabled (fc56156)

ESP-WIFI-MESH

Fixed

Fixed the TX issue when mesh lifetime remain equal to zero (8742f24)

Wi-Fi Supplicant

Added

Added API support to disable PMK caching. (9efa26a)
Added support for SAE-PK, WPA3-Enterprise and OWE transition disable indication (afa39b0)

Changed

CVE-2023-52160 Updated phase2 requirement for WiFi PEAP authentication to required when client cert/private key is not used. (e759833)

Fixed

Fixed compile error when CONFIG_SAE is disabled (d2fb805)
Fixed dereferencing a dangling function pointer in WPS (93f7ae7)
Fixed DPP example init error by setting STA mode before DPP init (30c6144)

ESP Vendor Feature

Changed

Changed the magic variable from int to uint32_t on the receiving side (#10912) (3b9d5e1)
Updated the documentation for the use of sniffer APIs (#10740) (3b9d5e1)

Ethernet

Added

Added functions to access MDIO Managed Devices (MMD) PHY registers (30c6144)

Fixed

Fixed link detection for DP83848 to use BMSR (#13560) (d82d703)
Fixed access to PHY registers for DM9051 (b60280e)
Fixed reset timing of IP101 to align with datasheet. (4024dce)
Fixed issue when Ethernet MAC didn't start after the second start/stop sequence when auto-negotiation disabled. (f2da2e8)

Security

Fixed

Fixed incorrect results for GCM operations that used non-AES ciphers using software fallback (bf17be9)

Peripheral Drivers

Added

USB Serial JTAG: Added an example for illustrating the usage of USB Serial communication (#12620) (9582b3c)
I2C: Added a parameter to configure SCL await value (d56ae4c)
I2C: Added more docs for using i2c_master_probe (#12929) (1158811)
Parallel IO TX: Support non-blocking transaction queue (4fe7b96)
SPI Flash: Added check for safe write address in encrypted flash write API (00f1306)

Fixed

GPIO: Fixed the drive capability issues for some IOs on ESP32C3 and ESP32S3 (8374791)
GPIO ETM: Allow the same GPIO to take more than one ETM actions (9b3ae86)
I2C: Fixed timeout being overwritten when starting an I2C transfer (#4999) (78b6d51)
I2C: Fixed receive data is less than sent error will cause core panic (#13354) (f2fd239)
I2C: Fixed the issue that interrupt priority set in the slave_config::intr_priority is not taken effect (#13374) (f2fd239)
I2C: Fixed potential deadlock in i2c_transaction_start (#13388) (1158811)
I2C: Fixed I2C wastes too much cpu source in waiting transaction done (#13137) (#13322) (1158811)
I2C: Fixed memory leak issue that use callback/async transaction (#12878) (1158811)
I2C: Fixed i2c_master_new_bus fails on ESP32 (#12929) (1158811)
I2C: The i2c functions will return error if NACK detected (#13142) (#13398) (1158811)
I2C: Fixed issue that i2c speed incorrect after error (#13397) (1158811)
RMT: Fixed the issue that RX filter can't work properly when using REF_TICK as the clock source on ESP32/S2(#13510) (69359f4)
RGB LCD: Flush the PSRAM frame buffer after allocation (#13294) (7863797)
SDMMC: Fixed initialization process for certain cards in SPI mode (#6686, #10542) (0a83a25)
SPI Flash: Fixed document issue of Auto suspend enabled by default (f3ec76b)
SPI Flash: Fixed wrong detected MXIC flash size (#12222) (4894464)
SPI Flash: Fixed issue that flash encryption failed when using the implementation from ROM, this increases around 1.2KB IRAM usage. (8bf27c1)
UART: Fixed inconsistent number of UART wake up rising edges required by the threshold configured on ESP32S2 and later chips (#12586) (4cf7387)
UART: Fixed the maximum baud rate value (UART_BITRATE_MAX) on ESP32C2 that ensures the data sampling correctness. (bc4c826)
UART: Enlarged LP_UART_EMPTY_THRESH_DEFAULT value to 4 to achieve a higher baud rate on the LP UART controller. (6121027)
UART: Added missing include of esp32/rom/uart.h (#13025) (8b99b2d)
USB Host: Fixed a bug in the USBH layer where multiple concurrent events on the same device would result in some of those events being dropped. (6fe8a34)
USB Serial JTAG: Auto-flush buffers in most cases if MPS size packet is sent. (9582b3c)
USB Serial JTAG: Fixed the issue that FIFO is not flushed when TX buffer is full (#12628) (9582b3c)

System Hardware

Added

Cache: Added unaligned check to esp_cache_msync API for ESP_CACHE_MSYNC_FLAG_DIR_M2C direction (b3a1ec3)

Fixed

Solve CLK calibration timeout problem caused by the wrong range of RTC_CLK_CAL_CYCLES. (08299f5)
Fixed bbpll calibration failure for ESP32-S3 to avoid TG0WDT_SYS_RESET. (9beb67d)

Core System

Added

Newlib: Added definition of aligned_alloc declared in stdlib.h (2ac4df6)

Changed

Reduced binary size of image in case c++ exceptions or eh_frame usage is disabled (f8319f0)
HMAC: Updated method for disabling HMAC to avoid unnecessary reset during disabling. (fcb76f0)

Fixed

Updated the Kconfig option CONFIG_ESP_SYSTEM_PANIC_GDBSTUB to be available only if esp_gdbstub is included in the build. (#13218) (028093e)
Updated and added missing reset reasons for C6, H2 and P4 (9e5c30b)
Fixed the incorrect flash I/DROM region PMP entries for C6/H2 (8a151a5)
Fixed the flash I/DROM region PMP entries for C6/H2 (8c6ce09)
Heap: Fixed missing block owner information in memory allocated in heap_caps_init() (see #13467) (62e9dfe)
Heap: Fixed size propagated to allocation failed hook in heap_caps_calloc() (5753eba)
Interrupts: Fixed esp_intr_free when task has no core affinity (#12608) (5724944)
Log: Fixed incorrect argument type in hexdump log functions (#13347) (9b2c0ff)
Log: Fixed wrap-around of cache generation counter (#6516) (a007178)
ROM: Fixed ROM version of systimer HAL functions always being used even when CONFIG_HAL_SYSTIMER_USE_ROM_IMPL=n was selected. (85ac17e)
Fixed the issue that when the external 32k clock source is selected as the slow clock source on the 26MHz version esp32c2, the RTC_WDT will be triggered during the startup when the clock source is missing. (29a04ba)
Fixed risky PMU initialization sequence at startup (7b97a3d)
Fixed build failure with anti rollback and silent panic handler config (#13417) (3c8b370)

Debugging

Changed

Coredump: Moved the log strings from RAM to flash (eb8e894)
Coredump: Enable SHA256 flash integrity verification for all targets (335b970)

Fixed

Coredump: Fixed a bug preventing the usage of stack guard alongside a custom stack for coredump (016b27c)
Gcov: Fixed unhandled exceptions when GCOV enabled (a7d981d)
Gcov: Avoid multiple tick hook registration (c36c0c3)

Toolchain

Changed

Upgraded gdb version to 14.2_20240403 (3d56f1b)
Upgraded openocd version to v0.12.0-esp32-20240318 (6025739)
Updated QEMU to esp-develop-8.2.0-20240122 (cf7b9be)

FreeRTOS

Added

Added support for application task tag feature (enabled via the CONFIG_FREERTOS_USE_APPLICATION_TASK_TAG option) (23540fa)

Fixed

Fixed broken FreeRTOS port macro portTRY_ENTER_CRITICAL_SAFE() (#13022) (aaf3f4a)
Fixed a bug where CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER was enabled by having esp_gdbstub component in the build even without enabling GDBStub features. (a2e5622)
Fixed CPU core no affinity value to -1 when rendered via vTaskList (#12858) (eb7c381)
Fixed the ordering of the parameters printed by vTaskList() (#13675) (eb7c381)
Fixed xPendedTicksTemp build error when the CONFIG_FREERTOS_USE_TICK_HOOK option is enabled (#13297). (9fe886e)
Idf Additions: Fixed a potential issue where FreeRTOS could access illegal memory when fetching tasks data using the xTaskGetNext additional function. (8c5ccec)
Fixed a bug where vTaskSuspendAll() could suspend the wrong core (9f4f8e2)

Low Power Features

Power Management

Added

Added feature of sleep retention multiple modules initialization and dependency management (470d540)

Fixed

Fixed Fast Memory and Slow Memory may lost in sleep modes on C3/S3 (80cfe30)
Fixed a small probability of getting stuck when entering deep sleep without deinit wifi/bt on esp32c6. (8352be2)
Fixed the problem that CPU frequency is not updated immediately after pm_config updated. (#13492) (9323c19)
Fixed the issue of modem hang caused by incorrect configuration of power and isolate signals in modem domain (c722d8a)

App Utils

Fixed

Fixed incorrect processing of HTTP header (#13497) (2c64d8d)

mbedTLS

Changed

Updated mbedTLS to v3.6.0 (af26dc7)

ESP-TLS

Fixed

Fixed time value overflow for timeout calculation (#13593) (4c7562d)

ESP-MQTT

Fixed

Fixed error code handling for MQTT5(espressif/esp-mqtt#272) (806b14d)
Fixed possible crash when allocation failed for MQTT5 messages(espressif/esp-mqtt#270) (806b14d)
Fixed retransmission timer initialization when first connected(espressif/esp-mqtt#270) (806b14d)
Fixed multiple subscribe macro to handle const char * (espressif/esp-mqtt#269) (806b14d)
Fixed timeout handling when occurs in the process of receiving message(espressif/esp-mqtt#232) (806b14d)

Storage

Changed

NVS: Improved NVS initialisation by extending consistency check of multi page BLOBs (afe0e31)

Fixed

FatFS: Fixed wrong Wear Levelling mode for FatFS generation (wl_fatfsgen.py) (4005c24)
NVS: Fixed race condition during Lock class initialisation (afe0e31)
NVS: Fixed buffer overrun in nvs_get_blob when reading from NVS partition containing inconsistent multi page BLOBs (afe0e31)
VFS: Fixed selecting of eventfd - added conditions for event_start_select check to avoid relating the semaphore to unmonitored eventfd (fd4b09f)
VFS: Fixed build errors when CONFIG_ESP_CONSOLE_NONE was enabled (#12984) (93ec3ac)

Tools

Added

Added additional Python environment checks (#13196) (729e5cb)

Changed

The ESP-IDF version is acquired only from the version or header file (git tags are not considered anymore) (#13385) (1a5e528)

Fixed

Exit gracefully without traceback when running proccess via asyncio (#13418) (f0e5c92)
Described the option to configure flashing with --extra-args (#6337) (ea967cf)
Fixed return codes in BAT scripts (f18329b)
Fixed "Access Violation Error" on Windows with Python 3.12 (#13232) (a258fa9)

Documentation

Fixed

Fixed mistake in ESP Event API docs (#13346) (2456b83)
Fixed mistake (<= vs. <) in the heap allocator docs (#13353) (a61d799)

Removed

Removed mentions of ULP in deep sleep example readme (#13340) (a8d3034)

ESP-IDF Release v5.2.2

Obtaining v5.2.2

Using git

Download an archive with submodules included

Major changes

Changelog

802.15.4

802.15.4 MAC

Thread

Bluetooth Low Energy (BLE)

Bluetooth Low Energy Controller

ESP Bluedroid Host

ESP NimBLE Host

BluFi

Classic Bluetooth

Classic Bluetooth Bluedroid Host

Classic Bluetooth Controller

Bluetooth Common

Bluedroid

Controller

PHY

Wi-Fi

Wi-Fi MAC

ESP-WIFI-MESH

Wi-Fi Supplicant

ESP Vendor Feature

Ethernet

Security

Peripheral Drivers

System Hardware

Core System

Debugging

Toolchain

FreeRTOS

Low Power Features

Power Management

App Utils

mbedTLS

ESP-TLS

ESP-MQTT

Storage

Tools

Documentation