An ESP32 based presence detection node for use with the Home Assistant mqtt_room component for localized device presence detection.

Contents

1. Requirements
2. Getting Started
   1. Flashing the Hardware
   2. Define Settings
   3. Flashing the device via USB
   4. Flashing/updating via OTA
3. Home Assistant Configuration
4. Trackable Devices
   1. Beacons
   2. Generic BLE Devices
   3. Android Phones
   4. iPhones
5. Sensors
6. Credits
7. Troubleshooting
8. Release Notes

Requirements

You’re going to need the following items:

• An ESP32 development board
• A running instance of Home Assistant
• The Atom IDE with the PlatformIO package installed.
• A Bluetooth Low Energy beacon (either iBeacon or EddyStone), or
• An Android phone with a beacon app installed.

Getting Started

Flashing the Hardware

You can get started by cloning this repository to your local machine using git. Alternatively, you can download the zip. To get the code onto your device, thanks to some great work by kylegordon, you can now build and upload using PlatformIO.

Define your settings

Create a copy of the Settings.h file, and rename it to Settings_local.h or something similar. Any variation of the name Settings followed by an underscore will be ignored by git. This will allow you to set your own configuration without the risk of any commits to the repository of sensitive information. It can also be helpful to keep a settings file for each device you will run, as they will differ.

Flashing the device via USB

Open the project folder in Atom, using the open project option in the PlatformIO Home screen. Modify the settings in the Settings_local.h file to match your environment. Set the correct port in the platformio.ini file (or remove the line to use auto-detection), and upload to the board. Open the serial monitor after successful upload to check for success.

Flashing via OTA

It is possible to update the device using “Over the Air” (OTA) updates from the command line interface of PlatformIO. You will need to know the IP address of the device itself (check your router). From the command line, enter the command platformio run -t upload --upload-port . During the update process, you will see the on-board LED blinking slowly. Once the update has completed, you should see the device reconnect and update its telemetry.

Home Assistant Configuration

See the section on configuring Home Assistant.

Trackable Devices

Beacons

See the section on tracking beacons

Generic BLE Devices

Some other devices that advertise as BLE (such as the Mi Flora plant sensors or the Mi Band fitness tracker) can also be tracked, as long as you can scan the device and see its hardware ID. See the section on tracking generic BLE devices.

Tracking Android Phone

Read more here about getting your Android phone configured and tracked.

Tracking iPhone

Unfortunately, Apple does not allow devices to advertise iBeacon data in the background. As I do not own an iPhone, I will not attempt to implement scanning and reporting by device name, but I welcome pull requests.

Sensors

It is now possible to use the HTU21D i²c temperature and humidity sensor. By enabling and defining the htuSensorTopic property, the device will bring in the required file and connect to the sensor. Be sure to use the built-in hardware i2c bus pins, SDA on GPIO21 and SCL on GPIO22. While pull-up resistors are recommended, if you have short wires connecting the sensor to the board, you should be fine. Values will be published to the topic you defined, with /temperature appended for temperature measurements, and /humidity appended for humidity measurements.

Credits

This depends heavily on the hard work done by a number of people.

• pcbreflux (GitHub) (YouTube) - this code takes heavy inspiration from ESP32_BLE_beaconscan
• Neil Kolban (GitHub) (YouTube) - provided the Bluetooth low enery libraries used
• Marvin Roger (GitHub) - provided the Async MQTT library
• Benoit Blanchon (GitHub) (YouTube) - provided the Arduino JSON library
• Me No Dev (GitHub) - provided the Async TCP library
• Kyle Gordon (GitHub) - wrote the necessary code for PlatformIO support

Troubleshooting

If you’re having difficulty getting things set up and work properly, check out the troubleshooting section before you open an issue. It will help you determine what information you need to provide to identify and fix what’s gone wrong.

Release Notes

If you’re having difficulty updating your device to the newest version, or you’re just curious, check out the release notes.