Unit Encoder Home Assistant 集成

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

1. 准备工作

环境准备

参考 Home Assistant 官方文档安装 Home Assistant（要求 2026.5.0 或更高版本）。
参考 ESPHome 官方文档完成 ESPHome Device Builder 插件安装。（注意：本教程基于 ESPHome 2026.4.5 或更高版本编写。）

硬件产品

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

2. 固件编译 & 烧录

编译时长

首次构建可能需要一段时间，具体取决于 Home Assistant 主机的性能和网络质量。

创建设备

打开 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`