fshr

The musings of a grumpy hairless ape

ESPHome Presence Sensor - Part 1 - Pre-Reqs

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.

Introduction

If you’re looking to build a smart home with Home Assistant, one thing you’re most certainly going to need is devices, whether it’s a smart lightstrip, some smart plugs, or something more esoteric and specialised. For anyone searching through the likes of Amazon or Aliexpress there’s an ever growing range of devices available, whether you’re into Zigbee, Z=Wave, Matter, or a less common standard, and most “standard” devices are now pretty much plug-and-play out of the box on any smart home hub (assuming it supports your standard of choice).

But what if you want something a little different? What if you really want that Public Transport Countdown Timer, you absolutely must automate your ergonomic bed, or a robotic cat laser is more your thing - well you’re probably going to need to get a little more creative and do some smart home DIY.

As you may have noticed, all the links in the above paragraph aren’t entirely random, they’re all taken from the ESPHome Discord, specifically the “Show-Off” channel, where ESPHome users can show off their creations.

For the unintiated, ESPHome is a toolbox to allow the (relatively) easy creation of smart devices using off-the-shelf components. This typically means some kind of microcontroller (usually either an ESP32 or ESP8266 variant), and one or more components (sensor / input / output) to provide some means for that microcontroller to talk to the outside world. You then create a YAML configuration file describing what microcontroller and components you’re using and what you want them to do, and ESPHome uses that configuration file to build a custom firmware to run on your device.

The way you connect up the components can vary depending on your specific level of skill, from literal off-the-shelf boards which you connect together with patch cables, through to custom designed all-in-one boards with the specific components you require.

What Are We Building?

Now for the purposes of what we’re going to cover here, we’re staying simple, using off the shelf boards which we can hook up to create a fairly basic mmWave based presence sensor which we can then connect into Home Assistant to detect whether someone’s in the room.

A presence sensor differs from a normal motion sensor in that, while a motion sensor specifically works on motion - whenever it detects a movement it sends a Movement event, and when it stops detecting movement it stops sending events - a presense sensor works on the basis of presence, i.e. when it detects someone in the room, it sends a simple Presence event, and when the room is empty it sends a simple Clear event (they can even still detect presence if someone is asleep in bed for example).

Using mmWave for presence (vs IR or acoustic) also gives advantages in accuracy, plus in my experience mmWave can easily travel through a few mm of plastic, making it a lot easier to build into any other project.

What Are We Not Building?

I won’t be including any sort of case as part of this, this is just covering off a basic “get the sensor piece working”. If you do this, and subsequently design a case for it, let me know and I’ll pop a link to it here :-)

Requirements

If you want to follow along and build your own sensor you’ll need a few things…

A Working Home Assistant install

While you can use ESPHome devices standalone, or with anything which talks MQTT, I personally think that you’ll get the most out of your devices if you partner them with Home Assistant. ESPHome natively integrates with HA very well and it also opens up the ability to link into HA automations, etc.

An ESP32 Board

You’ll need some kind of controller board, preferably ESP32, with header pins attached. I recommend the Waveshare ESP32-S3-Zero-M, you should be able to pick them up for under £5 (ex shipping) from somewhere like Aliexpress. You’re free to use any other board, but the configs I’ll use here will be written for the ESP32-S3-Zero-M, so you’ll need to adapt them if you use anything else.

ESP32-S3-Zero-M
ESP32-S3-Zero-M

A mmWave Presence Sensor

You’ll need some kind of ESPHome supported presence sensor, again with header pins attached. Again I recommend the Hi-Link LD2420, and similar to the ESP32 you should be able to get one for around £2 (ex shipping) from Aliexpress. Also again, you can use a different sensor if you want, but the configs will be written for the LD2420, so you’ll need to adapt them if you use anything else.

LD2420
LD2420

Dupont Jumper Wires

You’ll need some wires to connect the ESP32 to the LD2420. I’d recommend to use “Dupont Jumper Wires (Female-Female)” as they’re preterminated with the right connectors to fit the header pins on the boards. For the purposes of this exercise the shortest and smallest set of cables will be fine (they normallly seem to come as minimum 10cm, and 40 connected wires [we need 4 wires for this]). Again, available for £1-2 from Aliexpress (or I’ve bought from eBay before).

Dupont Female-Female
Dupont Female-Female

A Suitable USB-C Cable

Power and initial programming for the ESP32 board is via a USB cable, specifically USB-C for the ESP32-S3-Zero-M. Depending on your computer’s USB ports (and potentially any external USB PSU you use), this means you’ll need either a USB-C to USB-C, or USB-C to USB-A cable to connect the ESP32 to your PC or PSU. Length depends on your particular requirement/preference, but it does need to be a power and data cable, some cheaper USB-C cables only connect power or data pins and not both.

USB-C to USB-A Cable
USB-C to USB-A Cable

ESPHome Install

Once you’ve got all of the above lined up, the next thing you’ll need is a working ESPHome install. For Home Assistant use you can run ESPHome in one of two ways:

Home Assistant Add-In

This installs the ESPHome Device Compiler as an Add-In within Home Assistant. This is the option I’m going to use for the remainder of this guide.

This has the advantages of:

  • It’s neatly integrated into the HA ecosystem
  • It gives you a nice web UI to manage everything with
  • HA prompts you to update ESPHome when a new release comes out
  • You don’t need to worry about a separate ESPHome install to manage
  • You can access it from just about any device with a browser (with the caveat below)

But the disadvantages of:

  • The initial firmware install is best done over a USB connection from the PC you’re working on. If you’re using the web UI this requires WebSerial support which is only available in a Chrome/Edge/Chromium based browser (also see caveat below!). It won’t work from Safafi, Firefox, etc., so you may need to install Chrome/Edge/Chromium if you don’t already have it.
  • The firmware build runs where the ESPHome install is, in this case on the Home Assistant server. Depending on what you’re using for HA this may mean slow compiles and/or higher CPU/RAM/Disk usage on the HA server.
  • This assumes you can install HA Add-Ons. If you’re running HA on Docker, or some other solution where you can’t run Add-Ons you may need to use the command line option.

Additional Caveat - WebSerial also has a requirement for an HTTPS connection to the web server making the serial connection. Unless your Home Assistant server has a valid local HTTPS certificate you won’t be able to make a WebSerial connection fromn the ESPHome Device Compiler.

Luckily ESPHome provide a hosted WebSerial interface at web.esphome.io which will allow us to build a firmware file in the ESPHome Device Compiler, and then separately upload it to the device.

Note this is only for the initial firmware install, and your firmware file stays local through the process.

Command Line

This installs the ESPHome Device Compiler using Docker, or as a local Python app (I would recommend the Python install). This is a more advanced usage for a first time install, so I won’t be using it in this guide, but you’re free to use it if you feel comfortable.

This has the advantages of:

  • The initial firmware install is best done over a USB connection from the PC you’re working on. As you’re running the ESPHome utility from the CLI you can likely access the USB port connection with little issue (you may need to put your account in the ‘dialout’ group in Linux).
  • The firmware build runs where the ESPHome install is, in this case on your PC. Depending on what your PC is you likely have a suitably performant PC to run the compiles quickly and without issue.
  • If you can use a CLI, can install Python, and can create a venv, you can run ESPHome, you don’t need anything else.

But the disadvantages of:

  • It’s not neatly integrated into the HA ecosystem
  • It (mainly) relies on using the CLI (you can run the WebUI locally, but then you may as well run it under HA)
  • You need to manually track new releases and update
  • It’s a separate install to HA that you need to manage
  • You can only use it on the PC it’s installed on (excepting if you have SSH access or similar)

Assumptions

Some of these are assumptions, some are closer to pre-reqs, and/or you may need to do more to get stuff working if you don’t have the following:

Local LAN

Both Home Assistant and ESPHome use mDNS extensively for discovery and stuff talking to each other. In practice, mDNS works best when everything is on the same layer 3 subnet / network / VLAN, and tends to fall over if stuff is sat on different sides of a gateway/router. You can get both HA and ESPHome working with a router between bits of the system, but it’s going to need extra work and configuration. For this guide I’m going to assume that you have everything on the same layer 3 subnet.

WiFI

In general, ESP32 devices connect to the network via WiFi. Therefore I’m going to assume that you have your “Local LAN” above on WiFi, and that you know the SSID and Password to connect to it!

General Technical Ability

It hopefully goes without saying that this is going to be a technical guide, and a general technical ability to know how to connect things up, plug things in, use a command line, write config files, etc. is required. This guide is presented as-is, and work and life commitments mean I unfortunately don’t have the time to answer basic questions of how to connect stuff up, or how to edit config files :-)

You’re Using The Components I’ve Listed

This guide isn’t written as a “set up anything on ESPHome”, it’s going to be written to be specific to what I’ve listed above. You’re free to change what you use and use different bits, but that means you’re also free to work out how to get it working yourself and fix your own issues!

Posted 10 January 2025

In HomeAutomation SmartHome HomeAssistant ESPHome Updated

© Paul Fisher 2025 / CC BY-NC-SA 4.0 / Disclaimer