Skip to content
Choose a tag to compare

ESP-IDF Pre-release v4.0-beta1

@projectgus projectgus released this
· 11656 commits to master since this release
Choose a tag to compare

ESP-IDF V4.0-beta1 Pre-Release

Documentation for release v4.0-beta1 is available at

ESP-IDF v4.0-beta1 is a prerelease of ESP-IDF v4.0, which is a major update for ESP-IDF v3.x.

ESP-IDF v4.0-beta1 is mostly compatible with apps written for ESP-IDF v3.x, but there are some breaking changes (please consult the list below) and removal of deprecated functionality which will require code changes when updating projects

The latest stable release of ESP-IDF is v3.3 at time of writing.

Major New Features

  • Bluetooth: Added alternative BLE-only host stack - NimBLE. Reduced resource usage compared to Bluedroid (but no dual mode support).
  • Bluetooth: Added feature-rich ESP BLE Mesh stack (SIG Certified)
  • Build system: New CMake-based build system, including native Windows support (MSYS2 is no longer required). GNU Make build system from earlier ESP-IDF versions is still supported as a legacy build system.
  • ESP-TLS: Added support for server side SSL/TLS connection
  • Ethernet: Refactored ethernet support into new esp_eth component, added support for DM9051 standalone Ethernet interface
  • Flash Encryption: New "Development" mode allows unlimited serial flashing of encrypted flash during development
  • lwIP: Updated lwIP version from v2.0.3 to v2.1.2
  • New "ESP Local Control" feature to provide capability to control an ESP32 over Wi-Fi+HTTPS or BLE using protocomm messages
  • SPI Flash: New SPI flash driver includes support for storage on additional SPI flash chips, partitions on external SPI flash chips
  • SPIFFS: New host based image generator tool
  • SystemView based heap and log tracing
  • toolchain: New "IDF Tools" scripts and mechanism for installing toolchain for a specific ESP-IDF version
  • toolchain: Upgraded ESP32 toolchain to gcc 8.2.0 (esp32-2019r1 toolchain release)
  • toolchain: Upgraded libc to newlib version 3
  • VFS: New semihosting driver for outputting via JTAG debugger
  • Websocket: New Websocket client component
  • Wi-Fi: New Wi-Fi Provisioning Manager feature
  • Wi-Fi: Refactor and improve softAP power saving support
  • Wi-Fi: wpa_supplicant code is now open source as part of ESP-IDF

Breaking Changes Since v3.x

This does not include removing functions/types which already produced deprecation warnings in ESP-IDF v3.x.

  • AWS IoT: The AWS IoT SDK is now an independent component repository:
  • Bluetooth: Added new parameter for updating whitelist API
  • Bluetooth: Adding AVRCP Target (TG) role means interfaces of AVRCP Controller(CT) have changed
  • Bluetooth: API of esp_bt_gap_set_scan_mode() is changed to allow setting connection modes as well as discovetrable modes
  • CMake: argument parsing has changed, and not all argument orders that work with v3.x are still valid
  • CMake: defconfig and bootloader-clean targets are removed (these existed but did not work correctly in earlier versions)
  • CMake: CMake "external project" integration API is different to ESP-IDF v3.x and not compatible.
  • CMake: Variables like IDF_PATH, IDF_TARGET, PYTHON etc are now read-only inside the IDF build system. Instead, modify build properties of the same name using the idf_build_set_property function.
  • Core: Some function-like macros (ESP_ERROR_CHECK, ESP_PM_TRACE_ENTER/EXIT had incorrect trailing semicolons which have been removed. May cause problems if relying on non-single-statement macro behaviour.
  • ESP32: The hwcrypto AES & SHA APIs are now internal to the mbedTLS component. Suggest refactoring existing code to use the mbedTLS APIs directly, provided hardware acceleration is enabled in project configuration then the same implementations will be used.
  • esp_event: Refactored Wi-Fi, Ethernet, IP event handling to use the new esp_event library. Old event handling code is no longer supported.
  • FATFS no longer includes integer.h. Applications should either include "ff.h", or redefine types such as BYTE, DWORD, etc.
  • Flash encryption workflow has changed to develop/release workflow. In "develop" mode unlimited serial flashing is supported, but the device is not secure. It is still possible to OTA update devices with flash encryption to ESP-IDF V4.0, but set Release mode in config before building a project for a production device, including for an OTA update.
  • freemodbus: Refactor the "port" API to have a common master and slave interface, port mode is now selected via API not in KConfig.
  • ldgen: The fragment grammar has changed to simplify the syntax. Linker fragments written for ESP-IDF V3.x will need to be updated.
  • LWIP: Multicast UDP socket interface binding has changed, and multicast sockets can no longer bind to all interfaces in a single call
  • micro-ecc: The micro-ecc component is now part of the ESP-IDF bootloader only. For existing projects which use micro-ecc, recommend refactoring to use mbedTLS for the same functionality. If this is not possible, micro-ecc can be added to the project source files directly.
  • nvs_util & mfg_util command lines are not 100% backwards compatible with ESP-IDF v3.x
  • protocomm: Session security now supports multiple instances of the same type (security APIs have changed to add a "handle" parameter).
  • ringbuffer: Interface to vRingbufferGetInfo has an additional parameter
  • SmartConfig: esp_smartconfig_start has been changed to esp_err_t esp_smartconfig_start(const smartconfig_start_config_t *config);
  • SmartConfig: SmartConfig has been refactored to use IDF new event mechanism. Old events SC_STATUS_WAIT, SC_STATUS_FIND_CHANNEL, SC_STATUS_GETTING_SSID_PSWD, SC_STATUS_LINK, SC_STATUS_LINK_OVER have been removed, and new events SC_EVENT_SCAN_DONE, SC_EVENT_FOUND_CHANNEL, SC_EVENT_GOT_SSID_PSWD, SC_EVENT_SEND_ACK_DONE have been added.
  • Storage: esp_partition encrypted reads/writes are now disabled if flash encryption is disabled in project config
  • VFS: fcntl() argument is now an int not va_list, in line with newlib
  • VFS: Custom drivers which implemented select support will need to implement a new select API
  • ESP-MESH: use the new esp_event library and remove event_cb from mesh_cfg_t

Major Non-Breaking Changes Since v3.x

The following major changes are non-breaking but are not compatible if downgrading to ESP-IDF v3.x:

  • CMake-based build system no longer uses "linker groups" to allow circular dependencies in the project at link time. Instead, components are expected to declare which other components they require. See build system docs
  • CMake: New component registration API. The API that was used by CMake for ESP-IDF v3.x is still supported but is deprecated
  • Many header files have been consolidated or moved, as part of reorganization to support multiple chip targets. These are not breaking changes in ESP-IDF V4.0, but the compiler will emit a warning which includes the new header path. The old headers will be completely removed in ESP-IDF V5.0
  • KConfig config item names have been standardized, meaning many items were renamed. The build system will automatically rename old config names to the new names on first build. Take care if you plan to downgrade a project to v3.x again, as the sdkconfig names will no longer be recognized.

Tip: If writing code that needs to work with ESP-IDF v3.x and v4.0, include the esp_idf_version.h header and check against the provided macros.

Known Issues

  • Not all APIs deprecated in ESP-IDF v3.x have been removed in this beta
  • Flash Encryption will fail to boot if PSRAM is not enabled
  • If Secure Boot and Flash Encryption features are in use, an additional firmware change is required to avoid potential fault injection attacks. Please refer to this security advisory
  • Watchdog timeout when using an RSA 4096-bit key to connect to WPA2-Enterprise (EAP-TLS) AP
  • SmartConfig may occasionally emit the log message wifi ipc: failed to post wifi task and then crash
  • Wi-Fi sniffer doesn't work correctly after switching Wi-Fi mode from WIFI_MODE_STA, WIFI_MODE_AP or WIFI_MODE_APSTA to WIFI_MODE_NULL
  • Bluedroid host may occasionally take a long time (more than 10s) to initialize
  • BT BB reset lock may cause assert when WiFi do start/stop.
  • WiFi MAC reset may block and cause task watch dog timeout.
  • If bluetooth host send some HCI command to controller but do nothing TX/RX actions, controller may delay to enter modem sleep.

Known issue bugfixes are planned before the next v4.0 pre-release.

List of changes since ESP-IDF v3.3:


  • Documented that SSID & Password fields should be NULL terminated strings (#1176)
  • Maximum TX power range changed from 0-20dBm to 10-20dBm to avoid poor performance
  • Fixed a smartconfig crash when no AP is found
  • Added check that ESP32_WIFI_RX_BA_WIN is less than ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM
  • Fix the bug that esp_wifi_set_country() fails to set policy WIFI_COUNTRY_POLICY_MANUAL
  • Fix the bug SmartConfig crashes if it fails to scan any APs.
  • Fix the bug WPS leaks some memory each time it completes the WiFi connection.
  • Fix the bug esp_wifi_stop() generates error log E(18732) event: system_event_ap_stop_handle_default 172 esp_wifi_internal_reg_rxcb ret = 0x3014.
  • Fix the bug that soft-AP doesn't return fail when setting to WIFI_AUTH_WPA2_ENTERPRISE or WIFI_AUTH_WEP
  • Fix the bug that WiFi/LWIP fails to allocate memories in SPIRAM first when the option is enabled.


ESP BLE Mesh (SIG Certified)

  • All SIG BLE Mesh Core Features (excluding Proxy Client)
    • PB-ADV and PB-GATT
    • Provisioner and Node roles
    • Friend and Low Power Node
    • Proxy Server
    • Configuration Server & Client Models
    • Health Server & Client Models
    • Relay, Segmentation and Reassembly, Key Refresh, IV Update, etc
  • All SIG BLE Mesh Client Models
    • Generic Client Models
    • Sensor Client Models
    • Time and Scenes Client Models
    • Lighting Client Models
  • BLE Mesh and Wi-Fi Coexistence
  • Performance Optimizations (e.g., Fast Provisioning Solution, 100 nodes provisioned within 50s)


  • All SIG BLE Mesh Server Models and Proxy Client feature have been developed and are under testing
    • They will be available on IDF master very soon and released in ESP-IDF v4.1

Bluedroid BLE Host

  • Added API to clean GATTC cache
  • Added discover service complete event
  • Added BLE MESH beacon adv and svc UUID for duplicate scan exceptional list
  • Added new API to get connection parameters in GATTC and GATTS connection events
  • Added svc_inst_id param for create service table event (#3256)
  • Added BLE link timeout config in menuconfig
  • Added new parameter for updating whitelist API
  • Fixed BLE data loss and occasional double-send of a packet
  • Fixed ADV data error under some circumstances
  • Fixed ADV start/stop crash under some circumstances
  • Fixed no adv report when scanning with sleep enabled
  • Fixed Blufi preparation write crash
  • Fixed memory leak when setting TX power
  • Fixed rxwinsz assert in BLE and WiFi coex
  • Fixed the unpack error for HCI_enhance_connection_complete event


New NimBLE alternative BLE host stack. Documentation.

Classic Bluetooth

  • Added AVRCP Target Role (TG) support
  • Added AVRCP volume feature
  • Fixed AVRCP command not executed while playing music
  • Added Wide Banch Speech HFP support
  • Fixed connection failure with some speakers

Bluetooth Controller

  • Added support for BTDM modem sleep when using 32kHz external crystal and light sleep mode
  • Fixed BLE SMP free without init
  • Fixed A2DP example use of unallocated memory
  • Fixed PLC use of unallocated memory


  • Consolidated Bluedroid tasks, reduce overall memory overhead


  • Refactored ethernet component into new esp_eth component
  • Added support for DM9051 SPI Ethernet PHY
  • Fixed ethernet APLL clock configuration (#3704)

Peripheral Drivers

  • gpio, rmt, pcnt: Optimize ISR function behaviour for better performance (#2861)
  • i2c: Fix an issue with single byte register writes when using GCC 8.2.0
  • i2c: Power management support
  • i2s: Power management support
  • ledc: Fixed LEDC low speed clock selection bufs
  • ledc: Added feature allowing low speed channel to selecT CLK8M clock source, meaning it can work in sleep mode
  • sdio: Added support for SDIO over SPI peripheral interface
  • sdmmc: Add support to print CIS inforomation from a card
  • SPI drivers: Refactored to use new driver HAL layer
  • spi_master: Added support for variable dummy length per transaction

Core System & FreeRTOS

  • esp32: Added new backtrace API to print a backtrace at any point (esp_backtrace_print())
  • esp32: The esp_sha() API now uses mbedTLS internally.
  • esp32: Now uses FPU for floating point divide, power, complex multiplications provided by libgcc
  • esp32: Added support for a fixed static RAM size and DRAM heap size (#3222)
  • esp32: Added new esp_idf_version.h and macros to check ESP-IDF version
  • esp32: Disable DPORT workaround if running on (forthcoming) revision 2 silicon version
  • freertos: Added explicit check that FreeRTOS mutex semaphores must be given by the owner task. This is required by FreeRTOS but was not explicitly checked before. Behaviour can be disabled, but not recommended as incorrect RTOS behaviour may result.
  • esp_event: Added API to allow posting events from ISRs
  • esp_event: Fixed issue where post data could be incorrectly supplied to the handler
  • esp_timer: Simplified timer deletion logic, resolving deadlock if a timer callback became blocked on another task that tried to delete a timer (#3458)
  • log: Fixed CCOUNT register overflow during boot, leading to incorrect "jump" backwards in startup log timestamps
  • psram: Optimize PSRAM SPI timings when used in DIO mode
  • pthread: Fix linker issues causes by pthread component linker order (#3709)
  • ringbuffer: Added static allocation support, removed some deprecated types/functions
  • ringbuffer: Added new API to allow allocating memory in the ringbuffer before it is actually sent
  • soc: All peripherals now have a soc/name_periph.h header which includes all SoC-level declarations (registers, characteristics, etc)


mbedTLS Related

  • Added fault injection checks for hardware AES & SHA peripherals
  • Added configuration option to set the debug level (#3521)


  • protocomm: Fixes in handling BLE read/write requests
  • protocomm: Added support for NimBLE in BLE provisioning, for reduced resource usage


  • Fixed mdns crashing on reception of txt packet without a corresponding service (#2866)
  • Fixed mdns txt item types to const char * to avoid warning
  • Updated mdns_out_question_s to be in line with mdns_parsed_question_s struct (#1568)
  • Fixed ignoring an mDNS packet if it contained an invalid name entry in the question field


  • Support buffered stdout


  • New semihosting driver and example using VFS layer
  • Added SystemView based heap and log tracing features


  • NVS: Fixed issue where an item was always written even if unmodified (#3310)
  • NVS: Appended _t to nvs_handle & nvs_open_mode types (#3239)
  • NVS: Added new NVS Iterators API
  • NVS: nvs_util now has support for decrypting encrypted NVS partitions on the host
  • VFS: Added support for pread() and pwrite() (#3515)
  • VFS: Added support for concurrent calls to select()


  • Added support to override certificate Common Name via config, instead of using hostname
  • Fixed incorrect closing of FD 0 on connection failure (#3149)
  • Added new error reporting API to provide error codes to application code (reference)

HTTP Client

  • Fixed lost username when setting new URL with a path (#3250)
  • Fixed reading HTTP header in chunked mode (#3461)
  • New separate buffer_size config option for transmit (#3528)


  • Fixed HTTP URL redirection issue (#3218)
  • Fixed basic/digest auth issue with HTTP URL (#2921)
  • Fixed issue with lost HTTP_EVENT_HEADER_SENT event (#3095)
  • Added support for adding custom HTTP header
  • Added support for reading firmware image version
  • Added support for monitoring upgrade status

HTTP Server

  • Added ability to select core for HTTP server task (#3190)

tcp_transport Related

  • Fixed minor memory leak found by static analyzer (#3602)
  • Fixed minor memory leak when SSL transport used separately (#3541)

Build System & Tooling

  • Added Dockerfile to build docker images using ESP-IDF
  • cmake: Use of ccache is now opt-in, pass --cache or cmake -DUSE_CCACHE=1 to enable
  • cmake: Now passes environment variables internally using a file, to avoid command line length limitations on Windows
  • idf_monitor: Added feature to create log files (keyboard shortcuts)
  • Fix behaviour under PowerShell (
  • --print-filter option allows filtering idf_monitor output when running under
  • idf_monitor: Support Ctrl-T + A as well as Ctrl-T + Ctrl-A, as latter cannot be captured under Windows command prompt
  • Pass -DOUTPUT_JSON=1 to get JSON formatted output from size-related targets
  • GNU Make: make V=0 is now the same as make V= (no verbose output at all)
  • GNU Make: Fixed make read_otadata and erase-otadata not using esptool config correctly (#3135)
  • mfg_util: Optimise command line interface by adding subparser options (not compatible with ESP-IDF v3.x)
  • mconf: Added 'simple expand' logic for environment variables instead of using wordexp(), to make consistent with the mconf-idf shipped in the IDF Tools installer.
  • parttool & otatool: Now have baud rate command line option
  • toolchain: "Release" optimization level now passes -freorder-blocks to reorder code blocks in output, can improve both performance and code size when using gcc 8.2.0


External Libraries


  • New Chinese translation of many documentation sections


  • Added HTTP RESTful web server example, with modern Web UI

  • OTA Example now supports both Wi-Fi and Ethernet

  • New BLE GATTC and GATTS coexistence example

  • New BLE ANCS demo

  • Bluetooth examples have been restructured, examples for NimBLE & BLE Mesh are added

  • Added external flash chip FATFS example

  • UDP Multicast example: Now handles errors correctly

  • Wifi-AP example now includes Ethernet Layer 2 forwarding functionality