Unit Encoder Home Assistant Integration

This tutorial uses the Unit Encoder rotary encoder with an Atom Lite controller and integrates it into Home Assistant to enable knob value reading, button detection, and RGB LED control.

Preparation

1. Hardware list.

• 1 x Unit Encoder.
• 1 x Atom Lite.
• 1 x HY2.0-4P Grove Cable (20cm).
• 1 x Home Assistant host.

2. Software and versions.

• Home Assistant 2026.5.0 or later.
• ESPHome Device Builder 2026.4.5 or later.

Create Device

1. Open the ESPHome Dashboard. If the initial setup wizard appears, click CONTINUE.

2. Click the green + button in the bottom-right corner to start creating a new device.

3. Click New Device Setup to enter the device creation wizard.

4. Enter a device name and click NEXT.

5. Select the device type. First uncheck Use recommended settings, then select ESP32. In the details panel, find and select Unit Encoder, then click NEXT.

6. Click SKIP to skip the encryption key setup.

7. Click EDIT to open the YAML configuration page and customize the device.

Device Configuration

External Components

Add the External Components configuration to the YAML file to load the Unit Encoder driver.

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

I2C Bus Configuration

Add the I2C component and configure the communication pins between the Unit Encoder and Atom Lite.

i2c:
  sda: GPIO26
  scl: GPIO32
  scan: true

Sensor Configuration

Add the Sensor component to read the encoder rotation value.

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

Binary Sensor (Button) Configuration

Add the Binary Sensor component to detect encoder button press events.

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

Output Configuration

Add the Output component to map each color channel of the two SK6812 RGB LEDs as individual outputs for use by the Light component.

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 Configuration

Add the Light component to control the two built-in SK6812 programmable RGB LEDs on the Unit Encoder.

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

Key parameter descriptions:

Download and Flash Firmware

Compile Firmware

1. After completing the YAML edits, click SAVE in the top-right corner to save the configuration, then click INSTALL.

2. In the pop-up window, select Manual Download.

3. Wait for the firmware to compile, then click Download and select Factory format (Previously Modern) to save the firmware locally.

Flash Firmware

4. Connect the Atom Lite to your computer via a USB Type-C cable. Open ESPHome Web and click CONNECT.

5. In the serial port selection pop-up, find and select the corresponding port.

6. Click INSTALL.

7. Select the firmware file downloaded in step 3 to upload.

Getting Started

1. In Home Assistant, go to Settings > Devices & Services to open the integration management page.

2. In the Discovered section, find the online Unit Encoder device, click CONFIGURE, and follow the prompts to complete the setup.

3. Once added, the device page will show the encoder value, button state, and RGB LED control entities.

4. Finally, add the sensor entities to a dashboard to monitor the encoder value and button state in real time, and to control the LED color.