ESP-IDF Prerelease v3.1-beta1

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

This is a prerelease version with known issues (see below). The current release version is v3.0.1.

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

• Bluetooth modem sleep mode (disabled by default) has stability issues
• Bluetooth modem sleep mode can't work with Dynamic Frequency Scaling
• Wi-Fi NULL mode is currently non-functional
• When using BLE and Wi-Fi together, BLE advertising or scanning has a small chance of failing
• Wi-Fi performance is not good when signal is weak

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
• 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

BLE

Link Layer

• Fix the smartphone compatibility bug caused by LL Feature Exchange timing issue

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

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)

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

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

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
• 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

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()

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)

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

• 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)

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

Bug Fixes

• Fix flash QIO mode configuration for some flash chips

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

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.
• 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
• 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
• 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
• 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
• 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

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)

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
• 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

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

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

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

Download an archive with submodules included

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