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

ESP-IDF v5.0.9 is a bugfix update for ESP-IDF v5.0 and also the last bug fix release of ESP-IDF v5.0. According to ESP-IDF Support Period Policy, ESP-IDF v5.0 release branch reached end-of-life in May 2025. With EOL, new features, bug fixes, and security fixes will no longer be supported on this branch. Customers who are currently using ESP-IDF v5.0 release branch are encouraged to upgrade their projects to more recent ESP-IDF releases, such as ESP-IDF v5.3.x.

Obtaining v5.0.9

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

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

Download an archive with submodules included

Attached to this release is an esp-idf-v5.0.9.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. To reduce the size of the archive, the .git directory doesn't include the history of commits older than one year. Users who need to use git checkout to access an older release of IDF will have to use git fetch first to download the remaining part of the history.

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

Major changes

Major Bug Fixes

• Disable debug vendor HCI command on ESP32. (1f51604)

Breaking Changes

• Security/MbedTLS: If using MbedTLS for server certificate verification, it is mandatory to call mbedtls_ssl_set_hostname before the connection begins. No change is required if the application uses esp-tls layer. (34240b1)
• Bluetooth Common: Starting from this version, Espressif's Bluetooth vendor-specific HCI commands and events for all ESP Bluetooth chips are disabled by default in HCI UART mode and non-ESP host mode. Please refer to esp_bt_vs.h (E.g., components/bt/include/esp32/include/esp_bt_vs.h) for detailed information. (87a728c)
• Application Utilities/Provisioning: Security2 scheme has been updated for AES-GCM IV usage. Please refer to security2 scheme documentation for changes required on the provisioning entity side. (7ff4650)

Changelog

This is the list of changes since release v5.0.9.

Application Utilities

ESP HTTPS Server

• Updated the CA certificates that were used for self-signing/mutual authentication use cases to contain the Key Usage parameter due to the change in Python3.13's default ssl context requirements. (8df0a41)

Protocomm

• Add salt-verifier generation API in SRP6a implementation and make its interface public (6cb14d5)

Provisioning

• Update security2 scheme to fix the incorrect AES-GCM IV usage (7ff4650)
• Security2 scheme has been updated for AES-GCM IV usage. Please refer to security2 scheme documentation for changes required on the provisioning entity side. (7ff4650)

BLE

BluFi

• Fixed crash issue during memcpy in BluFi example. (9aea05c)
• Fixed potential out-of-bounds memory access issue in Blufi example. (8dde4f9)

Bluedroid

• Fix missing event reporting in esp_ble_create_sc_oob_data. (a5ecb8a)
• Fixed BLE crash when disable bluedroid host. (a5ecb8a)
• Fix potential uint32_t overflow in BLE btu_start_timer. (a5ecb8a)
• Fixed memory leak issue when using dynamic memory and deinitializing the host. (a5ecb8a)
• Added a new API esp_bt_config_file_path_get() to retrieve the Bluetooth configuration file path used for storing bond keys in the NVS module. (a5ecb8a)
• Added esp_ble_gap_read_channel_map() to retrieve the BLE channel map of a connected device. (a5ecb8a)
• Added BLE eddystone sender example. (c08af7b)
• Supported read periodic advertiser list size command. (cedd9a1)
• Added Read Long Characteristic Values example. (df5d6cd)
• Supported BLE vendor hci event reporting (e69a866)
• Supported BLE setting vendor event mask (e69a866)
• Supported SPI log output options for HCI. (66319fb)
• Fixed an issue where advertising data and scan response data were not reported together during BLE active scanning. (94adab5)
• Added BLE get started examples for Bluedroid. (743ed7b)
• Optimize the references to BLE GATT related APIs. (a68962b)

Controller

• Fixed BLE disconnection due to MIC error when pairing with an iOS device on ESP32-C3 and ESP32-S3. (54ec0a9)
• Disable anonymous extended advertising reporting on ESP32-C3 and ESP32-S3. (1779887)
• Fixed BLE assert lld_adv.c 2992 on ESP32-C3 and ESP32-S3. (1779887)
• Fixed heap assert due to advertising data buffer double freeing on ESP32-C3 and ESP32-S3. (1779887)
• Fixed BLE 0x08 disconnect when the window size is greater than half of the connection interval on ESP32-C3 and ESP32-S3. (1779887)
• Fixed the cache error if controller runs in flash and BLE sleep is enabled on ESP32-C2. (5fe7b4c)
• Fixed a heap assertion issue when enabling BLE and ESP32C2_REV_MIN_200 for ESP32-C2 v2.0 (8efb55e)
• Fixed an occasional load access fault issue when performing ext_conn creation for ESP32-C2. (87a728c)
• Added definitions for bluetooth hci vendor commands and events (87a728c)
• Fixed hci assertion issue when uart interference occurs on ESP32-C2. (096fb7f)
• Changed the maximum supported value of the whitelist to 31 on ESP32-C2. (096fb7f)
• Added a function to maintain the connection when an instant pass issue occurs on ESP32-C2. (e29cfa8)
• Fixed extended advertising interval upper limit issue on ESP32-C6 and ESP32-H2. (e29cfa8)
• reduce controller bin size for ESP32-C3 and ESP32-S3 (651fa8f)
• Fixed enhanced TX power setting and getting for legacy adv on ESP32-C3 and ESP32-S3. (95cafb5)
• Fixed BLE assert lld_con.c 2387 on ESP32-C3 and ESP32-S3. (95cafb5)
• Fixed compatibility issues during the encryption procedure on ESP32-C3 and ESP32-S3. (95cafb5)
• Added BLE debug log module on ESP32-C3 and ESP32-S3. (e831ba7)
• Fixed scan duplicate filter failure when receiving ADV_DIRECT_IND for ESP32-C2. (0364a68)
• Fixed an occasional assertion issue when msys memory cannot be obtained on ESP32-C6 and ESP32-H2. (5dbf151)
• Fixed an issue where the default tx power of connection is incorrect after setting the scan tx power on ESP32-C6 and ESP32-H2. (5dbf151)
• Fixed an issue that failed to establish a connection using a resolvable private address on ESP32-C2. (5dbf151)
• Updated the BLE rom.ld file for ESP32-C2 v1.0, v1.1, v1.2 and v2.0. (5dbf151)
• Supported for putting ble code into flash on ESP32-C6 and ESP32-H2. (5dbf151)
• Fixed an issue that failed to establish a connection using a resolvable private address on ESP32-C6 and ESP32-H2. (5dbf151)
• Fixed an occasional ACL disconnect issue under multiple connections on ESP32-C6 and ESP32-H2. (5dbf151)
• Added config to enable/disable BLE channel assessment and ping procedure on ESP32. (a55d6bc)
• Fixed BLE assert in lld_evt.c at line 2353 on ESP32. (a55d6bc)
• Fixed the issue where disconnection events were not reported as a slave on ESP32. (a55d6bc)
• Fixed interrupt watchdog timeout when shutdown BT controller on ESP32. (a55d6bc)
• Enhance Access Address validation in compatibility mode on ESP32. (a55d6bc)
• Provided DTM configuration command in HCI example. (245fb72)
• Support resolving peer RPA to identity address when creating connection on ESP32-C3 and ESP32-S3. (eb5c888)
• Fixed peer address type error in HCI LE meta event on ESP32-C3 and ESP32-S3. (eb5c888)
• Resolved assertion failure “assert lld_scan.c 1728, param 00000000 00000000” on ESP32-C3 and ESP32-S3. (eb5c888)
• Fixed BLE assert rwble.c 505 param 00400010 on ESP32-C3 and ESP32-S3. (eb5c888)
• Fixed setting random address failed when extended advertising is enabled on ESP32-C3 and ESP32-S3. (eb5c888)
• Added parameter validation for Periodic Advertising Enable on ESP32-C3 and ESP32-S3. (eb5c888)

Documentation

• Updated the BLE feature support status in API Guides. (6dcddbc)

NimBLE

• Fix sync handle assignment for PAwR connection (8480197)
• Fixed incorrect OTA address type assignment (152eb37)
• Corrected event posting in Read Remote Features event handling [ Closes https://github.com//issues/15670 ] (e5dc75e)
• Added missing ble_hs_unlock for periodic adv sync reattempt case. (d1deab0)
• Fix conversion for min-max itvl of periodic adv param in example (3adb4ed)
• Exposed the ble_gap_wl_tx_add API to add a device in whitelist (ac367ac)
• Fix SMP command allocation (30ff865)
• Add support for Vendor Event mask VSC (0ba9ba4)
• Fix incorrect event deinit in gatt caching discovery (e6c139e)
• Fixed pairing failure issue when SC only mode is selected (c22e7ae)
• Added a change in the BLE SPP Client example to allow the client to subscribe to the server. (16a0789)
• Handle application code compilation issue due to removal of link_estab structure (f55e6c3)
• Update controller data length upon connection creation. (e85dbe0)
• Deprecate BLE_GAP_EVENT_LINK_ESTAB event. (57ed699)
• Handle nested locks when BT_NIMBLE_DEBUG enabled (#15014, #15294, #15202) (608d5a7)
• Enhanced error handling by adding to print core error definitions (85109af)
• GATT server operation of long read updated to include offset information. (85109af)
• Restart adv / sync when periodic sync fails due to 0x3E (85109af)
• Fixed nvs corruption due to BLE_ENV_ADV_DATA flag (85109af)
• Handle not sending disconnect event if connect event was not sent (85109af)
• Fixed compilation issue observed when WARN_WRITE_STRINGS is set. [ PR: https://github.com/espressif/esp-nimble/pull/84 ] (85109af)
• Add support for missing legacy event type in report parsing (f9358b7)
• Fixed compilation issue due to variable name typo (d7e63ef)
• Added change to assign correct peer OTA address type (7de5c22)
• Fixed compilation issue for combination of Ext Adv and Reattempt connection flag. (7de5c22)
• Added a check for invalid offset (7de5c22)
• Save the gatt context in case of preemption (7de5c22)
• Clear our and peer security records cleanly during unpair. (7de5c22)
• Additional PAwR changes support for ESP IP (7de5c22)
• Fixed memory leak issue in Blufi example (7de5c22)
• Added a function that prints HCI error definition in case of failure (7de5c22)
• Fixed incorrect storing of csfc to nvs (7de5c22)
• Reset global variables during link disconnection (7de5c22)
• Added HCI Read Remote Version Information command. (7de5c22)
• Additional changes in PAwR IDF Examples/support for ESP IP (7de5c22)

Bluetooth Common

• Starting from this version, Espressif's Bluetooth vendor-specific HCI commands and events for all ESP Bluetooth chips are disabled by default in HCI UART mode and non-ESP host mode. Please refer to esp_bt_vs.h (E.g., components/bt/include/esp32/include/esp_bt_vs.h) for detailed information . (87a728c)

Controller

• Fixed the issue that disable Bluetooth controller may cause interrupt watchdog timeout on ESP32 (6683d50)
• Disable debug vendor HCI command on ESP32. (1f51604)
• Added API to get/set low power clock source on ESP32 (9659bb2)

Classic Bluetooth

Bluedroid

• Fixed no report of ESP_SPP_WRITE_EVT and Bluedroid btc task being blocked when SPP connecion number reaches the upper limit (2d8537a)
• Fixed connection failure due to insufficient number of service security records when multiple profiles are initialized. (c0478d2)
• Fixed reporting of unexpected ESP_BT_GAP_DISC_STATE_CHANGED_EVT event upon ACL disconnection, due to uninitialized local variable (63b16bc)
• Fixed the issue that after SPP reaches the maximum number of connections, it will mistakenly free the server resources when disconnecting, causing the next server start to fail. (36f41bf)
• Fixed memory leaks in SPP callback mode (8fbdf6c)
• Fixed incorrect records in SDP record search response using 16-bit UUID (f299f69)
• Fixed error type returned when searching for service records of SIM Access Profile(SAP) in SDP (f299f69)

Controller

• Fixed ACL has few chance to run when it coexists with SCO on ESP32 (1303c62)
• Fixed errors in dynamic priority configuration in Bluetooth dual mode on ESP32 (1303c62)
• Fixed a crash issue caused by accessing external memory in ISR context on ESP32 (1303c62)
• Fix the incorrect unit of duration_min in CPB TX on ESP32 (4300556)
• Recalculate the channel map when AFH is enabled on ESP32 (4300556)
• Fixed assessing NULL pointer in case of handling earlier message when Bluetooth Classic connection gets disconnected (#15128) (1f51604)
• Avoid accessing released ACL resources in SCO logic on ESP32 (1f51604)
• Fixed missing critical protections on linked-list structures of (e)SCO buffers on ESP32 (a55d6bc)

Coexistence

• Support BR/EDR (e)SCO and Wi-Fi coexistence. (9842b1f)
• Add coexistence scheme for BT Inquiry/Page coexist with WIFI (a2e76fa)

Core System

• Ensure proper reset for crypto peripherals before software restart. This fixes a rare and intermittent secure boot verification failure based on RSA-PSS scheme. The fix is recommended for aggressive revocation config. Please see commit log for more details. (5082a26)
• Fixed implementation of __atomic_test_and_set to be atomic (68448cf)

Panic handling

• Updated the panic handler to use RTC WDT. This fixes a bug where in the panic handler could get stuck without rebooting the system (#15166, #15018, #10110) (be7ea1c)

FreeRTOS

IDF Additions

• Fixed a bug wherein a no-split ring buffer does not receive any item if space on the buffer is acquired until the buffer is full and the acquire pointer wraps around (#14948) (92f710f)

LWIP

DHCP

• Fix dhcp server recv decline issue (3f94b6b)

Low Power Features

• Allows to keep sar adc power when using ADC_ULP_MODE. (#12426) (2122c07)
• Fixed power leakage when external 32k slow clock source detection fails. (f1af5bb)
• Fixed the issue that esp32c2 may fail to wake up after entering deepsleep with external 32 kHz oscillator. (386c346)

Networking

Examples

• minor fix in the modbus slave setup mode (#14878) (f3e576a)

PHY

• Fixed the issue that tsens read abnormal value in Wi-Fi STA mode for esp32c2eco4. (7781907)
• Optimization of RX calibration in high-interference environments. (638bb70)

Peripheral Drivers

ADC

• Fixed ADC calibration resolution loss on ESP32-S2（https://github.com/espressif/esp-idf/issues/15671） (c58641e)

GPIO

• Fixed the issue that configuring RTCIO as GPIO causes other initialized RTCIO to function abnormally on esp32s2 & esp32s3. (#10404, #12681) (ad2af15)

I2S

• Fixed clock not update issue when re-configure the slot (#15256) (dc58edb)

RMT

• Fixed the channel resolution divider rounding issue (#15092) (c6de21b)

SD_HOST

SDMMC

• Improved checking of SD being busy and always requesting SD to send status, even if a write operation failed. (4426dd5)
• Improved initialization of SD card relative address (RCA). (e8d1e3c)
• Fixed transfer timeout due to higher priority tasks (#13934) (7a59dfe)

SPI

• Fixed slave rx buffer overwrite when no DMA and configured trans_len don't match master trans_len. (#14462) (db9e335)

SPI Slave

• Fixed segment mode potential IWDT timeout when mix mount TX and RX (8f817ec)

SPI Flash

• Fixed build fail when rom_patch config disabled (#15229) (4ddfbf7)

TWAI

• Fixed twai assert failed during recover (#9697) (10130e9)
• Fixed other node got BUS-OFF when twai init. (#14548) (85443b1)

UART

• Allowed TX and RX configure to the same pin in uart_set_pin (#14787) (1730e74)
• Fixed potential UART_SELECT_READ_NOTIF race condition (1730e74)

USB

USB Host

• Fixed crash during sudden disconnection (#13364) (#15290) (16aba99)

USB Serial JTAG

• Fixed wrong return value from usb_serial_jtag_write_bytes when encounter invalid input parameters (#15620) (da555cc)

Security

• Fixed Memory protection interrupt check for ESP32S2 (PERI1 bus) (ae11fd5)

MbedTLS

• Update mbedTLS version to 3.6.3. (34240b1)
• If using MbedTLS for server certificate verification, it is mandatory to call mbedtls_ssl_set_hostname before the connection begins. No change is required if the application uses esp-tls layer. (34240b1)

Storage

VFS

• Fixed incorrect level of log messages (#14327) (331e9be)
• Fix incorrect open and close behavior for /dev/console (e59cc98)

System Hardware

• Fixed esp32s3 possible cache_error triggered by another core accessing flash in esp_restart (44c38da)
• Switched to flashing with stub with ESP32-C3 when USB Serial/JTAG mode is used (a1577d2)

MMU

• Fixed spi_flash_cache2phys return addr in PSRAM issue when SPIRAM_FETCH_INSTRUCTIONS or SPIRAM_RODATA enabled (6471d88)
• Fixed spi_flash_phys2cache return addr in PSRAM issue when SPIRAM_FETCH_INSTRUCTIONS or SPIRAM_RODATA enabled (6471d88)
• Fixed mmap failure caused by leftover register value when running multicore app with unicore bootloader on ESP32 (#11617) (89bcbca)

MSPI

• Improved the selection of timing tuning points when the last few tuning points succeed consecutively (0318fe8)

PSRAM

• Supported UnilC Octal PSRAM on ESP32S3 (4d78c54)
• Fixed external RAM .bss and .noinit section vaddr calculations (#15513) (2cec465)
• Fixed bad timing when reading mode registers on Octal and Hex PSRAMs (02e6557)

Toolchain

• Upgraded openocd version to v0.12.0-esp32-20250226 (f5fc667)

Tools

• Fixed processing of packages with dots in their names in Python dependency checks (9071238)
• Fixed deprecation warnings when using extractall() on Python 3.12 and newer (83b9a4d)
• Added input validation of optional install features (6bbaf8b)
• Fixed ValueError: invalid literal for int() with base 10: '' coming from the configuration system when the integer config option has no defined value (a5099fa)

WI-FI

• fix country element not update in beacon (a7d6b07)
• fix channel in rx_ctrl is zero when using sniffer (22789f4)
• fix compatibilty issues and crash during scan (22789f4)
• Fixed the scan information error in LR only mode (b39b0cc)
• Updated the description for esp_mesh_send() return value (#14440) (b39b0cc)
• Added timer to send wake null after STA received association response (b39b0cc)
• Add the missing brackets for the C++ guards for a few header files. (#14991) (cae81c6)
• Fixed the delete queue error in ESP-NOW example (#15383) (5949919)

MAC

• Fixed phy data partition restoring default fails issue (26e70c3)
• Fixed an issue to prevent writing configuration to NVS when the station configuration remains unchanged. (02f3948)
• Improve esp32s2 recv 24M Block Ack packet performance (02cead4)
• Fixed the WEP shared authentication association timeout issue. (f7faec9)
• Fix occasional dropping of SA Query responses by SoftAP (29797ad)
• Modified authmode to sta for sta connect event (efd8975)
• Fixed disable external coexist fail issue. (638bb70)
• Fix the issue of failing to connect to a shared WEP AP. (638bb70)
• Fixed issue of increased stack usage when 'failure_retry_cnt' is set in station configuration and Wi-Fi driver internally re-tries connection attempts (9d8fc56)

Supplicant

• Added domain name validation support for EAP connection. (a8e0e0b)
• Resolved WPS connectivity issue that caused failures when the station was already connected (1920192)
• Fixed stack corruption in Wi-Fi wpa_supplicant's tasks, fixed #15370 (e2a2dcd)
• Fixed issues reported by the static analyzer on GitHub (#15097, #15098, #15099). (a313683)
• Reduced WPS scan frequency to make it easier for users to enter the PIN on the AP. (45ff288)
• Enabled EAP workarounds by default (d452461)