LD2412 BLE — Home Assistant custom integration

Connects the HLK-LD2412 24 GHz presence radar to Home Assistant directly over Bluetooth LE — no ESP32, no UART wiring. Designed as the companion to MassiPi/ld2450_ble: run both side by side and fuse them (like Apollo Automation's R_PRO-1 pairs the same two radars) with the separate hlk_radar_fusion package (LD2450 zones + LD2412 stillness backup).

⚠️ Status: implemented but not yet hardware-verified

This integration was built entirely from the official protocol PDF and proven sibling implementations (LD2410 BLE, LD2450 BLE, ESPHome LD2412). The parser is unit-tested against byte-exact frames from the protocol spec, but no physical LD2412 has been connected yet. Items marked VERIFY-ON-HARDWARE in the source must be confirmed with tools/ble_probe.py (a repo-root dev tool, not installed by HACS) before trusting it in production. See Hardware verification.

Entities

Platform	Entity	Notes
binary_sensor	Presence, Moving target, Still target	from every data frame
sensor	Moving/Still target distance (cm) & energy, Detection distance, Light level, Target state	light level requires engineering mode
sensor ×28	Motion/Static gate 0-13 energy	diagnostic, disabled by default, engineering mode only
switch	Engineering mode	streams per-gate energies
button	Reboot, Factory reset, Start background correction
button	Calibrate against current noise (60s), Restore pre-calibration sensitivities	see below
number	Calibration margin	safety margin above measured noise (default 10)
binary_sensor	Calibration running	diagnostic

The protocol library also implements set_basic_params, set_motion_sensitivity and set_static_sensitivity (14 gates); number/select entities for them are planned once ACK behaviour is confirmed on hardware.

Guided noise calibration

If a fan, curtain, or people behind a door/wall cause false positives: leave the monitored area (noise source still running) and press Calibrate against current noise. For 60 s the integration samples the per-gate energies in engineering mode (the sensor's normal ~10 Hz stream — no extra load), then raises each gate's sensitivity threshold to observed noise + margin. Thresholds are only ever raised, never lowered; quiet gates keep their previous values, and Restore pre-calibration sensitivities undoes the last run. This complements the sensor's built-in Start background correction (on-chip, black-box) with a margin-controlled, reversible alternative.

Installation (HACS custom repository)

1. HACS → Integrations → ⋮ → Custom repositories → add this repo URL, category Integration.
2. Install LD2412 BLE, restart Home Assistant.
3. The sensor should be auto-discovered. The manifest matches the advertised names HLK-LD2412* and HLK_LD2412* (the HLK family convention is HLK-<model>_<last-4-of-MAC>; the underscore variant is a speculative fallback pending hardware confirmation). If yours differs, adjust the bluetooth matchers in manifest.json; otherwise Settings → Devices & Services → Add integration → LD2412 BLE.

Requires a Bluetooth adapter on the HA host or an ESPHome Bluetooth proxy (active connections must be enabled; each radar holds one persistent connection and an ESP32 proxy sustains ~3).

Hardware verification

When a physical LD2412 is available (Arch/CachyOS laptop, BlueZ):

cd ld2412_ble
python -m venv .venv && .venv/bin/pip install bleak bleak-retry-connector pytest
.venv/bin/python tools/ble_probe.py scan               # confirm advertised name
.venv/bin/python tools/ble_probe.py probe <MAC>        # GATT layout, password, frames
.venv/bin/python tools/ble_probe.py probe <MAC> --engineering  # gate energies + light
.venv/bin/python -m pytest tests/ -v

Assumptions to confirm (all marked VERIFY-ON-HARDWARE in the source):

1. Advertised name is HLK-LD2412_xxxx → fix manifest.json matchers + const.py::LOCAL_NAMES if different.
2. GATT characteristics are 0000fff1 (notify) / 0000fff2 (write) as on LD2410/LD2450 → fix ld2412_ble/const.py if different.
3. BLE password: the probe reports whether data streams before the LD2410-style 0xA8 "HiLink" write. The integration sends it tolerantly either way.
4. Engineering frame tail: light level at frame offset 45 (per Rihan9); check the probe's UNPARSED/debug output for firmware-variant extra bytes.
5. Turn the saved capture in tests/fixtures/ into parser test fixtures.

Protocol sources

• HLK-LD2412 Serial Communication Protocol V1.05 (2024-08-08) — command set, frame formats (PDF)
• 930913/ld2410-ble — BLE GATT chars + password handshake (LD24xx family)
• MassiPi/ld2450_ble — integration architecture template
• Rihan9/LD2412 — frame byte offsets (now the official ESPHome ld2412 component)
• Tasmota discussion #21976 — confirms LD2412 works over BLE with the LD2410 command set; warns payloads vary between firmware versions (the parser is length-tolerant for this reason)