Skip to content
OpticWorks Intranet

Presence Detection Engine Overview

The Presence Detection Engine is an open-source ESPHome/ESP32 presence detection system that combines mmWave radar telemetry with statistical signal processing for Home Assistant integration.

What is the Presence Detection Engine?

Section titled “What is the Presence Detection Engine?”

This project provides a DIY solution for accurate presence detection using affordable mmWave radar sensors. The reference implementation targets bed occupancy detection using an LD2410 sensor, but the architecture supports various presence sensing applications.

Key Differentiators

Section titled “Key Differentiators”
FeatureTraditional PIROur Engine
Stationary detectionNoYes
Sub-second responseNoYes
PrivacyYesYes
Works in darknessNoYes
CalibrationManualAutomatic
On-device processingN/AYes

Core Capabilities

Section titled “Core Capabilities”

On-Device Intelligence

Section titled “On-Device Intelligence”

All processing happens locally on the ESP32:

  • Mean (μ) and standard deviation (σ) maintenance
  • Z-score calculation and threshold comparison
  • State machine transitions and debouncing
  • No cloud dependency for core functionality

Transparent Diagnostics

Section titled “Transparent Diagnostics”

The engine exposes its decision rationale through Home Assistant sensors:

  • Presence State Reason - Current detection explanation
  • Presence Change Reason - Why state transitions occurred
  • Real-time z-scores and timer states

Runtime Tuning

Section titled “Runtime Tuning”

All parameters are adjustable via Home Assistant without reflashing:

  • Detection thresholds
  • Debounce durations
  • Distance windows
  • Calibration settings

Guided Calibration

Section titled “Guided Calibration”

MAD-based automatic baseline calibration:

  • Triggered via Home Assistant service calls
  • Visual wizard interface in HA dashboard
  • Persistent calibration storage

Detection Phases

Section titled “Detection Phases”

The engine has evolved through several phases of development:

PhaseFeatures
Phase 1Z-score detection, hysteresis, runtime thresholds
Phase 24-state machine, debouncing, absolute-clear guards
Phase 3MAD calibration, distance windowing, change-reason telemetry
Phase 3.1+Calibration persistence, analytics (in progress)

Hardware Requirements

Section titled “Hardware Requirements”

Reference Build

Section titled “Reference Build”
ComponentModelPurpose
MicrocontrollerESP32-WROOM-32Main processing
Radar SensorLD2410mmWave detection
Power5V USB or 5V adapterPower supply

Wiring Diagram

Section titled “Wiring Diagram”
ESP32                   LD2410
┌─────────┐            ┌─────────┐
│  3.3V   │────────────│  VCC    │
│  GND    │────────────│  GND    │
│  TX (17)│────────────│  RX     │
│  RX (16)│────────────│  TX     │
└─────────┘            └─────────┘

Technology Stack

Section titled “Technology Stack”
ComponentTechnology
LanguagesPython (55.1%), C++ (25.1%), Shell (19.8%)
PlatformESP32 with ESPHome
RadarLD2410 mmWave (24GHz)
IntegrationHome Assistant
TestingPlatformIO (C++), Python (E2E)

Repository Structure

Section titled “Repository Structure”
presence-detection-engine/
├── docs/               # Specifications and guides
│   ├── architecture/   # System design docs
│   ├── workflows/      # Development workflows
│   └── troubleshooting/ # Common issues
├── esphome/           # Firmware and components
│   ├── base.yaml      # Base configuration
│   └── components/    # Custom components
├── homeassistant/     # HA integration
│   ├── dashboards/    # Lovelace cards
│   ├── blueprints/    # Automation blueprints
│   └── helpers/       # Input helpers
├── tests/
│   ├── unit/          # C++ unit tests
│   └── e2e/           # Integration tests
└── hardware/          # CAD mounting references

Who Uses This

Section titled “Who Uses This”
  • Home Assistant enthusiasts looking for reliable presence detection
  • Smart home developers building automation systems
  • OpticWorks community evaluating our presence technology

Relationship to hardwareOS

Section titled “Relationship to hardwareOS”

The Presence Detection Engine is a simplified, ESP32-based version of the sensing algorithms used in hardwareOS. Key differences:

AspectPresence EnginehardwareOS
PlatformESP32RV1106
SensorLD2410LD2450 + Camera
FusionRadar onlyRadar + Vision
TrackingSingle targetMulti-target
InterfaceHome AssistantWebRTC

Getting Started

Section titled “Getting Started”
  1. Review the Architecture to understand the system
  2. Follow the Development Guide to set up your environment
  3. Set up the Home Assistant Integration

Resources

Section titled “Resources”