ESP-IDF Pre-release v3.1-rc1

Documentation for release v3.1-rc1 is available at http://docs.espressif.com/projects/esp-idf/en/v3.1-rc1/.

This is a pre-release release candidate version. The current release version is v3.0.3.

Changes Since v3.1-beta1

This is the list of changes since v3.1 Beta 1:

Known Issues

• Dynamic Frequency Scaling and Bluetooth modem sleep are not compatible. DFS will be automatically disabled if Bluetooth modem sleep is in use.

Bluetooth

Bluetooth Controller / Bluedroid

• Add Controller to Host Flow Control support
• Fixes and performance improvement when WiFi coexistence is enabled, including when modem sleep also enabled
• Fix lock protection when setting interrupts
• Fix conflict reading RSSI in dual mode
• Fix assertion failure in time conversion functions
• Fixes for removing bonded devices on BLE & Classic BT
• Fix incorrectly enabled erroneous data reporting in HCI layer
• Fix controller critical sections when called from ISR context
• Fix controller crash when controller is disabled and re-enabled under some circumstances

BLE

• New configuration option to deal with BLE queue congestion
• Fix CVE-2018-5383 ("Bluetooth implementations may not sufficiently validate elliptic curve parameters during Diffie-Hellman key exchange")
• Fix slave cannot receive long packets when using SMP
• Fix connection stability with modem sleep enabled
• Fix advertising stopped during connection
• Send an L2CAP error response if an invalid GATT request is received
• Fix error when advertising stops
• Fix service notification when registering multi GATTC
• Fix GATTC get count
• Fix Security Manager Protocol bonding failure with iPhones
• Fix get bond list error when connection is unbonded
• Fix pointer arithmetic errors in GAP

BT Classic

• Fix invalid SCO handle in HCI number_of_completed_packets event
• Fix crash on end of SCO link after link supervision timeout
• Retrieve disconnection reason in AVDT when ACL-U link is disconnected
• Fix SPP crash on reset
• Fix invalid retransmission setting for SCO link in HFP

WiFi

• Restore null mode configuration setting
• WiFi library memory use improvements: reduced WiFi stack size, freed some static memory usage, reduced some internal buffers
• Channel state information buffer changed to signed values
• Fix beacon information not updating after user scan
• Fix AMPDU duplicate frame issue
• WiFi coexistence fixes
• Decreate phy_init time from 900us to 347us when waking from sleep
• Fix interrupt watchdog issue when setting channel
• Fix bug where wrong AP was connected after an all channel scan

WPA2 Enterprise

• Fix memory corruption bug
• Fix memory leak bug
• WPA2 Enterprise API now thread safe

ESP-MESH

• New API to set/get announce interval
• New API to enable/disable minimum data rate limited to 6Mbps
• New API to set/get RSSI thresholds for self organization
• Fixes for AP loss handling
• Modify parent switch mechanism

LWIP

• Fix assertion in tcp_pcb_purge()
• Fix assertion when closing an non-blocking TCP socket
• By default don't automatically trust MAC entries of received IP packets, always send an ARP request (configurable)
• Add source IP based routing for unicast packets
• Fix compilation with AutoIP enabled

mDNS

• Send "Goodbye" packet when removing service as "Authoritative"
• Fix a portion of queries are issued with the wildcard query type

System

• freertos: Queue Sets are now multi-CPU safe
• Fix rtc_gpio_desc values for GPIOs 35, 37, 38, 39
• Fix for flushing UART output on deep sleep
• Fix addresses of some libgcc functions in ESP32 ROM
• Fix "make flash" arguments when partition table has no factory partition
• Fix idf_monitor interactive console performance
• Mark XTHAL_GET_INTERRUPT & XTHAL_GET_CCOUNT as volatile
• NVS Partition Generator: Support base64 encoded binary data
• Fix incorrect pad reported in esp_sleep_get_touchpad_wakeup_status() for touchpad wakeup
• spi_flash_mmap(): Allocate mmap pages array in internal memory (fixes crash when using SPIRAM)
• Improve spinlock performance when assertions are enabled

Bootloader

• Fixes for factory reset pin GPIO option
• Fixes when compiling with assertions disabled
• Fix boot error for uncommon case where partition table has no OTA app partitions but a non-empty ota_data partition
• Support QIO mode for XM25QU64A flash chip

Secure Boot

• Fix regression in secure boot & flash encryption functionality
• Partition table no longer has its signature verified as part of Secure Boot
• Pad app images to a 64KB boundary to ensure no unverified data is mapped into the address space

Drivers

• GPIO: Fix bitmask overflow in gpio_reset_pin for pin > 31
• GPIO: Fix bug clearing interrupt status when enabling interrupts for GPIO numbers > 31
• LEDC: Fix ledc_set_duty_and_update() to return immediately if duty is already set
• LEDC: Fix ledc_set_freq() for low speed mode
• PCNT: Add some additional parameter checks and improve example
• RMT: Reduce rmt_mem_num memory block limit to 8 (correct value)
• SDIO Slave: Fix race condition with high frequency interrupts
• SDIO Slave: Fix some return values, improve high speed & 4 bit mode configuration
• SDMMC: Disable all pulldowns used by SDMMC host
• SDMMC: Enable host auto stop only for certain commands
• Touchpad: New API touch_pad_get_wakeup_status()
• UART: Fix UART tx_empty interrupt wdt timeout bug
• UART: Fix timeout bug when UART clock source is ref_tick

Storage

• nvs_flash: Add version compatibility checks for NVS storage
• spiffs: Fix stackoverflow due to recursion in vfs_spiffs_readdir_r

Documentation

• New page with information about ESP-IDF versions
• Eclipse setup: Fix some inconsistent information on Windows English & Chinese Eclipse setup page, simplify description of some steps.

Examples

• ble_hid_device: Fix bugs with HID Information & HID Control characteristics
• ble_throughput: Improve default example configuration
• http2_request: Fix a crash when send/receive fails
• ULP example: Fix RTC IOs

ULP

• Expand documentation for JUMPS instruction, ULP binary format
• Add missing include in ulp.h header
• Fix calculation of ulp_run argument

esp_http_client

• Fix HTTP chunked encoding
• Fix for reading data from TLS connection
• API support for getting transport type
• Fix exception on 401 error without www-authenticate header set

External libraries

• mbedTLS: Updated to v2.12.0

Changes Since v3.0

This is the list of changes since release v3.0. ESP-IDF v3.1 is compatible with apps written for v3.0 (apart from one breaking change in esp_ping, see below).

Known Issues

• Dynamic Frequency Scaling and Bluetooth modem sleep are not compatible. DFS will be automatically disabled if Bluetooth modem sleep is in use.

Breaking Changes

• esp_ping units are now milliseconds (in v3.0 ping units were undocumented but they were treated as seconds)

Major Changes

• Support for Wi-Fi & Bluetooth modem sleep
• Support for Automatic Light Sleep to reduce overall power consumption (including Tickless FreeRTOS)
• Multiple antenna support (automatic using external RF antenna switch)
• Wi-Fi mesh functionality (ESP-MESH)
  • Autonomous self-organizing Wi-Fi-based networking protocol
  • Self-healing mesh topology
  • Can connect to external IP network via a "root node" and transparently route mesh packets to external network
  • Supports mesh network data encryption via WPA-PSK
  • Guide and API Reference
• OS adapter layer for Wi-Fi functionality (allows Wi-Fi libraries to run on other RTOS implementations)
• SDIO Slave peripheral driver
• Bootloader refactoring, configurable factory reset and test app trigger functionality
• Partition table can be relocated to allow a larger bootloader binary
• esp_https_ota: New simplified HTTPS OTA client feature

BLE

Link Layer

• Fix the smartphone compatibility bug caused by LL Feature Exchange timing issue
• New configuration option to deal with BLE queue congestion
• Send an L2CAP error response if an invalid GATT request is received

GATT Client

• Save GATTC cache in NVS and add an option to configure it through menuconfig
• A new parameter incl_srvc_e_handle is added to the struct esp_gattc_incl_svc_elem_t while getting include service information
• Fix the incorrect PID key result of the ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT event
• Fix advertising stopped during connection
• Fix error when advertising stops

GAP

• Fix the bug where the start/stop advertising completed events sometimes are not accurate
• Add the duplicate scan feature and add an option to configure the duplicate scan cache size through menuconfig
• New API esp_ble_gap_config_local_icon to set the local GAP appearance icon
• New API esp_ble_gap_get_local_used_addr to get the local address used (e.g. current random address used)

Security Manager Protocol (SMP)

• Fix CVE-2018-5383 ("Bluetooth implementations may not sufficiently validate elliptic curve parameters during Diffie-Hellman key exchange")
• Fix slave cannot receive long packets when using SMP
• Fix the bug that lead to crash when deinit bluetooth with SMP disabled
• Fix the incorrect results of the esp_ble_get_bond_device_list which is called after reboot
• Fix Security Manager Protocol bonding failure with iPhones

Blufi

• New "get wifi list" command
• New "report internal error report to phone" command
• New "send/receive custom data" command

Examples

• Add A2DP and BLE GATTS coex Demo
• Add BLE Throughput Demo
• Add HID Device Demo
• Fix ble_spp_clientdemo error when SUPPORT_HEARTBEAT is enabled

Performance optimization

• BLE throughput optimizations
• Automatic registration of GATTC service change notify

Bluetooth Common Parts

• Wi-Fi & Bluetooth coexistence support
• Bluetooth modem sleep mode
• Controller to Host Flow Control support
• Fix incorrectly enabled erroneous data reporting in HCI layer
• Fixes for removing bonded devices on BLE & Classic BT
• Fix conflict reading RSSI in dual mode

Classic BT

• HFP (Hands Free Profile) support
• GAP device and sevice discovery
• SPP profile (including VFS support to return a file descriptor)
• dynamic memory allocation
• A2DP: Source and sink functionality can be enabled/disabled at runtime (both cannot be enabled concurrently)
• A2DP: Performance improvements
• Allow setting BR/EDR TX power level

Wi-Fi

New Functionality

• Wi-Fi & Bluetooth coexistence support
• Modem sleep support
• Mesh feature
• Throughput optimizations
• Support for Channel State Information (CSI)
• Support to sniffer Wi-Fi control packets
• Add parts of WPA Supplicant source to ESP-IDF
• Fix some memory issues in WPA2 Enterprise support
• WPA2 Enterprise API is now thread safe
• New event mask API
• New esp_wifi_80211_tx function for sending 802.11 frames
• WPS: Support WPS in APSTA mode
• WPS: Add "set factory information" feature
• Allow creating the Wi-Fi task pinned to either core

Bug Fixes

• Fix issue where esp_wifi_stop never returns if start/stop is run repeatedly
• Fix for connecting to WEP APs
• Fix for de-authing station if Soft AP already has maximum connected
• Thread safety fixes in Wi-Fi library
• Fix issue that smartconfig crashes when switching channel
• Fix smartconfig crash issue with SPI RAM
• Fix the issue that esp_wifi_connect returns ESP_OK, but no system event posted (ap_loss) ([#1797](esp_wifi_connect returns ESP_OK, but no system event posted (ap_loss)))
• WPA2 Enterprise PEAP connection fixes ([#1887](Enterprise PEAP connection issue))
• Fix ESPNOW bug when add node in AP+STA mode

LWIP

New Functionality

• Add VFS file descriptors in select
• Add event SYSTEM_EVENT_AP_STAIPASSIGNED
  ** By default don't automatically trust MAC entries of received IP packets, always send an ARP request (configurable)

Bug Fixes

• Fix the issue that TCP connections don't abort when IP address is changed
• Modify default value of MTU in dhcp offer to 1500
• Fix the assertion issue caused by tcp_pcb_purge()
• Fix assertion when closing a non-blocking socket
• Fix compilation with AutoIP enabled

RF PHY

• Fix for full calibration accidentally running twice
• PHY performance improvements

Ethernet

Bug Fixes

• Set direction of SMI MDC & MDIO pins correctly

Network Functionality

• New esp-tls library (on top of mbedTLS) for high level TLS (SSL) functionality
• New esp_http_client library for HTTP/S client functionality
• mbedTLS: Update to v2.9.0
• dhcpserver: Fix maximum number of leases (was one less than configured)
• dhcpserver: Increase DHCP offer MTU size to 1500

Smartconfig

• Moved to its own component (no longer part of 'esp32')

Soc-Level Functionality

New Functionality

• Power Management: Support for automatic light sleep
• Dump stack of both cores when Interrupt watchdog timeout occurs
• New macros DMA_ATTR & WORD_ALIGNED_ATTR for declaring DMA-capable static buffers
• Add option to continue running if PSRAM was enabled but not detected at boot
• Support maximum CPU frequency rating efuse bits, if set from factory.
• Power Management: Allow disabling a deep sleep wakeup source
• Improve performance of DPORT access workaround
• Support __NOINIT_ATTR and RTC_NOINIT_ATTR for static memory not cleared on reset

Bug Fixes

• Power management: Dynamic frequency scaling stability improvements
• Fix for runtime configuration of PSRAM (improves stability for 80MHz PSRAM)
• Fix starting 32kHz crystal in some cases where crystal performance is borderline
• Fix loss of precision when estimating XTAL frequency
• Prevent Interrupt WDT from re-triggering in panic handler
• Heap: Fix tracing of newlib internal allocations (not all of these were being included in the trace)
• Link pure math functions from libgcc from ROM to reduce code size
• Fix incorrect pad reported in esp_sleep_get_touchpad_wakeup_status() for touchpad wakeup

Core System Libraries

New Functionality

• freeRTOS: Support tickless idle (works with Light Sleep)
• newlib: Add support for adjtime()
• New esp_err_to_name() function to look up error messages from esp_err_t codes.
• New API esp_intr_set_in_iram() to change interrupt "in IRAM" status
• pthreads: Allow configuring thread priority & stack size on creation
• C11 Thread Local Storage support
• Heap: New "record task" option for heap tracing
• esp_timer: Add a function to get next alarm time

Bug Fixes

• freeRTOS: Queue Sets are now multi-CPU safe
• Remove debug logging from pthread conditional variables
• Remove duplicate definition of system_restore
• Increase default event task stack size by 256 bytes (prevent stack overflow at Debug log level)
• Fix for idle task stack overflow under some circumstances
• Refactors and stability fixes for ESP-IDF RingBuffers
• Fix busy loop in esp_timer_impl_set_alarm (could trigger interrupt watchdog)
• Mark XTHAL_GET_INTERRUPT & XTHAL_GET_CCOUNT as volatile
• spi_flash_mmap(): Allocate mmap pages array in internal memory (fixes crash when using SPIRAM)
• Improve spinlock performance when assertions are enabled

Bootloader

New Functionality

• More modular bootloader. Minimal code in the bootloader component itself makes it easy to copy this component into a project to implement custom bootloader functionality.
• New "reset to factory" and "start test app" config options to watch a GPIO and trigger behaviour on reset
• Partition table can be relocated to allow a larger bootloader binary
• Partition table now generated with MD5 checksum, checked on boot
• Support QIO mode for XM25QU64A flash chip

Bug Fixes

• Fix flash QIO mode configuration for some flash chips

Secure Boot

New functionality

• Partition table no longer has its signature verified as part of Secure Boot
• Pad app images to a 64KB boundary to ensure no unverified data is mapped into the address space

Drivers

New Functionality

• esp_adc_cal: Read factory calibration data from eFuse if present in chip
• GPIO: Support digital pad hold function
• I2S: Support "fixed_mclk" configuration
• I2S: Support for expanding bit width for multi-data-bit input and output (not standard I2S)
• LEDC: New thread-safe duty cycle & fade API
• PCNT: Allow each unit to have its own interrupt handler
• RMT: New function rmt_register_tx_end_callback(). Called when RMT ISR has queued all outgoing items
• RMT: New API for sending generic uint8_t-typed data.
• SDIO Slave: New driver
• SDMMC: SDIO support at protocol layer
• SDMMC: Add support for reading CD & WP pins in driver
• SPI Master: Configuration item to place SPI send/receive code into IRAM for performance
• Touchpad: New API touch_pad_get_wakeup_status()

Bug Fixes

• Always reset various communication peripherals (UART, I2C, etc) on CPU reset
• ADC: Fix bug where some peripherals (DAC, HALL) needed to be disabled before ADC conversion
• esp_adc_cal: Simplify lookup table mode, due to inferior performance compared to linear mode for attenuations 0-2
• GPIO: modify return value when gpio ISR service already exists.
• GPIO: Fix bitmask overflow in gpio_reset_pin for pin > 31
• GPIO: Fix bug clearing interrupt status when enabling interrupts for GPIO numbers > 31
• I2C: Concurrency fixes
• I2C: Add xQueue and xSemaphore static allocation support when intr_alloc_flag set to ESP_INTR_FLAG_IRAM.
• I2S: Fix I2S ADC mode
• LEDC: Fix duty cycle and fade overflow issues
• LEDC: Fix ledc_set_freq() for low speed mode
• PCNT: Add some additional parameter checks and improve example
• SPI master: perform clock calculations in initialization not ISR
• SPI master: Don't reconfigure peripheral if settings are unchanged
• SPI master: Fix issue using GPIO0
• SPI master: Fix issue with variable command and address flag
• SPI master: Fix typo in LSBFIRST macro value
• SPI master: Allow using GPIO34-39 as MISO
• RMT: Remove logging which skewed timing
• RMT: Fix for LoadProhibited crash
• RMT: Fix TX stop API issue
• RMT: Reduce rmt_mem_num memory block limit to 8 (correct value)
• SDMMC: Fix for slave sometimes falling into SPI mode
• SDMMC: Fix init sequence ordering
• SDMMC: Improve host clock generation (set highest possible clock divider)
• SDMMC: Initializers are now C++ compatible
• SDMMC: Various other command-related fixes
• SDMMC: Disable all pulldowns used by SDMMC host
• SDMMC: Enable host auto stop only for certain commands
• SDSPI: Handle error flags for R3 & R7 responses, and delayed R1 responses
• SDSPI: Fix compatibility issues with multi-block reads
• SDSPI: Initializers are now C++ compatible
• UART: Remove unnecessary call to xSemaphoreGive()
• UART: Fix UART FIFO overflow bug
• UART: New pattern detect function
• UART: Fix uart_get_baudrate incorrect return value when using ref_tick
• UART: Fix UART tx_empty interrupt wdt timeout bug
• UART: Fix timeout bug when UART clock source is ref_tick
• Touch: Fix default touch channels enabled on startup
• Touch: Improve the touchpad filter mode

Virtual Filesystem

• Support for VFS file descriptors in select() (currently support mixing UART & socket fds in a single select() call)
• Support access() function
• UART driver: Support O_NONBLOCK flag

mDNS

• Send "Goodbye" packet when removing service as "Authoritative"
• Fix a portion of queries are issued with the wildcard query

External Libraries

• AWS IoT: Update AWS IoT SDK to v2.2.1
• AWS IoT: Allow setting Thing Shadow settings via menuconfig
• AWS IoT: Fine tune stack size for aws_iot examples
• AWS IoT: Fix compilation when "Override Shadow RX buffer size" is enabled in menuconfig
• micro-ecc: Update to version 1.0 (no code changes from previously used version)
• mbedTLS: Updated to v2.12.0

Storage Subsystems

New Functionality

• fatfs: Configurable allocation unit size
• fatfs: Character encoding configurations
• fatfs: Support for mounting read-only fatfs volumes without wear levelling
• nvs: New host-side utility to create a prepopulated NVS partition
• nvs: New functions for returning used/free entry counts
• nvs: Fix for NVS sometimes leaving free chunks unwritten in a page
• nvs_flash: Add version compatibility checks for NVS storage
• spiffs: New config option for logical page size

Bug Fixes

• nvs: Fix recovery from power off during erase or free cycle
• spiffs: Verify OBJ_NAME_LEN + OBJ_META_LEN is within limits
• spiffs: Fix esp_spiffs_format() if partition is not mounted
• spiffs: Fix stackoverflow due to recursion in vfs_spiffs_readdir_r

ULP

• Expand documentation for JUMPS instruction, ULP binary format
• Add missing include in ulp.h header
• Fix calculation of ulp_run argument
• ULP example: Fix RTC IOs

Documentation

• New documentation URL: https://docs.espressif.com/projects/esp-idf
• Chinese Translations of Getting Started Guides
• Documentation for new ESP32 DevKitC V4
• New page with list of esp_err_t error values
• New page with information about ESP-IDF versions
• Eclipse setup: Fix some inconsistent information on Windows English & Chinese Eclipse setup page, simplify description of some steps.

Build System

• New hooks to remove build-time requirement for 'git' to be installed
• Support for EXCLUDE_COMPONENTS project level variable
• Build-time check that configured flash size fits in the partition table

Host-Side Tools

• idf-monitor: Improve gdb session cleanup on Linux
• idf-monitor: Fix cases where monitor would crash writing to console on WSL
• espefuse: Support for reading ADC calibration data, where provided
• idf-size: Sort output by total size
• idf-size: Report per-symbol sizes from map file (new target make size-symbols)
• JTAG: Support software breakpoints set in flash (pending release of openocd support)
• gcov: Add GCOV debug stub support

Getting This Release

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 v3.1-rc1 --recursive https://github.com/espressif/esp-idf.git esp-idf-v3.1-rc1
cd esp-idf-v3.1-rc1/

This is the recommended way of obtaining v3.1-rc1 of ESP-IDF.

Download an archive with submodules included

Attached to this release is an esp-idf-v3.1-rc1.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.