Waveshare CH32V003 I/O 扩展器

Waveshare IO CH32V003 组件允许你在 ESPHome 中使用基于 CH32V003 微控制器的 Waveshare I/O 扩展模块。它使用 I²C 总线 进行通信。

Waveshare IO CH32V003 模块提供：

• 8 个 GPIO 引脚（0-7）：可以单独配置为数字输入或数字输出
• 1 个专用 PWM 输出：单个 PWM 通道，具有可配置的占空比和安全限制
• 1 个 ADC 输入：用于读取模拟值的 10 位模数转换器

配置完成后，你可以将 8 个 GPIO 引脚中的任意一个用于数字 I/O 操作。在 ESPHome 中，它们模拟真实的内部 GPIO 引脚，因此可以与 ESPHome 的许多组件一起使用，如 GPIO 二进制传感器和 GPIO 开关。PWM 输出和 ADC 输入通过其专用组件访问。

任何接受 引脚模式 的 GPIO 选项都可以用于这 8 个数字引脚。

NOTE

自 2024 年起，这款 I/O 扩展器芯片已用于多个 Waveshare 显示板。

组件/中心

Waveshare IO CH32V003 是 I²C 总线 从设备。其默认地址为 0x24。

waveshare_io_ch32v003:
  - id: wave_hub
    address: 0x24
    i2c_id: bus_a

配置变量

• id (必选, ID): 用于此组件的 id。
• address (可选, int): 扩展器的 I²C 地址。 默认为 0x24。
• i2c_id (可选): 如果你有多个 I²C 总线，则为 I²C 总线 ID。

二进制传感器示例

Waveshare IO CH32V003 引脚可以用作二进制传感器，用于读取数字输入状态。

# 示例配置
binary_sensor:
  - platform: gpio
    name: "IO Pin 0 Input"
    id: wave_pin_0
    pin:
      waveshare_io_ch32v003: wave_hub
      number: 0
      mode: INPUT
      inverted: false

开关示例

Waveshare IO CH32V003 引脚可以用作数字输出开关。

# 示例配置
switch:
  - platform: gpio
    name: "IO Pin 1 Output"
    id: wave_pin_1
    pin:
      waveshare_io_ch32v003: wave_hub
      number: 1
      mode: OUTPUT
      inverted: false

传感器示例

从 Waveshare IO CH32V003 的专用模拟输入读取内置的 10 位 ADC 值。返回值在 0…1 范围内。使用 reference_voltage 获取电压读数。例如，对于 3.3V 总线和 3:1 分压器，参考电压为 3.3V x 3 = 9.9V。

# 示例配置
sensor:
  - platform: waveshare_io_ch32v003
    waveshare_io_ch32v003_id: wave_hub
    id: wave_adc
    name: "Battery level"
    reference_voltage: 9.9

PWM 输出示例

Waveshare IO CH32V003 具有单个专用 PWM 输出，配有硬件安全限制以保护连接的电路。

# 示例配置：带安全限制的专用 PWM 输出
i2c:
  id: bus_a
  sda: GPIO8
  scl: GPIO9

waveshare_io_ch32v003:
  - id: wave_hub
    address: 0x24  # 默认地址为 0x24
    i2c_id: bus_a

output:
  - platform: waveshare_io_ch32v003
    waveshare_io_ch32v003_id: wave_hub
    id: wave_pwm
    inverted: true  # 示例：在 ESP32S3-Touch-LCD-7B 板上 PWM 是反转的
    safe_pwm_levels:
      min_value: 1 # 示例：power_supply 组件正常工作所需的安全级别
      max_value: 247 # 示例：ESP32S3-Touch-LCD-7B 板的安全级别

light:
  - platform: monochromatic
    id: pwm_light
    name: "PWM Light"
    output: wave_pwm
    default_transition_length: 0.5s

PWM 安全功能

PWM 输出包含可配置的安全限制以保护硬件：

• safe_pwm_levels：配置最小和最大占空比限制
  • min_value (可选, integer): 最小 PWM 占空比（0 到 255）。默认为 1。
  • max_value (可选, integer): 最大 PWM 占空比（0 到 255）。默认为 247。

这些限制确保 PWM 值被限制在安全范围内，防止极端占空比造成的潜在硬件损坏。

完整示例

# 完整配置示例
esphome:
  name: waveshare-io-test
  friendly_name: "Waveshare IO Test"

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf

# 配置 I²C 总线
i2c:
  id: bus_a
  sda: GPIO8
  scl: GPIO9
  scan: true

# 配置 Waveshare IO 扩展器
waveshare_io_ch32v003:
  - id: wave_hub
    address: 0x24
    i2c_id: bus_a

# 引脚 0 上的二进制传感器
binary_sensor:
  - platform: gpio
    name: "Button Input"
    pin:
      waveshare_io_ch32v003: wave_hub
      number: 0
      mode: INPUT
      inverted: true

# 引脚 1 上的开关
switch:
  - platform: gpio
    name: "Digital Output"
    pin:
      waveshare_io_ch32v003: wave_hub
      number: 1
      mode: OUTPUT

# 带安全限制的 PWM 输出
output:
  - platform: waveshare_io_ch32v003
    id: wave_pwm_out
    waveshare_io_ch32v003_id: wave_hub
    power_supply: wave_hub_backlight_enable
    inverted: true
    zero_means_zero: true
    safe_pwm_levels:
      min_value: 1
      max_value: 247

# 用于控制显示屏开/关的电源
power_supply:
  - id: wave_hub_backlight_enable
    pin:
      waveshare_io_ch32v003: wave_hub
      number: 2
      mode:
        output: true
    enable_time: 0ms
    keep_on_time: 0ms

# 使用 PWM 输出的灯
light:
  - platform: monochromatic
    name: "PWM Light"
    output: wave_pwm_out

# ADC 传感器
sensor:
  - platform: waveshare_io_ch32v003
    name: "Battery level"
    id: wave_adc
    # 将 ADC 值转换为电压（10 位 ADC，3.3V 参考电压，3:1 分压器）
    # value = adc * 3 * 3.3V / 1023.0
    reference_voltage: 9.9  # 因此返回的值为 ADC * 9.9 / 1023.0

参见

• I²C 总线
• GPIO 开关
• GPIO 二进制传感器
• 单色灯
• 输出
• API 参考：waveshare_io_ch32v003.h