ld2410.h File Reference

HLK-LD2410 24 GHz mmWave presence / motion radar codec (DETWS_ENABLE_LD2410). More...

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Classes
struct	Ld2410State
	Target presence state (report payload byte 2). More...
struct	Ld2410Report
	A decoded LD2410 target report. Engineering fields are 0 unless engineering. More...
struct	Ld2410Stream
	Byte-by-byte report-frame reassembler (fixed buffer, resyncs on noise). More...

Macros
#define	LD2410_MAX_GATES   9
	Range gates the LD2410 reports energy for in engineering mode (gate 0..8).
#define	LD2410_FRAME_MAX   72
	Largest assembled frame: header(4) + len(2) + payload(<=60) + footer(4), rounded up.

Functions
bool	ld2410_parse_report (const uint8_t *frame, size_t len, Ld2410Report *out)
	Decode one whole LD2410 report frame (header F4 F3 F2 F1 .. footer F8 F7 F6 F5). Pure - no I/O. Validates the header/footer, the intra-frame length, the data-type byte (0x02 basic / 0x01 engineering), the 0xAA head marker and the 0x55 tail.
void	ld2410_stream_reset (Ld2410Stream *s)
	Reset a stream to the syncing state.
bool	ld2410_stream_push (Ld2410Stream *s, uint8_t byte, Ld2410Report *out)
	Feed one received byte. When it completes a valid report frame, fills out and returns true; otherwise returns false (still syncing / mid-frame / bad frame - it resyncs).
bool	ld2410_present (const Ld2410Report *r)
	true if r shows any target (moving or stationary).
uint16_t	ld2410_distance_cm (const Ld2410Report *r)
	Best available target distance (cm): the moving distance if moving, else stationary.
size_t	ld2410_cmd_config_enable (uint8_t *buf, size_t cap)
	"Enable configuration" (word 0x00FF, value 0x0001).
size_t	ld2410_cmd_config_end (uint8_t *buf, size_t cap)
	"End configuration" (word 0x00FE).
size_t	ld2410_cmd_engineering (uint8_t *buf, size_t cap, bool on)
	Enable (0x0062) or disable (0x0063) engineering mode.
size_t	ld2410_cmd_restart (uint8_t *buf, size_t cap)
	Restart the module (word 0x00A3).
bool	ld2410_begin (int rx_pin, int tx_pin)
	Open UART2 at DETWS_LD2410_BAUD on rx_pin / tx_pin.
bool	ld2410_poll ()
	Pump the UART through the stream.
const Ld2410Report *	ld2410_last ()
	The most recently decoded report, or nullptr before the first one arrives.
bool	ld2410_set_engineering (bool on)
	Enable/disable engineering mode (brackets the command with enable/end).
bool	ld2410_restart ()
	Restart the module (brackets the command with enable/end).

Detailed Description

HLK-LD2410 24 GHz mmWave presence / motion radar codec (DETWS_ENABLE_LD2410).

The LD2410 streams a framed serial report at 256000 baud: header F4 F3 F2 F1, a little-endian intra-frame length, the payload, and footer F8 F7 F6 F5. The payload carries the target state (none / moving / stationary / both), the moving and stationary target distance (cm) and energy (0-100), the overall detection distance, and - in "engineering mode" - the per-gate energy of all nine range gates. Configuration is a second frame kind (header FD FC FB FA, footer 04 03 02 01) carrying a 2-byte command word.

This codec is pure and host-tested: ld2410_parse_report decodes one report frame, and Ld2410Stream reassembles frames byte-by-byte from a UART with resync on noise (no heap, fixed buffer). The command encoders build the config frames. On an ESP32 the binding pumps a HardwareSerial and keeps the latest report; only that read/write touches hardware.

A cheap solder-and-bench-test breakout: wire it to a UART, wave a hand, watch presence.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file ld2410.h.

Macro Definition Documentation

LD2410_MAX_GATES

#define LD2410_MAX_GATES   9

Range gates the LD2410 reports energy for in engineering mode (gate 0..8).

Definition at line 33 of file ld2410.h.

LD2410_FRAME_MAX

#define LD2410_FRAME_MAX   72

Largest assembled frame: header(4) + len(2) + payload(<=60) + footer(4), rounded up.

Definition at line 36 of file ld2410.h.

Function Documentation

ld2410_parse_report()

bool ld2410_parse_report	(	const uint8_t *	frame,
		size_t	len,
		Ld2410Report *	out
	)

Decode one whole LD2410 report frame (header F4 F3 F2 F1 .. footer F8 F7 F6 F5). Pure - no I/O. Validates the header/footer, the intra-frame length, the data-type byte (0x02 basic / 0x01 engineering), the 0xAA head marker and the 0x55 tail.

Returns

true on a valid frame; false on any mismatch or a short buffer.

ld2410_stream_reset()

void ld2410_stream_reset

(

Ld2410Stream *

s

)

Reset a stream to the syncing state.

ld2410_stream_push()

bool ld2410_stream_push	(	Ld2410Stream *	s,
		uint8_t	byte,
		Ld2410Report *	out
	)

Feed one received byte. When it completes a valid report frame, fills out and returns true; otherwise returns false (still syncing / mid-frame / bad frame - it resyncs).

ld2410_present()

bool ld2410_present

(

const Ld2410Report *

r

)

true if r shows any target (moving or stationary).

ld2410_distance_cm()

uint16_t ld2410_distance_cm

(

const Ld2410Report *

r

)

Best available target distance (cm): the moving distance if moving, else stationary.

ld2410_cmd_config_enable()

size_t ld2410_cmd_config_enable	(	uint8_t *	buf,
		size_t	cap
	)

"Enable configuration" (word 0x00FF, value 0x0001).

ld2410_cmd_config_end()

size_t ld2410_cmd_config_end	(	uint8_t *	buf,
		size_t	cap
	)

"End configuration" (word 0x00FE).

ld2410_cmd_engineering()

size_t ld2410_cmd_engineering	(	uint8_t *	buf,
		size_t	cap,
		bool	on
	)

Enable (0x0062) or disable (0x0063) engineering mode.

ld2410_cmd_restart()

size_t ld2410_cmd_restart	(	uint8_t *	buf,
		size_t	cap
	)

Restart the module (word 0x00A3).

ld2410_begin()

bool ld2410_begin	(	int	rx_pin,
		int	tx_pin
	)

Open UART2 at DETWS_LD2410_BAUD on rx_pin / tx_pin.

Returns

true on ESP32.

ld2410_poll()

bool ld2410_poll

(

)

Pump the UART through the stream.

Returns

true if a fresh report was decoded.

ld2410_last()

const Ld2410Report * ld2410_last

(

)

The most recently decoded report, or nullptr before the first one arrives.

ld2410_set_engineering()

bool ld2410_set_engineering

(

bool

on

)

Enable/disable engineering mode (brackets the command with enable/end).

ld2410_restart()

bool ld2410_restart

(

)

Restart the module (brackets the command with enable/end).