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

ESP-IDF v4.2.1 is a minor update for ESP-IDF v4.2.

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

This is the recommended way of obtaining v4.2.1.

Download an archive with submodules included

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

Changelog

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

Major Bug Fixes

• Secure Boot V2: Fixed the manual enablement of Secure Boot V2 (#6050)
• Secure Boot: Fixed crash in app if signature verification fails (#6210)

Known Issues

• NimBLE: This release adds ESP32 Bluetooth controller level fixes for C2H flow control which are dependent on Host level changes. The host level fixes are not part of v4.2.1 NimBLE and hence C2H flow control is broken for NimBLE in this release. If v4.2.1 release is to be used, we recommend to disable Host Flow Control from NimBLE menu ( menuconfig --> Nimble Options --> Deselect "Enable Host Flow Control" ) . If C2H flow control is necessary for your system, please roll back to the stable v4.2 release until the v4.2.2 release is available.

Breaking Changes

• esp_tls_wolfssl: Previously an API named wolfssl_tlsext_host_name was inappropriately used for domain (host) name check.
  In earlier case if the domain name was different than the ISSUER field in the peer's server certificate, then the connection might have succeeded (provided skip_common_name = false). The old API is now replaced with wolfSSL_check_domain_name, which makes wolfSSL to check if the domain name provided matches with the ISSUER name on the peer's server certificate. With this API change, wolfSSL_connect should return a fatal error in case of a domain name mismatch.

Bluetooth Controller

• Reduced IRAM consumption about 300kbytes
• Fixed assert without SW coexist enabled
• Fixed bt controller task watchdog in Wi-Fi test
• Fixed crash in Bluetooth caused by calling esp_restart() function
• Fixed IRAM_ATTR missing in coex mode
• Fixed for C2H flow control parameter check in Bluetooth controller. Required for NimBLE Host flow control to work.
• Modified E8192 ELx200 ELx40 log level to LOGD
• Synchronized multiple branches of bt lib

Bluetooth Low Energy

• No updated fixes

Classic Bluetooth

• Fixed HCI Timeout by 0x40F or 0x41C by freeing ACL RX Buffer in Exchange Memory
• Fixed unexpected LMP timeout problem when rejecting remote device
• Added check for NULL valued combination key to prevent ‘Impersonation in the Pin Pairing Protocol’ Vulnerability (-26555)
• Added protection for ACL-U packet type exchange procedure
• Fixed crash caused by dividing zero
• Fixed bug of modem sleep which may lead to the crash issue "assert(-218959118,0)"

Bluedroid

• Fixed ‘Impersonation in the Passkey Entry Protocol’ Vulnerability: -26558
• Added comments to avoid ‘Authentication of the LE Legacy Pairing Protocol'

Classic Bluetooth

• SPP: Fixed SPP vfs demo crash when use dynamic memory
• SPP: Fixed SPP vfs memory leaks when exception occurs
• Added API to config QoS for Classic Bluetooth ACL link
• Rejected connection request if BD_ADDR of peer is same as ours (-26555)
• A2DP: Added Init & Deinit Event for A2DP
• A2DP: Fixed data stream underrun for A2DP sink
• A2DP: Added Init & Deinit Event for A2DP
• AVRC: Fixed the issue that target unhandles set_player_app_value cmd
• HFP: Fixed the crash issue when bta_hf_client_sco_co_out_data is called
• SPP: Add API esp_spp_stop_srv_scn to stop a specific server
• SPP: Add parameter service_name with event ESP_SPP_DISCOVERY_COMP_EVT
• SPP: Add parameter scn with event ESP_SPP_START_EVT
• SPP: Add parameter scn with event ESP_SPP_SRV_STOP_EVT
• HFP: Fixed crash in btc_hf_arg_deep_copy when name or number is NULL
• Added check for peer device bdaddr to be different than ours when sending conn req to prevent ‘Impersonation in the Pin Pairing Protocol’ Vulnerability

Bluetooth Low Energy

• Support BLE Authorization
• Support BLE Application Layer Encryption key size check
• Support BLE Read Attribute value by UUID
• Support BLE Non-Resolvable Private Address setting
• Fixed BLE incorrect encryption flag setting
• Fixed a potential double free error
• Fixed exl200
• Added btdm_disable_adv_delay() function to enable/disable advertising delay
• Fixed RPA address update error
• Fixed the problem of early release of pointer(p_ccb) in function
• Added connection parameter check
• Fixed ble connection maximum latency is 499
• Disable bluedroid congest error log print
• Fixed add white list failed
• Fixed bluedroid repair faild if the two most significant bits of public address is '01'
• Fixed congest return value
• Fixed BLE read multiple characteristic error when the number of handles is more than 10
• Fixed scan response report length error sometimes
• Fixed vendor hci memory leak

NimBLE

• Fixed some bugs in NimBLE NVS storage and ble_eddystone
• Removed recursive call (apache/mynewt-nimble#857)
• Added missing MYNEWT_VAL_BLE_L2CAP_COC_MPS definition (#5825)

Blufi

• Fixed an error caused by incorrect conn_id parameters
• Added a macro to control the compilation of blufi
• Fixed the issue that sending longer customer data will cause congestion

ESP-BLE-Mesh

• New Kconfig options introduced to reduce code size
• Updated connection parameters used by central
• Fixed wrong description of BLE Mesh server model autorsp flag
• Persistent storage miscellaneous fixes
• Need uuid when adding device for provisioning
• Fixed Node ID adv with wrong timeout
• Added node local netkey/appkey get/add and bind AppKey functions
• Added support of receiving heartbeat messages for Provisioner
• Support using multiple NVS namespaces to store information by Provisioner
• Updated the definition of the macro ARRAY_SIZE
• Use a separate callback for BLE coexistence operations
• Support scanning normal BLE advertising packet
• Enable updating lighting HSL state
• Use different random for each provisioning procedure
• Fixed Proxy Client may fail to resend messages
• Fixed deinit server models with no matching model id
• Synchronized a few Zephyr BLE Mesh updates
  • Fix rpl not check by proxy configuration
  • Store kr phase after value changed
  • Replace the Zephyr integer types with C99 types

Wi-Fi Coexistence

• Changed wifi scan duration from 120ms to 100ms

Wi-Fi

• Reduced image size of Wi-Fi and Bluetooth by not linking coexistence code
• Optimization AP_STAIPASSIGNED now passes the IP through 'event_data'
• Fixed the issue when PMF packets are not sent after mode change
• Added support for 802.1x sha256 auth key mode
• Disabling Menuconfig option "Enable WPA3-Personal" now disables WPA3 code, reduces code size by around 7.7kB
• Replaced internal RSA APIs by mbedtls APIs
• Updated the description for WiFi APIs
• Fixed system crash on scan failure
• Do not check the return value of esp_wifi_connect()
• Fixed smartconfig issue when router replies to arp late
• Updated exception handling for iperf example's scan when no ap was found
• Fixed return type of esp_wifi_deinit when Wi-Fi is not stopped
• Fixed CSA and BAR crash issue
• Used DPORT bus instead of AHB bus to access Wi-Fi MAC and BB register
• Revert to report specific reason code on receiving deauth during 4-way-handshake
• Fixed the issue that Tx A-MPDU parameter is not from peer device
• Changed country code last byte to space instead of \0
• Fixed the issue that Soft-AP cannot forward A-MSDU
• Improved faster WiFi STA connect, avoid 100ms passive scan
• Added FCS failed packets filter
• Adjusted max tx power to 20dBm
• Fixed the issue that the esp_wifi_sta_get_ap_info can't get country
• Updated PHY version
• Fixed the issue that PHY version log could not be disabled
• Added exception handling for iperf example when scan doesn't find any AP
• Fixed resources leaks detected in static analysis
• Unlock mutex for esp_wifi_80211_tx when out of memory.
• Fixed issue that esp_wifi_80211_tx can't be used in ap mode
• Clear hotspot bss when auth timeout happens
• Fixed PMK not saved in NVS for SoftAP for PSK mode
• Fixed the bug for esptouch find hidden AP fail
• Fixed not connect to open AP when WPA3 auth fail
• Fixed issue with hidden AP scans after connecting AP
• Fixed watchdog issue when receiving action frame
• Fixed issue that parameters obtained form RAM cannot be saved to NVS
• Modify not to store the default value in NVS
• Fixed issue of reason code change from 15 to 204 when wrong password is provided
• Fixed esp_wifi_set_config return value error
• Fixed ampdu age timer memory leak

ESP-WIFI-MESH

• Fixed MESH Internal IP example to use esp_netif transmit_wrap functionality per recent WiFi Tx optimisation
• Chain topology: Added chain topology networking IE mesh_chain_assoc_t to esp_mesh_internal.h
• Mesh power save: add esp_mesh_ps_duty_signaling to signal the new duty in the mesh network

Security

• Secure Boot V2: Fixed the manual enablement of Secure Boot V2 (#6050)
• Secure Boot: Fixed crash in app if signature verification fails (#6210)
• Secure Boot: Fixed the issue when the bootloader image size is exactly equal to the size between the bootloader offset and partitions offset when secure boot V2 and flash encryption are enabled (#6236)
• Secure Boot: Fixed the issue which checks the signature block digest instead of the flash digest during OTA validation
• flash_encryption: Fixed the flash_encrypted_write/read issue under 40M psram and 80M spiflash on ESP32 (#6322, #6254)

Peripheral Drivers

• TWAI: Added support for running ISR when cache is disabled
• TWAI: Fixed bug where BRP divider is not zero initialized on the ESP32 ECO3 chip leading to baud rate being halved. (#5442)
• ADC: Fixed the issue that ADC power is affected by Wi-Fi usage
• I2C: Fixed PM lock release in case of a timeout
• PCNT: Fixed issue where only 4 pcnt units (out of 8) could be used on ESP32 (#6366)
• MCPWM: Fixed MCPWM second fault line broken (#6053)
• Freemodbus: Added MB_PORT_PARITY_GET() to propagate UART parity options from mb controller to serial port layer (#6377)
• Freemodbus: Fixed event processing failure after driver destroy
• ADC: Fixed the issue that ADC power is affected by Wi-Fi usage
• SPI Flash: Added config option to override inherited flash size from bootloader header
• I2S: Fixed PDM clock incorrect issue when using APLL (#5127, #5386)
• ADC: Fixed issue of crashing when verbose logs are enabled
• UART: Fixed uart module reset issue (#1202)
• UART: Fixed UART FIFO read on ESP32 with -O2 optimization
• Freemodbus: Added processing of events in one poll cycle
• touch_sensor: Fixed the last touch interrupt state will wake up the next deep sleep process
• touch_sensor: Fixed touch sensor false trigger in sleep mode

Core System

• Fixed default values for all RTC sources in the CONFIG_ESP32xx_RTC_CLK_CAL_CYCLES option
• pthread: Fixed the issue that pthread_mutex_lock_internal is used when pthread_mutex_destroy is used to release mutex, which results in incorrect release of priority inheritance
• Fixed error in reserved PSRAM region if set to 8MB PSRAM size (#5373)
• panic: don't interrupt the backtrace for InstrFetchProhibited exceptions ?
• ESP32-S2: Fixed lightsleep wakeup fail bug when power down rtc_peripheral on
• ESP32-S2: Improved 32k xtal startup time on ESP32-S2
• esp_log: Correct timestamp formatting to unsigned integer type (#6226)
• Fixed possible failure to boot if Stack Smashing Protection was set to Overall mode (#6403)

Power Management

• ESP32-S2: Decreased deepsleep current on ESP32-S2
• Deep sleep: Fixed issue calculating CRC for deep sleep wake stub on ESP32-S2 or ESP32 single core, if RTC is available for dynamic allocation as heap memory
• Deep Sleep: Disabled brownout detector before entering deep sleep on ESP32-S2 (#6179)

LWIP

• Fixed issue for TCP recv assert
• Fixed missing C++ header guards in netdb.h (#5900)
• Enable TCP initial sequence number (ISN) randomization hook
• esp_netif: Fixed PPP netif event posting to correctly include the esp_netif instance pointer (#6009)
• Fixed potential crash of ping when zero ping interval supplied

mDNS

• Fixed wrong mdns source address if lwIP zoning disabled
• Added support for queries in responses, so the mDNS responder works correctly with lwIP resolver (#5521)
• Fixed query ID in responses (#5574)
• Fixed the resolver to accept non-strict answers (allowing non empty question field within answers)
• Fixed length calculation of mDNS text field (#6114)

HTTP Client

• Fixed issue with esp_http_client when disable_auto_redirect is enabled
• Fixed issue with digest auth when opaque field is not present in response
• Added a configuration in esp_http_client_config_t to set user agent string
• Fixed buffer overread when esp_http_client_read is called after esp_http_client_perform (#6146)

mbedTLS

• Upgraded to release v2.16.9
• esp_crt_bundle: Allow verifying of trusted certificates with a weak signature hash algorithm (#6117)

Provisioning

• wifi_provisioning_manager: Fixed issue faced while adding 2 or more endpoints in wifi_provisioning_manager
• Fixed enable CONFIG_EXAMPLE_RESET_PROVISIONED will cause device crash
• Update README.md to explain QR code format (#6629)

Bootloader

• Fixed SECURE_ENABLE_SECURE_ROM_DL_MODE cannot be y when SECURE_DISABLE_ROM_DL_MODE=y (#6442)

ESP-TLS

• Update "tls->sockfd" after the socket is freed internally
• esp_tls_wolfssl: Use correct API to validate domain name with peer's server certificate
• Fixed memory leak in esp-tls
• Prevent freeing of global ca_store when mbedtls dynamic cert free is enabled
• esp_tls: Fixed misplaced parenthesis found during static analysis
• protocomm: Fixed NULL pointer check found during static analysis

Websocket

• Fixed posting the disconnect event twice on read error
• Fixed the client to skip reconnection when set disable_auto_connect
• Added options to support keepalive

ESP-MQTT

• Added configuration value to set network timeout
• Used size_t for all lengths to allow for other architectures
• mqtt_outbox: Removed unused retry_count field from outbox_item_t
• config: Fixed typo for configuring OUTBOX_EXPIRED_TIMEOUT_MS
• Fixed missing MQTT_API_UNLOCK in esp_mqtt_client_stop error path (espressif/esp-mqtt#173)
• Added esp_mqtt_client_get_outbox_size API
• Added config value to disable keepalive mechanism

TCP Transport

• Fixed issue in SSL mode: if esp_transport_poll_read function is used, the cache data in mebdtls will block
• Enable TCP keep-alive function in transport level

Storage

• NVS: Fixed string comparison in nvs_api.cpp
• NVS: ensuring default partition (#5347)
• Examples/SPI Flash Fatfs: Fixed ext flash fatfs cannot connect to external flash issue

Tools

• Fixed path handling errors in gen_esp_err_to_name.py for Windows
• ldgen: Added support for paths with Unicode characters in archive files parsed by ldgen (#5996)
• ldgen: Fix parsing of sections names on Windows (regression from 792087d)
• Added deprecation warning for Python 2 and Python 3.5 and older
• parttool.py: Add parameter out to save the output from the esptool
• Added check for existence build directory ?
• Fix requirements incompatible with Python 2
• docker: Add libpython2.7 in order to satisfy GDB dependencies (#5817, #5284)
• idf.py: Fixed gdb target to exit cleanly when no openocd watch task ?
• Fixed exception when specifying baudrate argument for IDF-Monitor
• Specify encoding for Eclipse Make build which is not the default value under Python 2 (#6505)
• Prefer python3 during install and export (#6471)
• Simpler installation by not requiring to set up manually an alias for python on Unix systems where it doesn't exist by default
• Don't count BSS into the total image size in the report of idf_size.py. Revert the behavior to ESP-IDF v4.1 and earlier
• CXX: Fixed extern "C" declarations (#6634)

Build System

• idf_as_lib example now places sdkconfig file outside the build directory
• Now always logs the sdkconfig file path from CMake

Examples

• esp-cryptoauthlib: Update submodule pointer to add a new feature (10830)
• flash_encryption example: Fixed the partition table - The partition_example.csv should not have fixed offsets for partitions because we want to move the whole table. The fixed offsets in the table were cleared
• Fixed socket examples to use sockaddr_storage for both IPv4 and IPv6 addresses
• Common connect component: Added unregister shutdown handler on disconnection
• pppos_client: Fixed a race condition on closing the PPP mode
• pppos_client: Remove esp-netif destroy from modem network glue code (#5486)
• pppos_client: Fixed esp_modem switch mode timeout and RX timeout interrupt (#3506, #4324)
• esp-ble-mesh: Delete local variables to avoid null global variables in coexistence example

Documentation

• Removed potentially confusing links to building the toolchain from scratch from the Getting Started guide
• Updated 32 kHz oscillator input signal from 32K_XP to 32K_XN as described in Hardware Design Guidelines
• Updated Chinese translation for get-started/index.rst and vscode-setup.rst
• Fixed typos for the English version of get-started/index.rst
• Removed link to PDF version of documentation hosted on Read the Docs server
• Updated ESP32-S2 related flash encryption information