Published September 12, 2025

A Tiny ESPHome Desktop Gadget Powered By XIAO

Build a desktop gadget with Seeed XIAO ESP32-C3 + ESPHome + HA: lights up, shows editable text, and responds to button automations.

IntermediateFull instructions provided2 hours10

Things used in this project

Hardware components

Seeed Studio XIAO ESP32C3

Seeed Studio XIAO Expansion Board

Seeed Studio IoT Button

Seeed Studio Grove - Blue LED

Software apps and online services

Home Assistant

Story

One day I felt like dressing up my desk, so I dug out a XIAO ESP32-C3 and its tiny OLED base—and, lucky me, a Seeed IoT Button. With ESPHome and Home Assistant, a tap wakes the display and LED, another tap flips the message (“Hello Atom!” ⇄ “Happy Today”), and you can even reboot the XIAO remotely. It’s tiny and simple—a playful prototype—but I hope it sparks your next idea.

A few lines of YAML later, ESPHome exposed everything I needed to HA: the OLED text, an on/off “screen” switch, the Grove LED, even a restart control. The IoT Button becomes a pocket remote—map single/double/long presses however you like. No firmware tangles, just tweak automations and watch the gadget change in real time over OTA.

Now it lives beside my keyboard: a friendly mood light, a micro message board, a little badge for quick reminders. It’s intentionally minimal, but that’s the point—start small, ship fast, and remix: swap the LED for a sensor, rotate messages on a schedule, or let HA push notifications straight to the screen.

System Diagram

Actually, for a cleaner setup, I removed the LED from the Grove LED-Blue module and connected it directly to the XIAO using jumper wires.

Build

1.Prepare HA & ESPHome

Install the ESPHome add-on in Home Assistant.
Create fonts/ under /config/esphome/, copy Roboto-Regular.ttf there.
Create secrets.yaml if you haven’t, and add wifi_ssid, wifi_password, api_key, ota_pass.

2.Flash the XIAO

Use ESPHome “Install” to compile/flash via USB-C.
After first flash, future updates can be OTA from the ESPHome dashboard.

3.Add to Home Assistant

HA should auto-discover the ESPHome device. Accept it in Settings → Devices & Services.
You’ll see entities like Grove LED, OLED Screen, OLED Text, and XIAO ESP32C3 Restart.

4. Wire

OLED is on the expansion board already.
Plug the Grove LED into A0/D0 (or D10 if you prefer GPIO10). No code changes needed unless you move to GPIO10.

Home Assistant Automations (5 Motions)

I've set up 5 automations for it myself in Home Assistant. You can see the specifics in the table below, but of course, feel free to create your own, more interesting ones.

Motion Table

Troubleshooting

OLED blank/garbled: Confirm I²C 0x3C, pins SDA=GPIO6 / SCL=GPIO7. Check ESPHome logs; make sure the font file exists and path is correct.
Strapping pin warning (GPIO2): It’s a reminder that the pin is sampled at boot. The Grove LED typically won’t hold it. If you ever see odd boot behavior, move the LED to D10/ GPIO10 and update the YAML pin.
No entities in HA: Check the ESPHome device is online, API key matches, and your HA instance can reach the device’s IP.
Text too wide: Shorten the text or slightly reduce font size; 20pt fits most short phrases on 128×64.
Chinese characters: Use a CJK font (e.g., Noto Sans CJK). Firmware size will increase significantly.

Extensions & Next Steps

PWM dimming: Swap the LED switch for output: ledc + light: monochromatic to get brightness and fades
Auto pages: Cycle pages on the OLED (clock, countdown, weather) using an interval: and page index.
Sensors: Add Grove temp/humidity or gesture sensors; show readings on the display.
HA-pushed notifications: Use HA automations to push reminders (Pomodoro end, doorbell, calendar alerts) into OLED Text.
Enclosure: 3D-print a tiny case or laser-cut a stand; cut a window for the OLED.

Code

Example Code

esphome:
  name: xiao-esp32-c3
  friendly_name: XIAO-ESP32-C3

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf

logger:

api:
  encryption:
    key: "xxx"

ota:
  - platform: esphome
    password: "xxxx"

wifi:
  ssid: xxxx
  password: xxxx
  ap:
    ssid: "Xiao-Esp32-C3 Fallback Hotspot"
    password: "LiMaVGJhvXsP"

captive_portal:

# ---------- I2C: Onboard 0.96" SSD1306 ----------
i2c:
  sda: GPIO6
  scl: GPIO7
  scan: true

# ---------- Font (ensure /config/esphome/fonts/Roboto-Regular.ttf exists) ----------
font:
  - file: "fonts/Roboto-Regular.ttf"
    id: oled_font
    size: 20

# ---------- Text and screen state ----------
globals:
  - id: screen_on
    type: bool
    restore_value: yes
    initial_value: 'true'

text:
  - platform: template
    name: "OLED Text"
    id: oled_text
    mode: text
    optimistic: true
    min_length: 0
    max_length: 32
    restore_value: true
    initial_value: "Hello Atom!"
    on_value:
      - component.update: oled

# ---------- OLED Display ----------
display:
  - platform: ssd1306_i2c
    id: oled
    model: "SSD1306 128x64"
    address: 0x3C
    rotation: 0
    update_interval: 1s
    lambda: |-
      if (!id(screen_on)) {
        it.fill(Color::BLACK);
        return;
      }
      it.fill(Color::BLACK);
      std::string msg = id(oled_text).state;
      if (msg.empty()) msg = "Hello Atom!";
      it.printf(64, 32, id(oled_font), TextAlign::CENTER, "%s", msg.c_str());

# ---------- Grove LED (A0/D0 → GPIO2; to avoid strapping use D10→GPIO10) ----------
switch:
  - platform: gpio
    id: grove_led
    name: "Grove LED"
    pin:
      number: GPIO2          # Currently on A0/D0: D0→GPIO2
      # number: GPIO10       # ← If you move LED to D10, change to GPIO10
      mode:
        output: true
      inverted: false
    restore_mode: RESTORE_DEFAULT_OFF

  - platform: template
    id: oled_power
    name: "OLED Screen"
    restore_mode: RESTORE_DEFAULT_ON   # ← Fix: replaces restore_state
    optimistic: true
    turn_on_action:
      - lambda: |-
          id(screen_on) = true;
      - component.update: oled
    turn_off_action:
      - lambda: |-
          id(screen_on) = false;
      - component.update: oled

  - platform: restart
    name: "XIAO ESP32C3 Restart"

# ---------- Power-on self-test: blink once ----------
interval:
  - interval: 1s
    then:
      - if:
          condition:
            lambda: 'static bool done=false; if(done) return false; done=true; return true;'
          then:
            - switch.turn_on: grove_led
            - delay: 500ms
            - switch.turn_off: grove_led

Credits

Atom Yang

2 projects • 1 follower

A Tiny ESPHome Desktop Gadget Powered By XIAO

Things used in this project

Hardware components

Software apps and online services

Story

System Diagram

Build

Home Assistant Automations (5 Motions)

Troubleshooting

Extensions & Next Steps

Schematics

Roboto-Regular.ttf

Code

Example Code

Credits

Atom Yang

Comments

Embed the widget on your own site

A Tiny ESPHome Desktop Gadget Powered By XIAO

A Tiny ESPHome Desktop Gadget Powered By XIAO

Things used in this project

Hardware components

Software apps and online services

Story

System Diagram

Build

Home Assistant Automations (5 Motions)

Troubleshooting

Extensions & Next Steps

Schematics

Roboto-Regular.ttf

Code

Example Code

Credits

Atom Yang

Comments

Related channels and tags