fshr

The musings of a grumpy hairless ape

ESPHome Presence Sensor - Part 2 - ESP32 Config

This guide is presented as-is with no guarantee or warranty as to it’s correctness, accuracy, or suitability for purpose. You use the information presented here at your own risk. Please see my general disclaimer for further details.

ESPHome Presence Sensor - Part 1 - Pre-Reqs
ESPHome Presence Sensor - Part 2 - ESP32 Config (You Are Here!)
ESPHome Presence Sensor - Part 3 - LD2420 Config

Introduction

This is the second part in my mini guide to setting up a basic presence sensor using ESPHome, Home Assistant, and some (cheap) off the shelf components. If you haven’t already looked at Part 1, go take a look now as it sets up some of the pre-reqs needed to do parts 2 & 3.

So in Part 1, we set out what we’re going to be making, and what we need to make it. If you’re planning on following along and making your own sensor, then I’ll assume now that you’ve got everything in place and you’re ready to go! If you’re just reading along for the fun of it, then that’s fine too and “Hi!”

Again I’m going to assume a basic level of technical ability for anyone following this, I’m not going to do detailed step-by-step of “click here”, type this, “click there”, etc

ESPHome Setup

Before we do anything else, there’s one thing we need to do. Open your browser and connect to your Home Assistant instance. In the left hand toolbar click the “ESPHome Device Compiler” icon to open the ESPHome UI:

In the UI, go to the “Secrets” configuration page via the link in the top right of the window:

Update the configuration in there with your WiFi SSID and Password, and click “Save” (again top right of the window):

# Your Wi-Fi SSID and password
wifi_ssid: "YourSSIDHere"
wifi_password: "YourPasswordHere"

These are the credentials that the ESPHome Device Compiler is going to use when building your firmware. We will reference these “secrets” from your configuration file, and it saves having your WiFI details stored separately in every file.

New Device

Once the above is done it’s time to start setting up our new device. In the main ESPHome UI click the “New Device” button in the bottom right corner:

You will likely get a dialog stating that you need to connect the device via USB, that you’re not connecting over HTTPS, and that you can use ESPHome Web. We already know about this from Part 1, so just click “Continue”.

You’ll then be prompted to create a new configuration:

Note: What you enter here is quite important as this is used to set the device name advertised over mDNS on your network, and is then used by ESPHome and Home Assistant to find your device for management. This means that it needs to be unique, and it’s also a little fiddly to change after the fact.

I tend to set a name along the lines of “manufacturer-type-uniqueid” here (where the unique ID is the last 6 characters of the device MAC address), e.g. “m5stack-atom-echo-b70634”, but feel free to use what you want.

For the purposes of this guide I’m going to use “waveshare-mini-guide”, so enter that and click “Next”.

You’ll then be prompted to select a device type. We’re using an ESP32-S3, so click that option.

You should then see a new device card appear in the UI window behind the dialog and you’ll get a “Configuration Created” message along with a prompt to create an encryption key for Home Assistant. For now, we’re not going to use any OTA or API keys (you can define them later if you wish), so just click “Skip” to close the window.

Hopefully you should now see your new device card in the UI. It will have a red border (as it’s not on the network), and should have the name you set in the wizard:

Updating The Config

As part of running the New Device wizard ESPHome has created a basic configuration for us. However we’re serious technical enthusiasts here (!!) so before we do anything else we’re going to replace the config with something of our own. So in the ESPHome UI, on your new device card, click the “Edit” button to open the configuration editor.

In the editor, delete the generated configuration and replace with the following (we’ll go through what it does at the end):

###############################################################################

# Substitutions
substitutions:
  name: waveshare-mini-guide
  friendly_name: Waveshare Mini Guide

# ESPHome Basics
esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  name_add_mac_suffix: false
  platformio_options:
    board_build.flash_mode: dio

# Board Configuration
esp32:
  board: esp32-s3-devkitc-1
  variant: esp32s3
  framework:
    type: esp-idf
    version: recommended
    sdkconfig_options:
      CONFIG_ESP32_S3_BOX_BOARD: "y"

psram:
  mode: quad
  speed: 80MHz

################################################################################

# Wifi Information
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: ${name}
    password: ${name}

captive_portal:

# Enable Home Assistant & ESPHome APIs
api:

ota:
  platform: esphome

# Enable logging
logger:

###############################################################################

# Home Assistant Buttons
button:
  - platform: shutdown
    name: "Shutdown"
  - platform: restart
    name: "Restart"
  - platform: safe_mode
    name: "Restart (Safe Mode)"

###############################################################################

“Save” the new configuration, and click the “X” in the top left to go back to the main UI.

You should see the name on the device card update to reflect the “friendly_name” we set above.

The First Firmware

We’re now going to build and upload the first firmware. In the UI on the device card, click the “three dots” and select “Install”. You’ll be prompted as to how you want to install the firmware on your device. As we’re going to use ESPHome Web, choose the “Manual Download” option.

All being well you’ll get a compiler window appear and it will start downloading the various frameworks and tools needed to build your firmware. Depending on the speed of your Home Assistant server this may take a while, so it’s a good opportunity to go do something else while it’s working (make a cup of tea, have lunch, go for a walk, etc.).

Useful Tip If you get errors during the firmware build which aren’t obviously down to a configuration error, it’s often worth cleaning the build files for the device (i.e. remove the temporary build files and start again). ESPHome will try and do this automatically if it detects that it’s needed, but it’s not 100% accurate.

To do this manually, on the device card click the “three dots” and select “Clean Build Files”. It’ll pop up a compiler window and run a manual clean. Once it’s done just try your build again and hopefully it should then work.

Once it’s built you’ll get a prompt to ask you which version you want to download, select “Factory Format” and your browser should download a file “waveshare-mini-guide.factory.bin” to wherever your downloads go. Find where this file is, you’re going to need it in a moment! You can then close the compiler window and go back to the main UI.

Installing the Firmware

Go ahead and plug the ESP32-S3-Mini into your computer (the computer you’re doing all this work on). Then go ahead and open a browser window (remember Chrome/Chromium based or Edge only) and go to web.esphome.io. You should see the ESPHome Web installer with a single card with a state of “Not Connected”:

At this point we need to put the ESP32 board into programming mode. On the board itself, on the top side of the board, next to the USB connector are a pair of buttons, one for “Boot” and another for “Reset”. They are marked with teeny, tiny letters which are almost impossible to see, so here’s a photo to help:

Very carefully hold down the “Boot” button, and while holding press the “Reset” button once. Wait a couple of seconds and then release the “Boot” button. The board should now be in programming mode.

In the web.esphome.io window, click the “Connect” button on the device card. You should get a pop-up that web.esphome.io wants to connect to a serial port:

Depending on your OS and configuration you will have different options here. In the above I’m using Debian and the option I want to use is the first one “USB JTAG”. Select the appropriate option and click “Connect”. (If you click away before clicking Connect you’ll get a pop-up about not selecting a port, just close the pop-up and try again).

If you don’t see a port, make sure the ESP32 board is properly connected, you’ve put it in programming mode, and you have the right permissions/drivers/etc to connect to USB serial devices. The “No Port Selected” dialog has some guidance on connectivity issues.

All being well, the board will connect and you’ll see the device card change to “Connected”:

Ignore the option for “Prepare for first use” and click the “Install” option. You’ll be prompted to choose a file, so click “Choose File” and browse to the “waveshare-mini-guide.factory.bin” file we built and downloaded earlier. With the file selected, click “Install” and wait while it installs the firmware.

All being well, you’ll get a “Configuration Installed” pop-up. You can just click “Close”.

To check the install has worked correctly, click the “Logs” option on the “ESP Device” card. then click the “Reset Device” option on the Logs window. You should hopefully see a whole bunch of device and ESPHome logs rush past, including seeing it connect to your WiFi, and hopefully at some point:

[11:57:50][I][safe_mode:041]: Boot seems successful; resetting boot loop counter
[11:57:50][D][esp32.preferences:114]: Saving 1 preferences to flash...
[11:57:50][D][esp32.preferences:142]: Saving 1 preferences to flash: 0 cached, 1 written, 0 failed

If you now switch back to your ESPHome Device Builder window you should (hopefully) see that it’s now connected to ESPHome:

If you’ve got this far and it’s worked….

Congratulations!! You’ve just built and installed your first ESPHome firmware!

If you want to keep the web.esphome.io window open to view logs you can, or you can now close it. We should now be able to see most logs by using the ESPHome Device Builder UI to view logs over the LAN. Just click the “Logs” option on the device card in the ESPHome Device Builder window and choose “Wirelessly”, and a logs window should open and start streaming logs from the device.

If at any point you’re doing troubleshooting and you need to see logging direct from the device (e.g. it’s not booting, or connecting to WiFI), then you can connect the board to your computer again, and use the logs view via web.esphome.io in your troubleshooting

Home Assistant Integration

If you’ve been keeping an eye on your Home Assistant dashboard through all of this, at some point (probably just after installing the firmware and rebooting) you should have seen a notification appear that a new device has been discovered. If you click the notification (or go to “Settings > Devices & Services > Integrations”) you should see that Home Assistant has automatically discovered your new device on the LAN and offered to Add it:

Go ahead and click “Add” and follow the prompts. When it’s done you should see an “ESPHome” integration appear in your Home Assistant dashboard. Click on the integration card and you should see your new ESPHome device listed:

Click on the “1 device” link under the device name, and you’ll be taken to the device page, which should look something like:

The three items under “Configuration” are the three Home Assistant Buttons we defined in our device config back at the start, and link across to those actions on the ESP32-S3-Mini (Restart / Safe Mode / Shutdown).

(You can now disconnect the ESP32 from your computer and plug it into a separate USB PSU, or disconnect it completely until the next part!)

Congratulations! You’ve now got a basic ESPHome device built and integrated into Home Assistant. Come back for Part 3 when we’ll add the LD2420 sensor and get presence working.

Config Walkthrough

If you want to know a little more about the config you just applied, here’s a quick walkthrough:

# Substitutions
substitutions:
  name: waveshare-mini-guide
  friendly_name: Waveshare Mini Guide

Substitutions are like variables, you can define them once and then reference them elsewhere in the file. Here we’re defining a device name, and a friendly name.

# ESPHome Basics
esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  name_add_mac_suffix: false
  platformio_options:
    board_build.flash_mode: dio

This sets up the basics of ESPHome on the device, including setting a device name and friendly name. The device name set here is what’s used to generate the device mDNS name. The “platformio_options” are board specific options relating to how ESPHome builds and flashes the firmware.

# Board Configuration
esp32:
  board: esp32-s3-devkitc-1
  variant: esp32s3
  framework:
    type: esp-idf
    version: recommended
    sdkconfig_options:
      CONFIG_ESP32_S3_BOX_BOARD: "y"

psram:
  mode: quad
  speed: 80MHz

This sets the details of the board itself, including the board type (board & variant), as well as which framework we’re using (arduino or esp-idf), and options for that framework. ESP-IDF is the newer framework, but Arduino seems to have better device support in some areas.

# Wifi Information
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: ${name}
    password: ${name}

captive_portal:

Here we set our WiFi details (pulling SSID and password from the Secrets configuration), as well as enabling the backup AP and captive portal in case we can#t connect to WiFi (see the ESPHome docs for more details)

# Enable Home Assistant & ESPHome APIs
api:

ota:
  platform: esphome

# Enable logging
logger:

Here we’re enabling both the Home Assistant API (api:) and ESPHome Over-The-Air (OTA) support. These are needed if you want to manage the device over the LAN from Home Assistant and/or ESPHome respectively. We also enable the logger here so that we can view logs from the board wirelessly or over USB Serial.

# Home Assistant Buttons
button:
  - platform: shutdown
    name: "Shutdown"
  - platform: restart
    name: "Restart"
  - platform: safe_mode
    name: "Restart (Safe Mode)"

Finally we define a set of buttons to display in Home Assistant. The specific “platform” definitions map the buttons to those three functions

Posted 15 January 2025

In HomeAutomation SmartHome HomeAssistant ESPHome