ESPHome builds firmware from a YAML configuration and is particularly useful for sensors and devices in Home Assistant. YAML describes the configuration; it is not the transport protocol between the device and Home Assistant.
Choose the right starting point
If you use Home Assistant OS, you can install ESPHome Device Builder through Home Assistant’s supported app/add-on catalogue. Alternatively, use ESPHome’s documented container or command-line setup. Follow the official installation guide; menu names and screenshots change over time.
Connect the board with a USB data cable. Browser-based installation requires a supported browser and access to the correct serial port. Install only a USB driver matching the board’s actual USB interface; CP210x, CH34x and native USB are not the same.
Board, framework and version
Select the exact ESP32 variant. ESP32, ESP32-S3, ESP32-C3 and ESP8266 cannot simply share board definitions, pin selections or Bluetooth features. See the ESP32 platform documentation. Let the current Device Builder generate the base configuration and save it with the version information.
API and wireless updates
Use API encryption for the Home Assistant connection. The old api.password setting was removed in ESPHome 2026.1. OTA configuration is also platform-based; do not blindly copy old examples containing only ota: and a password.
Follow the API documentation and the OTA documentation for your installed version. Keep Wi-Fi details and device keys in secrets.yaml, and never share that file in a public code repository.
Build the first measurement
- Start with one device and a simple sensor. Check the supply voltage, signal levels and pinout in the datasheet.
- Add the relevant ESPHome component. Check its exact model name and configuration fields.
- Validate the configuration, build the firmware and install it. YAML errors and electrical connection errors are solved in different places.
- Read the log and check that Home Assistant receives a stable measurement. Compare against a known reference.
- Back up the working setup before adding more features.
If it does not work
No serial port points first to the cable, USB interface or permissions. Repeated restarts may result from the wrong board configuration, code or an unstable supply. An incorrect sensor reading calls for checking wiring, address, units and calibration.
Software does not give an unprotected relay module safe electrical isolation. Begin with low-voltage USB or battery projects; mains work requires a suitable enclosed installation and relevant professional competence.
Find development boards and sensors in the store, and choose for the actual task rather than just the product family name.
