Unit Key Home Assistant Integration

This tutorial will introduce how to use the Unit Key single button input unit with the CoreS3 main controller and integrate it into Home Assistant to achieve button state acquisition and light control.

1. Preparation

Environment Setup

1. Follow the official Home Assistant documentation to install Home Assistant. (This tutorial uses Home Assistant 2026.2.0 or later.)
2. Follow the official ESPHome documentation to install the ESPHome Device Builder add-on. (Note: This tutorial is based on ESPHome 2026.2.2. If you encounter compilation errors, switch to this version first for verification.)

Hardware

• Unit Key
• CoreS3
• HY2.0-4P Grove Cable (20cm)

2. Firmware Compilation & Flashing

This section explains how to recompile the project based on the yaml configuration file, making it easier to perform secondary development, modify features, or add new features.

Create Device

1. Open the ESPHome Dashboard. If the initial guidance interface appears, click CONTINUE.

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

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

4. Enter the device name and click NEXT.

5. Select the device type, click ESP32S3.

6. Click SKIP to skip the encryption key setup.

Modify Configuration

1. Click EDIT to enter the YAML configuration page and customize device functionality.

Sensor Configuration

Add the Binary Sensor component to obtain button state.

binary_sensor:
  - platform: gpio
    name: "Button"
    id: unit_key_button
    pin:
      number: GPIO8 # CoreS3 PORT.B, please adjust according to the actual connected GPIO pin
      mode:
        input: true
        pullup: true
      inverted: true
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms
    on_press:
      then:
        - logger.log: "Pressed"
        - light.toggle: unit_key_led
    on_multi_click:
      - timing:
          - ON for at least 1s
        then:
          - logger.log: "Hold"
          - light.turn_off: unit_key_led

Light Configuration

Add the Light component to control the backlight RGB LED.

light:
  - platform: neopixelbus
    name: "LED"
    id: unit_key_led
    type: GRB            
    variant: SK6812
    pin: GPIO9 # CoreS3 PORT.B, please adjust according to the actual connected GPIO pin
    num_leds: 1
    method:
      type: esp32_rmt
      channel: 0
    default_transition_length: 200ms
    restore_mode: RESTORE_DEFAULT_OFF

Compile Firmware

1. After completing the YAML modifications, click SAVE in the upper right corner to save the configuration, then click INSTALL.

2. Select Manual Download in the pop-up window.

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

Flash Firmware

1. Connect the CoreS3 to your computer using a USB Type-C cable. Open ESPHome Web and click CONNECT.

2. In the serial port selection window that appears, select the correct serial port.

3. Click INSTALL.

4. Select the firmware file downloaded in step 3 and start flashing.

3. Getting Started

1. In Home Assistant, click Settings > Devices & Services in sequence to enter the integration management page.

2. Find the Unit Key device in the Discovered area, click CONFIGURE and follow the wizard to complete the configuration.

3. After the device is added, you can see real-time information of the button state and LED light state on the device details page.

4. Finally, add these sensor entities to the dashboard to monitor the button state and light status in real time.