Unit Encoder Home Assistant 集成

本教程将使用 Unit Encoder 旋转编码器搭配 Atom Lite 主控，并将其集成到 Home Assistant 中，实现旋钮数值读取、按键检测与 RGB LED 控制。

准备工作

硬件清单。

1 x Unit Encoder。
1 x Atom Lite。
1 x HY2.0-4P Grove 连接线 (20cm)。
1 x Home Assistant 主机。

软件与版本。

Home Assistant 2026.5.0 及以上。
ESPHome Device Builder 2026.4.5 及以上。

创建设备

打开 ESPHome Dashboard，若出现初始引导界面，点击 CONTINUE。

点击右下角的绿色 + 按钮，开始创建新设备。

点击 New Device Setup，进入设备创建向导。

输入设备名称，点击 NEXT。

选择设备类型，先取消勾选 Use recommended settings，然后选择 ESP32，在详情页中找到 Unit Encoder 并选中，点击 NEXT。

点击 SKIP，跳过加密密钥设置。

点击 EDIT，进入 YAML 配置页面，自定义设备功能。

设备配置

外部组件配置

在 YAML 文件中添加 External Components 配置，加载 Unit Encoder 驱动。

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

I2C 总线配置

添加 I2C 组件，配置 Unit Encoder 与 Atom Lite 之间的通信引脚。

i2c:
  sda: GPIO26
  scl: GPIO32
  scan: true 

说明

Atom Lite Grove 接口对应 SDA: GPIO26，SCL: GPIO32。Unit Encoder 默认 I2C 地址为 0x40。若使用其他接口，请根据实际管脚进行调整。

Sensor 传感器配置

添加 Sensor 组件，读取编码器旋转数值。

sensor:
  - platform: m5unit_encoder
    id: unit_encoder_1
    name: "Encoder Value" 

Binary Sensor 按键配置

添加 Binary Sensor 组件，检测编码器按键按下状态。

binary_sensor:
  - platform: m5unit_encoder
    m5unit_encoder_id: unit_encoder_1
    name: "Encoder Button" 

Output 输出配置

添加 Output 组件，将两颗 SK6812 RGB LED 的每个颜色通道映射为独立输出，供 Light 组件调用。

output:
  - platform: m5unit_encoder
    m5unit_encoder_id: unit_encoder_1
    led_index: 0
    channel: red
    id: led0_red
  - platform: m5unit_encoder
    m5unit_encoder_id: unit_encoder_1
    led_index: 0
    channel: green
    id: led0_green
  - platform: m5unit_encoder
    m5unit_encoder_id: unit_encoder_1
    led_index: 0
    channel: blue
    id: led0_blue
  - platform: m5unit_encoder
    m5unit_encoder_id: unit_encoder_1
    led_index: 1
    channel: red
    id: led1_red
  - platform: m5unit_encoder
    m5unit_encoder_id: unit_encoder_1
    led_index: 1
    channel: green
    id: led1_green
  - platform: m5unit_encoder
    m5unit_encoder_id: unit_encoder_1
    led_index: 1
    channel: blue
    id: led1_blue 

Light 灯光配置

添加 Light 组件，控制 Unit Encoder 内置的 2 颗 SK6812 可编程 RGB LED。

light:
  - platform: rgb
    name: "LED 0"
    red: led0_red
    green: led0_green
    blue: led0_blue
  - platform: rgb
    name: "LED 1"
    red: led1_red
    green: led1_green
    blue: led1_blue 

主要参数说明：

参数	说明
`m5unit_encoder_id`	关联到对应的 m5unit_encoder sensor 实例 ID
`led_index`	LED 索引，0 或 1，对应两颗 SK6812 LED
`channel`	颜色通道，可选 `red`、`green`、`blue`