Documentation for release v4.1 is available at https://docs.espressif.com/projects/esp-idf/en/v4.1/
ESP-IDF v4.1 is a minor update for ESP-IDF v4.0. ESP-IDF v4.1 will be supported until February 2023 in accordance with the ESP-IDF Support Policy.
Note: This is the first ESP-IDF release since the Support Policy was updated to change all ESP-IDF stable release support periods to 30 months. Previously this support period only applied to designated "Long Term Support" releases.
This is the list of changes since release v4.0:
Major New Features
- Wi-Fi: Added support for Protected Management Frames (PMF)
- Wi-Fi: Added SAE authentication support for WPA3 Personal
- New Python-based
menuconfig tool
- Networking: Added new esp_netif API to manage network interfaces, replaces tcpip_adapter which is now deprecated.
- Classic Bluetooth: Added support for Hands Free Profile (HFP) Audio Gateway (AG)
- DTLS support in libcoap using mbedTLS (https://github.com/espressif/esp-idf/pull/3977)
- Secure Boot V2 support (RSA based) added for ESP32 V3
- Preview support for ESP32-S2 Beta SoC. This support will be replaced with ESP32-S2 SoC support in ESP-IDF v4.2. ESP32-S2 Beta firmware is not compatible with the ESP32-S2 production SoC, and not all features are supported.
Major Bug Fixes
- Security fix: Fixed AP switch to adjacent channel without disconnect (-12638)
- Updated toolchain fixes for PSRAM issue in ESP32 revisions prior to V3 (note: there is a known issue with this fix, see below.)
Breaking Changes
- As part of the fix for -12638, the event
WIFI_EVENT_STA_AUTHMODE_CHANGE has been removed. STA will now disassociate (with reason WIFI_REASON_AUTH_CHANGED) and reassociate in this case.
Known Issues
- The
esp-2020r2 toolchain has been added in this release which includes some fixes for C++ exceptions, a fix for -O2 optimization of volatile word accesses, and an improved PSRAM fix. Extended stress testing of Wi-Fi & BT coexistence with heavy PSRAM use show there is a difficult to reproduce issue with the updated PSRAM fix. It is possible to roll back to the esp-2020r1 toolchain release by running git revert --no-edit 298f23c9 in the ESP-IDF directory, then re-run the install.sh/install.bat/install.ps1 and . export.sh/export.bat/export.ps1 steps as described in the Get Started guide. This issue will be fixed in the v4.1.1 release.
- A new macro to call a function with a user-allocated stack has been added but is non-functional
- Using ADC in DMA mode does not work correctly
- Can not correctly config IPv6 segmentation and reassembly from menuconfig
- Nimble doesn't support non-resolvable private address
- Watchdog timeout when using an RSA 4096-bit key to connect to WPA2-Enterprise (EAP-TLS) AP.
- CAN driver doesn't work correctly if assertions are disabled in menuconfig
Bluetooth
Controller
- Added API to query the number of available buffers for the current connection
- Improved handling of calloc() failure
- Fixed HCI timeout issues when using multiple cores and sleep is enabled
- Fixed BLE crash issue triggered by BLE event interrupt missed
- Fixed bugs related to role switch
- Fall back to main XTAL as Bluetooth sleep clock source if the External 32kHz crystal is configured but not detected
- Fixed a division by zero error in BT sleep clock cycle calculation
- Fixed software assertion of invalid state when using HCI_Create_Connection_Cancel command
- Fixed LMP timeout issue when handling LMP_sniff_req
- Fixed the issue of repeatedly sending LMP_features_req_ext
Bluedroid
- Fixed bug with fixed_queue semaphore pointer dereference
- Fixed potential memcpy buffer overflow problem
- Fixed wrong complete Identity Address (Public Address) of the Privacy-enabled Bonded Device got after bonding
- Fixed the issue with pointer type conversion in gattc
- Added missing GATT descriptors 0x2909 (Number of Digitals) through 0x290E (Time Trigger Setting) (https://github.com/espressif/esp-idf/pull/4082, https://github.com/espressif/esp-idf/pull/4470)
- Fixed some spurious uninitialized variable warnings when optimization level set to Performance
NimBLE
Classic Bluetooth
- GAP: Added new
esp_bt_gap_read_remote_name() function to get remote device's Bluetooth name at any time
- GAP: Fixed error on EIR type in Config EIR event
- HFP: Added Audio Gateway (AG) support
- HFP: Added AT+NREC=0 command for disabling AG echo cancellation (https://github.com/espressif/esp-idf/pull/3665)
- HFP: Fixed crash on incoming audio
- HFP: Fixed connection fail and crash when receiving unknown AT command
- HFP: Fixed AG audio crash (change the return position)
- A2DP: Fixed assertion for de-initializing A2DP while audio streaming is ongoing
- AVRC: Fixed AVRC metadata length error
Bluetooth Low Energy
- Fixed BLE throughput wasting memory
- Fixed the BLE throughput client crash when enable the CONFIG_GATTC_WRITE_THROUTHPUT option
- Fixed client no BLE_AUTH_CMPL_EVT when client proactively initiate an encryption request after device restart
- Fixed notify malloc failed when testing multi-connection notify performance
- Fixed btc disable crash sometimes
- Fixed don't dequeue the command queue after process the read_by_type_req
- Add BLE API to set channel classification
- Added support to enable Peripheral Preferred Parameters in GAP service
- Fixed data loss and send same pkt twice sometimes
- Fixed adv data error in air sometimes
- Fixed adv start/stop crash sometimes
- Fixed the wrong mask value according to HID protocol
- Fixed GATTC trigger open event multiple times
Blufi
- Fixed the wrong type from
BLUFI_TYPE_DATA_SUBTYPE_SOFTAP_MAX_CONN_NUM to BLUFI_TYPE_DATA_SUBTYPE_SOFTAP_CHANNEL
- Fixed blufi prepare write buf len invalid
- Reply with an error response when the format of the received data packet is wrong
- Check if BLE is connected before sending a message via BLE
ESP-BLE-Mesh
- Miscellaneous modifications for Provisioner
- Support Provisioner persistent functionality
- Add a function to set Provisioner static oob value
- Add a function to set Provisioner unicast address
- Add a function to provision devices with fixed address
- Add a function to store node composition data
- Add a function to get node with device uuid
- Add a function to get node with unicast address
- Add a function to delete node with device uuid
- Add a function to delete node with unicast address
- Add a function for Provisioner to update local AppKey
- Add a function for Provisioner to update local NetKey
- Fix Provisioner entering IV Update procedure
- Fix Provisioner failed to publish messages
- Provisioner ignores msg from removed node
- Fixed Provisioner provisioning deadlock
- Checks if the AppKey exists before deleting it
- Updated next allocated address when node info is added
- Synchronized a few Zephyr BLE Mesh updates
- Support using a specific partition for BLE Mesh
- Add a function to de-initialize BLE Mesh stack
- Fixed use-after-free issue when de-initialize mesh
- Fixed not free beacon timer when de-initialize mesh
- Fixed de-initialize error when using NimBLE host
- Supports using SPIRAM for BLE Mesh dynamic memory, queue, etc.
- Fixed compile error when using performance optimization level
- Fixed compile error when including from C++ files
- Made RSSI value available to mesh applications
- Fixed reset transport info when node is removed
- Now allows sending maximum 377 octet payload
- Now uses lock for mesh timer operations
- Fix an issue which may cause client failing to send msg
- Added check of the result of creating mesh timer
- NULL can be used if client message has no parameters
- Unified client application and lower transport layer timeout
- Removed timeout for client message to non-unicast address
- Fixed timer start when sending client message
- Fixed client local parameters not initialized
- Calculates incomplete message timeout based on message info
- Added check of buf->ref before decrementing buffer ref count
- Sensor models related miscellaneous fixes
- Update the ESP BLE Mesh examples hierarchy
- Added BLE Mesh vendor models examples
- Added BLE Mesh sensor models examples
- Added BLE Mesh whitelist test functions
- Added option to send normal BLE advertising packets while connected to mesh
- Changed to continue node info restore even if failure happens
- Added check if assigned node address is duplicated
- Removed BLE_MESH_MAX_STORED_NODES option
- Associates replay protection list size with nodes count
- Fixed time scene wrong spelled macro name
- Add length check for some mesh operations
- Fix not erasing mesh node information completely
- Added a option to fix mesh node nvs information restore
- Now initializes mesh node device name during proxy server init
- Fix using old menuconfig options for mesh duplicate scan
Wi-Fi Coexistence
- Fixed A2DP disconnect when Wi-Fi switches channels
- Fixed A2DP stuck after creating another connection
- Improve Wi-Fi TX & RX performance
- Fixed wakeup delay when DFS is enabled
- New API
esp_coex_ble_conn_dynamic_prio_enable() allows configuring BLE/W-Fi relative priority in coexistence
- Optimize WiFi/BT coexist sleep
- Adjust coexist scheme when BT is in connected status
Wi-Fi
- Added PMK caching feature for WPA2 Enterprise stations
- Added support for Protected Management Frames (PMF)
- Added SAE authentication support for WPA3 Personal
- Fixed AP switch to adjacent channel without disconnect (-12638)
- Wi-Fi now uses new esp_event library added in ESP-IDF v4.0
- Fixed wpa_supplicant EAP re-authentication issue
- Fixed wpa_supplicant assoc_ie_len setting based on generated RSN/WPA IE
- Fixed EAPOL key used during reauthentication
- Fixed memory leak on Wi-Fi stop
- Added wpa_supplicant parsing support for WEP40 key
- Fixed esp_wifi_set_max_tx_power description
- Added new API
esp_wifi_ap_get_sta_aid
- Disabled wpa_supplicant TLS 1.2 support by default due to issues with some Enterprise Authentication Servers. This option can be enabled in menuconfig.
- Fixed wpa_supplicant memory leaks and invalid memory access
- Added check for Wi-Fi stop when calling esp_wifi_deinit
- Now places the Vendor Specific element at the end according to the protocol
- Fixed crash during WEP shared auth
- Fixed WiFi buffer reload that WiFi receiving no longer works because internal buffer reloading fails
- Fixed WiFi receiving that WiFi receiving no longer works because it writes the MAC registers when WiFi/BT common clock is disabled
- Fixed WiFi performance, including AMPDU parameter negotiations, WiFi TX optimization etc
- Fixed AMSDU decrypt that ESP32 can't decrypt the AMSDU if it's encrypted
- Reduced Wi-Fi compiled binary size
- Added TX packet length checking, Wi-Fi driver will drop a packet which is too long
- Improved RSSI scan accuracy
- Now returns an error if the setting AP's channel is out of range
- Fixed sniffer during WiFi mode switching
- Reduced Wi-Fi compiled binary size
- Throughput improvements
- Fixed Wi-Fi receive failure due to internal buffer reload failure
- Fixed some Wi-Fi timer issues
- Fix crash caused by too big of association request RSN information
- Fixed setting channel when Wi-Fi is in NULL mode
- Fixed the soft-AP incorrectly updates the second channel
- Fixed AP switch to adjacent channel without disconnect
- Added soft-AP example channel configuration
- Fixed beacon timeout and station fails to connect to AP sometimes when WiFi and Bluetooth run together
- Fixed the station can't get the IP address from China Mobile router
- Fixed a timeout issue in the EAPOL four-way handshake
- Added softap example channel configuration
- Placed the Vendor Specific element at the end according to Wi-Fi spec
- Fixed the bug for softAP update second channel wrong
- Fixed internal scan data struct definition, changed wifi_scan_time_t from union to struct
- Fixed country code query when policy change from manual to auto
ESP-WIFI-MESH
- Remove coexist warnings for mesh.
ESP-NOW
- Fixed unicast packet TX failure
- Fixed randomly crash (https://github.com/espressif/esp-idf/issues/4311)
- Fixed modifying the channel info of peer node
- Fixed the crash when modifying peer node between unencrypted and encrypted
- Fixed the bug for fetch peer
- Fixed the bug that the channel parameter doesn't work when adding peer node
Smartconfig
Ethernet
- Fixed Ethernet interrupt crash when cache is disabled. New flag
ETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE introduced to support Ethernet MAC continuing to operate while cache is disabled.
- Ensure that eth_driver handle is allocated in internal RAM (https://github.com/espressif/esp-idf/issues/4635)
- Ensure that calling
esp_eth_stop() stops the EMAC hardware layer
- Improved reliability of ethernet driver start/stop/uninstall/install
Peripheral Drivers
- Most drivers have been refactored internally, however public behaviour of existing APIs should be the same as in ESP-IDF V4.0
- Added option to place UART ISR in IRAM
- Added new ESP Serial Slave Link library to communicate with serial slave devices via SDIO or similar interfaces
- CAN: Fixed can_reconfigure_alerts() function taking semaphore in a critical section
- CAN: Fixed possible logging in critical sections
- CAN: Added bitfields to
can_message_t as an alternate way to set CAN message flags.
- I2S: Fixed compile error if FreeRTOS header not included before I2S header (https://github.com/espressif/esp-idf/pull/4251)
- LEDC: Added missing
ledc_set_pin() function declaration
- MCPWM: Fixed off-by-one error when setting period
- SDSPI & SDMMC: Fixed
gpio_pin_bit_mask truncation to max GPIO value 31
- PSRAM: Added support for 2T mode
- UART: Added simplified API to set threshold values for RX FIFO full and TX FIFO empty
- SPI: Fixed bug where spihost handle could be allocated in PSRAM
- SPI_SLAVE: Fixed assertion failure when
spi_slave_initialize failed with DMA channel equals zero (https://github.com/espressif/esp-idf/issues/2740)
- TIMER_GROUP: Fixes the interrupt enable/disable of timer groups
- SIGMA_DELTA: Fixed the cpp guard in the header file
Core System
Debugging
- core dump: Default Core Dump data format is now ELF (configurable)
- core dump: Disable core dump to flash if stack in PSRAM option is enabled
- panic handler: Moved some panic handler code into flash to reduce IRAM usage, cache will be re-enabled in panic handler if necessary
- panic handler: Fixed printing of ELF file if cache is disabled
FreeRTOS
- Reduced interrupt cycle overhead by using window overflow and underflow exceptions to speed up Xtensa register spills to the stack
- Added support for including FreeRTOS headers using the traditional header paths, instead of requiring
freertos/ prefix
newlib libc
- Fixed linking of newlib nano from ROM only if PSRAM cache workaround is disabled
LWIP
mDNS
Provisioning
- NimBLE: Fix bug in
protocomm_nimble chararcteristic access callback
- Unified Provisioning: Fixed BLE characteristics read response issue when read response length is a multiple of () length
- Wifi_provisioning_softap: Allow applications to start webserver externally
- Wifi_prov_manager: Fix to ensure that provisioning status is reliably conveyed to remote host
- Wifi_prov_manager: Fix to ensure Wi-Fi events still received after Connection errors
- BLE: Change service_uuid to non-standard 128-bit UUID
OTA
- Fixed bug where erase size could be one sector too long (https://github.com/espressif/esp-idf/issues/4953)
- esp_https_ota: Added error checking functionalities. A few additional error checking mechanisms have been added which returns the control in case an invalid header is received, and a wrapper to the
esp_http_client_is_complete_data_received() function of esp_http_client has been added.
- esp_https_ota: Fixed OTA when using a server with chunked HTTP encoding
- esp_https_ota: Added errno check for network disconnection when performing OTA
HTTP Client
mbedTLS
- Added new fast Montgomery exponentiation implementation for RSA accelerator. Significantly improves ESP32 RSA performance (especially public key operations)
- Don't allow disabling ECDSA support in mbedTLS config if app image signature checking is enabled
- Fixed incorrect compilation of MPI accelerator functions when hardware support is disabled (https://github.com/espressif/esp-idf/issues/5321)
ULP
Bootloader
- Added option to skip image validation when waking from deep sleep (incompatible with Secure Boot) (https://github.com/espressif/esp-idf/pull/3304)
- Restructured bootloader initialization, moving target-specific initialization into separate source files
- Fixed bug where bootloader header variable could be linked to an unaligned address, causing boot failure
ESP-TLS
TCP Transport
- Added API to use password protected client keys
- Added functionality to use ALPN with SSL
Websocket
ESP-MQTT
Storage
VFS
- VFS: Check in select() if the UART driver is installed or not
Modbus
- Added support for Modbus ASCII master mode
- Fixed issue re-initializing Modbus controller after call to
mbc_master_destroy()
External Libraries
Tools
Build System
- Added PowerShell versions of "install.bat" and "export.bat" for Windows PowerShell users
- Added
idf.py --cache option and support for setting config variable IDF_ENABLE_CCACHE to permanently enable CCache
- Added minor fixes for
convert_to_cmake.py
- Added new
idf.py --version command
- Allow idf.py and CMake build system to work on FreeBSD (not officially supported) (https://github.com/espressif/esp-idf/pull/2029)
- Added new
idf.py --monitor-baud option (can also set default with IDF_MONITOR_BAUD environment variable)
- Fix IDF_PATH case mismatches on case insensitive filesystems
- Fixed execution order for dependent tasks
- Updated kconfiglib to the upstream version, switch to a Python-based menuconfig tool
- ldgen linker script mapping rules order is now deterministic
- Fixed generation of hex config values for Make & CMake (https://github.com/espressif/vscode-esp-idf-extension/issues/83)
- Updated MSYS2 legacy build environment to use Python 3 (Python2 packages have been removed from MSYS2)
Examples
- http_request: Fixed some non-compliant parts of the HTTP request, made example configurable
- Improved the example behaviour when
esp_restart() is called and Wi-Fi is initialized
- ping: Added new example
- restful server: Added NetBIOS support for discovery
- tcp_server: Fixed unnecessary reopening of listening socket
- efuse: Added example demonstrating efuse API for writing efuses
- ble throughput: Fixed intermittent crash when running the BLE throughput client
- ble hid device: Fixed the wrong mask value based on the HID protocol
- ble hid device: Fixed issue with security info restore when a paired BLE HID device disconnects and then reconnects after a BT Classic HID device has connected
- BLE mesh: Update mesh console example
- BLE mesh: Added BLE mesh vendor models examples
- BLE mesh: Added BLE mesh sensor model examples
- blufi: Changed the Wi-Fi storage mode to default
WIFI_STORAGE_FLASH
- bluetooth: Added HFP Audio Gateway example
- ota: Fixed bug with failing OTA if the connection closed prematurely
- softap example: Added channel configuration
Documentation
- Translated more ESP-IDF Programming Guide pages into Chinese
- Added basic C++ style guide
- Encourage Python 3 rather than Python 2 for new users
- Added Getting Started Guide for Ethernet Kit V1.1
- Added some definitions removed during driver refactoring back to API reference
- Included feedback link in footer of all documentation pages
- Removed duplicate commands and invalid serial port information in description of examples
- Corrected description of ULP instructions REG_WR and REG_RD
- Added caveats about using JTAG debugging with hardware security features
Obtaining v4.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 v4.1 --recursive https://gitee.com/EspressifSystems/esp-idf.git esp-idf-v4.1
cd esp-idf-v4.1/
This is the recommended way of obtaining v4.1 of ESP-IDF.
Download an archive with submodules included
Attached to this release is an esp-idf-v4.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/dl/esp-idf/releases/esp-idf-v4.1.zip
Espressif Systems
