m5-docs

Chain DualKey Home Assistant 集成

简介

Chain DualKey 是一款基于 ESP32-S3FN8 主控芯片的可编程双键输入开发板。正面集成了 2 个可热插拔的蓝轴机械键盘按键和 2 颗可编程 RGB LED，提供良好的交互反馈。板载 350mAh 锂电池，结合低功耗设计，具备不错的续航表现。产品预装 Chain 宏键盘固件，支持 USB / BLE 连接，可以模拟 HID 输入设备。设备上电后，可连接设备的 AP 热点，通过内置网页为本机或扩展节点配置 HID 功能映射，实现多种控制功能。该开发板采用 M5Stack Chain 系列可扩展设计，提供两个 HY2.0-4P 扩展接口，支持左右侧扩展并连接其他传感器设备。配合 ESP32-S3 内置的 USB-OTG 外设功能，适用于智能家居、键盘外设、宏键盘等各种场景。

准备工作

Home Assistant 主机
在 Home Assistant 中安装并启用 ESPHome Builder
Chain DualKey
Chain Angel
Chain Encoder
Chain Key
Chain Joystick
Chain Tof

提示

本教程中，固件在 ESPHome 2025.1.2 下编译和上传。如果遇到编译/上传问题，请考虑将 ESPHome 切换至此版本。

步骤 1. 创建新设备

点击右下角的绿色按钮创建设备。

步骤 2. 创建设备名称

点击 CONTINUE。

点击 New Device Setup。

输入设备名称后点击 NEXT。

步骤 3. 选择设备类型

提示

这里我们使用 Atom-Lite 作为主控来操作 Chain DualKey 及其扩展传感器。

点击 ESP32-S3。

点击 SKIP。

步骤 4. 编辑 YAML 文件

点击 EDIT，我们可以通过 YAML 文件自定义设备功能。

设备配置

Master 作为系统的主控制器。在连接扩展传感器时，需要正确区分连接方向以及 ID 编号顺序。

方向选择

根据扩展传感器连接在 Master 的哪一侧，选择对应的 uart_id：

连接在 Master 左侧 → 使用 chain_uart_left
连接在 Master 右侧 → 使用 chain_uart_right

ID 编号规则

chain_id 表示扩展传感器相对于 Master 的位置：

编号从距离 Master 最近的模块开始
ID 依次递增（ID:1 → ID:2 → ID:3 …）
左右两侧分别独立编号
可参考上图确定正确的顺序

配置示例

uart_id: chain_uart_left
chain_id: 1

Chain DualKey

uart:
  - id: chain_uart_right
    tx_pin: GPIO6
    rx_pin: GPIO5
    baud_rate: 115200

  - id: chain_uart_left
    tx_pin: GPIO48
    rx_pin: GPIO47
    baud_rate: 115200

sensor:
  - platform: adc
    pin: GPIO10
    name: "ADC_BAT"
    update_interval: 1s

  - platform: adc
    pin: GPIO2
    name: "ADC_VBUS"
    update_interval: 1s

  - platform: adc
    pin: GPIO9
    name: "ADC_CHARGE"
    update_interval: 1s

output:
  - platform: gpio
    id: pwr_en
    pin: GPIO40

light:
  - platform: esp32_rmt_led_strip
    id: key_light_raw
    internal: true
    pin: GPIO21
    num_leds: 2
    chipset: ws2812
    rgb_order: GRB
    restore_mode: ALWAYS_OFF

  - platform: partition
    name: "Key Light 1"
    id: key_light_1
    segments:
      - id: key_light_raw
        from: 0
        to: 0

  - platform: partition
    name: "Key Light 2"
    id: key_light_2
    segments:
      - id: key_light_raw
        from: 1
        to: 1

binary_sensor:

  - platform: gpio
    name: "KEY_2"
    pin:
      number: GPIO17
      inverted: true
      mode: INPUT_PULLUP
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms

    on_press:
      - light.turn_on:
          id: key_light_1
          transition_length: 0ms

    on_release:
      - light.turn_off: key_light_1

  - platform: gpio
    name: "KEY_1"
    pin:
      number: GPIO0
      inverted: true
      mode: INPUT_PULLUP
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms

    on_press:
      - light.turn_on:
          id: key_light_2
          transition_length: 0ms

    on_release:
      - light.turn_off: key_light_2

  - platform: gpio
    name: "SWITCH_1"
    pin:xs
      number: GPIO7
      mode: INPUT

  - platform: gpio
    name: "SWITCH_2"
    pin:
      number: GPIO8
      mode: INPUT 

Chain Key

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: [m5stack_chain_key]
    refresh: 0s

binary_sensor:
  - platform: m5stack_chain_key
    name: "Chain Key Right 1"
    uart_id: xx
    chain_id: xx        
    update_interval: 50ms 

Chain Angle

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: [m5stack_chain_angle]
    refresh: 0s

sensor:
  - platform: m5stack_chain_angle
    name: "Chain Angle Left"
    uart_id: xx
    chain_id: xx
    update_interval: 50ms 

Chain Encoder

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: [m5stack_chain_encoder]
    refresh: 0s

sensor:
  - platform: m5stack_chain_encoder
    name: "Chain Encoder"
    uart_id: xx   
    chain_id: xx                
    update_interval: 100ms 

Chain Joystick

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: [m5stack_chain_joystick]
    refresh: 0s

sensor:
  - platform: m5stack_chain_joystick
    name: "Chain Joystick Left X"
    uart_id: xx
    chain_id: xx
    axis: x
    update_interval: 50ms

  - platform: m5stack_chain_joystick
    name: "Chain Joystick Left Y"
    uart_id: xx
    chain_id: xx
    axis: y
    update_interval: 50ms 

Chain Tof

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: [m5stack_chain_tof]
    refresh: 0s

sensor:
  - platform: m5stack_chain_tof
    name: "Chain Tof"
    uart_id: xx   
    chain_id: xx                
    update_interval: 100ms 

示例

下面的代码示例是根据上图所示的连接顺序进行配置的。

外部组件

添加 External 组件

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: [m5stack_chain_angle,m5stack_chain_encoder,m5stack_chain_tof,m5stack_chain_joystick,m5stack_chain_key]
    refresh: 0s 

UART 组件

添加 Uart 组件

captive_portal:
uart:
  - id: chain_uart_right
    tx_pin: GPIO6
    rx_pin: GPIO5
    baud_rate: 115200

  - id: chain_uart_left
    tx_pin: GPIO48
    rx_pin: GPIO47
    baud_rate: 115200 

传感器组件

添加 Sensor 组件

sensor:
  - platform: m5stack_chain_encoder
    name: "Chain Encoder"
    uart_id: chain_uart_right   
    chain_id: 1                
    update_interval: 100ms

  - platform: m5stack_chain_tof
    name: "Chain Tof"
    uart_id: chain_uart_right   
    chain_id: 3                
    update_interval: 100ms

  - platform: m5stack_chain_angle
    name: "Chain Angle Left"
    uart_id: chain_uart_right
    chain_id: 2
    update_interval: 100ms
    
  - platform: m5stack_chain_joystick
    name: "Chain Joystick Left X"
    uart_id: chain_uart_left
    chain_id: 1
    axis: x
    update_interval: 100ms

  - platform: m5stack_chain_joystick
    name: "Chain Joystick Left Y"
    uart_id: chain_uart_left
    chain_id: 1
    axis: y
    update_interval: 100ms

  - platform: adc
    pin: GPIO10
    name: "ADC_BAT"
    update_interval: 1s

  - platform: adc
    pin: GPIO2
    name: "ADC_VBUS"
    update_interval: 1s

  - platform: adc
    pin: GPIO9
    name: "ADC_CHARGE"
    update_interval: 1s 

输出组件

添加 Output 组件

output:
  - platform: gpio
    id: pwr_en
    pin: GPIO40 

灯光组件

添加 Light 组件

light:
  - platform: esp32_rmt_led_strip
    id: key_light_raw
    internal: true
    pin: GPIO21
    num_leds: 2
    chipset: ws2812
    rgb_order: GRB
    restore_mode: ALWAYS_OFF

  - platform: partition
    name: "Key Light 1"
    id: key_light_1
    segments:
      - id: key_light_raw
        from: 0
        to: 0

  - platform: partition
    name: "Key Light 2"
    id: key_light_2
    segments:
      - id: key_light_raw
        from: 1
        to: 1 

二进制传感器组件

添加 Binary Sensor 组件

binary_sensor:
  - platform: gpio
    name: "KEY 2"
    pin:
      number: GPIO17
      inverted: true
      mode: INPUT_PULLUP
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms

    on_press:
      - light.turn_on:
          id: key_light_2
          transition_length: 0ms

    on_release:
      - light.turn_off: key_light_2

  - platform: gpio
    name: "KEY 1"
    pin:
      number: GPIO0
      inverted: true
      mode: INPUT_PULLUP
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms

    on_press:
      - light.turn_on:
          id: key_light_1
          transition_length: 0ms

    on_release:
      - light.turn_off: key_light_1

  - platform: m5stack_chain_key
    name: "Chain Key Right 1"
    uart_id: chain_uart_left
    chain_id: 2        
    update_interval: 50ms

  - platform: gpio
    name: "SWITCH 1"
    pin:
      number: GPIO7
      mode: INPUT

  - platform: gpio
    name: "SWITCH 2"
    pin:
      number: GPIO8
      mode: INPUT 