ESPresense

I work with many creative individuals who frequently come up with interesting projects, and occasionally, their ideas intersect with my own.

In my apartment, I’ve set up several Ubiquiti cameras along with a variety of Hue lights. This particular project began with a simple goal: to automatically enable camera recordings and turn off the lights when both my partner and I leave the apartment and to revert those actions when either of us returns.

Since I use Home Assistant, I experimented with several approaches before receiving a recommendation to try ESPresense, but more on that later. I tend to explore multiple solutions independently before seeking out advice, so let’s start by looking at the methods I initially attempted.

Unify WiFi Route

If you’re familiar with Home Assistant, you’ll know it supports integration with a wide range of devices and systems. One of those is Ubiquiti’s UniFi network equipment, which I happen to use specifically, UniFi access points that I had already integrated into Home Assistant.

With that in place, I created an automation that monitored whether our mobile devices were marked as seen or offline on the network. Initially, this setup worked as expected. However, I soon realized there was a noticeable delay in how quickly devices were marked as offline after leaving the apartment, and similarly, a lag before they were recognized as seen upon returning.

For example, I could walk nearly 50 meters away before my device was flagged as offline, and it might take up to a minute after re-entering the apartment for the automation to trigger depending on when the phone reconnected to WiFi. This made the solution less than ideal for my use case.

Apple iCloud Route

The next approach I tried was integrating Home Assistant with iCloud, since iCloud has access to the real-time location of our phones. While this method somewhat worked, it came with a few drawbacks. Home Assistant repeatedly triggered iCloud login attempts, which resulted in a constant stream of email alerts from Apple. Additionally, the location accuracy wasn’t particularly reliable, making this solution less effective than I had hoped.

Home Assistant App Route

Since I don’t expose Home Assistant to the public internet and didn’t want to rely on a VPN on both of our devices, I quickly ruled out this option.

ESPresense to the Rescue

Now for the fun part after laying out the backstory. A colleague of mine, who previously worked for an IoT company specializing in smart home solutions, shared what both he and his father use for presence detection in similar scenarios. Namely ESPresense.

ESPresense in itself

ESPresense is an ESP32-based presence detection node designed for localized device tracking.

Reasons to use this over other solutions:

• ESP32 nodes are cheaper and easier to use than Raspberry Pis
• Extensive fingerprint-based IDs instead of MAC addresses for tracking or counting devices others can’t
• IRK-based enrollment of Apple devices to passively locate them uniquely, even with private random addresses
• Home Assistant MQTT Discovery for easy HA configuration
• Auto-updates by downloading GitHub-released binaries (optional, with a preference to disable if desired)
• Filters measured distance with both a median pre-filter and a 1Euro filter (reduces jitter for greater accuracy)
• Companion allows for full multilateration

XIAO ESP32C3

Following his recommendation, I ordered a pack of XIAO ESP32C3 boards from a local vendor. Given how affordable they are, I ended up purchasing 20 units.

Here is some of the specs:

• Flexible MCU Board: Incorporate the ESP32-C3 32-bit RISC-V chip, operating up to 160 MHz, mounted multiple development ports,
• Developer Friendly: Compatible with Arduino IDE, MicroPython, CircuitPython, PlatformIO, ESP IDF, Zephyr, Matter, ESPNow, Meshtastic, WLED, ESPHome, Home Assistant, Ubidots
• Outstanding RF performance: Complete Wi-Fi functions and Bluetooth Low Energy, while supporting communication over 100m with anFL antenna
• Elaborate Power Design: 4 working modes as low as 44 μA in deep sleep mode, while supporting lithium battery charge management
• Thumb-sized Design: 21 x 17.5mm, Seeed Studio XIAO series classic form factor
• Perfect for Production: Breadboard-friendly with elegant Surface-Mounted SMD design, no components on the back

The most important feature of these boards is their support for Bluetooth Low Energy (BLE).

These compact devices are ideal for discreet placement, thanks to their small size. They also come equipped with an external antenna and 3M adhesive, making it easy to mount them wherever needed without drawing attention.

Flashing ESPresense on the device

Installing the firmware on the device was quite easy affair as the website had a ESP Web Tool on it.

For this kind of boars you only need to pick the latest version and select standard as flavor.

The tool will prompt you to select the serial port to which the device is connected typically labeled as USB JTAG/serial debug unit. After that, you’ll be presented with two options: Install ESPresense or Logs & Console. In this case, we want to proceed with the installation.

Next, it will ask whether you’d like to erase the device before installing. Once confirmed, the tool will flash the ESPresense firmware onto the device.

Once the installation is complete, the device will automatically reboot and broadcast its own WiFi network for initial configuration. In my case, it appeared as espresense-e8df86.

When you connect to the device, it will present a captive portal similar to what you might see when connecting to hotel WiFi for the first time. Here, you simply need to enter your WiFi SSID, WiFi password, and assign a room name to indicate where the device will be located. Once saved, restart the device to complete the setup.

It will now be available in your network for rest of the configuration later on.

Home Assistant setup

Head over to Home Assistant

MQTT

In Home Assistant you need to add MQTT and MQTT Room Presence integrations.

Once the installation is complete, you’ll need to retrieve the MQTT password used by the integration. Since Home Assistant OS (HAOS) runs on Docker, and this integration operates within its own container, I inspected the container to extract the randomly generated MQTT password.

docker exec -it addon_core_mosquitto cat /data/system_user.json
{"homeassistant":{"password":"THIS IS A LONG F STRING"},"addons":{"password":"THIS IS NOT HE PASSWORD WE NEED, THE HOMEASSISTANT ONE IS"}}

Copy the password associated with homeassistant, we will be needing it later.

Configuring MQTT on ESPresence

Now we can connect to the ESPresence again over HTTP to do configurations to it. In my case it had the IP 192.168.1.173

Next, you’ll need to configure the ESPresense device to connect to your Home Assistant instance. Enter the following details:

• MQTT Server IP: 192.168.0.161 (your Home Assistant IP address)
• MQTT Port: 1883
• Username: homeassistant
• Password: the one retrieved from the Docker container

Once that’s saved and the device connects, you’ll see it appear in Home Assistant under MQTT Devices, typically named something like espresense-hallway.

At this point, the device is successfully connected to Home Assistant, but it still doesn’t know what to detect or report on.

To configure this, go to the ESPresense device page in Home Assistant. At the bottom, you’ll find a link labeled “Click here to edit other settings!”. Clicking this opens the advanced ESPresense configuration interface.

Here, you can view detected devices and examine fingerprints which are the Bluetooth signatures of nearby devices the ESPresense unit can see.

Enroll bluetooth device

Under the Devices section in the ESPresense interface, there’s an Enroll button that allows you to register Bluetooth devices for tracking. However, during my setup, I had some issues on enrollment of our Apple devices while running ESPresense version 3.3.5.

Based on my research, there appears to be a known issue related to enrolling iPhones with S3/C3 boards, which affects consistent detection.

Fortunately, since I had access to a MacBook, I was able to manually retrieve the Identity Resolving Keys (IRKs) for both my iPhone and my partner’s by digging through the iCloud Keychain.

I later came across a comment on the GitHub issue suggesting an alternative approach: connecting the ESPresense device via USB and using the debug console to capture the IRK while attempting to enroll an iPhone. However, I haven’t tested this method myself, as the comment was posted after I had already completed my setup.

If you connect a serial monitoring application to the USB port of the Espresense device, during enrollment the irk:value is clearly displayed, though the alias never shows up on the fingerprints page.

Getting IRK from Keychain due to bug

Method for doing that is as follow’s:

• On MacOS, ensure you are logged in with the iCloud ID associated with your device.
• Launch the Keychain Access application.
• In the left sidebar, click on iCloud.
• In the upper right search bar, type bluetooth.
• A series of entries will appear with the application password type.
• On your Apple Watch device, go to Settings > About, scroll down to find the Bluetooth address, in the format: XX:XX:XX:XX:XX:XX
• Open each entry to find the one associated with your Apple Watch. The Account field should match the Bluetooth address of your watch, in the format: Public: XX:XX:XX:XX:XX:XX.
• Click on Show password. Type your macOS password twice and copy the contents.

The output will contain a Base64-encoded string, which needs to be decoded to extract the Identity Resolving Key (IRK).

Example of a Base64-encoded string: WWVzIHRoaXMgaXMgYSBiYXNlNjQgZW5jb2RlZCBzdHJpbmc=

Decode on Linux/Mac:

echo "WWVzIHRoaXMgaXMgYSBiYXNlNjQgZW5jb2RlZCBzdHJpbmc=" | base64 --decode

Decode on Windows:

[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("WWVzIHRoaXMgaXMgYSBiYXNlNjQgZW5jb2RlZCBzdHJpbmc="))

Once decoded, you should have a 32-character IRK. Be sure to save this key for future use.

For the purposes of the examples that follow, I’ll use the placeholder xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx to represent the IRK.

Continue with the configuration in Home Assistant

In Home Assistant, navigate to Settings → Devices & Services → MQTT, then click Configure under core-mosquitto.

From there, use the Publish a packet section to send configuration data directly to your ESPresense device. This feature is especially useful when managing multiple ESPresense units across different rooms, allowing you to centrally configure and update them as needed.

Under Topic you add the following and replace xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your IRK:

espresense/settings/irk:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/config

And with the payload you will need to add a id that we will be referencing later and a name:

{"id":"irk:mikael_ble", "name":"Mikael BLE"}

Once you have done that hit Publish.

Once the configuration has been successfully published, you’ll see the new entry appear at the top of the ESPresense device’s settings page, as well as under Devices.

Next, we need to create a sensor in Home Assistant that can receive and reflect updates from ESPresense. To do this, open your configuration.yaml file and add the following snippet of code:

sensor:
  - platform: "mqtt_room"
    device_id: "irk:mikael_ble"
    name: "Mikael iPhone BLE"
    state_topic: "espresense/devices/irk:mikael_ble"
    away_timeout: 60
    timeout: 10
    unique_id: "mikael_iphone_BLE"

What we’re doing here is creating a sensor to store presence data, using the reference we specified in the Publish command. We’re assigning it a human-readable name and a unique_id so it can be easily identified and managed within Home Assistant.

Next, we’ll create an automation to convert this sensor data into device_tracker entities. These will report values of either home or not_home, depending on whether the device is currently detected (seen) or not.

alias: ESPresense - Convert to device_tracker
description: Convert ESPresence sensors to device_trackers
triggers:
  - entity_id:
      - sensor.mikael_iphone_ble
    trigger: state
conditions: []
actions:
  - variables:
      dev_id: "{{ trigger.to_state.entity_id.split('.')[1] }}"
      previous_state: "{{ states('device_tracker.' ~ dev_id) }}"
  - data:
      dev_id: "{{ dev_id }}"
      source_type: bluetooth_le
      location_name: |-
        {% if not is_state('sensor.' ~ dev_id, 'not_home') %}
          home
        {% else %}
          not_home
        {% endif %}
    action: device_tracker.see
mode: parallel

Since this automation can be quite active and generate frequent state changes, it may end up cluttering the logs. To avoid this, we can return to the configuration.yaml file and adjust the logging settings to suppress unnecessary log entries.

recorder:
  exclude:
    entities:
      - automation.espresense_convert_to_device_tracker

Since we’ve made changes to the configuration.yaml file, we need to reload the configuration. To do this, go to Settings → System, then click the power icon in the top-right corner and select Quick reload. This will apply the changes without requiring a full Home Assistant restart.

The final step is to link the newly created device_tracker to a person in Home Assistant. Navigate to Settings → People, select the appropriate person, and under Select the devices that belong to this person, add the device tracker for example, mikael_iphone_ble.

Success

Thanks to its use of Bluetooth Low Energy (BLE), ESPresense is capable of detecting presence with millisecond-level responsiveness allowing near-instant recognition when a device enters or leaves the area.

Below is an example of the automation I created to trigger actions based on whether we’re home or away:

alias: Nobody Home
description: ""
triggers:
  - trigger: state
    entity_id:
      - zone.home
    from: null
    to: "0"
conditions: []
actions:
  - action: input_boolean.turn_on
    metadata: {}
    data: {}
    target:
      entity_id: input_boolean.camera_record
  - action: light.turn_off
    metadata: {}
    data: {}
    target:
      area_id:
        - living_room
        - bedroom
        - guest_room
      device_id:
        - 6622ef2f97a996d30c75cab328520f93
        - cffb87d6e88692ecbe7f554fc4a2e89a
mode: single

alias: Someone Arrived Home
description: ""
triggers:
  - trigger: state
    entity_id:
      - zone.home
    from: "0"
    to: null
conditions: []
actions:
  - action: input_boolean.turn_off
    metadata: {}
    data: {}
    target:
      entity_id: input_boolean.camera_record
  - action: light.turn_on
    metadata: {}
    data:
      brightness_pct: 50
      kelvin: 2652
    target:
      area_id:
        - living_room
        - kitchen
mode: single

By placing an ESPresense device in the bedroom, you can also detect when someone has gone to bed, enabling additional automation based on presence in that specific room.

alias: Detect that Mikael and The better half has gone to bed!
description: ""
triggers:
  - trigger: state
    entity_id:
      - sensor.wife_iphone_ble
    to: bedroom
    for:
      hours: 0
      minutes: 1
      seconds: 0
    alias: When The better half changed to Bedroom for 1 min
  - alias: When Mikael changed to Bedroom for 1 min
    trigger: state
    entity_id:
      - sensor.mikael_iphone_ble
    to: bedroom
    for:
      hours: 0
      minutes: 1
      seconds: 0
conditions:
  - alias: If The better half and Mikael is in the bedroom and time is between 23:00 and 08:00
    condition: and
    conditions:
      - condition: state
        entity_id: sensor.wife_iphone_ble
        state: bedroom
      - condition: state
        entity_id: sensor.mikael_iphone_ble
        state: bedroom
      - condition: time
        after: "23:00:00"
        before: "08:00:00"
actions:
  - action: light.turn_off
    metadata: {}
    data: {}
    target:
      area_id:
        - living_room
      device_id:
        - 6622ef2f97a996d30c75cab328520f93
        - cffb87d6e88692ecbe7f554fc4a2e89a
    alias: Turn off all Light except under bench in kitchen
  - type: turn_on
    device_id: 73218151408795c2dcc5f7ba6c65aa2e
    entity_id: 17bae889032cfd2c7ed14c7d8862056e
    domain: light
    brightness_pct: 10
    alias: Set Benklight 1 to 10%
  - type: turn_on
    device_id: e5671e11169722cd9539ce8eef105b82
    entity_id: fdb242e9d98cd86edba64edd7e4b84d0
    domain: light
    brightness_pct: 10
    alias: Set Benklight 2 to 10%
mode: single

As a bonus, if you need a 3D model for printing of a case for the device I created one and uploaded to Makerworld

Bugs

Strange behavior on Apple Device tracking

For Bluetooth Low Energy (BLE) presence detection to remain active on an iPhone—even when the screen is off—you typically need to have a companion device that supports Apple’s Continuity features, such as an Apple Watch. Without such a device, iOS tends to suspend BLE advertising shortly after the screen turns off.

This limitation has been a known issue for some time. I first noticed the behavior when my partner stopped using her Apple Watch due to battery issues, which led to inconsistent presence detection and unexpected automation triggers in Home Assistant.

Note: Some iOS devices do not emit a beacon while the phone screen is off if there is not a reason for the device to broadcast a signal, consequently the device may not appear while the screen is off. Something like an iWatch, Universal Clipboard with Handoff enabled, or other services that require the phone to communicate regularly may resolve this issue as they require the subject iOS device to communicate while ‘sleeping’. In the case you do not have a bluetooth device like an iWatch, some people report that using background apps like iCloud Family Sharing, iCloud Photo Backup, or Room Assistant have convinced the device to communicate while ‘sleeping’. This issue is not universal, but it’s not clear why this occurs at this time and you may not experience this issue even if the device seemingly has no reason to communicate.

You can find more information on this issue here.

Enrollment issues with apple devices and ESP32S3 / ESP32C3

Based on my research, there appears to be a known issue related to enrolling iPhones with S3/C3 boards, which affects consistent detection.

Fortunately, since I had access to a MacBook, I was able to manually retrieve the Identity Resolving Keys (IRKs) for both my iPhone and my partner’s by digging through the iCloud Keychain.

I later came across a comment on the GitHub issue suggesting an alternative approach: connecting the ESPresense device via USB and using the debug console to capture the IRK while attempting to enroll an iPhone. However, I haven’t tested this method myself, as the comment was posted after I had already completed my setup.

I wrote about it in-dept on this page.