i2c

[English]

简介

i2c 外设描述 ESP-IDF I2C master bus。BMGR 将 board_peripherals.yaml 中的 i2c 条目转换为 i2c_master_bus_config_t，并在初始化时创建 I2C master bus 句柄。

i2c 常用于外接音频 codec 控制、LCD touch、IO expander、摄像头 SCCB 控制等设备。设备侧通过外设实例名引用同一条 I2C 总线，并在设备 peripherals 引用条目中填写器件地址等设备私有参数。

支持的工作模式

i2c 按控制器端口族区分配置方式。当前外设初始化入口仅创建 master bus，不提供 slave 设备模式。

最小配置

HP I2C master

完整字段见 HP I2C master 完整字段。

board_peripherals.yaml：

peripherals:
  - name: i2c_master
    type: i2c
    config:
      port: 0
      pins:
        sda: 17     # [IO]
        scl: 18     # [IO]

LP I2C master

完整字段见 HP I2C master 完整字段。

board_peripherals.yaml：

peripherals:
  - name: lp_i2c_master
    type: i2c
    config:
      port: LP_I2C_NUM_0
      clk_source: LP_I2C_SCLK_DEFAULT
      pins:
        sda: 6      # [IO]
        scl: 7      # [IO]

模式说明

HP I2C 使用 I2C_NUM_0 或 I2C_NUM_1 等端口宏，或对应的数字索引。port: -1 表示由 ESP-IDF 自动选择 HP I2C 端口，不可与 LP I2C 时钟源组合。

LP I2C 需显式使用 LP_I2C_NUM_0 一类端口宏，并使用 LP_I2C_SCLK_* 时钟源。LP I2C 的 GPIO 选择受目标芯片 LP GPIO 能力限制。

I2C 器件地址不写入外设 config：音频 codec 使用 address，LCD touch 与 IO expander 使用 i2c_addr，这些字段属于设备侧引用条目。

完整字段

HP I2C master 完整字段

# I2C Peripheral Default Configuration
# This file shows the default values used by the I2C peripheral parser
# Based on periph_i2c.py parsing script

- name: i2c_master
  type: i2c
  config:
    # I2C port number (default: -1 for auto selection)
    port: -1
    # Valid values:
    # - -1 (auto select, HP I2C only)
    # - numeric index: 0 / 1 (will map to I2C_NUM_0 / I2C_NUM_1)
    # - macro: I2C_NUM_0 / I2C_NUM_1 / LP_I2C_NUM_0

    # I2C clock source macro (optional)
    # If omitted:
    # - HP I2C uses I2C_CLK_SRC_DEFAULT
    # - LP I2C uses LP_I2C_SCLK_DEFAULT
    # Example values:
    #   I2C_CLK_SRC_DEFAULT, I2C_CLK_SRC_APB, I2C_CLK_SRC_XTAL,
    #   I2C_CLK_SRC_RC_FAST, I2C_CLK_SRC_REF_TICK,
    #   LP_I2C_SCLK_DEFAULT, LP_I2C_SCLK_LP_FAST, LP_I2C_SCLK_XTAL_D2
    clk_source: I2C_CLK_SRC_DEFAULT

    # I2C pins configuration
    pins:
      # SDA pin (default: -1, not set)
      sda: -1                     # [IO] SDA pin
      # SCL pin (default: -1, not set)
      scl: -1                     # [IO] SCL pin

    # Enable internal pullup resistors (default: true)
    enable_internal_pullup: true

    # Glitch filter count (default: 7)
    glitch_count: 7

    # Interrupt priority (default: 1)
    intr_priority: 1

适用设备

device type

使用方式

说明

audio_codec

设备 peripherals 引用 i2c，并填写 address 和 frequency

外接 codec 控制接口；I2C 地址写在设备侧

lcd_touch

设备 peripherals 引用 i2c，并填写 i2c_addr

触摸控制器通信；触摸坐标和复位/中断 GPIO 属于设备侧配置

gpio_expander

设备 peripherals 引用 i2c，并填写 i2c_addr

IO 扩展芯片控制；扩展 IO 的方向和默认电平属于设备侧配置

camera

DVP / SPI 摄像头可引用 i2c 作为 SCCB 控制总线

摄像头数据总线或 SPI 数据线不写进 i2c 外设

参考代码

  • esp_board_manager/peripherals/periph_i2c/periph_i2c.c

  • esp_board_manager/peripherals/periph_i2c/periph_i2c.h

  • esp_board_manager/examples/play_embed_music/main/play_embed_music.c

  • esp_board_manager/examples/record_to_sdcard/main/record_to_sdcard.c

板级参考

  • esp_friends_boards/esp32_s3_korvo_2l/board_peripherals.yaml：音频 codec 使用的 I2C 控制总线。

  • esp_boards/esp32_s3_lcd_ev_board/board_peripherals.yaml：音频、触摸和 IO expander 共用 I2C 总线。

  • m5stack_boards/m5stack_tab5/board_peripherals.yaml：音频、触摸和多个 IO expander 使用 I2C 总线。

注意事项

  • 公共 YAML 字段规则见 YAML 标记与写法。

  • clk_source 必须与端口族匹配。LP I2C 端口不可使用 I2C_CLK_SRC_*，HP I2C 端口不可使用 LP_I2C_SCLK_*。

  • 设备地址、I2C 传输频率、触摸控制参数、codec 控制参数属于设备侧配置，不写入 i2c 外设的 config。

  • 修改 I2C 外设配置后，需重新执行 idf.py bmgr -b <board>。

调试技巧

API 参考

使用 esp_board_manager_get_periph_handle() 获取 I2C 外设句柄，句柄类型为 ESP-IDF 原生的 i2c_master_bus_handle_t，可直接传入 i2c_master_* 系列 API 或用于挂载 I2C 设备。

相关声明位于 esp_board_manager/peripherals/periph_i2c/periph_i2c.h。

底层 ESP-IDF 驱动文档：I2C 接口。

此文档对您有帮助吗？