ESPHome Usage Tutorial

This tutorial explains how to use ESPHome Device Builder to create an ESPHome configuration, compile the firmware, and flash it to a device.

1. Preparation

Set Up the Environment

1. Install and start Home Assistant by following the official Home Assistant documentation.
2. Install and start ESPHome Device Builder by following the official ESPHome documentation.

2. Compile and Flash the Firmware

Create a Device

1. Open ESPHome Builder from the Home Assistant sidebar.
2. Click + Create device in the lower-right corner. On the first run, you can also click Add new device on the page.

3. In the Create configuration window, select Create new project.

4. Search for and select the board actually used from the board list.

• If the exact model is listed, select it.
• If you are unsure which board to use, click Connect your board and let ESPHome try to identify it.
• Use a generic board such as Generic ESP32 Board only after confirming the chip model and required parameters.

5. Enter a device name, then click Finish setup.

Edit the Configuration

After the project is created, ESPHome generates a minimal configuration. Edit YAML in the editor on the right. Use Core configuration, Components, and Automations on the left to review or add configuration items.

The default configuration usually contains the following sections:

Using Unit TMOS PIR as an example, first import the ESPHome component repository:

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

Then use the component in the appropriate ESPHome platform configuration. Refer to the corresponding component page for the exact platform name, parameters, and entity configuration for each product.

When editing is complete, click Save in the lower-right corner. Correct any syntax or component errors reported by the editor before compiling.

Compile the Firmware

1. Click Install in the lower-right corner of the editor.

Use the following table when choosing an installation method:

Flash the Firmware

Plug into this computer

This method is recommended for the first flash.

1. Connect the device to the current computer with a USB data cable. Some devices must first enter download mode; see the product-specific instructions.
2. Select Plug into this computer in the installation method dialog.
3. Wait for compilation to finish. When the log shows Successfully compiled program, click Open USB flasher.

4. ESPHome Web opens in a new browser tab. Confirm that it has received firmware.factory.bin, then click Connect & install.

5. Select the target device from the serial-port list and click Connect.

Common serial-port names include:

• macOS: cu.usbmodem... or cu.usbserial...
• Linux: /dev/ttyUSB... or /dev/ttyACM...
• Windows: COM...

6. Confirm the installation as prompted and wait for erasing, writing, and verification to complete. Keep the page visible and do not disconnect the USB cable during flashing.
7. Restart the device after flashing. It uses the Wi-Fi settings in the YAML to connect. If the connection fails, it starts a fallback access point.

Plug into your Home Assistant server

Use this method when the device is connected directly to the Home Assistant host rather than to the computer running the browser.

1. Connect the device to a USB port on the Home Assistant host.
2. Select Plug into your Home Assistant server.
3. Select the target device from the serial-port list, such as /dev/ttyUSB0 or /dev/ttyACM0.
4. Wait for compilation and flashing to finish, then restart the device.

If the target port is not listed, check that:

• The USB cable supports data transfer and the device is powered correctly.
• The Home Assistant host has detected the USB device.
• A virtual machine, Docker, or NAS environment has passed the USB device through to Home Assistant/ESPHome.
• The serial port is not in use by another add-on or program.

On the network (OTA)

Use this method only for devices that are already running ESPHome firmware and are currently online.

1. Confirm that the device and Home Assistant can communicate over the network.
2. Select On the network.
3. Select the target device and wait for compilation, upload, and restart to finish.
4. Check the logs to confirm that the device is back online without startup errors.

For a first flash, an offline device, a device that cannot reconnect after network changes, or a device with OTA removed, recover it over USB instead.

Flash Manually after Downloading the Firmware

Click Download on the compilation results page to save the firmware. A first full flash normally uses firmware.factory.bin; firmware.ota.bin is for OTA updates and must not replace the first full-flash image.

Before flashing manually, verify the file type, chip model, Flash settings, and write address. If no product-specific instructions are available, use the ESPHome USB flasher where possible.

After flashing, ESPHome Web displays the installation progress and restart status.

3. Get Started

Add to Home Assistant

After the firmware starts and connects to the network, Home Assistant normally discovers the ESPHome device automatically.

1. Open Settings -> Devices & services.

2. Find the ESPHome device under Discovered and click Add.

3. Check the device information in the confirmation dialog, then click Submit.

4. Enter a device name, select the appropriate Area, and click Finish.

5. Open the device details page and confirm that entity states and sensor data update normally.

If Home Assistant does not discover the device automatically:

1. Click Add integration and search for ESPHome.
2. Enter the device hostname, such as living-room-sensor.local, or its IP address.
3. If prompted, enter the key corresponding to api.encryption.key in the YAML.