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

ESP-IDF v5.0.2 is a bugfix update for ESP-IDF v5.0.

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

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

Download an archive with submodules included

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

Major changes

Breaking Changes

• NimBLE: Updated return type for nimble_port_init / nimble_port_deinit functions. (358ed1a)
• cxx: experimental components moved to a separate repository (834ca54)

Changelog

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

Bluetooth

Controller

Fixed

• Fixed that functions "coex_enable" and "coex_disable" are not used in pairs on ESP32-C3, ESP32-S3 and ESP32-C2 (f39c3b2)

Bluetooth Low Energy

Changed

• Modified the default ACL buffer count to decrease the usage of mbuf used by the bluedroid on ESP32-C2. (7c20c37)
• Used esp timer to implement npl callout by default on ESP32-C2. (7c20c37)

Fixed

• Fixed BLE disconnect due to channel map update instant passed on ESP32 (4cc0364)
• Fixed the issue that adv stops abnormally when the same device initiates two connections on ESP32-C2. (564b94f)
• Fixed the issue of abnormal reporting of connection update complete event on ESP32-C2. (564b94f)
• Fixed the occasional assertion when the controller is disabled on ESP32-C2. (564b94f)
• Fixed flow control count error on ESP32-C2. (564b94f)
• Fixed hci uart flow ctrl error on ESP32-C2, ESP32-H4 (2ab97d5)
• Fixed task watchdog timeout issue when the hci uart is closed on ESP32-C2, ESP32-H4 (2ab97d5)

Bluedroid

Fixed

• Fixed Bluedroid compile errors after setting CONFIG_ESP_SYSTEM_USE_EH_FRAME=y on RISC-V SoCs (9718c91)

Removed

• Removed -Wno-format compile option for bluedroid classic bluetooth examples (15b160a)

Classic Bluetooth

Added

• Added status parameter for AVRCP passthrough command response event to make user notified of the response code from AVRCP target. (fe743a0)

Fixed

• Fixed memory leak in AVDT delay report. (f944418)
• Fixed the error the module HFP-AG used an out-of-bounds array index. (cf7a01c)
• Fixed HID Host bug when handling the two consecutive connection request (41e52fc)
• Fixed status parameter for SDP_CREATE_RECORD_USER_EVT get overridden due to use of union.(#10607) (3d80d4b)
• Fixed build errors when sniff subrating is enabled. (8439e61)
• Fixed crash caused by accessing nullptr in btm_acl_disconnected (11c6594)

Bluetooth Low Energy

Added

• Examples: Support BLE notify and write throughput test at the same time (e9092c2)
• Support BLE privacy by controller (4cc0364)
• Added parameters for GATT connect event (4cc0364)

Fixed

• Examples: Fixed BLE address type of advertising and scan parameters (4cc0364)

NimBLE

Added

• Added custom GATT server functionality and encryption(c35de0c)
• Added ble_gap_ext_adv_active() to check if extended advertising instance is active or not. (273b1b3)
• Added debug related code under debug flag to improve throughput (b837e91)
• Added code to retry for memory allocation if previous allocation attempt fails for a Rx packet handling. (#10849, 10010b1)
• Added pcl demo in blecent app (0c1e80f)
• Added return value (success / failure ) to nimble_port_init (358ed1a)

Changed

• Updated functions related to adding and clearing peer_dec_rec table. (008a4dc)
• Updated example configuration setting for BLE ext advertising. (df0ec3f)
• Changed the component path to relative in IDF examples ( #10797, 8ebb509)
• Updated bleprph example to re-enable ext adv after adv is completed (8644754)
• Update ble_l2cap_coc example to handle memory double free issue(d4eebd5)

Fixed

• Fixed clearing of connection_handle array in spp_server example (8a83241)
• Fixed advertising instance check api in bleprph example (63983fb)
• Fixed README of SPP server (1ea59bd)
• Fixed compilation issues for ESP32-C6 / ESP32-H4 chips ( a9af208 )
• Fixed runtime assertion in bleprph due to two disconnect events ( b29c869)

Removed

• Removed global min/max definition (5ca38da)

Blufi

Fixed

• Fixed vulnerability attacks that could cause heap overflow in fragmented Blufi packet processing (e9092c2)
• Fixed hdr getting freed twice while using blufi (b94db7a)

ESP-BLE-Mesh

Fixed

• Transmit Transaction ACK before closing provisioning link by Provisioner (c86f48a)
• Send Link Close message before resetting provisioning link by Provisioner (c86f48a)

Wi-Fi

Changed

• Changed the log level of abnormal beacons to debug (6dc6b57)
• Improved the handling of station SA query procedures (63994a2)

Fixed

• Added fixes for potential null pointer dereference in wpa_supplicant (89bb920)(122dd1e)
• Added validations for Suite B Enterprise connections (e3778fa)
• Fixed the initialization of EAP methods during reassociation (e3778fa)
• Stored some station config parameters in NVS (7cf3f99)
• Fixed the default WPA2 cacheing PMK recalculation (faad05c)
• Improved connection management in STA and SoftAP (89bb920)
• Buffered deauth, disassoc, and action frames for stations in sleep mode (89bb920)
• Fixed an issue with espnow unexpectedly entering modem sleep on ESP32-C2 (7d5c6b9)
• Fixed a typo in the wifi_enterprise example README (#10042 3d3df29)
• Fixed a bug where sending two M1 WPS EAP messages with different enrollee nonces in response to an expanded WPS request (1f73b5e)
• Fixed processing of association response in OWE mode (04f04d6)

Removed

• Removed -Wno-format compile option from Wi-Fi related examples. (fa4dccb)(3132e45)(224b320)

ESP-WIFI-MESH

Changed

• Updated the discard context condition and the process disconnect condition (2048d1e)
• Updated the mesh documentation (2048d1e)

Fixed

• Fixed the bug where esp_mesh_is_root() returned an error when setting the root type (2048d1e)
• Fixed the bug where users couldn't set inactive time on mesh root (2048d1e)
• Fixed the bug in setting idle type (2048d1e)

Security

Added

• Added new APIs to confirm that all eFuse security features are enabled correctly in bootloader. (8a6fb6d)

Changed

• Updated documentation regarding input endianness required by esp_ds API (#10391)
• examples: Enabled security/flash_encryption example for ESP32-C2 (30058e3)

Peripheral Drivers

Added

• ADC: Supported calibration on ESP32-C2 (f58f811)
• esp_hw_support: Reduced power consumption of some ESP32-S3 chips (763e369)
• MCPWM: Support keeping the GPIO configuration when deleting the MCPWM capture channel ( #10327)
• MCPWM: Support configure MCPWM generator actions one by one, without using variable length argument lists (#10449) (3f68b61)
• USB Host: Added SetAddress() recovery time. Added possibility to configure Root Hub Configuration (delay values) via menuconfig. (5919c3f)

Changed

• GDMA: Changed the UHCI GDMA trigger ID from SOC_GDMA_TRIG_PERIPH_UART0 to SOC_GDMA_TRIG_PERIPH_UHCI0 (27ca654)
• LEDC: Moved the callback in ledc_fade example to IRAM (#10402 2b14b7d)
• LCD: Changed RGB endian in LCD SPI example, when used with ILI9341 controller (#10242, d3b1ae1)
• TinyUSB: Use latest compatible version of TinyUSB from IDF component manager (8ae1ed5)

Fixed

• ADC: Fixed continuous mode PM lock release fail issue (#10853) (21b42ce)
• ADC: Fixed ADCx_GPIOxx_CHANNEL macros not aligned with new ADC driver issue (#10508) (1990335)
• GDMA: Fixed SPI2 DMA can't work with async memory copy (#10575) (27ca654)
• GPIO: Fixed the issue that IOs, which are used for deep sleep wakeup, keep staying in holding state after waking up. These IOs can now be re-configured. (#10921) (55e040b)
• GPTimer: Fixed potential race condition between timer start and stop (b7ca432)
• GPTimer: Acquire ESP_PM_NO_LIGHT_SLEEP pm lock for XTAL clock source. (92b1f4f)
• I2S: Fixed wrong interrupt allocation flag (#10997) (ef4b1b7)
• I2S: Fixed PDM TX frequency 48kHz limitation (#10420) (3050ea6)
• I2S: Fixed i2s tx/rx update failed issue (f603aa7)
• I80_LCD: Fixed the issue that PLL240M clock source is not allowed to use by ESP32-S3 i80 LCD (4ec2823)
• SPI: Fixed micro SPI_HOST_MAX error on target ESP32-C2/ESP32-C3 (#10349) (db8b56c)
• SPI Slave: Fixed SPI slave IO pin not released after deinitialize. (385ca5a)
• MSPI: Fixed timing turning issue on high frequency lead to crash when entering sleep on ESP32S3 (d8d6d3d)
• spi_flash: Fixed compute size wrongly for > 256MBit (#9566) (c575587)
• SDM: Fixed potential memory leak. (ac02376)
• TWAI: Fixed a HW errata where the TWAI controller could still send dominant bits when placed into listen only mode. The errata workaround is enabled by default via the CONFIG_TWAI_ERRATA_FIX_LISTEN_ONLY_DOM option. (fd707e1)
• RMT: Fixed wrong buffer memory allocation in the legacy RMT driver (#9487) (6b08f05)
• RMT: Avoid auto light sleep if RMT clock source is XTAL (10dd0cc)
• PSRAM: Fixed wrongly detecting Octal PSRAM issue on ESP32-S3. Now an error will be returned. (4cd4762)
• Touch Sensor: Fix touch sensor filter failure caused by static ram not zeroed on ESP32 (d759ee5)
• UART: Increased default stack size for nmea example (#11044) (e715f0f)
• UART: Fixed concurrency which could cause ESP_ERR_TIMEOUT when calling uart_wait_tx_done due to the TX_DONE interrupt bit being wrongly cleared in the task instead of triggering the ISR. (8f202f0)
• UART: Fixed concurrency which could cause RTS line being mis-reset while tx transmission is not done in RS485 mode. (8f202f0)
• HAL/UART: Fixed UART LL functions can't compile with cxx on ESP32-S3 (#10640) (6b397d5)
• USB Host: Fixed a race condition in USB Host Stack HAL where halting a pipe/channel right when it completes a transfer could result in the pipe/channel not being halted. (6a86124)
• USB Host: Fixed a bug in usb_host_transfer_submit_control() where the internal control transfer argument checking would always assume control transfers were OUT transfers. (6a86124)
• USB Host: Fixed issue where the Hub driver would fail at GET_SHORT_LANGID_TABLE on some devices. Fixed by ensuring that a LANGID of 0 was used when fetching the LANGID table itself. (75b7202)
• USB Host: Fixed issue where the Hub driver would attempt to fetch Manufacturer/Product/Serial string descriptors even if the device does not support them, leading to a STALL on the control endpoint. Hub driver will now only fetch string descriptors if they exist. (75b7202)
• USB Host: Fixed interface descriptor parsing for interface numbers >= bNumInterfaces (75b7202)

Removed

• TinyUSB: Removed sample_descriptor example (6a86124)

Core System

Added

• heap: Added size and capabilities information to the log printed during system abort when an allocation fails (#10650) (5b718a8)

Changed

• ULP: Updated ULP ADC example struct initialization to be compatible with C++ (#10970) (04758d2)
• rtc time: Reenabled esp_rtc_get_time_us for ESP32-C2 (335ad04)
• esp_hw_support: Changed physical memory protection on ESP32-C2 to allow writing in IRAM when memory split is disabled. (18bda1b)
• esp_hw_support(esp32): If the MAC_FACTORY CRC check fails, then esp_efuse_mac_get_default returns INVALID_CRC instead of aborting (#10401) (08283c2)

Fixed

• psram + virt eFuse: Fixed issue when the eFuse virt mode has not ready yet but psram init func reads efuses (#10925) (bf082dc)
• sleep: Fixed GPIO wakeup not working properly in some cases (4abb6ef)
• sleep: Fixed ESP32-C2's 8md256 configured as rtc slow clk can not work properly during deep sleep (335ad04)
• Sleep: Fixed build errors regarding the usage of the ESP_PD_DOMAIN_RTC_PERIPH on targets that don't support selective RTC power control. (e68bc99)
• MMU: Fixed "g0 build needs CONFIG_MMU_PAGE_SIZE" issue (491800f)
• MMU: Fixed IRAM/DRAM addr range in ext_mem_defs.h (da46d21)
• heap: Fixed heap_caps_get_allocated_size() return value when poisoning is active to not account for canary head and tail. (53c66a6)
• heap: Fixed allocation failure when allocating memory as IRAM in the startup stack region when memory protection is enabled (c71f9a3)
• ULP-RISC-V I2C: Fixed an issue where the ULP RISC-V I2C example caused a spurious wakeup of the main CPU on esp32s2 and got stuck thereafter. (#10301) (bca7446)

Debugging

Added

• espcoredump: Added support for stacks in external RAM for all targets. (82458fd)
• GDB Stub: Added support for GDB Stub on ESP32-C2 (86a75d1)

Fixed

• Fixed coredump chip-id for ESP32-C2 (66f5a4a)
• Fixed a bug on Xtensa targets that triggered an exception when using coredump custom stack. (886e98a)

FreeRTOS

Changed

• Updated documentation so clearly indicate that ESP-IDF FreeRTOS and Amazon SMP FreeRTOS are two separate FreeRTOS implementations supported by ESP-IDF (fc3f49d)

Power Management

Fixed

• Fixed the sleep time inaccuracy bug when selecting 8MD256 as RTC slow clock on ESP32 (#6687) (69dd34d)
• Fixed the incorrect RTOS tick when XTAL powers up during sleep on ESP32-C3 (7d5c6b9)
• Fixed string formatting build error if CONFIG_PM_PROFILING is enabled (#10347) (e68bc99)

newlib libc

Fixed

• Fixed the issue that errno was not set properly in adjtime (#10334) (2aed3d6)
• Fixed wrong mutex types being used for env and tz (#10649, #9441, #10626, #10686) (41bf6da)

Removed

• Removed tests using RTC related features from the ESP32-C2 test set. (d33d3d7)

LWIP

Added

• Added api to enable/disable napt based on lwip netif (6dc6b57)

Changed

• Optimization dhcp coarse timer (6dc6b57)

Fixed

• esp-netif: Fixed thread-safety violations when accessing TCP/IP core functionality (e8205de)
• Fixed forwarding multicast packets on some routers (6dc6b57)
• Fixed DHCP server's bug allowing the assigned IP addresses to exceed the configured subnet range (6dc6b57)
• Fixed TCP (Out of order segments) to incorrectly trim a segment when FIN flag was moved (6dc6b57)
• Fixed addrtype and length in gethostbyname (6dc6b57)
• Fixed ondemand fine timers bug, that allowed only one dhcp (6dc6b57)

TCP Transport

Added

• Added HTTP authorization header in websocket client. (22a45d2)
• Added new API esp_transport_ws_get_upgrade_request_status to get http status code from server (4c606d3)

HTTP Client

Fixed

• Prevent infinite loop with the disable_auto_redirect case (#10629) (d56a6e1)

HTTP Server

Fixed

• Fixed return values for httpd_socket_send() and httpd_socket_recv() APIs (a823a49)

Provisioning

Added

• protocomm: Added a new ble_link_encryption flag in protocomm_ble_config_t to enable users to consume the protocomm component independently of any other component (#9443) (4fc89f4)

Fixed

• wifi_prov_mgr: Fixed return value of characteristic read operation in nimble (#10888)
• wifi_provisioning: Stop provisioning service in the default event loop rather than a separate task (#10378) (7863864)

mbedTLS

Added

• Added and refactored sanity checks and their return values (395b682)

Changed

• Updated mbedTLS to v3.3.0 (b289b7a)

Fixed

• Fixed data corruption issue in the MPI H/W peripheral when COMPILER_OPTIMIZATION_PERF is enabled (#10403) (f31e3c1)
• ecc_accelerator: Fixed ECC point multiplication in case of short scalar values (dcae357)

Bootloader

Fixed

• Fixed potential bootloader and app overlap issue on ESP32-C2 and ESP32-C3 (0a5ed6f)

ESP-TLS

Fixed

• Fixed build issue when server session tickets have been enabled (#10765) (83e7710)

Storage

Changed

• NVS: made all object allocations "noexcept" (416ada0)

Fixed

• VFS: Fixed usb_serial_jtag console block issue when no data to transfer (#10208) (76c8f09)
• nvs_flash: Fixed potential memory leak in nvs::Storage::init() (319208c)

Tools

Added

• Added support for "set -u" bash option in export.sh script (#10935) (58f24af)

Changed

• Improved idf.py error message when the argument value collides with the environment variable (#10475) (ca16d12)
• partition_table: Allow 4K aligned APP partition size for secure boot v2. This allows to use remaining space after signature block (worth 60K) for other data partitions. (962d716)

Fixed

• Don't add the esptool directory with wrappers to the PATH (#10926) (7398a9b)
• Fixed export.fish return code (#10828) (1ed1d1c)
• Allow custom Python installation path set with IDF_PYTHON_ENV_PATH environment variable (#10489) (d7cc519)
• Fixed "idf.py gdb" memory access before remote target is connected (6b1869b)
• Fixed riscv32-esp-elf-gdb not being installed if dependencies for only ESP32-C2 were installed (d576146)
• Fixed an issue where on Windows --build-dir and other directory related options would result in creating folders with lowercase names (#10282) (db7348e)

Build System

Fixed

• Fixed build failure when SDKCONFIG_DEFAULTS was set in environment using a relative path (188f118)

Documentation

Changed

• ULP: Corrected description for ULP FSM JUMPR and JUMPS instructions. (#10923) (e14c47e)
• Updated WiFi AMSDU docs. (5fca587)

Fixed

• Fixed a reference to check_kconfigs.py, it now lives in tools/ci (#10922) (2ce6dda)
• Fixed strapping pin number in api-reference/peripherals/gpio.rst (84d6cce)
• Fixed a broken link in API Reference > Peripherals > MCPWM for ESP32 (33ba447)
• UART: Updated wrong referenced function name uart_enable_pattern_det_intr in programming guide (#10856) (6f74272)