Skip to content

ESPHome Starter Kit - Getting Started

This guide walks you through setting up the hardware in your kit, installing the ESPHome Device Builder add-on in Home Assistant, and writing your first ESPHome YAML configuration from scratch.

By the end you'll have your ESP32-C6 board flashed with a working configuration and showing up in Home Assistant.

1. Setting up your device

Identify the ESP32-C6 board

The ESP32-C6 is the main board in your kit. It is the small module with the USB-C port on one edge and a row of pin headers along the side. Every project you build with the kit starts here.

Plug a module into the C6

For your first project, snap a module off the panel and plug it into the matching pin headers on the ESP32-C6 board.

Connect the C6 to your computer

Plug the ESP32-C6 into your computer using a USB-C cable.

First-time flashing

The very first time you flash an ESP32-C6, you may need to put it into bootloader mode manually:

  1. Hold down the BOOT button on the C6.
  2. While still holding BOOT, press and release the RESET button.
  3. Release the BOOT button.

The board will now stay in bootloader mode until you flash it. After the first flash you usually won't need to do this again.

Use a quality USB-C cable and power source

ESP32 boards are sensitive to power. If your device keeps restarting, won't be detected, or won't broadcast its hotspot, try a different USB-C cable or a different USB port. A 5V 1A supply is plenty.

2. Setting up ESPHome Device Builder

ESPHome Device Builder is a Home Assistant add-on that gives you a web UI for writing, compiling, and flashing ESPHome configurations. You'll use it to build the firmware for your kit.

Install the add-on

  1. In Home Assistant, open Settings → Add-ons → Add-on Store.
  2. Search for ESPHome Device Builder and install it.
  3. Once installed, click Start, then Open Web UI.

If you don't have Home Assistant set up yet, follow the official Home Assistant installation guide first, then come back here.

Fill in your Wi-Fi secrets

ESPHome keeps your Wi-Fi credentials in a separate secrets.yaml file so they aren't pasted into every device config.

  1. In the ESPHome Device Builder dashboard, click Secrets in the top right.
  2. Add your Wi-Fi name and password:
# Replace the values inside the quotes with your own Wi-Fi name and password.
wifi_ssid: "your-wifi-ssid-here"
wifi_password: "your-wifi-password-here"
  1. Click Save.

Add a new device

  1. Click + New Device in the bottom right of the ESPHome Device Builder dashboard.
  2. Give your device a name (for example apollo-esk-1).
  3. When asked for the device type, choose ESP32-C6.
  4. ESPHome Device Builder will scaffold a starter YAML for you. Don't flash it yet, you're going to replace it in the next section.

3. Writing your first ESPHome configuration

ESPHome configs are YAML files. Each top-level block configures a different part of the device. Here's a complete starting config for the kit, broken down section by section. Paste each block into your device's YAML in ESPHome Device Builder as you go, or jump to the complete config at the bottom and paste the whole thing at once.

YAML basics

YAML uses indentation (spaces, not tabs) to define structure. Two spaces per level is the convention used throughout these examples.

Substitutions

Substitutions are reusable variables. Define them once at the top of the file and reference them anywhere with ${name}.

substitutions:
  name: apollo-esk-1
  version: "25.5.5.1"
  device_description: ${name} made by Apollo Automation - version ${version}.
Variable Purpose
name Device identifier used in ESPHome and Home Assistant.
version Track your firmware version. The convention used here is Year.Month.Day.Build.
device_description Human-readable description. Notice it references other substitutions with ${}.

Core ESPHome configuration

This block tells ESPHome how the device should appear in the dashboard and in Home Assistant.

esphome:
  name: "${name}"
  friendly_name: Apollo ESPHome Starter Kit
  comment: ${device_description}
  name_add_mac_suffix: true
  platformio_options:
    board_build.flash_mode: dio
  project:
    name: "ApolloAutomation.ESK-1"
    version: "${version}"
  min_version: 2024.6.0
Option Description
name Internal device name, pulled from substitutions.
friendly_name The name shown in Home Assistant's UI.
name_add_mac_suffix Appends part of the MAC address to the name, useful when you flash more than one device.
platformio_options Low-level build settings. dio flash mode is what the ESP32-C6 expects.
project Identifies this as an Apollo Automation project.
min_version Refuses to compile on ESPHome versions older than this.

ESP32 board

Tell ESPHome which chip you're targeting.

esp32:
  board: esp32-c6-devkitm-1
  variant: esp32c6
  flash_size: 8MB
  framework:
    type: esp-idf

ESP32-C6 needs the ESP-IDF framework

The older Arduino framework does not fully support the C6. Stick with esp-idf here.

Home Assistant API

One line enables the native Home Assistant API connection. ESPHome handles the encryption and discovery for you.

api:

Wi-Fi

This block uses the secrets you saved earlier and sets up a fallback hotspot in case the device can't reach your Wi-Fi.

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  ap:
    ssid: "Apollo ESK-1 Hotspot"

If the device can't connect to your Wi-Fi at boot, it will broadcast its own network called Apollo ESK-1 Hotspot. You can join that network from your phone or laptop to fix the credentials.

Captive portal

Pairs with the fallback hotspot to give you a web page for entering Wi-Fi details when you connect to the hotspot.

captive_portal:

Logger

Enables ESPHome's logging output. You'll see these logs in the ESPHome Device Builder dashboard when viewing the device, and they're invaluable for debugging.

logger:

Binary sensors

Binary sensors report on/off state. The first one tracks whether the device is connected to Home Assistant. The second exposes a GPIO pin so you can wire up the button module or any other digital input.

binary_sensor:
  - platform: status
    name: Online
    id: ha_connected

  - platform: gpio
    pin:
      number: GPIO9
      inverted: true
      mode:
        input: true
        pullup: true
    id: my_button
    name: "Button"
Option Description
platform: status Reports the HA connection state. Useful for automations that check device availability.
platform: gpio A simple digital input.
number: GPIO9 The physical pin you've wired the input to.
inverted: true The pin reads LOW when the button is pressed (active-low).
pullup: true Enables the C6's internal pull-up resistor so the pin doesn't float.

Complete configuration

substitutions:
  name: apollo-esk-1
  version: "25.5.5.1"
  device_description: ${name} made by Apollo Automation - version ${version}.

esphome:
  name: "${name}"
  friendly_name: Apollo ESPHome Starter Kit
  comment: ${device_description}
  name_add_mac_suffix: true
  platformio_options:
    board_build.flash_mode: dio
  project:
    name: "ApolloAutomation.ESK-1"
    version: "${version}"
  min_version: 2024.6.0

esp32:
  board: esp32-c6-devkitm-1
  variant: esp32c6
  flash_size: 8MB
  framework:
    type: esp-idf

api:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "Apollo ESK-1 Hotspot"

captive_portal:

logger:

binary_sensor:
  - platform: status
    name: Online
    id: ha_connected

  - platform: gpio
    pin:
      number: GPIO9
      inverted: true
      mode:
        input: true
        pullup: true
    id: my_button
    name: "Button"

4. Flash and add to Home Assistant

  1. In ESPHome Device Builder, click Install on your device.
  2. Choose Plug into the computer running ESPHome Dashboard (or Wirelessly if you're updating an already-flashed device).
  3. Wait for the compile and flash to finish. The first compile can take several minutes.
  4. Once it's done, the device will reboot and connect to your Wi-Fi.
  5. In Home Assistant, go to Settings → Devices & Services. Your new device should appear under Discovered. Click Add, pick an area, and finish.

You did it!

Your ESP32-C6 is now running ESPHome and showing up in Home Assistant. You've written your first ESPHome configuration from scratch.

Next steps