警告

This document is not updated for ESP32H21 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

# SPI 接口的 LCD

[English]

1. 创建 SPI 总线。详情请参阅 SPI 主机 API 文档。

   > 目前驱动支持 SPI， Quad SPI 和 Octal SPI（模拟 Intel 8080 时序）模式。

   >     spi_bus_config_t buscfg = {
   >         .sclk_io_num = EXAMPLE_PIN_NUM_SCLK,
   >         .mosi_io_num = EXAMPLE_PIN_NUM_MOSI,
   >         .miso_io_num = EXAMPLE_PIN_NUM_MISO,
   >         .quadwp_io_num = -1,
   >         .quadhd_io_num = -1,
   >         .max_transfer_sz = EXAMPLE_LCD_H_RES * 80 * sizeof(uint16_t), // 单次最多可传输 80 行像素（假设像素格式为 RGB565）
   >     };
   >     ESP_ERROR_CHECK(spi_bus_initialize(LCD_HOST, &buscfg, SPI_DMA_CH_AUTO)); // 启用 DMA

2. 从 SPI 总线分配一个 LCD IO 设备句柄。在此步骤中，需要提供以下信息：

   > - `esp_lcd_panel_io_spi_config_t::dc_gpio_num` 设置 DC 信号线的 GPIO 编号（部分 LCD 将该信号线称为 `RS` 线）。使用此 GPIO，LCD 驱动可以在发送命令和发送数据之间切换。

   > - `esp_lcd_panel_io_spi_config_t::cs_gpio_num` 设置 CS 信号线的 GPIO 编号。使用此 GPIO，LCD 驱动可以选择 LCD 芯片。如果 SPI 总线只连接了一个设备（即此 LCD），可将 GPIO 编号设置为 `-1`，从而独占总线。

   > - `esp_lcd_panel_io_spi_config_t::pclk_hz` 设置像素时钟的频率 (Hz)。设定的频率不应超过 LCD 规格书中推荐的范围。

   > - `esp_lcd_panel_io_spi_config_t::spi_mode` 设置 SPI 模式。LCD 驱动程序使用此模式与 LCD 通信。有关 SPI 模式的详细信息，请参阅 SPI 主机 API 文档。

   > - `esp_lcd_panel_io_spi_config_t::lcd_cmd_bits` 和 `esp_lcd_panel_io_spi_config_t::lcd_param_bits` 分别设置 LCD 控制器芯片可识别的命令及参数的位宽。不同芯片对位宽要求不同，请提前参阅 LCD 规格书。

   > - `esp_lcd_panel_io_spi_config_t::trans_queue_depth` 设置 SPI 传输队列的深度。该值越大，可以排队的传输越多，但消耗的内存也越多。

   > - `esp_lcd_panel_io_spi_config_t::cs_ena_pretrans` 设置 SPI 在传输之前应激活 CS 信号线的 SPI 位周期数 （0-16）。

   > - `esp_lcd_panel_io_spi_config_t::cs_ena_posttrans` 设置 SPI 在传输之后保持激活 CS 信号线的 SPI 位周期数 （0-16）。

   >     esp_lcd_panel_io_handle_t io_handle = NULL;
   >     esp_lcd_panel_io_spi_config_t io_config = {
   >         .dc_gpio_num = EXAMPLE_PIN_NUM_LCD_DC,
   >         .cs_gpio_num = EXAMPLE_PIN_NUM_LCD_CS,
   >         .pclk_hz = EXAMPLE_LCD_PIXEL_CLOCK_HZ,
   >         .lcd_cmd_bits = EXAMPLE_LCD_CMD_BITS,
   >         .lcd_param_bits = EXAMPLE_LCD_PARAM_BITS,
   >         .spi_mode = 0,
   >         .trans_queue_depth = 10,
   >     };
   >     // 将 LCD 连接到 SPI 总线
   >     ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)LCD_HOST, &io_config, &io_handle));

3. 安装 LCD 控制器驱动程序。LCD 控制器驱动程序负责向 LCD 控制器芯片发送命令和参数。在此步骤中，需要指定上一步骤中分配到的 SPI IO 设备句柄以及一些面板特定配置：

   > - `esp_lcd_panel_dev_config_t::reset_gpio_num` 设置 LCD 的硬件复位 GPIO 编号。如果 LCD 没有硬件复位管脚，则将此设置为 `-1`。

   > - `esp_lcd_panel_dev_config_t::rgb_ele_order` 设置每个颜色数据的 RGB 元素顺序。

   > - `esp_lcd_panel_dev_config_t::bits_per_pixel` 设置像素颜色数据的位宽。LCD 驱动程序使用此值计算要发送到 LCD 控制器芯片的字节数。

   > - `esp_lcd_panel_dev_config_t::data_endian` 指定传输到屏幕的数据的字节序。不超过一字节的颜色格式（如 RGB232）不需要指定数据字节序。若驱动程序不支持指定数据字节序，则将忽略此字段。

   >     esp_lcd_panel_handle_t panel_handle = NULL;
   >     esp_lcd_panel_dev_config_t panel_config = {
   >         .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
   >         .rgb_ele_order = LCD_RGB_ELEMENT_ORDER_BGR,
   >         .bits_per_pixel = 16,
   >     };
   >     // 为 ST7789 创建 LCD 面板句柄，并指定 SPI IO 设备句柄
   >     ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));

## API 参考

### Header File

- components/esp_lcd/include/esp_lcd_io_spi.h

- This header file can be included with:

  >     #include "esp_lcd_io_spi.h"

- This header file is a part of the API provided by the `esp_lcd` component. To declare that your component depends on `esp_lcd`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_lcd

  > or

  >     PRIV_REQUIRES esp_lcd

### Functions

esp_err_t esp_lcd_new_panel_io_spi(esp_lcd_spi_bus_handle_t bus, const esp_lcd_panel_io_spi_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io)

  Create LCD panel IO handle, for SPI interface.

  参数:

    - bus -- [in] SPI bus handle

    - io_config -- [in] IO configuration, for SPI interface

    - ret_io -- [out] Returned IO handle

  返回:

    - ESP_ERR_INVALID_ARG if parameter is invalid

    - ESP_ERR_NO_MEM if out of memory

    - ESP_OK on success

### Structures

struct esp_lcd_panel_io_spi_config_t

  Panel IO configuration structure, for SPI interface.

  Public Members

  gpio_num_t cs_gpio_num

    GPIO used for CS line

  gpio_num_t dc_gpio_num

    GPIO used to select the D/C line, set this to -1 if the D/C line is not used

  int spi_mode

    Traditional SPI mode (0~3)

  unsigned int pclk_hz

    Frequency of pixel clock

  size_t trans_queue_depth

    Size of internal transaction queue

  esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done

    Callback invoked when color data transfer has finished

  void *user_ctx

    User private data, passed directly to on_color_trans_done's user_ctx

  int lcd_cmd_bits

    Bit-width of LCD command

  int lcd_param_bits

    Bit-width of LCD parameter

  uint8_t cs_ena_pretrans

    Amount of SPI bit-cycles the cs should be activated before the transmission (0-16)

  uint8_t cs_ena_posttrans

    Amount of SPI bit-cycles the cs should stay active after the transmission (0-16)

  struct esp_lcd_panel_io_spi_config_t::esp_lcd_spi_flags_t flags

    Extra flags to fine-tune the SPI device

  struct esp_lcd_spi_flags_t

    Extra flags to fine-tune the SPI device.

    Public Members

    unsigned int dc_high_on_cmd

      If enabled, DC level = 1 indicates command transfer

    unsigned int dc_low_on_data

      If enabled, DC level = 0 indicates color data transfer

    unsigned int dc_low_on_param

      If enabled, DC level = 0 indicates parameter transfer

    unsigned int octal_mode

      transmit data and parameters with 8 lines

    unsigned int quad_mode

      transmit data and parameters with 4 lines

    unsigned int sio_mode

      Read and write through a single data line (MOSI)

    unsigned int lsb_first

      Transmit LSB bit first

    unsigned int cs_high_active

      CS line is high active

### Type Definitions

typedef int esp_lcd_spi_bus_handle_t

  Type of LCD SPI bus handle

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。