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

ESP-IDF v5.3.1 is a bugfix release for ESP-IDF v5.3.

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

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

Download an archive with submodules included

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

Major changes

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

Known Issues

• For ESP32-P4, the data in PSRAM will be destroyed during lightsleep.
• For ESP32-P4, CPU frequency switching has become slightly slower when the DFS is used.

Changelog

15.4

Thread

Added

• Added a task switching lock holder check (e1f066e)
• Supported changing openthread version information (dc7fb34)

Changed

• Made ot task queue sending non-permanent blocking (be5feaf)
• Updated CONFIG_LWIP_IPV6_NUM_ADDRESSES to 12 in Thread BR lib (be5feaf)
• Updated openthread submodule (f32c18b) (dc7fb34)
• Move the registration of UART VFS devices to UART initialization function (c2d5712)

MAC

Added

• Added a frame length check for the transmition frame (23e2b6a)

Fixed

• Refactored the next_operation() logic to avoid some risks when multiple IEEE802154 events are processed in one ISR (23e2b6a)

Application Utilities

Fixed

• Provisioning: Exposed API to set BLE random address (8795e7a)
• Provisioning: Fixed incorrect input decoding when using console transport (f0ba6eb)
• ESP HTTP Client: Fixed allocating if_name in client context multiple times (#13945) (86b9fb7)

BLE

Changed

• Documentation: Revised and improved Bluetooth Controller && VHCI API references for ESP32. (25ff0fb)

Bluedroid

Added

• Added support for BLE 5.0 instances in related events (1fa25ff)
• Added the check for setting BLE advertising parameters when deleting GATTS services (1fa25ff)
• Added definitions for BLE authentication failure reasons. (638577b)

Changed

• Optimized BLE event reporting time for connection failures (67b0e9b)

Fixed

• Reset BLE security parameters during initialization (#13869) (883ee8b)
• Fixed incorrect state issue when unregistering BLE GATTC application. (530f10f)
• Fixed the issue where BLE could not create a connection if the controller doesn't support the coexistence of scanning and connection initiating states. (b81f351)
• Fixed BLE security vulnerability when using fixed local IRK. (638577b)

Removed

• Removed error print when failing to remove a device from the resolving list. (638577b)

Controller

Added

• Supported UHCI function on ESP32-C6 and ESP32-H2. (0efdd4a)
• Added support for configurable default TX power on ESP32-C6, ESP32-H2, and ESP32-C2. (0efdd4a)
• Supported mesh duplicate with extended scan on ESP32-C3 and ESP32-S3. (2ea1eff)

Fixed

• Fixed the issue where directed advertising could not be connected when the advertisement filter was set to 0x2 on ESP32-C6, ESP32-H2, and ESP32-C2. (bbe0750)
• Fixed occasional WDT issue in multi-connection scenarios on ESP32H2. (bbe0750)
• Fixed the issue where connected advertising could still be set after reaching the maximum number of connections on ESP32-C6, ESP32-H2, and ESP32-C2. (bbe0750)
• Fixed response timeout triggered when updating connection parameters on ESP32-C6, ESP32-H2 and ESP32-C2. (bbe0750)
• Fixed a low-probability assertion issue in adv and scan coexistence scenarios on ESP32-C6. (bbe0750)
• Prevent BLE interrupt from being preempted on ESP32-C3 and ESP32-S3. (2ea1eff)
• Fixed the issue where RSSI is incorrect when the peripheral latency for the connection is not zero on ESP32-C3 and ESP32-S3. (2ea1eff)
• Fixed a memory leak in advertising data after restarting advertising on ESP32-C3 and ESP32-S3. (638577b)
• Using system API to alloc BLE interrupt on ESP32-C3 and ESP32-S3. (638577b)
• Fixed BT BB interrupt allocation on ESP32-C3 and ESP32-S3. (638577b)
• Fixed the issue of occasional assertion in multi-synchronization scenarios on ESP32-H2. (0efdd4a)
• Fixed HCI not returning 0x45 when adv interval and data length mismatch on ESP32-C6,ESP32-H2,ESP32-C5 and ESP32-C2. (0efdd4a)
• Fixed occasional cache error crash in DTM process on ESP32-C2. (0efdd4a)
• Fixed occasional assert issue in adv and scan coexistence scenario on ESP32-C6. (0efdd4a)
• Fixed occasional packet loss issue during severe air interference on ESP32-C6 and ESP32-H2. (0efdd4a)

Mesh

Fixed

• Fixed an issue which may cause transmission resources not been released correctly (1316c4b)
• Fixed that some of the advertised segmented message sent to subscribed group address are not transmitted (d4ac547)

NimBLE

Added

• Added support for host with callback option to provide IRK during host init. (d434587)

Changed

• Updated Advertising Tx power levels to match with specification. (c4d4bfd)
• Increased Timer stack size for nimble application to fix timer overflow issue. (e78cd20)
• Updated menuconfig options to consider BLE 5.0 support options. (14135f9)

Fixed

• Fixed BLE security vulnerability when using fixed local IRK (9f7f1f3)
• Fixed the sequence of posting pairing complete event to host (9f7f1f3)
• Fixed issue where cb information passed in connect request was getting corrupted. (9f7f1f3)
• Zero initialized variables to fix incorrect paired device number information received after host initialization. (8595590)

Bluetooth Common

Controller

Fixed

• Fixed Bluetooth disconnect issue after waking up from modem sleep with external 32k crystal on ESP32 (0bbd728)

Build & Config

Removed

• Removed duplicate entry for IDF_TARGET_LINUX from the project Kconfig file. (#14145) (e438c69)

Classic Bluetooth

Bluedroid

Fixed

• Fixed the stack overflow of uTask in bt example spp initiator (d390c6f)
• Fixed the wrong connection handle in the event handler of BTA_JV_L2CAP_READ_EVT(#13847) (35e9a11)

Controller

Added

• Added integrity check for HCI_Link_Key_Selection command on ESP32 (9788842)

Fixed

• Fixed failure of eSCO connection establishment eSCO when connected to two devices on ESP32(#11172) (4a4d20f)
• Fixed uninitialized random number before pausing AES encryption on ESP32 (4a4d20f)
• Fixed not report HCI_Disconnection_Complete event after the controller has initiated a disconnection procedure on ESP32 (4a4d20f)
• Fixed disconnection caused by channel map update in sniff mode on ESP32 (808950a)
• Fixed an assertion in ACL link driver which can be triggered on peripheral SNIFF mode when RX window is adjusted on ESP32. (2e512fb)

Coexistence

Fixed

• Fixed LoadProhibited issue in coexistence scenario on ESP32-C3 and ESP32-S3. (2ea1eff)

Core System

Fixed

• Print backtrace for both CPUs when cache error does not determine CPU (68bdc86)
• Console: Fixed console freeze when USB Serial JTAG is used and input data is received prior to the initialization of the driver (see #13940) (6c52686)
• Newlib: Fixed ROM(P4/H2) nano newlib can not printf float issues (90bb23f)
• Pthread: Fixed pthread join/detach potentially freeing the wrong TLS pointer(#14084) (474a926)
• Watchdogs: Allow XTAL32K WDT only on supported chips (#13955) (3914802)

Debugging

Added

• Core Dump: Include .data, .bss, and heap sections into the core dump (5325cac)

Fixed

• Core Dump: Fixed array out of the bounds compile error (ba3a106)

Ethernet

Added

• Ethernet: Added configuration of SPI Ethernet MAC address based on esp_read_mac in Protocols Connect Example (#13808) (7f1b752)

FreeRTOS

Fixed

• IDF Additions: Fixed an issue where the vTaskDeleteWithCaps() API leaked memory (#14222) (cada05a)
• IDF Kernel: Fixed a bug where the FreeRTOS port layer would incorrectly crash on an assert failure when the system is not in an interrupt context but the port layer determines the opposite. (39a3d54)

LWIP

Fixed

• Fixed compilation error in lwIP undefined reference to if_nametoindex.(#13577) (b82594e)
• ESP Netif: Fixed setting missing IPv6 auto-configuration flag for PPP interfaces if enabled in menuconfig (#13713) (f5e6f72)
• ESP Netif: Fixed esp_netif_get_all_ip6() to return only valid addresses. (7a538b9)

Low Power Features

ULP

Added

• Added option for routing LP-Core prints to HP-Core console uart (fc847a0)
• Added support for ETM events as a wake-up source (5966682)
• Added LP SPI support to the LP Core on esp32p4. (fd6e699)

Changed

• Changed wakeup time calc to use a precomputed tick value, as this calculation cause the binary to pull in software division functions. With this LP-Core binaries now use 1.1k less bytes. (21e23c1)

Fixed

• Fixed ULP_SHARED_MEM address being wrong on P4, causing the stored wakeup time to be overwritten by the stack. (da81652)
• Fixed a bug where an incorrect register was being written to for setting RTC IO output mode for the ULP RISC-V (#14010) (a2d2f30)
• Fixed a bug wherein the RTC I2C peripheral got stuck when performing read or write of multiple bytes (#12235) (ddc482f)
• Fixed an issue where the first I2C read or write failed when using the LP I2C or the RTC I2C peripheral. (#14043, #11608) (93578b5)

Peripheral Drivers

Added

• Touch Sensor: Added a new touch sensor driver for ESP32-P4, which supports frequency hopping. (86bcea6)
• UART: Support UART sleep retention on ESP32-C6/ESP32-H2/ESP32-P4 (e566fff)

Changed

• UART: Shortened uart_read_bytes blocking period when the RX ring buffer is already full (1796220)

Fixed

• ADC: Fixed ADC usage after TRNG init/deinit sequence (#14124) (0526c35)
• Camera: Corrected Cache M2C operations in CSI and ISP_DVP camera controller drivers (b131527)
• GPIO: Fixed the issue that USB DP pin can not disable pullup on ESP32-C6/ESP32-H2/ESP32-P4 (04220bd)
• I2C: Corrected the semaphore release in command loop (#13962) (9fb47d0)
• LCD: Fixed function panel_io_i2c_rx_buffer when called without a command. (6fffc3b)
• LCD: Fixed build errors in cxx project when using the deprecated esp_lcd_color_space_t type (#14029) (0903bcc)
• LCD: Fixed esp_lcd_new_panel_io_i2c build errors in cxx project (#14037) (0903bcc)
• PARL_IO: Fixed cache sync issue of TX channel driver on ESP32-P4. (df5bf8c)
• SPI: Fixed SPI slave segment mode potential interrupt watchdog timeout when mix mount TX and RX (124778f)
• SPI Flash: Fixed broken external flash driver on ESP32-C6/ESP32-H2/ESP32-P4/ESP32-C5 (21147cd)
• USB: Fixed ISOC channels occasionally skipping transfers on ESP32-S2 and ESP32-S3 (c4d3716)
• USB: Fixed ISOC channels abort on error (5f96f87)
• USB Serial JTAG: Fixed issue that rom print will not work if driver is installed (0e2b19b)

Security

Fixed

• AES: Fixed extra cache sync of memory caused due to aligned up size of DMA descriptors (466a392)
• Flash Encryption: Fixed encrypt only image instead of the partition optimisation not being enabled (24c6528)
• Flash Encryption: Fixed flash encryption enablement through bootloader for ESP32-P4 (aa754d4)
• AES: Fixed wrong dma descriptor alignment (2c84e2e)

System Hardware

Added

• PSRAM: Supported APS3204L (a156e28)
• Cache: Supported catching illegal instruction access and load access fault errors from/to cache for ESP32-P4 (8957785)

Changed

• Move RTC initialization before MSPI time tuning to improve stability (18a8fcd)

Fixed

• Fixed non-iram rtc code in early stage on p4 which would cause the xip_psram stuck (4c53b93)
• MMU: Fixed virtual address calculation for sub-region from already memory mapped region (ab6203d)

Toolchain

Changed

• Upgraded qemu version to esp_develop_9.0.0_20240606 (6568f8c)
• Reverted breaking change to <sys/dirent.h> header (adb5d60)

Tools

Changed

• idf_tools.py: Improved the non-fatal warning message about the Python environment (a2056b0)

Wi-Fi

Added

• Added support for broadcast TWT (0df2bb2)

Fixed

• Avoid internal retries for off channel FTM Requests (7ccfd7d)

MAC

Fixed

• Station should ignore FT, Enterprise APs for connection when their capabilities are disabled in sdkconfig (5028896)
• Fixed the issue that esp_wifi_get_config got wrong SoftAP DTIM and CSA count (5028896)
• Fixed the issue that STA can't connect to AP after association refused temporarily by some APs (5028896)
• Fixed the issue of DNS failure caused by continuously initiating connections to the same router(#12315) (5028896)
• Fixed the issue that STA may join bad RSSI AP when APs sort by signal(#13958) (5028896)
• Fixed the issue that SSN update failed when ESP32C6 STA wake up from light sleep. (5028896)
• Fixed ESP32 crash due to too latency of TBTT (5028896)
• Fixed rarely happened issue that Wi-Fi can not RX anymore (5028896)

Mesh

Fixed

• Fixed the issue that XON request timeout constantly when root reboot (#13212) (5028896)

Supplicant

Fixed

• Fixed crash in wifi deinit due to roaming neighbor list lock. (9775832)
• Fixed the issue that deiniting old DPP authentication when config is received. (9a481d8)
• Recomputed keys in OWE in case of mismatched or absent PMKID from association response (ab8e197)
• Fixed the issue that setting WPS status failed when connection fails. (5028896)