ESPHome Restart Button: Safe Use in Home Assistant

Albert BarnosellEditor and publisher of Tecnoyfoto

Updated on September 1, 2026

In the world of IoT, rock-solid stability is the name of the game. But let’s be real—even the most dependable device can freeze up and need a good old-fashioned reboot. If you have an ESPHome board installed in a hard-to-reach place—like inside a drop ceiling, an electrical panel, or behind a heavy piece of furniture—a simple device hang-up can become a massive headache. Fortunately, in 2026, we have a simple and elegant solution: creating a virtual ESPHome restart button directly in our Home Assistant interface.

This definitive guide will show you how to configure a restart button in Home Assistant for any board, from the classic ESP8266 and ESP32 to the latest models. I’ve personally tested this method on dozens of my own devices, and its reliability is rock-solid.

Option 1: Create a Restart Button (Recommended Method)

The cleanest and most modern way to implement this feature is through ESPHome’s native button platform. This will create a button entity in Home Assistant that, when pressed, executes the restart action on the microcontroller.

To get started, simply add the following code to your device’s ESPHome YAML file:

# Example configuration for a restart button
button:
  - platform: restart
    name: "Garage Sensor Reboot"
    id: garage_reboot

Once you save, compile, and upload this code to your board, a new entity called button.garage_sensor_reboot will appear in Home Assistant, ready to use.

Configuration Parameters

While the basic setup is minimal, it’s helpful to know what each parameter does:

Parameter	Description
`name` (Required)	The friendly name for the button entity in Home Assistant. Make it descriptive so you know exactly what you’re rebooting.
`id` (Optional)	A unique identifier for using this button elsewhere in your ESPHome code, such as in scripts or lambdas.
`icon` (Optional)	Lets you define a custom icon from the Material Design Icons catalog (e.g., `icon: "mdi:restart-alert"`).

Option 2: Use a Restart Switch (Legacy Method)

An alternative, more old-school but still perfectly functional method is to use a switch. The restart platform is also available for switches. When you toggle it on, the device reboots immediately. The key difference is that a switch is a stateful entity (on/off). In this case, even though you toggle it ‘on’ to restart the device, it will always report back as ‘off’ after the reboot is complete.

The configuration for an ESPHome restart switch is very similar:

# Example configuration for a restart switch
switch:
  - platform: restart
    name: "Kitchen Lights Controller Reboot"

This will create a switch.kitchen_lights_controller_reboot entity in Home Assistant. It’s a valid option if your existing automations or scripts are already designed to work with switches instead of buttons.

Common Troubleshooting Steps

Although setting this up is straightforward, you can occasionally hit a snag. Here are the fixes for the most common problems:

The button isn’t showing up in Home Assistant: After adding the code and flashing the device, if the new entity is missing, check the ESPHome logs. Ensure the board is properly connected to your WiFi network. Sometimes, a full power cycle (unplugging it and plugging it back in) will force the sync. Also, verify that your OTA updates completed without errors.
YAML validation error: 99% of the time, this is an indentation issue. YAML is notoriously strict about spaces. If you need a refresher on how to keep your code clean and reusable, check out our ultimate guide to YAML Anchors & Aliases.
Device reboots but won’t reconnect: This issue usually isn’t with the restart button itself, but with the device’s core network configuration. Double-check the wifi: section in your code to ensure the credentials are correct and that the device has a strong enough signal.

Automatic recovery after a lost connection

A Home Assistant button works only while the ESPHome node remains reachable. If the device is already offline, Home Assistant cannot send a restart command. Do not build an automation that presses the button after the node has disconnected.

ESPHome provides local watchdog behavior in both the api and wifi components. Their default reboot_timeout is 15 minutes: if no connection is established for that period, the node restarts itself without relying on Home Assistant.

api:
  encryption:
    key: !secret api_encryption_key
  reboot_timeout: 15min

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  reboot_timeout: 15min

You do not need to declare these values to keep the 15-minute defaults. Writing them explicitly documents the intended behavior. Do not set them to 0s unless another recovery method exists, because that disables this watchdog behavior.

The manual button is still useful when the node is online and you want to reboot after an integration change or during diagnosis. For physically inaccessible hardware, keep a way to cycle power and avoid automatic restarts on devices controlling critical functions.

Technical sources

Next related guide · 6 min read

HC-SR04 with ESP8266 and ESPHome: Safe Distance Guide

Updated August 1, 2026. The HC-SR04 ultrasonic sensor measures distance without touching the target. Pair it with an ESP8266 running ESPHome and every reading…

Continue with this article