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

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

Obtaining v5.2.1

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.1 --recursive https://github.com/espressif/esp-idf.git esp-idf-v5.2.1
cd esp-idf-v5.2.1/

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

Download an archive with submodules included

Attached to this release is an esp-idf-v5.2.1.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.1/esp-idf-v5.2.1.zip

Major changes

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

Breaking Changes

• Removed CONFIG_IEEE802154_RECEIVE_DONE_HANDLER option, now the code using the 802.15.4 driver directly must call ieee802154_receive_handle_done after receiving the frame. ( dbbe2cf1)

Changelog

802.15.4

802.15.4 MAC

Added

• Added the pending tx while rx feature ( dbbe2cf1)

Removed

• Removed CONFIG_IEEE802154_RECEIVE_DONE_HANDLER option, now the code using the 802.15.4 driver directly must call ieee802154_receive_handle_done after receiving the frame. ( dbbe2cf1)

Thread

Added

• Added ESP Radio spinel for external protocol stack ( dbbe2cf1)
• Added ESP OpenThread vendor commands support ( dbbe2cf1)
• Added configure option for openthread address query ( dbbe2cf1)
• Supported the common console command in OT CLI ( dbbe2cf1)
• Supported openthread radio caps rx on when idle ( dbbe2cf1)

Fixed

• Fixed RCP handle timeout crashing issue ( dbbe2cf1)
• Enabled UART ISR in IRAM for UART RCP process ( dbbe2cf1)
• Disabled the rx on when idle in coex scenario ( dbbe2cf1)

Zigbee

Changed

• Updated Zigbee examples to align with esp-zigbee-lib v1.0.9 ( dbbe2cf1)

Bluetooth Low Energy (BLE)

Bluetooth Low Energy Controller

Added

• Support enable aux packet when extend advertising data length is zero on ESP32-C3 and ESP32-S3. ( d4dd0d42)

Fixed

• Fixed the occasional assertion of rxbuffer_free_all on ESP32-C6 and ESP32-H2. ( b0fc0210)
• Fixed the assertion in memory check when the host processing is too slow on ESP32-C6 and ESP32-H2. ( b0fc0210)
• Fixed the assertion of get_rxed_buffer() when the host task is blocked for a long time on ESP32-C6 and ESP32-H2. ( 1c2a6712)
• Resolved the problem of packet loss occurring during the 1M DTM Rx process on ESP32-H2. ( 1c2a6712)
• Fixed the occasional cache error issue when sleep is enabled on ESP32-C6 and ESP32-H2. ( 1c2a6712)
• Fixed scheduling when modem sleep wakeup delayed on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed BLE IRQ FIFO overflow when enter critical on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed clock sync timeout when exit modem sleep on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed directed advertising with RPA when privacy disabled on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed instant passed when connection updating or PHY updating on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed BLE TX count in direct test mode on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed BLE modem sleep enter failed sometimes on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed BLE TX count in direct test mode on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed BLE modem sleep enter failed sometimes on ESP32-C3 and ESP32-S3. ( d4dd0d42)
• Fixed Bluetooth not waking up due to internal 136k oscillator clock drift on ESP32-C3 and ESP32-S3 ( 9e984cd4)
• Fixed BLE scan request IFS time error in coexistence scenarios on ESP32 ( 11eaf41b)

ESP Bluedroid Host

Added

• Added getter for BLE GATTC GATTS and GAP calllback. ( d4dd0d42)

Changed

• Optimized BLE heap allocation to fix malloc fail in malloc_internal_wrapper (https://github.com/espressif/esp-idf/issues/12574). ( d4dd0d42)

Fixed

• Fixed BLE dangling pointer issue in deletion of bonded devices. ( d4dd0d42)
• Fixed xQueueSemaphoreTask assert when deinit host during scan ( 7e6e769a)
• Example: Fixed UART HCI when flow control is off on ESP32C3 and ESP32-S3. ( 5cb1e9f6)

ESP-BLE-Mesh

Fixed

• Fixed compiling error when PB-ADV is disabled for node ( 95b5f129)
• Fixed using wrong adv type for ADV_NONCONN_IND in NimBLE Host adapter ( 8a0132aa)
• Fixed the struct initialization to meet C++ requirements for BLE Mesh stack ( 7a9b6861)
• Fixed the struct initialization to meet C++ requirements for BLE Mesh examples ( 7a9b6861)

ESP NimBLE Host

Added

• Added change to return success for API execution in "ble_sm_inject_io" ( e0944287)
• Added APIs to support BLE DTM functions. ( e0944287)
• Added Gatt Caching support ( 8b08d11e)
• Added connection reattempt in case of Ext connect ( 8b1c5327)
• Added check to validate adv interval min /max range ( e0944287)
• Added test API to show stack operations status ( e0944287)
• Added nimble-host only support over UART. ( e0944287)
• Added observer role flag. ( e0944287)
• Added support for user to authorize GATT read or write operations. ( e0944287)
• Added support for more advertisement data AD Types. ( e0944287)
• Added support for Characteristic Presentation Format Descriptors. ( e0944287)
• Added support for Characteristic Aggregate Format Descriptor. ( e0944287)
• Added support for sending and receiving signed write commands using CSRK and Sign Counter. ( e0944287)

Changed

• Updated variable name to remove keyword. ( e573b7ce)

Fixed

• Fixed wrong #if guard in porting layer and UART configuration support. ( a707ab94)
• Fixed signed write procedure using correct CSRK and message. ( 9feab170)
• Authorized or deauthorized a BLE device for a connection ( 768bd475)
• Fixed general and limited scanning to check relevant Flags AD Type. ( e0944287)
• Fixed allowing selective and auto connection establishment. ( e0944287)
• Fix out of order message causing DOS during SMP procedure. ( e0944287)
• Fixed address resolution during inquiry for host based privacy. ( 93ea06fe)
• Fixed issue of enabling address resolution across reboot ( 2d36710c)

Removed

• Removed unwanted assert. ( 99552ebd)
• Removed double free of l2cap packet in example ( 923546b1)
• Removed duplicate hci_common.h file. ( e0944287)

Classic Bluetooth

Classic Bluetooth Bluedroid Host

Added

• Added field link key type to the parameter structure of callback event ESP_BT_GAP_AUTH_CMPL_EVT ( 77f53910)
• Added callback event ESP_BT_GAP_ENC_CHG_EVT to notify the change of encryption mode to application layer ( 77f53910)
• Added description of use limitations of security masks in SPP API document ( 9dcc8c9e)

Changed

• Update migration docs for new version of API for Bluedroid host stack initialization ( 3de398b8)

Fixed

• Fixed SPP connection failure due to out-of-sync status of application layer and BTU layer ( ee4fdf84)
• Fixed the dangling pointer in processing the list of bonded Bluetooth device ( 406e11be)

Classic Bluetooth Controller

Bluetooth Common

Bluedroid

Changed

• Make the maximum number of bond devices to be configurable. ( 5cb1e9f6)

Coexistence

Fixed

• Fixed circular dependency issue on ESP32 (https://github.com/espressif/esp-idf/issues/13113) ( 12ae1c19)

PHY

Fixed

• Fixed BLE 2M PHY TX problem causing by phy_wifi_enable_set() on ESP32-C3 and ESP32-S3 ( 8ab1027f)
• Fixed BLE CCA bug on ESP32-C2 ( 8ab1027f)
• Fixed Wi-Fi boot bug at low temperature on ESP32-C6 ( 8ab1027f)
• Fixed BLE and Wi-Fi could not receive packets after entering light sleep for a long time on ESP32-C3, ESP32-S3, ESP32-C2 and ESP32-C6 ( 8ab1027f)

Wi-Fi

Fixed

• Smart Config: Removed rogue semicolon in SMARTCONFIG_START_CONFIG_DEFAULT() which was causing some build errors when used in C++ (https://github.com/espressif/esp-idf/pull/12867) ( f1561c6b)

Wi-Fi MAC

Changed

• Updated scan AP number when clear scan AP records ( a328e1a0)

Fixed

• Fixed beacon timeout after restart ( a328e1a0)
• Fixed Wi-Fi stop cost too much time at coexist scenario ( a328e1a0)
• Fixed the old_snd filed error in WIFI_EVENT_HOME_CHANNEL_CHANGE event (closes https://github.com/espressif/esp-idf/issues/13051) ( a328e1a0)
• Fixed issue that task watchdog got triggered in mplen clear on ESP32C6( a328e1a0)
• Fixed issue that esp_wifi_set_mode() not returning error for invalid argument ( a328e1a0)
• Used low rate to send DHCP offer and DHCP ack to avoid get IP fail ( a328e1a0)
• Used QoS data to send EAPOL packets ( a328e1a0)
• Fixed potential memory issue in wifi stop(may increase binary image by 2KB) ( a328e1a0)
• Fixed esp_wifi_scan_start memory leakage issue (https://github.com/espressif/esp-idf/issues/10693) ( 1cd164b8)
• Fixed PMK invalid causes same SSID WPA and WPA2 connect fail issue ( e8548e7a)
• Fixed ESP32-C2 disconnect reason code wrong issue ( 4f6cca6f)

ESP-WIFI-MESH

Fixed

• Waited for child disconnect event when mesh deinit ( a328e1a0)

Wi-Fi Supplicant

Added

• Added low heap Kconfig option for EAP enterprise ( 4a3f224f)
• Added support to move supplicant BSS to external memory ( 65d127da)

Fixed

• Added change to allow calling esp_mbo_* APIs only when MBO config flag is enabled. ( 7e9a9b35)

ESP Vendor Feature

Fixed

• Example: Fixed smart config BSSID set issue. ( 1cd164b8)

Ethernet

Added

• Added option to use SPI Ethernet modules in poll mode without interrupt. #12682 ( 34ec96ef)
• Added a timeout in Rx task when waiting for interrupt for KSZ8851. ( 34ec96ef)
• Added option to read/write PHY registers via ioctl API ( 5a557bb5)
• Added extra delay after setting PHY speed for LAN87xx ( 5a557bb5)

Fixed

• Fixed SPI Ethernet _alloc_recv_buf error handling ( 527ce5eb)
• Fixed W5500 flush received frame function ( 527ce5eb)

Security

Fixed

• Fixed build failure and incorrect GCM hardware usage when CONFIG_MBEDTLS_HARDWARE_GCM is disabled ( b43aa040)
• Additional protection for secure version check in anti-rollback case to avoid security bypass with physical access to flash ( d7f19c4a)
• Updated API esp_hmac_disable_jtag() to disable JTAG access correctly. ( 1bd76ee0)

Peripheral Drivers

Added

• RMT: Support update bytes encoder configurations at runtime （https://github.com/espressif/esp-idf/issues/12775） ( df558f4f)
• RMT: Added help function to allocate the memory used by the encoder (https://github.com/espressif/esp-idf/issues/13032) ( 9961629d)
• SPI LCD: Added flags to control the DC level in cmd/param/data phase separately (https://github.com/espressif/esp-idf/pull/12908) ( 715df99f)
• USB Host: USB host allows user to filter enumerated devices and set the device configuration during the enumeration ( 56c7df9f)

Changed

• I2C LCD: Updated the OLED example with the new I2C master driver (https://github.com/espressif/esp-idf/issues/13201) ( 383a1e86)

Fixed

• Modbus: Fixed possible incorrect event processing in modbus slave examples ( 6717fa03)
• ADC: Fixed disable adc will make temperature sensor crash (https://github.com/espressif/esp-idf/issues/12921) ( 6e702901)
• ADC: Fixed wrong results after ADC continuous mode stops and starts again on ESP32-C6/H2/S3/S2/C2/C3 ( 1156370c) ( db3aa57a)
• Dedicated GPIO: Fixed the software UART driver to stop sending the dummy byte from the emulate_uart_send routine. ( 08105017)
• I2C: Fixed i2c_master driver failed to read one byte on ESP32. ( 4bf00b2c)
• I2S: Fixed incorrect reg base name on ESP32-C3 (https://github.com/espressif/esp-idf/issues/12643) ( 81dc597d)
• MCPWM: Reset the generator GPIO after deleting (https://github.com/espressif/esp-idf/issues/12980) ( 48e3103c)
• RGB LCD: Fixed the issue that the restart transmission can't work with RGB332 pixel format (https://github.com/espressif/esp-idf/pull/13020) ( de6aecf2)
• Temperature Sensor: Fixed issue that temperature sensor cannot change range smoothly on ESP32-H2 ( 2fc023ef)
• Temperature Sensor: Fixed incorrect value after disable and enable again (https://github.com/espressif/esp-idf/issues/12864) ( 6e702901)

Removed

• RGB LCD: Removed the validation of pins for RGB_LCD output (https://github.com/espressif/esp-idf/pull/13103) ( de6aecf2)

System Hardware

Added

• Efuse: Added new eFuses for ESP32-H2 and ESP32-C6 ( 3c7c5829)

Changed

• Improved voltage convergence of ESP32-C6/H2 chips for better stability ( 8e1cd389) ( 3c7c5829)

Fixed

• BOD: Fixed the wrong threshold set on ESP32-H2 ( a65db35c)
• Cache: Fixed the startup crash on ESP32-S2 when the DCache size is set to zero ( cc60b863)

Core System

Fixed

• Console: Fixed a bug in linenoise console where a negative prompt length can lock up the console, making it unresponsive and leading to a task watchdog timeout. (https://github.com/espressif/esp-idf/issues/4924) ( 6b6ca2d1)
• Console: Fixed app failing to boot with CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG on ESP32C3 (https://github.com/espressif/esp-idf/issues/13197) ( 7ec8266e)
• Heap: Fixed missing include in esp_heap_task_info.h ( 08a50af0)
• Heap: Fixed double traversal of SLIST in map_find_and_remove() when heap trace standalone is enabled (https://github.com/espressif/esp-idf/issues/12820) ( 709d8ef6)

Debugging

Added

• Coredump: Add ESP32-P4 support ( 61db22a5)

Changed

• Coredump: Improved TCB access by changing task traversal method. ( 04ce3aff)

Low Power Features

Power Management

Added

• Support GDMA channel configuration retention in peripheral power down light sleep ( 2b084b1f)

Fixed

• Deep sleep current may decrease about 0.2uA on ESP32-H2 ( 3c7c5829)
• Deep sleep current may decrease about 0.2uA on ESP32-C6 ( 8e1cd389)
• Light sleep current may decrease about 3uA when top_on and cpu_on on C6 ( 8e1cd389)

ULP

Added

• ULP: Added API for de-initing the ULP-RISCV ADC (https://github.com/espressif/esp-idf/pull/12785) ( 47b7e61d)

Fixed

• ULP: Fixed an issue where the RTC I2C SDA and SCL lines were not initialized in open-drain mode. ( 2c0d846e)
• ULP: Fixed an issue where the LP I2C SDA and SCL lines were not initialized in open-drain mode. https://github.com/espressif/esp-idf/issues/12969 ( 228c9a75)

LWIP

Added

• Added a config option to set fall back DNS server (https://github.com/espressif/esp-idf/issues/12530) ( 3f730f24)

Fixed

• Fixed compilation error in lwIP debug print formatting. (https://github.com/espressif/esp-idf/issues/12982) ( 1cd164b8, 3f730f24)
• Fixed DNS initialization to work correctly with FALLBACK_DNS_SERVER_ADDRESS() in IPv4 only mode (https://github.com/espressif/esp-lwip/pull/62) ( 3f730f24)

HTTP Client

Fixed

• Fixed esp_http_client_example build failure for ESP32-C6 ( 585f9a0f)
• Fixed esp_http_client digest auth without qop ( 3549a154)
• Fixed reset errno value to 0 before call esp_transport_read. ( 51d2f67f)

mbedTLS

Changed

• Updated mbedTLS to v3.5.2 ( 360ecf56)

Bootloader

Added

• Added legacy retained memory CRC calculation as an option (https://github.com/espressif/esp-idf/issues/12849) ( da6412b2)
• Added a config to encrypt only the app image instead of the whole partition when flash encryption is enabled (#12576) ( 4beadd4c)

Fixed

• Fixed the value of the image_length field of the image metadata populated by esp_image_verfiy() to include the size of the signature sector when Secure Boot V1 is enabled. ( 4beadd4c)

Storage

Fixed

• Fatfs: Fix issue where FatFs tried to trim on sd cards that did not support it ( 001b8ff9)

Tools

Fixed

• Fixed support of gdbgui on Unix with Python 3.11 (https://github.com/espressif/esp-idf/issues/12764) ( 0d3486b0)
• Removed extra new lines in saved command's output (stdout/stderr) on Windows, which may break hint processing. ( 7ab6811a)

Documentation

Fixed

• Added missing semi-colons in the code blocks presented in the esp_event documentation. (https://github.com/espressif/esp-idf/issues/13156) ( 98cbd1fd)