1. Project purpose
Build a distributed Bluetooth Low Energy (BLE) detection system integrated with Home Assistant.
The system will use one or more ESP32 devices running ESPHome as BLE scanners. Each ESP32 is assigned a physical location, such as:
- Kitchen
- Living room
- Bedroom
- Garage
- Main entrance
- Hallway
The ESP32 devices detect nearby BLE devices and report observations to Home Assistant.
Home Assistant is responsible for:
- Maintaining the device database
- Learning which devices are familiar
- Allowing devices to be manually classified as known or ignored
- Tracking when devices were last seen
- Managing device expiration/downgrading/deletion
- Determining device presence
- Estimating which physical zone a device is closest to
- Exposing useful sensors and states
- Driving automations and notifications
The ESP32s should remain relatively simple BLE observation devices. The main intelligence and persistent state should reside in Home Assistant.
2. Main objectives
The system should provide five major capabilities.
A. BLE device discovery
Detect nearby BLE devices and report information such as:
- Device identifier/address when available
- Advertised name when available
- RSSI
- Timestamp
- ESP32 that detected the device
- Physical location of that ESP32
- Other useful advertisement information where available
B. Device learning
The system should automatically learn about devices that repeatedly appear.
A newly detected device should not necessarily be considered suspicious or permanently unknown immediately.
The system should maintain a lifecycle such as:
NEW
↓
OBSERVED
↓
FAMILIAR
↓
KNOWN
with additional states such as:
IGNORED
STALE
DELETED
C. Presence detection
The system should be able to determine whether devices are currently present.
Examples:
- iPad present
- iPhone absent
- Unknown BLE device present
- No known devices present
Presence must tolerate temporary gaps in BLE advertisements.
A device disappearing for a few seconds should not immediately be considered absent.
D. Approximate location
With multiple ESP32 receivers, the system should compare RSSI measurements and determine which receiver/zone a device is probably closest to.
For example:
iPad
Kitchen: -43 dBm
Living room: -59 dBm
Garage: -79 dBm
Main entrance: -67 dBm
Estimated location: Kitchen
The system should use the concept of “closest/most likely zone” rather than attempting to provide precise coordinates.
E. Home Assistant automation
The resulting information should be exposed as normal Home Assistant entities so it can be used by automations.
Examples:
- Turn kitchen lights on when a known household device enters the kitchen.
- Turn garage lights on when an unknown BLE device is detected strongly in the garage.
- Notify when a completely new BLE device appears.
- Turn lights off when all known household devices have been absent for a configurable period.
3. Hardware
Initial hardware
The first prototype will use an existing:
ESP32-WROOM-32
running ESPHome.
No SD card is required for the initial system.
The ESP32 should primarily perform BLE scanning and transmit observations to Home Assistant.
Future hardware
Additional ESP32 devices can be added as required.
Each ESP32 should have a meaningful physical location.
Examples:
ble_kitchen
ble_living_room
ble_garage
ble_main_entrance
ble_hallway
ble_bedroom
The physical location should be part of the device’s configuration and should be included with observations.
External antennas
External-antenna ESP32 hardware may be useful for locations where coverage is poor, particularly:
- Garage
- Outdoor areas
- Locations separated by thick walls
- Locations where the ESP32 must be installed inside an RF-unfriendly enclosure
However, maximum range is not necessarily desirable.
The objective is not to make every ESP32 detect every BLE device as strongly as possible.
For location estimation, having several receivers with distinguishable RSSI measurements is more useful.
Therefore the initial recommendation is to test the normal onboard antenna before purchasing specialized external-antenna hardware.
4. Fundamental architecture
The architecture should be:
BLE devices
phones / tablets /
watches / headphones
│
│ BLE
▼
┌─────────────────────────┐
│ ESP32 │
│ ESPHome │
│ BLE scanner │
└────────────┬────────────┘
│
│ Wi-Fi
▼
┌─────────────────────┐
│ Home Assistant │
│ │
│ Device registry │
│ Observations │
│ Presence │
│ Location │
│ Familiarity │
│ Automations │
└─────────────────────┘
With multiple ESP32s:
Home Assistant
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
Kitchen Garage Main Entrance
ESP32 ESP32 ESP32
│ │ │
└──────────── BLE observations ────────────┘
Home Assistant is the central authority.
5. ESP32 responsibilities
ESP32 devices should perform as little business logic as possible.
Their primary responsibilities are:
- Scan for BLE advertisements.
- Identify the advertiser as far as BLE permits.
- Measure RSSI.
- Timestamp observations.
- Associate observations with the ESP32’s configured location.
- Send the observations to Home Assistant.
The ESP32 should not be responsible for determining:
- Whether a device is known
- Whether a device is familiar
- Whether a device should be deleted
- Whether a device is suspicious
- Whether a person is home
- Which room a device is in
Those decisions belong in Home Assistant.
This allows the rules to be changed without reflashing ESP32 devices.
6. BLE scanning configuration
The scan behavior should be configurable.
At minimum, the system should allow adjustment of:
Scan interval
How frequently the scanner performs a scan cycle.
Example:
1 second
5 seconds
10 seconds
30 seconds
Scan window
How much of each interval the ESP32 actually listens.
This should be configurable separately from the interval where practical.
Presence timeout
How long a device can go without being observed before being considered absent.
Example:
5 minutes
These are separate concepts.
A scan interval of 5 seconds does not mean that a device should be declared absent after 5 seconds without an advertisement.
7. Configurable system parameters
All important time thresholds should be configurable from Home Assistant rather than hard-coded.
Potential configuration parameters include:
BLE scan interval
BLE scan window
Presence timeout
Unknown-device alert delay
New-device grace period
Familiarity observation threshold
Familiarity time period
Known-device expiry
Stale-device period
Deletion period
Unknown-device notification cooldown
Minimum RSSI for location confidence
Minimum RSSI for security automations
Minimum location RSSI difference
Location smoothing period
Security-light activation delay
Security-light timeout
The exact values should be determined experimentally.
Example initial values:
Scan interval: 5 seconds
Presence timeout: 5 minutes
New-device grace period: 30 seconds
Familiarity period: 7 days
Familiarity threshold: 20 observations
Stale-device period: 30 days
Deletion period: 180 days
Unknown notification cooldown: 30 minutes
Minimum location difference: 8 dB
These are examples only and should remain user-configurable.
8. Device identity considerations
BLE device identification must not rely blindly on a single Bluetooth MAC address.
Modern BLE devices can use address randomization and may change their observable identity.
Some devices may also:
- Advertise intermittently
- Change advertisement behavior
- Use different identifiers for different functions
- Stop advertising when idle
- Advertise different information depending on operating-system behavior
Therefore the system should treat the BLE identifier as an observation identity rather than guaranteeing that it represents a permanent physical device.
The device registry should be designed so that the identity strategy can be improved later without rebuilding the whole system.
9. Device lifecycle
The system should distinguish between automatic learning and explicit user approval.
Recommended states:
NEW
OBSERVED
FAMILIAR
KNOWN
IGNORED
STALE
NEW
A device has been detected for the first time.
Example:
First seen:
2026-10-02 14:00
Observations:
1
OBSERVED
The device has been seen repeatedly, but has not yet met the familiarity criteria.
Example:
Observations:
17
First seen:
12 days ago
Last seen:
2 minutes ago
FAMILIAR
The device has been observed repeatedly over a meaningful period.
This means:
The system recognizes this device as frequently encountered.
It does NOT necessarily mean:
The user has explicitly approved this device.
KNOWN
The user has explicitly approved the device.
Known devices can be used for trusted presence automations.
IGNORED
The user has explicitly decided that the device should not generate alerts.
Examples could include:
- Neighbor’s device
- Known vehicle
- Permanent nearby BLE beacon
- Device that isn’t relevant to the household
Ignored devices may still be retained in the database for informational purposes.
STALE
The device has not been seen for a configurable period.
A stale device is retained temporarily rather than immediately deleted.
DELETED
The device record and/or historical observations are removed after the configured retention period.
10. Familiar versus known
These concepts must remain separate.
Familiar
Automatically inferred by the system.
Meaning:
“This device has appeared frequently enough that it is no longer particularly unusual.”
Known
Explicitly approved by the user.
Meaning:
“I recognize this device and want the system to treat it as a trusted device.”
This distinction allows the system to discover patterns without automatically granting trust.
11. Manual device management
Home Assistant should provide a way to manually manage devices.
Possible actions:
Make Known
Make Familiar
Ignore
Unignore
Rename
Forget
Delete
Reset learning
A device should be renameable.
Example:
BLE identifier:
AA:BB:CC:DD:EE:FF
Name:
Dad's iPad
The raw identifier should remain available internally even if the user gives it a friendly name.
12. Device history
The system should retain useful historical information.
Each device record should ideally contain:
Device ID
Friendly name
Current state
Classification
First seen
Last seen
Number of observations
Number of days observed
Last known location
Current estimated location
Approval time
Familiarity time
Last state change
Historical observations should contain information such as:
Timestamp
Device ID
ESP32 ID
ESP32 location
RSSI
Advertised name
BLE metadata
13. Observation retention
Raw observations should not necessarily be kept forever.
A sensible model is:
Detailed observations:
retain for X days
Device registry:
retain for Y days
Known device:
retain until manually removed
For example:
Raw observations: 14 days
Stale devices: 30 days
Delete unknown: 180 days
Known devices: manual deletion
These periods should be configurable.
This reduces database growth while preserving useful device history.
14. Per-location sensors
Each ESP32 represents a physical BLE detection zone.
For example:
Kitchen BLE
Garage BLE
Main Entrance BLE
Living Room BLE
Bedroom BLE
Each location should expose aggregate information to Home Assistant.
Numeric sensors
At minimum:
Unknown devices
Familiar devices
Known devices
Ignored devices
Total devices
Potential additional sensors:
Strongest device RSSI
Strongest unknown RSSI
Number of observations
Last scan timestamp
Scanner status
15. Per-location binary sensors
Each ESP32/location should expose convenient binary states.
Recommended:
Unknown device present
Familiar device present
Known device present
Any BLE device present
New unknown device detected
For example:
Garage BLE
Unknown device present: ON
Familiar device present: OFF
Known device present: ON
Any BLE device present: ON
These should be easy to use directly in Home Assistant automations.
16. Unknown-device detection
There should be a distinction between:
Unknown device present
A device currently classified as unknown is currently being detected.
This remains active for as long as the device is considered present.
New unknown device
A device has been detected that has not previously been observed.
This can trigger a notification.
This distinction prevents repeated notifications.
Example:
New unknown device:
→ send notification
Unknown device remains present:
→ keep security light on
→ do not send another notification every few seconds
17. Unknown-device alerting
Notifications should be configurable.
Possible alert conditions:
New unknown device detected
Unknown device present for > X seconds
Unknown device with RSSI stronger than X
Unknown device repeatedly detected over X minutes
Unknown device detected in a specific zone
There should be an alert cooldown to avoid notification spam.
Example:
Unknown-device notification cooldown:
30 minutes
18. Location estimation
Multiple ESP32 receivers should be used to estimate the location of a device.
Example:
iPad
Kitchen: -43 dBm
Living room: -59 dBm
Garage: -79 dBm
Main entrance: -67 dBm
Estimated location:
Kitchen
The system should primarily think in terms of:
“Which receiver/zone is the device closest to?”
rather than:
“What are the exact coordinates of the device?”
19. RSSI smoothing
Individual RSSI readings should not be trusted blindly.
RSSI can change significantly due to:
- Human bodies
- Walls
- Furniture
- Device orientation
- Multipath effects
- Radio interference
- Device antenna orientation
Therefore the location system should use a rolling average, median, exponential smoothing, or another filtering mechanism.
The exact algorithm can be determined during implementation/testing.
20. Location confidence
The system should not always force a location.
Example:
Kitchen: -51 dBm
Living room: -52 dBm
This should be considered ambiguous.
But:
Kitchen: -41 dBm
Living room: -67 dBm
Garage: -81 dBm
is much stronger evidence for Kitchen.
A configurable minimum RSSI difference should therefore be used.
Example:
Minimum location confidence difference:
8 dB
If the strongest receiver is not sufficiently stronger than the next receiver, the location can be:
Unknown
rather than incorrectly choosing a room.
21. Location sensor
Each recognized device can have a calculated location.
Example:
sensor.ipad_location
Possible states:
Kitchen
Living Room
Garage
Main Entrance
Bedroom
Unknown
Away
Attributes can contain:
Kitchen RSSI
Living Room RSSI
Garage RSSI
Main Entrance RSSI
Confidence
Last update
Number of receivers
22. “Closest to” logic
The preferred abstraction is:
device → closest zone
For example:
iPad → Kitchen
Phone → Main Entrance
Watch → Bedroom
Unknown device → Garage
This makes Home Assistant automations very straightforward.
Example:
IF iPad location == Kitchen
THEN turn Kitchen lights on
23. Person/device association
The BLE device registry should remain separate from Home Assistant person logic.
Eventually a user can associate several devices with one person.
Example:
Person: User A
Devices:
- iPhone
- Apple Watch
- iPad
Then presence can be calculated from multiple devices.
For example:
Any trusted device associated with Person A present
↓
Person A probably home
This avoids relying on one phone.
24. Presence logic
Presence should have hysteresis.
Do NOT use:
BLE seen
→ HOME
BLE not seen
→ AWAY
because BLE advertisements can disappear temporarily.
Instead:
Device observed
↓
Present
↓
No observations for X minutes
↓
Absent
The timeout should be configurable.
25. Security/light automation example
One intended use case is improving visibility for CCTV.
Example:
IF
Garage unknown devices > 0
AND
strongest unknown RSSI > configurable threshold
AND
unknown device has been present for > configurable duration
THEN
turn garage lights on
Possible configuration:
Minimum RSSI: -70 dBm
Activation delay: 10 seconds
Light timeout: 5 minutes
The actual values must be tested at the property.
This allows the system to distinguish a strong nearby device from a weak BLE signal originating farther away.
26. Other possible automations
Examples include:
Known device enters kitchen
IF
iPad location becomes Kitchen
THEN
turn kitchen lights on
Household device enters garage
IF
known device location becomes Garage
THEN
turn garage lights on
Unknown device appears
IF
new unknown BLE device detected
THEN
notify user
Everyone leaves
IF
all trusted household devices are absent
for X minutes
THEN
turn selected lights off
Unknown garage activity
IF
unknown devices > 0
AND garage door is closed
AND nobody is home
THEN
activate garage lighting
optionally notify user
The system should not automatically assume that an unknown BLE device represents a person. It is simply an additional sensor input.
27. Learning mode
A dedicated learning mode should be provided.
Example:
LEARNING MODE
Duration: 30 minutes
During learning mode, Home Assistant should present newly observed devices prominently.
Example:
BLE Learning Mode
iPad
47 observations
Seen at:
Kitchen
Living Room
AirPods
21 observations
Seen at:
Kitchen
Unknown Device A
6 observations
Seen at:
Garage
[Make Known]
[Ignore]
This makes initial setup significantly easier.
28. Per-zone dashboard
Home Assistant should eventually have a dashboard similar to:
BLE MONITOR
──────────────────────────────────────
Kitchen
Known: 2
Familiar: 1
Unknown: 0
Location activity: Normal
Living Room
Known: 1
Familiar: 0
Unknown: 0
Garage
Known: 0
Familiar: 0
Unknown: 2
⚠ Unknown BLE activity
Main Entrance
Known: 1
Familiar: 0
Unknown: 1
A separate device-management view should show the full registry.
29. Device management dashboard
Example:
BLE DEVICES
────────────────────────────────────────────
Device State Location Last seen
----------------------------------------------------
My iPhone KNOWN Kitchen 20 sec
My iPad KNOWN Garage 1 min
AirPods FAMILIAR Kitchen 2 min
Device A UNKNOWN Garage 10 sec
Device B UNKNOWN Main Entrance 4 min
Neighbor BLE IGNORED Main Entrance 2 min
Actions:
[Make Known]
[Make Familiar]
[Ignore]
[Forget]
[Rename]
30. Device expiry and downgrading
The system must support automatic aging.
Example:
Known
↓
not seen for X days
↓
Stale
Familiar devices can similarly be downgraded if they stop appearing.
Unknown devices can eventually be deleted if they have not been seen for a long period.
The exact lifecycle should be configurable.
Important distinction:
Automatically learned states may be automatically downgraded.
Manually approved KNOWN devices should preferably not be silently deleted unless the user explicitly enables that behavior.
31. Data retention and privacy
The system should minimize historical BLE data where practical.
BLE observations may represent devices belonging to people who are not members of the household.
Therefore:
- Retain detailed observations only as long as necessary.
- Allow the retention period to be configured.
- Provide a way to delete a device and its historical observations.
- Avoid storing unnecessary BLE information.
- Keep the system local to Home Assistant where possible.
32. Important technical limitations
The system must account for BLE limitations.
Address randomization
Some devices can change their BLE address.
Therefore MAC/address matching is not guaranteed to identify a physical device permanently.
Intermittent advertising
A device may not advertise continuously.
Not seeing a device does not necessarily mean that it has physically left.
RSSI is not distance
RSSI should be treated as a relative signal-strength measurement, not a precise distance measurement.
RSSI is not direction
A normal ESP32-WROOM-32 receiver cannot directly determine the direction of a BLE signal.
Direction/location is instead approximated using multiple receivers.
BLE range is variable
Range depends on:
- Device
- Antenna
- Walls
- Construction
- Interference
- Device orientation
- Receiver placement
The system should therefore be calibrated using actual measurements at the property.
33. Development strategy
Development should proceed incrementally.
Phase 1 — Single ESP32
Use the existing ESP32-WROOM-32.
Implement:
- ESPHome BLE scanning
- Configurable scan interval
- Device observation
- RSSI collection
- ESP32 location/name
- Home Assistant integration
Do not initially implement complicated location logic.
Phase 2 — Device registry
Implement:
- New
- Observed
- Familiar
- Known
- Ignored
- Stale
- Deleted
Implement configurable lifecycle timers.
Phase 3 — Home Assistant entities
Create:
- Device counts
- Unknown count
- Familiar count
- Known count
- Presence sensors
- New-device sensor
- Scanner status
- Last scan
- RSSI sensors
Phase 4 — Learning interface
Add:
- Make Known
- Make Familiar
- Ignore
- Rename
- Forget
- Learning mode
Phase 5 — Multiple ESP32s
Deploy additional receivers.
Each receives a unique physical location.
Example:
Kitchen
Living Room
Garage
Main Entrance
Phase 6 — Location estimation
Implement:
- RSSI smoothing
- Receiver comparison
- Closest-zone calculation
- Minimum confidence margin
- Unknown/ambiguous location state
Phase 7 — Automation
Implement Home Assistant automations for:
- Lighting
- Presence
- Security illumination
- Notifications
- Zone-based actions
34. Initial test methodology
Before purchasing many additional ESP32 devices, use the existing WROOM-32 to gather real measurements.
Test a known device such as an iPad at fixed locations.
Record:
Location
ESP32
RSSI
Time
Example:
Location RSSI
---------------------
Kitchen -40
Living Room -54
Hallway -62
Main Entrance -68
Garage -79
Outside -84
Repeat measurements several times.
The objective is to determine whether the RSSI differences between zones are sufficiently distinct to make location estimation practical.
If locations have highly overlapping RSSI values, additional receivers or different hardware placement may be required.
35. Design principles
The project should follow these principles:
- ESP32s are sensors, not the central database.
- Home Assistant owns persistent state and intelligence.
- All important time thresholds are configurable.
- Device learning is separate from manual approval.
- Known, familiar, unknown and ignored are separate concepts.
- Raw observations are separate from the device registry.
- Historical data should expire independently from device records.
- Presence should tolerate intermittent BLE advertisements.
- RSSI should be smoothed before location decisions.
- Location should be expressed primarily as a zone, not exact coordinates.
- Location confidence should be available.
- Multiple receivers are more important for location than simply maximizing one receiver’s range.
- Security automations should use configurable thresholds and delays.
- The system should be useful even with only one ESP32.
- Additional ESP32s should be easy to add later without redesigning the data model.
36. Target end state
The finished system should behave conceptually like this:
BLE ENVIRONMENT
│
▼
┌───────────────────────┐
│ ESP32 receivers │
│ │
│ Kitchen │
│ Living Room │
│ Garage │
│ Main Entrance │
└───────────┬───────────┘
│
▼
BLE observations
│
▼
┌───────────────────────┐
│ Home Assistant │
│ │
│ Device Registry │
│ Observation History │
│ Familiarity │
│ Presence │
│ Location │
│ Confidence │
│ Retention │
└───────────┬───────────┘
│
┌────────────┼─────────────┐
▼ ▼ ▼
KNOWN FAMILIAR UNKNOWN
│ │ │
└────────────┼─────────────┘
│
▼
Zone determination
│
┌────────────┼────────────┐
▼ ▼ ▼
Kitchen Garage Entrance
│ │ │
└────────────┼────────────┘
│
▼
HA Automations
The ultimate goal is a flexible BLE-based presence and zone-awareness system for Home Assistant, capable of learning the normal BLE environment over time while allowing explicit user control over which devices are trusted.
The system should be designed so that adding another ESP32, changing scan intervals, changing retention periods, changing familiarity rules, or changing automation behavior does not require redesigning the entire system.