I’m sharing a standalone security firmware for ESP32 + HLK-LD2412 (24 GHz FMCW radar). It’s been in production since early 2026, went through 50+ firmware iterations, a formal security audit, and has 41 unit tests. MIT licensed.
What makes this different from ESPHome / basic presence sensors
Most LD2412 integrations give you a binary presence sensor. This is a full intrusion detection system:
- 5-state alarm machine — DISARMED → ARMING (exit delay) → ARMED → PENDING (entry delay) → TRIGGERED. Not just “someone is here.”
- Up to 16 detection zones with per-zone behavior: entry delay, immediate trigger, ignore, or ignore-static-only (for metal shelves/reflectors that create phantom readings)
- Anti-false-alarm stack:
- Pet immunity (configurable energy threshold)
- Anti-masking detection (sensor obstruction / tampering)
- Loitering detection (persistent presence in restricted zones)
- Static zone auto-learning (180s baseline scan, auto-suggests ignore zones)
- Debounce frame counting before state transitions
- Motion direction tracking — APPROACHING vs RECEDING, with 16-event approach forensics buffer logged during armed state
- RSSI anomaly detection — sudden WiFi signal drops flagged as potential jamming
- Offline resilience — events buffered to LittleFS flash when MQTT/WiFi is down. Alarm triggers locally regardless of network state
Home Assistant integration
MQTT auto-discovery publishes 38+ entities out of the box:
alarm_control_panelwith full arm/disarm/pending/triggered states- Distance, motion energy, static energy, presence state
- Per-gate engineering data (14 motion + 14 static gates)
- Health score, frame rate, UART status, free heap, uptime
- Tamper, anti-masking, loitering binary sensors
- Light level sensor
No YAML configuration needed — just point it at your MQTT broker.
Telegram bot
Built-in bot with 12 commands: /arm, /disarm, /arm_now, /status, /learn, /light, /mute, /unmute, /eng_on, /eng_off, /restart, /help. Group chat support, notification cooldowns, mute functionality. Also supports Discord webhooks and generic HTTP webhooks.
Web dashboard & REST API
Dark-mode responsive dashboard with real-time SSE streaming (250ms updates). 50+ REST API endpoints covering:
- Telemetry, health, configuration
- Per-gate sensitivity tuning
- Zone management (JSON)
- Alarm control, security monitoring config
- Scheduled arm/disarm with timezone support
- Auto-arm after configurable idle period
- Config export/import (full JSON backup)
- Event log with CSV export
- OTA firmware update with 60-second automatic rollback
HTTP Digest authentication on all endpoints.
Hardware & cost
| Part | Cost |
|---|---|
| ESP32 DevKit (any WROOM-32) | ~$3–5 |
| HLK-LD2412 radar module | ~$4–6 |
| 5V power supply | ~$2–3 |
| Total | ~$10 |
4 wires (VCC, GND, TX, RX). Two tested pin configurations included. ~10 minutes from git clone to a working alarm.
Technical stack
PlatformIO, Arduino framework, ESP32-WROOM-32, C++, ~7K+ LOC, MIT license. MQTT supports both plaintext and TLS. NTP time sync, mDNS discovery, WiFi failover with backup credentials + AP captive portal.
Sensor firmware quirks
The LD2412 has version-dependent UART bugs (V1.26 ACKs commands but doesn’t execute them). The firmware includes built-in workarounds — gate config verification post-boot, aggressive retry logic, and auto-recovery. All documented in the README.
Questions, feature requests, or bug reports welcome. Happy to help with wiring or setup.