Peripherals

[中文]

Common Changes

Legacy Driver Dependencies Removal

The legacy driver component driver has been deprecated and no longer contains public dependencies on the following driver components:

If your project uses legacy driver component, it is strongly recommended to remove driver component dependencies, and add new driver component (usually esp_driver_xxx) dependencies to your project.

If you still need to keep legacy driver component (e.g. your project depends on the legacy i2c driver), please keep the driver component remaining in the dependency list of your project (usually <project_root>/main/CMakeLists.txt), and manually add component dependencies that are no longer included in driver as needed.

All drivers' io_loop_back configuration have been removed

Different driver objects can share the same GPIO number, enabling more complex functionalities. For example, you can bind the TX and RX channels of the RMT peripheral to the same GPIO to simulate 1-Wire bus read and write timing. In previous versions, you needed to configure the io_loop_back setting in the driver to achieve this "loopback" functionality. Now, this configuration has been removed. Simply configuring the same GPIO number in different drivers will achieve the same functionality.

Peripheral Clock Gating

Peripheral clock gating is managed within the driver layer. Users do not need to manually handle peripheral module clock gating. Its corresponding APIs are included via a private header file esp_private/periph_ctrl.h. There used to be another header file driver/periph_ctrl.h for the same purpose, which is now removed.

RTC Subsystem Control

Low power modules usually share some common resources like interrupt number. To avoid conflicts, some private APIs are created in the esp_private/rtc_ctrl.h header file to manage these shared resources with ease. There used to be another header file driver/rtc_cntl.h for the same purpose, which is now removed.

ADC

The legacy ADC driver driver/adc.h is deprecated since version 5.0 (see ADC). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_adc, and the header file path is esp_adc/adc_oneshot.h, esp_adc/adc_continuous.h, esp_adc/adc_cali.h and esp_adc/adc_cali_scheme.h.

RMT

The io_od_mode member in the rmt_tx_channel_config_t configuration structure has been removed. If you want to use open-drain mode, you need to manually call the gpio_od_enable() function.

GPIO

gpio_iomux_in() and gpio_iomux_out() have been replaced by gpio_iomux_input() and gpio_iomux_output(), and have been moved to esp_private/gpio.h header file as private APIs for internal use only.

LEDC

  • ledc_timer_set() has been removed. Use ledc_timer_config() or ledc_set_freq() instead.

  • LEDC_APB_CLK_HZ and LEDC_REF_CLK_HZ have been removed.

  • LEDC_SLOW_CLK_RTC8M macro has been removed. Please use LEDC_SLOW_CLK_RC_FAST instead.

  • Removed esp_driver_gpio as a public required component from esp_driver_ledc.

  • ledc_isr_register() has been deprecated. LEDC interrupt handling is implemented by driver itself, please only register event callbacks if necessary.

  • ledc_channel_config_t::intr_type has been deprecated. LEDC_INTR_FADE_END interrupt enable / disable control is handled by the driver internally. Users can still register a callback for this interrupt by ledc_cb_register().

  • soc_periph_ledc_clk_src_legacy_t::LEDC_USE_RTC8M_CLK has been removed. Please use LEDC_USE_RC_FAST_CLK instead.

UART

UART_FIFO_LEN macro has been removed. Please use UART_HW_FIFO_LEN instead.

I2C

I2C slave has been redesigned in v5.4. In the current version, the old I2C slave driver has been removed. For details, please refer to the I2C slave section in the programming guide.

The major breaking changes in concept and usage are listed as follows:

Major Changes in Concepts

  • Previously, the I2C slave driver performed active read and write operations. In the new version, these operations are handled passively via callbacks triggered by master events, aligning with standard I2C slave behavior.

Major Changes in Usage

  • i2c_slave_receive has been removed. In the new driver, data reception is handled via callbacks.

  • i2c_slave_transmit has been replaced by i2c_slave_write.

  • i2c_slave_write_ram has been removed.

  • i2c_slave_read_ram has been removed.

Meanwhile, I2C master also has some change in its APIs' definitions.

Major Changes in Usage

Following functions now will return ESP_ERR_INVALID_RESPONSE instead of ESP_ERR_INVALID_STATE when NACK from the bus is detected: - i2c_master_transmit - i2c_master_multi_buffer_transmit - i2c_master_transmit_receive - i2c_master_execute_defined_operations

Legacy Timer Group Driver is Removed

The legacy timer group driver driver/timer.h is deprecated since version 5.0 (see Legacy Timer Group Driver is Deprecated). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_gptimer, and the header file path is driver/gptimer.h.

Legacy I2S Driver is Removed

  • The legacy i2s driver driver/i2s.h is deprecated since version 5.0 (see I2S Driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_i2s, and the header file path is driver/i2s_std.h, driver/i2s_pdm.h and driver/i2s_tdm.h.

  • API i2s_set_adc_mode, i2s_adc_enable and i2s_adc_disable are deprecated since version 5.0. Starting from version 6.0, these APIs are completely removed.

GDMA

  • The GDMA_ISR_IRAM_SAFE Kconfig option has been removed due to potential risks. Now, the interrupt behavior of different DMA channels during Cache disabled periods are independent of each other.

  • gdma_new_channel is removed. When requesting a GDMA channel, use either gdma_new_ahb_channel or gdma_new_axi_channel according to the bus type.

  • The sram_trans_align and psram_trans_align members have been removed from async_memcpy_config_t. Use async_memcpy_config_t::dma_burst_size to set the DMA burst transfer size.

  • The esp_dma_capable_malloc and esp_dma_capable_calloc functions have been removed. Use heap_caps_malloc() and heap_caps_calloc() from heap/include/esp_heap_caps.h with MALLOC_CAP_DMA|MALLOC_CAP_CACHE_ALIGNED to allocate memory suitable for DMA and cache alignment.

SDMMC

  • The get_dma_info member in the sdmmc_host_t structure, as well as the sdspi_host_get_dma_info and sdmmc_host_get_dma_info functions, have been removed. DMA configuration is now handled internally by the driver.

Legacy Temperature Sensor Driver is Removed

The legacy temperature sensor driver driver/temp_sensor.h is deprecated since version 5.0 (see Legacy Temperature Sensor Driver is Deprecated). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_tsens, and the header file path is driver/temperature_sensor.h.

LCD

  • The GPIO number type in the LCD driver has been changed from int to the more type-safe gpio_num_t. For example, instead of using 5 as the GPIO number, you now need to use GPIO_NUM_5.

  • The psram_trans_align and sram_trans_align members in the esp_lcd_i80_bus_config_t structure have been replaced by the esp_lcd_i80_bus_config_t::dma_burst_size member, which sets the DMA burst transfer size.

  • The psram_trans_align and sram_trans_align members in the esp_lcd_rgb_panel_config_t structure have also been replaced by the esp_lcd_rgb_panel_config_t::dma_burst_size member for configuring the DMA burst transfer size.

  • The color_space and rgb_endian configuration options in the esp_lcd_panel_dev_config_t structure have been replaced by the esp_lcd_panel_dev_config_t::rgb_ele_order member, which sets the RGB element order. The corresponding types lcd_color_rgb_endian_t and esp_lcd_color_space_t have also been removed; use lcd_rgb_element_order_t instead.

  • The esp_lcd_panel_disp_off function has been removed. Please use the esp_lcd_panel_disp_on_off() function to control display on/off.

  • The on_bounce_frame_finish member in esp_lcd_rgb_panel_event_callbacks_t has been replaced by esp_lcd_rgb_panel_event_callbacks_t::on_frame_buf_complete, which indicates that a complete frame buffer has been sent to the LCD controller.

  • The LCD IO layer driver for the I2C interface previously had two implementations, based on the new and legacy I2C master bus drivers. As the legacy I2C driver is being deprecated, support for it in the LCD IO layer has been removed. Only the APIs provided in driver/i2c_master.h are now used.

  • esp_lcd_dpi_panel_config_t::pixel_format member is deprecated. It is recommended to only use esp_lcd_dpi_panel_config_t::in_color_format to set the MIPI DSI driver's input pixel data format.

  • The NT35510 LCD device driver has been moved out of ESP-IDF and is now hosted in the ESP Component Registry. If your project uses the NT35510 driver, you can add it to your project by running idf.py add-dependency "espressif/esp_lcd_nt35510".

SPI

  • The CONFIG_SPI_MASTER_IN_IRAM option is now invisible by default in menuconfig and depends on CONFIG_FREERTOS_IN_IRAM. This change was made to prevent potential crashes when SPI functions in IRAM call FreeRTOS functions that are placed in flash.

  • To enable SPI master IRAM optimization:

    1. Navigate to Component config → FreeRTOS → Port in menuconfig.

    2. Enable Place FreeRTOS functions in IRAM (CONFIG_FREERTOS_IN_IRAM).

    3. Navigate to Component config → ESP-Driver:SPI Configurations in menuconfig.

    4. Enable Place transmitting functions of SPI master into IRAM (CONFIG_SPI_MASTER_IN_IRAM).

    Note

    Note that enabling CONFIG_FREERTOS_IN_IRAM will increase IRAM usage. Consider this trade-off when optimizing for SPI performance.

  • Deprecated HSPI and VSPI related IOMUX pin macros on ESP32 and ESP32S2 have been removed.

PSRAM

Deprecated header file esp_spiram.h has been removed. Please use esp_psram.h instead.

SPI Flash Driver

  • Deprecated enum type esp_flash_speed_t has been removed. The main flash speed is controlled by CONFIG_ESPTOOLPY_FLASHFREQ option.

  • Deprecated header file esp_spi_flash.h has been removed. Please use spi_flash_mmap.h instead.

  • Deprecated API spi_flash_dump_counters has been removed. Please use esp_flash_dump_counters() instead.

  • Deprecated API spi_flash_get_counters has been removed. Please use esp_flash_get_counters() instead.

  • Deprecated API spi_flash_reset_counters has been removed. Please use esp_flash_reset_counters() instead.

Note

Note that enabling CONFIG_FREERTOS_IN_IRAM will increase IRAM usage. Consider this trade-off when optimizing for SPI performance.

Touch Element

The touch_element component is moved to ESP Component Registry.

You can add this dependency to your project by running idf.py add-dependency "espressif/touch_element".

Touch Sensor

The touch_sensor_sample_config_t::bypass_shield_output member for version 3 touch sensor has been removed because it is not supported in the version 3 hardware.

I2S

  • i2s_port_t type has been removed. Please use int type instead. Its enum items I2S_NUM_0, I2S_NUM_1, I2S_NUM_2 and I2S_NUM_AUTO have been replaced by macro definitions to ensure compatibility.

USB

The usb component is moved to ESP Component Registry

You can add this dependency to your project by running idf.py add-dependency "espressif/usb".

Was this page helpful?