# I2C 接口的 LCD

[English]

1. 创建 I2C 总线。详细信息，请参阅 I2C API 文档。

   >     i2c_master_bus_handle_t i2c_bus = NULL;
   >     i2c_master_bus_config_t bus_config = {
   >         .clk_source = I2C_CLK_SRC_DEFAULT,
   >         .glitch_ignore_cnt = 7,
   >         .i2c_port = I2C_BUS_PORT,
   >         .sda_io_num = EXAMPLE_PIN_NUM_SDA,
   >         .scl_io_num = EXAMPLE_PIN_NUM_SCL,
   >         .flags.enable_internal_pullup = true,
   >     };
   >     ESP_ERROR_CHECK(i2c_new_master_bus(&bus_config, &i2c_bus));

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

   > - `esp_lcd_panel_io_i2c_config_t::dev_addr` 设置 LCD 控制器芯片的 I2C 设备地址。LCD 驱动程序使用此地址与 LCD 控制器芯片通信。

   > - `esp_lcd_panel_io_i2c_config_t::scl_speed_hz` 设置 I2C 时钟频率 (Hz)。该值不应超过 LCD 规格书中推荐的范围。

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

   > - `esp_lcd_panel_io_i2c_config_t::transaction_timeout_ms` 设置每次底层 I2C 传输的超时时间（毫秒）。设为 0 或 -1 时表示无限等待；如指定为正值，则面板 IO 相关调用会在超时后返回 `ESP_ERR_TIMEOUT`，适用于共享总线或总线可能被从设备挂死的场景。

   >     esp_lcd_panel_io_handle_t io_handle = NULL;
   >     esp_lcd_panel_io_i2c_config_t io_config = {
   >         .dev_addr = EXAMPLE_I2C_HW_ADDR,
   >         .scl_speed_hz = EXAMPLE_LCD_PIXEL_CLOCK_HZ,
   >         .control_phase_bytes = 1, // 参阅 LCD 规格
   >         .dc_bit_offset = 6,       // 参阅 LCD 规格
   >         .lcd_cmd_bits = EXAMPLE_LCD_CMD_BITS,
   >         .lcd_param_bits = EXAMPLE_LCD_CMD_BITS,
   >     };
   >     ESP_ERROR_CHECK(esp_lcd_new_panel_io_i2c(i2c_bus, &io_config, &io_handle));

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

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

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

   >     esp_lcd_panel_handle_t panel_handle = NULL;
   >     esp_lcd_panel_dev_config_t panel_config = {
   >         .bits_per_pixel = 1,
   >         .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
   >     };
   >     ESP_ERROR_CHECK(esp_lcd_new_panel_ssd1306(io_handle, &panel_config, &panel_handle));

## API 参考

### Header File

- components/esp_lcd/include/esp_lcd_io_i2c.h

- This header file can be included with:

  >     #include "esp_lcd_io_i2c.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_i2c(i2c_master_bus_handle_t bus, const esp_lcd_panel_io_i2c_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io)

  Create LCD panel IO handle, for I2C interface in new implementation.

  备注

  Please don't call this function in your project directly. Please call `esp_lcd_new_panel_to_i2c` instead.

  参数:

    - bus -- [in] I2C bus handle, (in i2c_master_dev_handle_t)

    - io_config -- [in] IO configuration, for I2C 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_i2c_config_t

  Panel IO configuration structure, for I2C interface.

  Public Members

  uint32_t dev_addr

    I2C device address

  uint32_t scl_speed_hz

    I2C LCD SCL frequency (hz)

  size_t control_phase_bytes

    I2C LCD panel will encode control information (e.g. D/C selection) into control phase, in several bytes

  uint8_t dc_bit_offset

    Offset of the D/C selection bit in control phase

  int lcd_cmd_bits

    Bit-width of LCD command

  int lcd_param_bits

    Bit-width of LCD parameter

  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

  unsigned int dc_low_on_data

    If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa

  unsigned int disable_control_phase

    If this flag is enabled, the control phase isn't used

  struct esp_lcd_panel_io_i2c_config_t flags

    Extra flags to fine-tune the I2C device

  int transaction_timeout_ms

    Timeout for each I2C transfer in ms, 0/-1: wait forever, >0: finite timeout

此文档对您有帮助吗？

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

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