esphome-ld2411s/llms.txt at main · DAB-LABS/esphome-ld2411s · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
# esphome-ld2411s

> esphome-ld2411s is an ESPHome external component for the HLK-LD2411S 24GHz mmWave
> presence sensor by Hi-Link. It provides motion detection, stationary presence
> detection, and target distance reporting as native Home Assistant entities. Zone
> boundaries and unoccupied timeout are configurable at runtime from Home Assistant
> without reflashing the ESP32.

The component communicates with the sensor over UART at 256000 baud using the
LD2411S serial protocol. It is implemented as an ESPHome external_component (C++/Python)
and installed via a single external_components block in your ESPHome YAML -- no manual
file copying required.

Key behaviors:
- Binary presence sensor: detects stationary occupancy (someone sitting still).
- Binary motion sensor: detects active movement.
- Distance sensor: reports target distance in cm.
- Runtime zone config: motion zone min/max, presence zone min/max, and unoccupied
  timeout are exposed as Home Assistant number entities. Adjust sliders, press Apply
  Settings once -- no reflash needed.
- Bluetooth toggle: enable or disable the sensor's onboard BLE from Home Assistant
  without the HLKRadarTool app. Uses a two-phase commit sequence (End config to flash,
  then reboot inside a fresh config session). Toggling BT reboots the radar -- sensors
  are unavailable for a few seconds while it restarts.
- Radar reboot and factory reset buttons exposed as HA entities.
- OUT pin: hardwired to GND in LD2411S firmware V1.01 and cannot be used as a presence
  output. Do not connect it.

Hardware compatibility:
- Primary target: HLK-LD2411S
- Also works on HLK-LD2411 (same hardware, same firmware, same UART protocol -- the
  two are the same product sold under different model names for different markets).
- Tested on ESP32-WROOM-32 with ESPHome 2026.2.4 and ESP-IDF framework.
- Requires 5V on VIN -- the LD2411S will not produce UART output on 3.3V.

Known issues:
- The radar can lock up after rapid repeated zone adjustments. Fix: press the Reboot
  Radar button in Home Assistant. Best practice: adjust all zones, press Apply once,
  then leave it.

What this component is NOT:
- Not compatible with the LD2410, LD2410B, LD2410C, or LD2412 -- those are different
  sensors with different protocols. Use the esphome-hlk-ld2410 component for those.
- Not a standalone integration -- requires ESPHome and an ESP32 (or compatible) host.
- Not available in the official ESPHome component registry -- installed as an
  external_components source directly from this GitHub repository.

## Repositories

- [esphome-ld2411s (this repo)](https://github.com/DAB-LABS/esphome-ld2411s): Full
  component source, example YAML, wiring guide, and hardware research notes.

## Documentation

- [README](https://github.com/DAB-LABS/esphome-ld2411s/blob/main/README.md): Full
  installation and configuration guide, wiring diagram, zone configuration reference,
  Bluetooth toggle usage, crash diagnostics, and known issues.
- [example.yaml](https://github.com/DAB-LABS/esphome-ld2411s/blob/main/example.yaml):
  Complete ESPHome YAML with all sensors, runtime zone controls, diagnostic entities,
  radar control buttons, and Bluetooth toggle.

## Optional

- [LD2411 vs LD2411S Research](https://github.com/DAB-LABS/esphome-ld2411s/blob/main/docs/LD2411-vs-LD2411S-Research.md):
  Hardware comparison, firmware investigation, UART protocol reference, OUT pin
  behavior, and community findings. Relevant for contributors or users with LD2411
  boards.
- [DAB-LABS](https://github.com/DAB-LABS): Other open-source homelab and Home
  Assistant projects by the same author.