This is a companion article for the YouTube video, ESPHome Starter Kit: Build Your First Smart Device. It is recommended that you watch the video, then use this article to review some of the specifics, like wiring diagrams and sample code.
ESPHome is a Home Assistant add-on or a standalone app that creates and installs custom local firmware onto a microcontroller. No coding experience is needed and you just provide ESPHome with a simple configuration file that includes information like your WiFi credentials along with information about the types of devices connected to your controller. The end result is a smart device that is completely local... no Internet required... and is also completely under your control!
Parts List
The follow are the parts used or shown in this article and/or in the related YouTube video. Note that ESPHome supports many different types of components and the ones I'm including here are simply examples of how you add and define components in ESPHome.
|
Item |
Notes |
|
Standard MCU, other
types supported |
|
|
|
|
|
Avoid DHTx sensors |
|
|
|
|
|
|
|
|
|
|
|
Check docs. Not every
type of LED supported. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Some of these links may be Amazon affiliate links. Use of these links will not affect your pricing, but as an affiliate this channel may earn a small commission if you make a purchase.
Why Use ESPHome?
There are so many different types of retail smart home devices on the market today, why would you want to consider using ESPHome to build your own device?
Well to start, most retail devices are going to follow a model similar to this one:
The device then uses your Internet connection to connect to their own servers or "cloud". At this point, you are the mercy of the manufacturer. They could collect data from your device or even force unwanted updates. Of course you can pour over their privacy policy, but there's no way to be 100% sure of what data is being collected... or what they are doing with that data. And of course if the Internet or their cloud servers go down (or are intentionally shut down), your device no longer works. In addition, more than one manufacturer has pulled a "bait-and-switch" where the cloud services are initially free, but then they start charging a subscription for continued use... or increase the subscription rate if you were already paying one. Refuse to pay... and your device quits working!
Finally, there is no guarantee your device will integrate into Home Assistant. Even if does, and if that integration relies on the vendor's "cloud", the same issues could occur if there is an outage... or the vendor changes their API. There have been more than one instance where a manufacturer has intentionally changed their API to block Home Assistant users from integrating their device.
*Note: Some manufacturer's recognize the 'local only' desire of some of us and provide ways, such as MQTT, that allow direct local integration into Home Assistant. But currently, these are the exception and not the rule. In addition, devices that use certain protocols, like Zigbee, Z-Wave or Matter can be integrated directly into Home Assistant without the cloud if your local infrastructure supports it.
The device is completely local and under your control. It is not susceptible to external outages. And with its tight automatic integration with Home Assistant, your device will seamlessly appear for integration. There will never be a subscription fee (unless you decide to start charging yourself!) and you can often save additional money by building your own device over purchasing a retail version. Finally, you can build the device to your exact needs so you aren't wasting money on features or other bells and whistles you don't need.
Now obviously, it is called ESPHome and was originally designed for the ESP8266 and ESP32, so you will have the best compatibility and feature-set when using one of these microcontrollers. I'll be using a standard ESP32 NodeMCU-style board. See the ESPHome documentation (links at the end of this article) for details on using other board types.
While you certainly can connect directly to your Home Assistant server, it may be located in an inconvenient location, may not have a keyboard and monitor attached (which will be needed to create the configuration and perform the upload) or, if like me, you are running Home Assistant in a virtual machine, you have to deal with USB passthrough for your your VM.
This file contains a list of key:value pairs. If you define 'wifi_ssid' and 'wifi_passord' and include your credentials, ESPHome will automatically substitute the actual values with the secrets key:
I'm using a ProtoBoard so I have ample room to add multiple peripherals for testing. A 5V DC power supply is used to create a 5V power rail. The ESP32 is powered via this 5V rail by connecting the VIN and GND pins. On the opposite side, the 3V3 pin and GND are used to create a 3.3V power rail. These power rails can be used to power additional peripherals.
As long as your device is online, you can use the LOGS button for your node in the ESPHome dashboard to launch and view the logs.
The logs will show any input/output from your sensor(s) or other connected peripherals. We will make substantial use of the ESPHome log as we begin to add components.
The motion sensor is a simply binary sensor... it's either 'on' or 'off'... and that signal is via a single GPIO pin. You should update the GPIO pin to match your wiring and of course you can change the name if desired.
I've connected the ADDR pin on my BH1750 to GND, so the I2C address will be 0x23. I could have connected it to the 3.3V line and the address would be 0x5C. But both addresses are different from the AHT20 (0x38), so we can connect the BH1750 to the same GPIO pins (GPIO21 and GPIO22) as the AHT20.
If using the default ESP-IDF framework, you'd just select one of the other platforms based on your type of LEDs and use the example provided there. But since I am using the arduino platform, this platform works for my project.
What about the LEDs? Well, the LEDs are an output device so we must send some sort of command. To do this, I'm going to introduce the concept of ESPHome automations.
I could have adopted this in Home Assistant right from the start, but there would not have been any entities since I hadn't added any components yet. Personally, I like t to wait until I at least have all my components defined and working in ESPHome before I adopt it in Home Assistant. That way if I make any name changes or alter the type of components, I don't have to worry about updating any pre-existing entity names in Home Assistant.
The device is added to Home Assistant without any YAML or configuration on the Home Assistant side. And as you can see, I have all six of my defined sensors. Since the light is an 'output' device, I have a control added where I can toggle the state of the light. I can also click on the entity to change things like brightness, color and effect (if any are defined).
This will compile your current configuration into a .bin file and then prompt you to download and save it.
This will download a plain-text .yaml file of your configuration. I recommend you at least backup the YAML before deleting any node, but it isn't required.
But if at anytime you integrated the device into Home Assistant there are extra steps that should be completed before removing the node from ESPHome.
Click the top half of the integration where the chevron appears. This will provide a list of all devices integrated via ESPHome.
Locate the device you wish to remove and click the three dot overflow menu on the top half of the device listing. Don't click the bottom three dots as you won't see a delete option. But from the upper overflow menu, choose 'Delete' to remove the device and all its entities.
But it serves an example of how you can mix and match various components to build a custom, local smart device that provides exactly the features you need. You never have to worry about whether the device will work with Home Assistant or if your device will suddenly stop working based on some remote cloud service.
However, when you create a device using ESPHome:
The device is completely local and under your control. It is not susceptible to external outages. And with its tight automatic integration with Home Assistant, your device will seamlessly appear for integration. There will never be a subscription fee (unless you decide to start charging yourself!) and you can often save additional money by building your own device over purchasing a retail version. Finally, you can build the device to your exact needs so you aren't wasting money on features or other bells and whistles you don't need.
Controller Support
ESPHome supports a variety of different microcontrollers:
Now obviously, it is called ESPHome and was originally designed for the ESP8266 and ESP32, so you will have the best compatibility and feature-set when using one of these microcontrollers. I'll be using a standard ESP32 NodeMCU-style board. See the ESPHome documentation (links at the end of this article) for details on using other board types.
For my examples, I will be connecting various components to different GPIO pins on the ESP32. But I won't be covering why I might have selected certain pins or why I wired things in a particular manner. If you haven't used an ESP microcontroller before, I'd recommend the following video and blog article, which covers the use of ESP microcontrollers, including topics such as GPIO pin selection, the proper way to power your projects and more:
YouTube Video: How to Use the ESP8266 or ESP32 Microcontroller
Companion Blog Article: ESP Microcontrollers: An Introduction
Installing the ESPHome Add-on in Home Assistant
You need an installed version of ESPHome to create your own devices. If you are a Home Assistant user, there is an ESPHome add-on (or app as they are soon to be called) that just requires a couple of mouse-clicks to install and activate. The video provides the step-by-step process of installing the add-on in Home Assistant, so I'm not going to repeat that here in the blog article.
But do note that even if you are not a Home Assistant user, ESPHome can be installed as a standalone app for creating your own devices. See the links at the end of this article for more information on installing a free standing version of ESPHome.
Preparing the ESP32
ESPHome works by taking a simple configuration file that you provide with information like your WIFI credentials, the type of microcontroller you are using along with details on any connected peripherals. This is done via a simple YAML file... but don't worry if you've never used YAML. In most cases, you can simply copy and paste from the documentation and just make a few minor tweaks, like changing an entity's name.
ESPHome will take this simple configuration file and use it to generate specific custom firmware designed specifically for your device. No Arduino, C++, Python or other coding needed!
But the very first time you upload (or flash.. I'll use these terms interchangeably) ESPHome firmware to your device, it must be done via a computer and USB cable. This initial flash will contain your WiFi information so after the very first flash, you can disconnect from the computer and perform any additional updates wirelessly, over-the-air (OTA). However, whether due to legacy reasons or unclear documentation, many newcomers are led to believe that they must connect the ESP microcontroller to the actual Home Assistant server for the initial flash. This is absolutely NOT true!
While you certainly can connect directly to your Home Assistant server, it may be located in an inconvenient location, may not have a keyboard and monitor attached (which will be needed to create the configuration and perform the upload) or, if like me, you are running Home Assistant in a virtual machine, you have to deal with USB passthrough for your your VM.
Instead, you can use any computer that can connect to Home Assistant. There may be one small additional step when using this method, but for me that extra step of downloading a copy of the firmware before uploading, allows me to retain a copy of the firmware should I need it again.
The YouTube video does a much better job of showing and explaining the different initial flashing options that I could cover here in writing, so I'll direct you there for the initial flash. But regardless of the method used to create the initial configuration, the end result is the same... a starting configuration with all the basics. All you need to do is add your specific peripheral information.
Sample Starting Configuration:
esphome:
name: youtube-demo
friendly_name: YouTube Demo
esp32:
board: esp32dev
framework:
type: arduino
# Enable logging
logger:
# Enable Home Assistant API
api:
encryption:
key: "your-auto-generated-random-key-here"
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
# Enable fallback hotspot (captive portal) in case wifi fails
ap:
ssid: "Youtube-Demo Fallback Hotspot"
password: !secret ap_password
captive_portal:
This starting template contains all the information needed to complete the initial flash, join your device to your WiFi and to integrate it into Home Assistant. This means that after flashing the firmware create from just this simple auto-generated configuration file will allow your device to be disconnected from the computer and then accessed wirelessly for additional updates.
Note: The framework I'm using in my example is the "arduino" framework. Beginning with release 2026.1 of ESPHome, the default framework will switch to "esp-idf". In most cases if you aren't doing advanced things like adding your own lambda code blocks, you won't notice the difference. However, there are some sensors where a different configuration is needed depending upon the framework. This is noted in the documentation and I'll note any differences impacting my examples below.
Note the use of !secret in my example. ESPHome supports a special secrets.yaml file. If it doesn't exist, you can create it in the /homeassistant/esphome folder on your Home Assistant server.
This file contains a list of key:value pairs. If you define 'wifi_ssid' and 'wifi_passord' and include your credentials, ESPHome will automatically substitute the actual values with the secrets key:
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
But you can add your own key:value pairs and make substitutions in your configuration file. This is most important if you share your ESPHome configuration file online or elsewhere (so you don't reveal private info), but it's good practice in general. You can see where I've done that for the AP and OTA passwords:
ota:
- platform: esphome
password: !secret ota_password
ap:
ssid: "Youtube-Demo Fallback Hotspot"
password: !secret ap_password
(api_password is a legacy setting and no longer used for new ESPHome devices).
This file, once it exists, can also be accessed/edited from the ESPHome Dashboard:
Of course this configuration file doesn't yet contain any sensors, switches or other peripherals that might be part of your device. So, using this starting framework, we just need to add the specific components that are part of our device.
Testing Platform
I will be using the following setup for all adding components and testing the ESPHome configuration:
![]() |
| Click to enlarge |
I'm using a ProtoBoard so I have ample room to add multiple peripherals for testing. A 5V DC power supply is used to create a 5V power rail. The ESP32 is powered via this 5V rail by connecting the VIN and GND pins. On the opposite side, the 3V3 pin and GND are used to create a 3.3V power rail. These power rails can be used to power additional peripherals.
This setup works fine for a handful of low power (e.g. low current) devices. If you are going to start using devices that could draw more than about 1A, then you should consider powering those devices in parallel.. provide power directly from the power supply in parallel to the ESP32/breadboard. This is required for things like relays, motors or LED strips (with more than a handful of pixels). Of course your power supply must also be rated for the expected current draw.
You can use a standard breadboard but note that some Node-MCU style ESP32 boards are just slightly too wide to fit on a standard breadboard while leaving a row of contact points on each side. You can either order 'narrow' ESP32's that are breadboard friendly (but note these have unusual GPIO pin locations) or place your ESP32 on pin headers which would allow connections to the contact points underneath the board.
Adding Components
To add a component, such as a sensor or control, to your configuration, you just need to wire it properly and then define it in your ESPHome configuration. This generally involves specifying things like a specific model or version and connection information, like the GPIO pin(s) used.
You can add as many components as desired... one at a time or all at once. If you are a beginner and plan on adding multiple components, I recommend that you add and test them one at a time. If an error occurs, it will be easier to resolve. The ESPHome error messages can be somewhat cryptic, especially if you are a beginner. If you add one component at a time, flash and test, then if you get an error, you pretty much know which component (and section of the YAML configuration) is at fault. But if you add five new components at the same time and then get an error, it can be more difficult to locate the component/YAML that is causing the error. I'll take the approach of one component at a time, similar to how I did in the video.
Using the ESPHome Logs
While you may eventually be planning on integrating your ESPHome device into Home Assistant, I recommend that you add and test all your components and finalize your device before you integrate the device. This is because if you make additions/deletions/changes to your configuration after integration, you may need to manually update entity names on the Home Assistant side.
But how can you test your components to assure they are working if you can't see the entities in Home Assistant yet? You can use the ESPHome logs!
As long as your device is online, you can use the LOGS button for your node in the ESPHome dashboard to launch and view the logs.
![]() |
| Example log output |
The logs will show any input/output from your sensor(s) or other connected peripherals. We will make substantial use of the ESPHome log as we begin to add components.
For the following examples, the configuration was generally copied right from the ESPHome documentation. I then modified the configuration (modified values shown in blue) to match my project.
AM312 PIR Motion Sensor
The first component I am going to add is a simple PIR motion detector.
The data pin of the AM312 is connected to GPIO13. This is the configuration that is added to the ESPHome configuration:
binary_sensor:
- platform: gpio
pin: GPIO13
name: "Demo Motion"
device_class: motion
The motion sensor is a simply binary sensor... it's either 'on' or 'off'... and that signal is via a single GPIO pin. You should update the GPIO pin to match your wiring and of course you can change the name if desired.
After saving and updating your configuration, you can open the ESPHome log for your node and you should see the output from the motion detector change as you move in and out of its detection path.
You can also manage how long motion must exist and how long it must be cleared before ESPHome reports the state change. To do this, you can apply "filters" to the sensor.
binary_sensor:
- platform: gpio
pin: GPIO13
name: "Demo Motion"
device_class: motion
filters:
- delayed_on: 500ms
- delayed_off: 10s
In this example, motion must exist for at least 0.5s before the state will show "ON". This might be used to 'debounce' the sensor or eliminate false triggers. On the other end, motion must be cleared for at least 10 seconds before ESPHome will report "OFF". This might be used to keep a light on for at least 10 seconds after motion stops.
There are many, many different types of filters that can be applied, including math operations where you can convert units... such as converting °C to °F. I'm not going to cover all the available filter options, but you can find them (along with examples) in the ESPHome documentation.
AHT20 Temperature and Humidity Sensor
Now I'll add a second sensor that actually returns two different values: temperature and humidity (and therefore acts as two 'sensors').
![]() |
| Click to enlarge |
This particular sensor is an I2C device. This means that it uses the Inter-Integrated Circuit (I2C) Protocol to communicate. Two GPIO pins are needed... one for the "clock" (SCK or SCL) signal and one for the "data" (SDA) signal. On the ESP32, the default pins are GPIO22 and GPIO21 respectively. Of course you can use different pins but you'll need to explicitly specify the pins in the configuration. And we'll need to tell ESPHome that we want to enable I2C communications. In addition, multiple I2C devices can actually share the same GPIO pins as long as each I2C device has a different address. The address can be found in the peripheral's documentation, but it will be needed for the configuration file. For this AHT20, the I2C address is 0x38.
#define the I2C bus
i2c:
sda: GPIO21 #<== These can be omitted if using the defaults
scl: GPIO22 # but are required if using different pins
sensor:
- platform: aht10
variant: AHT20
temperature:
name: "Demo Temperature"
humidity:
name: "Demo Humidity"
update_interval: 180s
Once again, the configuration is added to the existing ESPHome configuration file.
The first part of this configuration defines the I2C bus and tells ESPHome to include the necessary libraries to support I2C. Unless we define a second I2C bus, we only need to add this section once for all I2C components added.
The second part is the actual AHT20 configuration. The platform is actually aht10 but it supports AHT10, AHT20 and AHT30 (listed in documentation), so a variant key is included specifying the exact model.
This component returns two values so you must define both temperature and humidity in the configuration and provide a meaningful name for each. The update interval is important here as it tells ESPHome how often to pull a reading from the sensor. If omitted, the update interval defaults to 60 seconds. Since temperature and humidity likely won't change that quickly, I've set an update interval of 3 minutes. This means a new reading will occur once every three minutes. Change this to meet your needs. You might start with a shorter interval for testing, but then increase it once you are satisfied with the results.
After saving and flashing the updated configuration file, you should see temperature and humidity readings in the logs, updated once for every update_interval specified.
HC-SR04 Distance Sensor
Now I'll add a sensor to measure distance.
The HC-SR04 ultrasonic distance sensor requires two GPIO pins, one for the trigger and one for the echo. I'm using GPIO26 for the trigger and GPIO25 for the echo.
sensor:
- platform: aht10
...
- platform: ultrasonic
trigger_pin: GPIO26
echo_pin: GPIO27
name: "Demo Distance"
update_inteval: 1s
Since we already have a 'sensor' section, which was added for the AHT20, we add the configuration for the HC-SR04 under this same sensor section. For testing, I've set the update interval to 1 second.
Again, once saved and flashed to the ESP32, the ESPHome logs should show reported distance when an object is detected within the range of the HC-SR04 (note that the valid range is approximately 2 - 200 cm).
Use filters if you wish the distance to be in units other than meters.
BH1750 Light Level Sensor
Next, we'll add a sensor to detect ambient room light level.
Like the AHT20, the BH1750 is an I2C device. And this shows the unique nature of these types of components. As long as each device has a unique address, they can share the same GPIO pins on the ESP32! And in some cases, like with the BH1750, you can change or select a different address.
I've connected the ADDR pin on my BH1750 to GND, so the I2C address will be 0x23. I could have connected it to the 3.3V line and the address would be 0x5C. But both addresses are different from the AHT20 (0x38), so we can connect the BH1750 to the same GPIO pins (GPIO21 and GPIO22) as the AHT20.
#define the I2C bus
i2c:
sda: GPIO21 #<== These can be omitted if using the defaults
scl: GPIO22 # but are required if using different pins
sensor:
- platform: aht10
...
- platform: ultrasonic
...
- platform: bh1750
name: "BH1750 Illuminance"
address: 0x23
update_interval: 5s
The I2C bus was defined when we added the AHT20, and since we are using the same bus/GPIO pins, we don't need to define it again. And since the BH1750 is a 'sensor' we add the configuration under the pre-existing 'sensor:' section.
For the BH1750 configuration, note that the I2C address is normally required. And like the other sensors, you can specify how often you wish a reading to be taken from the sensor. You might start out with a shorter value for testing and then increase it to the final desired interval when ready to deploy.
TTP223 Touch Sensor and WS2812b LED strip
Next, I'm going to add a capacitive touch sensor. To test this sensor and to also introduce an output component, along with the concept of internal ESPHome automations, we'll also add a short strip of WS2812 addressable LEDs.
The TTP223 is a simply binary sensor with a single data pin, which I've connected to GPIO18. The LED strip is 5V WS2812b and it has 19 pixels (which is needed for the configuration).
Since the TTP223 is a binary sensor, the configuration is added under the existing binary_sensor: section.
binary_sensor:
- platform: gpio
#PIR Sensor
...
- platform: gpio
pin: GPIO18
name: "TTP223 Touch"
filters:
- delayed_on: 250ms
- delayed_on: 250ms
For the LED strip, it is considered a 'light' entity, so we'll add a new light section and provide the configuration under this section.
light:
- platform: neopixelbus #only for arduino framework
type: GRB
variant: wx2812x
pin: GPIO4
num_leds: 19
initial_state:
state: false
color_mode: rgb
brightness: 35%
red: 100%
blue: 100%
green: 0%
I'm using the neopixelbus library. But note that this is one of those few components that are impacted by the framework (ESP-IDF vs. Arduino) selected and that I covered back near the start of this article. But the documentation will let you know about the platform if it impacts a component configuration:
If using the default ESP-IDF framework, you'd just select one of the other platforms based on your type of LEDs and use the example provided there. But since I am using the arduino platform, this platform works for my project.
The initial_state section is optional, but it sets the initial state of the LED strip. In my case, I'm setting a color and brightness, but initially setting the state of the strip to false (or off).
After saving, validating and uploading, you can again check the logs and touch the TPP223 sensor to see the state change.
What about the LEDs? Well, the LEDs are an output device so we must send some sort of command. To do this, I'm going to introduce the concept of ESPHome automations.
ESPHome Automations
If you are planning on integrating your device into Home Assistant, all of your defined components will be created as entities. And of course you can use these entities to create automations (like toggling the LEDs when you tap the touch sensor). But you can also create automations locally within ESPHome! Why would you want to do this?
For one, any local automations will always be the fastest. Even with local Home Assistant, data still has to travel over your WiFi to the Home Assistant server (and vice versa). In most cases, this is normally only a few milliseconds, but if you have a project that requires precise timing, local ESPHome automations will always be faster than any other option.
Next, any automations defined in ESPHome run locally on the ESP32 (or whatever controller you are using). This means that Home Assistant could go down... or even your WiFi... and the automation(s) will still continue to operate since they are local to the ESP32.
ESPHome automations work in a similar manner to Home Assistant, with a trigger, optional conditions and an action. To see the available triggers for a given component type, see the documentation. In my case, I want to use the TTP223 touch sensor as the trigger. Looking at the documentation, a binary sensor has the following available triggers:
- on_press: An automation to perform when the button is pressed.
- on_release: An automation to perform when the button is released.
- on_state: An automation to perform when a state change is published.
- on_click: An automation to perform when the button is held down for a specified period of time.
- on_double_click: An automation to perform when the button is pressed twice for specified periods of time.
- on_multi_click: An automation to perform when the button is pressed in a specific sequence.
For my project, I'm going to use on_click because it allows me to specify a touch duration. This means I could also implement a long press or double-click as well.
The automation goes under the configuration for the component you want to use as the trigger. In my case, that's the TTP223 binary sensor:
binary_sensor:
...
- platform: gpio
name: "TTP223 Touch"
filters:
- delayed_on: 50ms
on_click:
min_length: 100ms
max_length: 1s
then:
light.toggle: led1
light:
- platform: neopixelbus
id: led1
...
Note the min and max lengths of the on_click automation. As described above, you could also have an automation for a long or double-click if the touch lasts longer than 1 second. Also note in the action, it is set to toggle a light and the ID is shown as led1. Where did this come from?
If you want to use a component in an automation or elsewhere in your configuration, you assign it an ID. For the light component, you can see where I added an ID of 'led1'. Think of IDs in ESPHome as similar to entity_ids in Home Assistant. Once I assign an ID, I can then use it in the action of the binary sensor.
As is, the LEDs will toggle on when the touch sensor is touched (for at least 100ms but no more than one second).
In addition, since my touch automation handles the timing, I really don't need the prior delayed_on and delayed_off parameters. I left the delayed_on, but with a very short time just to handle debouncing and ghost triggers. But the automation now handles the time of a touch that is to be considered a "click".
Of course you are much more likely to do your automations (especially ones that rely on other non-ESPHome entities) in Home Assistant. So now that the project is built, let's look at integrating it in Home Assistant.
Integration into Home Assistant
You may not have noticed it, but as soon as we flashed the starting firmware to the ESP32 and it joined WiFi (and before we started adding components), it was automatically discovered by Home Assistant.
![]() |
| Discovered Devices can be found under System -> Devices & Services |
I could have adopted this in Home Assistant right from the start, but there would not have been any entities since I hadn't added any components yet. Personally, I like t to wait until I at least have all my components defined and working in ESPHome before I adopt it in Home Assistant. That way if I make any name changes or alter the type of components, I don't have to worry about updating any pre-existing entity names in Home Assistant.
But once ready, you simply click 'Add', confirm that you truly do want to add the device to Home Assistant and optionally specify an area (or skip it). That's all there is to it!
The device is added to Home Assistant without any YAML or configuration on the Home Assistant side. And as you can see, I have all six of my defined sensors. Since the light is an 'output' device, I have a control added where I can toggle the state of the light. I can also click on the entity to change things like brightness, color and effect (if any are defined).
Removing an ESPHome Device (the right way!)
As you are first starting out with ESPHome, you may create a number of test nodes (nodes are the term for an individual ESPHome configuration file). Or as you gain experience and discover new devices, you might decide to create a new version of one of your old devices. In either case, you may wish to remove an existing ESPHome node. There are two different methods to remove a node depending on whether the device has been integrated into Home Assistant or not.
Making Backups
In the event that you may want to restore or recreate the node at a later time, you can create backups of both the compiled binary and the YAML configuration.
You likely created a local copy of the .bin file as part of the initial flashing process. But this .bin doesn't contain any changes or components added after the first flash. But you can snag a current copy of the .bin file at any time by simply selecting 'Manual' for the installation method.
This will compile your current configuration into a .bin file and then prompt you to download and save it.
For the YAML configuration, just click the three dot overflow menu for your node from the ESPHome dashboard.
This will download a plain-text .yaml file of your configuration. I recommend you at least backup the YAML before deleting any node, but it isn't required.
Non-Integrated Devices
If your ESPHome device has never been integrated into Home Assistant... e.g. you never completed any of the steps shown above for integrating your device into Home Assistant, nothing yet exists on that side, so you can simply delete the node via the three dot overflow menu.
But if at anytime you integrated the device into Home Assistant there are extra steps that should be completed before removing the node from ESPHome.
Home Assistant Integrated Devices
If at any point you integrated your ESPHome device into Home Assistant but then wish to remove it, you must follow these steps carefully. If you fail to do this, and later attempt to reuse the ESP32 for another ESPHome project, you will very likely end up with orphaned and cross-linked entities in Home Assistant... which can be a real pain to clean up. But you can avoid this by properly removing unwanted ESPHome devices. You must follow these steps in order:
1. Remove the device's integration from Home Assistant
First, within Home Assistant, go to System -> Devices -> Integrations. Locate the ESPHome integration.
Click the top half of the integration where the chevron appears. This will provide a list of all devices integrated via ESPHome.
Locate the device you wish to remove and click the three dot overflow menu on the top half of the device listing. Don't click the bottom three dots as you won't see a delete option. But from the upper overflow menu, choose 'Delete' to remove the device and all its entities.
2. Restart Home Assistant
This is important! To assure the internal database is updated and your device and its entities are completely removed from Home Assistant, you need to restart it. You can do this via the System menu or via the Developer tools. Once Home Assistant has restarted, you should no longer see any of the original entities listed.
3. Remove the ESPHome Node
Once you've completed the first two steps, you can now safely remove the ESPHome node by following the instructions for a non-integrated device above.
Safely removing a node in this manner assure that you can either recreate the node on a different ESP32 later or reuse the existing ESP32 for a different ESPHome node without causing issues on the Home Assistant side.
Final Thoughts
Odds are, you aren't going to create a device that looks like this:
But it serves an example of how you can mix and match various components to build a custom, local smart device that provides exactly the features you need. You never have to worry about whether the device will work with Home Assistant or if your device will suddenly stop working based on some remote cloud service.
Finally, you can often save significant money over a retail device by just building your own from low-cost components! Yes... the configuration requires YAML, but if you watch the video, you'll see how I built the entire configuration and all its components simply by copying and pasting the YAML from the documentation and didn't write any of it "by hand". I just made minor edits like the name or GPIO pins used.
As always, thanks for reading and let me know any thoughts down in the comments!
Links and Additional Information
Starter Kit: The Complete Beginner's Guide to ESPHome (YouTube video)
Supporting this blog and related YouTube channel
It takes significant time and effort (and often expense) to create these articles and videos. If you'd like to support future content on this blog and the related YouTube channel, or just say thanks for something that helped you out, you can consider buying me a one-off cup of coffee or two at:




























No comments:
Post a Comment
To help eliminate spam and to keep all conversations civil, submitted comments are moderated. Therefore your post may not show up immediately. Please be patient as most reviews are completed within a few hours.