Skip to content

ESPHome Starter Kit - First Steps

This guide walks you through installing the ESPHome Device Builder app, and making your first ESPHome YAML configuration from scratch.

By the end you'll have your ESPHome Starter Kit flashed with a working configuration and showing up in Home Assistant and with a working web server accessible at its IP address or esphome-starter-kit.local in a browser.

ESPHome Device Builder

ESPHome Device Builder is the software that gives you a user interface for writing, compiling, and flashing ESPHome YAML configurations. You'll use it to build the firmware for your kit.

Think of it like telling the starter kit about what devices it has connected and how to use them!

Pick the platform you'll be running ESPHome Device Builder on:

  1. Download the ESPHome Device Builder for Windows.
  2. Open the installer and click Next then click Next again to start the installation process. Once it shows completed, click Next again then Finish to complete the installation.
  3. If Windows shows a blue Windows protected your PC warning, click More info → Run anyway to continue.

  1. Once installed, a web browser should launch and navigate to http://localhost:6052/. Once you see this page, your ESPHome Device Builder installation is complete.
  2. Use a Chromium-based browser such as Chrome or Edge. Firefox does not yet support WebSerial, which is required for the initial flashing of the device over USB. If Firefox is your default, copy the URL into Chrome or Edge instead.
  3. Navigate to the system tray (bottom right of your Windows taskbar). Hover over Backend and switch from Classic to the ESPHome Builder Beta with the new layout and features.

  1. Wait 30+ seconds, then refresh your browser (F5). You should now see the new ESPHome Device Builder Preview.

  1. Download the ESPHome Device Builder for Mac. Pick the build that matches your chip:

  2. Open the .dmg and drag ESPHome Builder into your Applications folder. Launch it from Applications or Spotlight.

    • On first launch, macOS may block the app with a Gatekeeper warning. If that happens, right-click the app in Applications and choose Open, then click Open in the confirmation dialog. After the first launch, double-click will work normally.

  1. Once installed, a web browser should launch and navigate to http://localhost:6052/. Once you see this page, your ESPHome Device Builder installation is complete.

    • Use a Chromium-based browser such as Chrome or Edge. Safari and Firefox do not currently support WebSerial, which is required for the initial USB flash.

  2. Find the ESPHome Builder icon in the menu bar (top right of your Mac's screen). Click it, hover over Backend, and switch from Classic to the ESPHome Builder Beta.

  1. Wait 30+ seconds, then refresh your browser. You should now see the new ESPHome Device Builder Preview.

The ESPHome Device Builder runs as a Home Assistant app served right inside your existing HA dashboard. This is the easiest option if you already run Home Assistant OS or a supervised install.

Method 1

To add the ESPHome Device Builder to your Home Assistant instance, use this My button:

Open your Home Assistant instance and start setting up a new integration.

Method 2

  1. In Home Assistant, open Settings → Apps → App Store.
  2. Search for ESPHome Device Builder and click Install.
  3. Once installed, click Start, then Open Web UI. The Device Builder will open inside your Home Assistant dashboard.

Already on the new layout

The HA app version of Device Builder is already the new beta backend, so you can skip the backend toggle and browser refresh shown in the desktop tabs.

  1. Download the ESPHome Device Builder for Linux. Pick the package that fits your distro:

  2. Install or run the file you downloaded:

    • AppImage: chmod +x ESPHome.Builder_0.7.0_amd64.AppImage then double-click the file, or run it from a terminal.
    • .deb: sudo apt install ./ESPHome.Builder_0.7.0_amd64.deb
    • .rpm: sudo dnf install ./ESPHome.Builder-0.7.0-1.x86_64.rpm

  1. Once installed, a web browser should launch and navigate to http://localhost:6052/. Once you see this page, your ESPHome Device Builder installation is complete.

    • Use a Chromium-based browser such as Chrome or Edge. Firefox does not currently support WebSerial, which is required for the initial USB flash.

  2. Look for the ESPHome Builder icon in your system tray or notification area. Its exact location depends on your desktop environment (top bar on GNOME, system tray on KDE, XFCE, or Cinnamon). Click it, hover over Backend, and switch from Classic to the ESPHome Builder Beta.

  1. Wait 30+ seconds, then refresh your browser. You should now see the new ESPHome Device Builder Preview.

Set up Wi-Fi Credentials

Fill in your Wi-Fi network name (SSID) and Wi-Fi password then click Save credentials. The password is case sensitive so be careful when entering your password.

Secrets Folder

One popular option is to store your encryption keys here. That way, you can share your full YAML with other users without needing to edit and hide your encryption key. See our using secrets wiki for step by step directions!

If you make a mistake or want to change this later, click the 3 dots menu in the top right then select Secrets. Click the Eye icon to unhide the Wi-Fi SSID and password and change them then click Save in the bottom right.

Get busy!

You are done with the install guide and can now use the kit!

Add a new device

1. Navigate back to the ESPHome Device Builder and click Add new device then click Create new project.

2. Select the Apollo ESPHome Starter Kit and give it a name such as esphome-starter-kit then click Finish Setup.

Configure Components

When you install ESPHome Device builder, you will see a list of components under Core Configuration. We will add three more components for our tutorial below.

Accessory Power Rail

The Accessory Power Rail is used behind the scenes to give power to your optional modules including the Onboard RGB LED.

  1. In the ESPHome Device Builder, navigate to the Components section.
  2. Click Add component.
  3. Scroll to Accessory Power Rail and click Add.
  4. Click Add once more to confirm.

Web Server Component

The Web Server is used to broadcast a local website using your device. This allows you to navigate to the IP address of your device or hostname such as esphome-starter-kit.local to easily control your new device!

  1. In the ESPHome Device Builder, navigate to the Core configuration section.
  2. Click Add component.
  3. Scroll to Web Server and click Add.
  4. Click Add once more to confirm.
  5. Toggle Show advanced settings.
  6. Scroll down to Version and select 3 from the dropdown.

Onboard RGB LED

The Onboard RGB LED is a small LED above the Reset button of your ESP32-C6 Module. Useful for testing automations and doubles as a status light.

  1. In the ESPHome Device Builder, navigate to the Components section.
  2. Click Add component.
  3. Scroll to Onboard RGB LED and click Add.
  4. Click Add once more to confirm.

Boot Mode

The device is required to be flashed via USB using the bootloader mode the very first time it is used. Once you flash it once, you do not have to do these steps 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.

1. Hold the sides of the ESP32-C6 and gently push the USB-C cable firmly into the USB-C port. Plug in the other side of the USB-C cable into your computer. Please be careful not to snap or damage the FPC ribbon cable connectors located on the sides of the device.

2. Hold down the boot button. While still holding the boot button, press and release the reset button, then release the boot button.

3. Your device is now in boot mode - The board will now stay in bootloader mode until you flash it.

Installing Firmware

Before we continue, confirm that you installed the ESPHome Device Builder, configured your components, and put your device in boot mode.

  1. Click Save in the bottom right which will then show an Install button.
  2. Click Install in the bottom right.
  3. Click Plug into this computer.
  4. Select the COM port, then click Connect to connect to the ESP32-C6 module.
  5. Wait for the firmware to compile and install. This usually takes two to five minutes.
  6. Once it completes, click Stop, then press the Reset button on your device. Your device will reboot and it's now ready to test out!

Click Show details during the install to watch the compile and flash process

It's a great way to see what's happening under the hood.

Test your LED

Above we installed the web_server component which allows us to navigate to the ip address of our device or the hostname.local such as esphome-starter-kit.local

It should load your new device and show you the Onboard RGB LED. We can click the toggle button to make sure the RGB LED turns on and off on our device!

Example of the light changing colors below!

Back - Start Here Next - Add Button Module