# 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 psram_dma_direct

      If color buffer is in PSRAM, use PSRAM for DMA buffer directly, has speed limit, but no temp buffer and save memory

    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

此文档对您有帮助吗？

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

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