Unit Step16 Home Assistant 集成

本教程将介绍如何使用 Unit Step16 16 位旋转编码器控制单元集成至 Home Assistant，实现旋钮数值与灯光控制。

1. 准备工作

环境准备

参考 Home Assistant 官方文档安装 Home Assistant。
参考 ESPHome 官方文档完成 ESPHome Device Builder 插件安装。（注意：本教程基于 ESPHome 2026.1.2 版本编写，如遇编译错误，建议先切换至该版本进行验证。）

硬件产品

2. 固件编译 & 烧录

本小节将说明如何基于 yaml 配置文件重新编译项目，便于二次开发、功能修改或新增功能。

编译时长

通过 HA 进行固件编译较为耗费资源，首次编译可能会需要较长时间进行资源下载，跟实际部署 HA 服务的设备以及网络质量相关。

创建设备

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

创建设备名称。

点击 CONTINUE。

点击 New Device Setup。

输入设备名称并点击 NEXT。

选择设备类型。

点击 ESP32。

点击 SKIP。

修改配置

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

以下是代码的核心部分。下面提供了相关的参考和说明。

外部组件配置

添加 External 组件：

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: unit_step16
    refresh: 0s

unit_step16:
  id: my_step16
  i2c_id: bsp_iic
  address: 0x48 

I2C 配置

i2c:
  - id: bsp_iic
    scl: GPIO32
    sda: GPIO26
    scan: True 

传感器配置

添加 Sensor 组件：

sensor:
  - platform: unit_step16
    unit_step16_id: my_step16
    name: "Encoder Value"
    update_interval: 100ms
    on_value:
      then:
        - logger.log:
            format: "Encoder value changed to: %.0f"
            args: ["x"] 

输出配置

添加 Output 组件：

output:
  - platform: unit_step16
    id: led_brightness_output
    unit_step16_id: my_step16
    channel: led_brightness

  - platform: unit_step16
    id: rgb_brightness_output
    unit_step16_id: my_step16
    channel: rgb_brightness

  - platform: unit_step16
    id: rgb_red_output
    unit_step16_id: my_step16
    channel: rgb_red

  - platform: unit_step16
    id: rgb_green_output
    unit_step16_id: my_step16
    channel: rgb_green

  - platform: unit_step16
    id: rgb_blue_output
    unit_step16_id: my_step16
    channel: rgb_blue 

灯光配置

添加 Light 组件：

light:
  - platform: rgb
    id: step16_rgb_light
    name: "Step16 RGB Light"
    red: rgb_red_output
    green: rgb_green_output
    blue: rgb_blue_output
    restore_mode: ALWAYS_ON
    default_transition_length: 0s

  - platform: monochromatic
    id: step16_led_display
    name: "Step16 LED Display"
    output: led_brightness_output
    restore_mode: ALWAYS_ON
    default_transition_length: 0s 

数字配置

添加 Number 组件：

number:
  - platform: template
    name: "RGB Brightness"
    min_value: 0
    max_value: 100
    step: 1
    optimistic: true
    initial_value: 50
    on_value:
      then:
        - output.set_level:
            id: rgb_brightness_output
            level: !lambda "return x / 100.0;" 