ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
ld600x.h
Go to the documentation of this file.
1#pragma once
2
3// Shared base for the Hi-Link 60 GHz radars that speak the TinyFrame serial protocol: the LD6002B and
4// the LD6004. The LD6001A uses AT commands and another report format and is a separate component.
8#include "esphome/core/log.h"
12#ifdef USE_SENSOR
15#endif
16#ifdef USE_BINARY_SENSOR
18#endif
19#ifdef USE_TEXT_SENSOR
21#endif
22#ifdef USE_NUMBER
24#endif
25#ifdef USE_SELECT
27#endif
28#ifdef USE_SWITCH
30#endif
31
32#include <array>
33#include <cmath>
34
35namespace esphome::ld600x {
36
37static constexpr uint8_t AREA_COUNT = 4;
38// Interference areas own ids 0..AREA_COUNT-1 and detection areas the next four, so
39// this is the whole id space TYPE_SET_AREA accepts.
40static constexpr uint8_t AREA_ID_COUNT = AREA_COUNT * LD600X_AREA_KINDS;
41static constexpr uint16_t DEFAULT_MAX_DATA_LEN = 1024;
42static constexpr uint16_t DEFAULT_MAX_DATA_LEN_POINT_CLOUD = 4096;
43// Largest protocol payload is TYPE_SET_AREA: int32 area id + 6 floats = 28 bytes.
44static constexpr size_t CMD_MAX_DATA_LEN = 28;
45
46static constexpr uint8_t LD600X_MODEL_KIND_BASE = 0x80;
47
58
74
75#ifdef USE_SENSOR
77 sensor::Sensor *x{nullptr};
78 sensor::Sensor *y{nullptr};
79 sensor::Sensor *z{nullptr};
81 // A cluster id names a person, so like the counts it is published on change, not per frame.
83};
84
85// Indexed by AreaAxis.
86using AreaSensors = std::array<sensor::Sensor *, AREA_AXIS_COUNT>;
87#endif
88
89// Index of one area in the tables that hold every area of every kind.
90static constexpr uint8_t area_index(uint8_t kind, uint8_t area) { return kind * AREA_COUNT + area; }
91
92struct AreaConfig {
93 float x_min{NAN};
94 float x_max{NAN};
95 float y_min{NAN};
96 float y_max{NAN};
97 float z_min{NAN};
98 float z_max{NAN};
99};
100
102 char value[20];
103};
104
106 public:
107 // The tag comes from LOG_STR, so it stays in flash on ESP8266 like an ESPHOME_LOG_TAG. It keeps the
108 // model's own name on every log line, so a logger `logs:` filter on `ld6002b` keeps working.
109 explicit LD600XComponent(const LogString *log_tag) : log_tag_(LOG_STR_ARG(log_tag)) {}
110
111 void setup() override;
112 void loop() override;
113 void dump_config() override;
114
115#ifdef USE_SENSOR
117 SUB_SENSOR_WITH_DEDUP(point_count, uint32_t)
118
119 void set_target_x_sensor(uint8_t target, sensor::Sensor *sensor) {
120 if (target >= LD600X_MAX_TARGETS)
121 return;
122 this->targets_[target].x = sensor;
123 }
125 if (target >= LD600X_MAX_TARGETS)
126 return;
127 this->targets_[target].y = sensor;
128 }
130 if (target >= LD600X_MAX_TARGETS)
131 return;
132 this->targets_[target].z = sensor;
133 }
135 if (target >= LD600X_MAX_TARGETS)
136 return;
137 this->targets_[target].dop_idx = sensor;
138 }
140 if (target >= LD600X_MAX_TARGETS)
141 return;
142 this->targets_[target].cluster_id.set_sensor(sensor);
143 }
144 void set_area_sensor(uint8_t kind, uint8_t area, uint8_t axis, sensor::Sensor *sensor) {
145 if (kind < LD600X_AREA_KINDS && area < AREA_COUNT && axis < AREA_AXIS_COUNT)
146 this->areas_[area_index(kind, area)][axis] = sensor;
147 }
148#endif
149
150#ifdef USE_BINARY_SENSOR
152 void set_target_presence_binary_sensor(uint8_t target, binary_sensor::BinarySensor *sensor) {
153 if (target >= LD600X_MAX_TARGETS)
154 return;
155 this->target_presence_[target] = sensor;
156 }
158 if (area >= AREA_COUNT)
159 return;
160 this->area_presence_[area] = sensor;
161 }
162#endif
163
164#ifdef USE_TEXT_SENSOR
165 SUB_TEXT_SENSOR(work_mode)
166 SUB_TEXT_SENSOR(ota_version)
167#endif
168
169#ifdef USE_NUMBER
170 SUB_NUMBER(hold_delay)
171 SUB_NUMBER(z_min)
172 SUB_NUMBER(z_max)
173 SUB_NUMBER(low_power_sleep)
174
175 SUB_NUMBER(area_x_min)
176 SUB_NUMBER(area_x_max)
177 SUB_NUMBER(area_y_min)
178 SUB_NUMBER(area_y_max)
179 SUB_NUMBER(area_z_min)
180 SUB_NUMBER(area_z_max)
181#endif
182
183#ifdef USE_SELECT
184 SUB_SELECT(sensitivity)
185 SUB_SELECT(trigger_speed)
186 SUB_SELECT(installation)
187 SUB_SELECT(area_id)
188#endif
189
190#ifdef USE_SWITCH
191 SUB_SWITCH(point_cloud)
192 SUB_SWITCH(target_display)
193#endif
194
195 // Each setter picks its setting by entity pointer, so the entities share one generated class. A model
196 // with its own entities handles those first and passes the rest down.
197#ifdef USE_NUMBER
198 // Returns false when the value was rejected or its command not queued, so the number keeps its old value.
199 virtual bool set_number_value(number::Number *entity, float value);
200#endif
201#ifdef USE_SELECT
202 // Returns false when the command was not queued, so the select keeps its old option.
203 virtual bool set_select_value(select::Select *entity, size_t index);
204#endif
205#ifdef USE_SWITCH
206 // Returns false when the command was not queued, so the switch keeps its old state.
207 virtual bool set_switch_state(switch_::Switch *entity, bool state);
208#endif
209#ifdef USE_BUTTON
210 virtual void press_button(uint8_t kind);
211#endif
212
213 protected:
214 virtual bool handle_model_report(uint16_t type, const uint8_t *data, uint16_t len) { return false; }
215 // Whether one of the model's own entities reads the target stream, so boot switches it on.
216 virtual bool model_wants_target_stream() const { return false; }
217 // Called after every target or area presence report and whenever target presence is cleared.
218 virtual void on_presence_update() {}
219 // Lets the model hold a frame back (for example to wake the module first) and write it later with
220 // write_frame_(). Returns true when it took the frame.
221 virtual bool defer_frame_write(uint16_t type, const uint8_t *data, uint8_t len, bool track) { return false; }
222 virtual void setup_model() {}
223 virtual void dump_model_config() {}
224
225 const char *log_tag_;
226
228 uint16_t type{0};
229 uint8_t len{0};
230 std::array<uint8_t, CMD_MAX_DATA_LEN> data{};
231 };
232
233 void handle_frame_(uint16_t type, const uint8_t *data, uint16_t len);
234 void handle_target_report_(const uint8_t *data, uint16_t len);
235 void handle_point_cloud_(const uint8_t *data, uint16_t len);
236 void handle_area_presence_(const uint8_t *data, uint16_t len);
237 void handle_area_report_(uint8_t kind, const uint8_t *data, uint16_t len);
238 void handle_delay_report_(const uint8_t *data, uint16_t len);
239 void handle_sensitivity_report_(const uint8_t *data, uint16_t len);
240 void handle_trigger_speed_report_(const uint8_t *data, uint16_t len);
241 void handle_z_range_report_(const uint8_t *data, uint16_t len);
242 void handle_installation_report_(const uint8_t *data, uint16_t len);
243 void handle_low_power_sleep_report_(const uint8_t *data, uint16_t len);
244 void handle_version_report_(const uint8_t *data, uint16_t len);
245 // Drops every target-derived reading and the slot table they are indexed by.
246 void clear_target_state_();
250#ifdef USE_SENSOR
251 void clear_target_slot_(uint8_t index);
252#endif
253#ifdef USE_NUMBER
254 void publish_number_clamped_(number::Number *number, float value);
255#endif
256 void update_area_numbers_(const AreaConfig &area);
257 void update_area_numbers_for_id_(uint8_t area_id);
258 bool queue_area_config_(uint8_t area_id, const AreaConfig &desired);
259 void try_apply_pending_area_(uint8_t reported_kind);
260 void init_area_id_pref_();
261 void save_area_id_pref_(uint8_t value);
262 void init_version_pref_();
263 void save_version_pref_(const char *value);
264
265 // Returns whether the command was queued: it is dropped, with a log line, when
266 // the payload is too long or the ring is full.
267 bool queue_command_(uint16_t type, const uint8_t *data, uint8_t len);
269 void send_command_(uint16_t type, const uint8_t *data, uint8_t len);
270 void send_command_internal_(uint16_t type, const uint8_t *data, uint8_t len, bool track);
271 void write_frame_(uint16_t type, const uint8_t *data, uint8_t len, bool track);
272 // Returns whether the command reached the queue; see queue_command_.
273 bool send_control_command_(uint32_t command);
274 // Writes the candidate range; the caller stores it only on true. Returns false when it was not
275 // queued: crossed bounds or a full queue. A bound held until the other one is known counts as accepted.
276 bool send_z_range_(float z_min, float z_max);
277#ifdef USE_NUMBER
278 // Writes a whole-number setting as a uint32; returns false for a fractional value or a full queue.
279 bool queue_u32_setting_(uint16_t type, float value);
280#endif
281 void apply_area_config_();
282
283#ifdef USE_SENSOR
284 std::array<TargetSensors, LD600X_MAX_TARGETS> targets_{};
285 std::array<AreaSensors, AREA_COUNT * LD600X_AREA_KINDS> areas_{};
286#endif
287#ifdef USE_BINARY_SENSOR
288 std::array<binary_sensor::BinarySensor *, LD600X_MAX_TARGETS> target_presence_{};
289 std::array<binary_sensor::BinarySensor *, AREA_COUNT> area_presence_{};
290#endif
291#ifdef USE_TEXT_SENSOR
294#endif
295#ifdef USE_SELECT
298#endif
299
301 uint16_t next_frame_id_{0};
302
303 // Sized for the two bursts that reach it, both counted as what is still queued
304 // once the first command is dequeued: boot leaves 11 with every platform
305 // configured, and pressing all fourteen buttons before an ack lands leaves 15.
306 // Neither overflowed 16, but one free slot is not headroom, and overflowing is a
307 // dropped command with only a log line to show for it. Costs 256 bytes more per
308 // configured instance, and this component is MULTI_CONF.
309 static constexpr uint8_t CMD_QUEUE_SIZE = 24;
310 static constexpr uint32_t CMD_ACK_TIMEOUT_MS = 300;
311 // A sleeping module consumes the first frame to wake and answers only the one after it.
312 static constexpr uint32_t CMD_FIRST_ACK_TIMEOUT_MS = 600;
313 // How long the module stays awake after any frame, and so still answers the next one.
314 static constexpr uint32_t MODULE_AWAKE_MS = 10000;
315 static constexpr uint8_t CMD_MAX_RETRIES = 3;
316 // Free for one keyed timer of the model's own.
317 static constexpr uint32_t MODEL_TIMEOUT_ID = 0;
318 // Keyed so a burst of writes collapses to one read once they settle, rather than
319 // one read per write.
320 static constexpr uint32_t AREA_REFRESH_TIMEOUT_ID = 1;
321 // A reply cannot trail the frame that earned it for longer than this; the field worst case is ~726ms.
322 static constexpr uint32_t STALE_ACK_MAX_AGE_MS = 1000;
323
325 bool command_active_{false};
326 bool command_sent_{false};
328 uint8_t retries_left_{0};
330 // Last frame seen in either direction; any traffic keeps the module awake.
332 // Frames transmitted for the command in flight, including retries; drives the retry budget.
333 uint8_t attempts_sent_{0};
334 // Subset of those the module can actually answer: a frame that woke it is consumed, not replied to.
335 uint8_t acks_expected_{0};
336 // ACKs still owed for superseded attempts; they carry no id, only their arrival order.
337 uint16_t stale_ack_type_{0};
339 // When that debt was booked, so a debt no reply can still settle expires instead of eating a live ACK.
341 // Bumped whenever the active command changes, so a deferred send can tell it was retired.
343
344 float z_min_{NAN};
345 float z_max_{NAN};
346 float area_x_min_{NAN};
347 float area_x_max_{NAN};
348 float area_y_min_{NAN};
349 float area_y_max_{NAN};
350 float area_z_min_{NAN};
351 float area_z_max_{NAN};
352 // What the user has typed and not yet applied; NaN per axis means "nothing of
353 // mine here, take the module's value". Same sentinel shape as
354 // pending_area_updates_. Exactly two things empty it: the area_id select moving
355 // to another area, and an apply that was accepted. A write the bounds guard
356 // refused leaves it alone, and a deferred apply that had to be dropped hands its
357 // staged values back here -- but only while the user is still on the area they
358 // were staged for. Either way the values stay the user's to fix.
360 std::array<AreaConfig, AREA_COUNT * LD600X_AREA_KINDS> area_values_{};
361 uint8_t area_id_{0xFF};
362 bool area_id_set_{false};
363
364 // Which person owns each target_N slot, so a slot survives the module re-sorting its array.
365 std::array<int32_t, LD600X_MAX_TARGETS> slot_cluster_{};
366 std::array<bool, LD600X_MAX_TARGETS> slot_occupied_{};
367
369 // What the switches and setup asked the module for, which is not the same as
370 // what it is doing yet: a stream keeps sending until it acts on the command.
371 // The report handlers read these and drop anything a stopped stream still emits.
377 uint8_t pending_area_id_{0xFF};
379
380#ifdef USE_SENSOR
381 std::array<bool, LD600X_MAX_TARGETS> last_target_presence_{}; // one-shot NAN clear for target sensors
382#endif
383};
384
385} // namespace esphome::ld600x
Fixed-size circular buffer with FIFO semantics and iteration support.
Definition helpers.h:408
Base class for all binary_sensor-type classes.
static constexpr uint8_t CMD_MAX_RETRIES
Definition ld600x.h:315
bool queue_u32_setting_(uint16_t type, float value)
Definition ld600x.cpp:967
PendingCommand active_command_
Definition ld600x.h:327
void set_target_y_sensor(uint8_t target, sensor::Sensor *sensor)
Definition ld600x.h:124
void set_area_presence_binary_sensor(uint8_t area, binary_sensor::BinarySensor *sensor)
Definition ld600x.h:157
static constexpr uint32_t CMD_ACK_TIMEOUT_MS
Definition ld600x.h:310
void update_area_numbers_for_id_(uint8_t area_id)
Definition ld600x.cpp:1127
std::array< AreaConfig, AREA_COUNT *LD600X_AREA_KINDS > area_values_
Definition ld600x.h:360
bool queue_area_config_(uint8_t area_id, const AreaConfig &desired)
Definition ld600x.cpp:1136
std::array< int32_t, LD600X_MAX_TARGETS > slot_cluster_
Definition ld600x.h:365
bool send_z_range_(float z_min, float z_max)
Definition ld600x.cpp:949
LD600XComponent(const LogString *log_tag)
Definition ld600x.h:109
void handle_sensitivity_report_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:690
void handle_z_range_report_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:716
uint32_t void set_target_x_sensor(uint8_t target, sensor::Sensor *sensor)
Definition ld600x.h:119
virtual bool set_switch_state(switch_::Switch *entity, bool state)
Definition ld600x.cpp:1391
void write_frame_(uint16_t type, const uint8_t *data, uint8_t len, bool track)
Definition ld600x.cpp:924
SUB_SENSOR_WITH_DEDUP(target_count, uint32_t) SUB_SENSOR_WITH_DEDUP(point_count
virtual void press_button(uint8_t kind)
Definition ld600x.cpp:1417
void handle_low_power_sleep_report_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:742
virtual bool model_wants_target_stream() const
Definition ld600x.h:216
SUB_BINARY_SENSOR(presence) void set_target_presence_binary_sensor(uint8_t target
void set_target_dop_idx_sensor(uint8_t target, sensor::Sensor *sensor)
Definition ld600x.h:134
static constexpr uint32_t AREA_REFRESH_TIMEOUT_ID
Definition ld600x.h:320
std::array< bool, LD600X_MAX_TARGETS > slot_occupied_
Definition ld600x.h:366
void handle_trigger_speed_report_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:703
std::array< bool, LD600X_MAX_TARGETS > last_target_presence_
Definition ld600x.h:381
std::array< AreaSensors, AREA_COUNT *LD600X_AREA_KINDS > areas_
Definition ld600x.h:285
virtual bool defer_frame_write(uint16_t type, const uint8_t *data, uint8_t len, bool track)
Definition ld600x.h:221
void clear_target_slot_(uint8_t index)
Definition ld600x.cpp:1281
bool queue_command_(uint16_t type, const uint8_t *data, uint8_t len)
Definition ld600x.cpp:799
void handle_area_presence_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:622
void set_target_z_sensor(uint8_t target, sensor::Sensor *sensor)
Definition ld600x.h:129
static constexpr uint32_t STALE_ACK_MAX_AGE_MS
Definition ld600x.h:322
void update_area_numbers_(const AreaConfig &area)
Definition ld600x.cpp:1094
void handle_target_report_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:507
void try_apply_pending_area_(uint8_t reported_kind)
Definition ld600x.cpp:1175
void handle_version_report_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:778
void handle_point_cloud_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:604
void publish_number_clamped_(number::Number *number, float value)
Definition ld600x.cpp:752
virtual bool handle_model_report(uint16_t type, const uint8_t *data, uint16_t len)
Definition ld600x.h:214
StaticRingBuffer< PendingCommand, CMD_QUEUE_SIZE > cmd_queue_
Definition ld600x.h:324
void set_area_sensor(uint8_t kind, uint8_t area, uint8_t axis, sensor::Sensor *sensor)
Definition ld600x.h:144
binary_sensor::BinarySensor * sensor
Definition ld600x.h:152
std::array< binary_sensor::BinarySensor *, AREA_COUNT > area_presence_
Definition ld600x.h:289
void handle_installation_report_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:729
virtual void on_presence_update()
Definition ld600x.h:218
void set_target_cluster_id_sensor(uint8_t target, sensor::Sensor *sensor)
Definition ld600x.h:139
std::array< TargetSensors, LD600X_MAX_TARGETS > targets_
Definition ld600x.h:284
void handle_area_report_(uint8_t kind, const uint8_t *data, uint16_t len)
Definition ld600x.cpp:644
static constexpr uint32_t CMD_FIRST_ACK_TIMEOUT_MS
Definition ld600x.h:312
void handle_frame_(uint16_t type, const uint8_t *data, uint16_t len)
Definition ld600x.cpp:414
virtual void dump_model_config()
Definition ld600x.h:223
ESPPreferenceObject version_pref_
Definition ld600x.h:292
ESPPreferenceObject area_id_pref_
Definition ld600x.h:296
void send_command_internal_(uint16_t type, const uint8_t *data, uint8_t len, bool track)
Definition ld600x.cpp:907
bool send_control_command_(uint32_t command)
Definition ld600x.cpp:943
static constexpr uint32_t MODEL_TIMEOUT_ID
Definition ld600x.h:317
virtual SUB_TEXT_SENSOR(work_mode) SUB_TEXT_SENSOR(ota_version) SUB_NUMBER(hold_delay) SUB_NUMBER(z_min) SUB_NUMBER(z_max) SUB_NUMBER(low_power_sleep) SUB_NUMBER(area_x_min) SUB_NUMBER(area_x_max) SUB_NUMBER(area_y_min) SUB_NUMBER(area_y_max) SUB_NUMBER(area_z_min) SUB_NUMBER(area_z_max) SUB_SELECT(sensitivity) SUB_SELECT(trigger_speed) SUB_SELECT(installation) SUB_SELECT(area_id) SUB_SWITCH(point_cloud) SUB_SWITCH(target_display) virtual bool set_number_value(number bool set_select_value(select::Select *entity, size_t index)
Definition ld600x.cpp:1078
static constexpr uint8_t CMD_QUEUE_SIZE
Definition ld600x.h:309
void handle_delay_report_(const uint8_t *data, uint16_t len)
Definition ld600x.cpp:681
static constexpr uint32_t MODULE_AWAKE_MS
Definition ld600x.h:314
void save_version_pref_(const char *value)
Definition ld600x.cpp:1268
void send_command_(uint16_t type, const uint8_t *data, uint8_t len)
Definition ld600x.cpp:903
void save_area_id_pref_(uint8_t value)
Definition ld600x.cpp:1243
Base-class for all numbers.
Definition number.h:29
Base-class for all selects.
Definition select.h:28
Base-class for all sensors.
Definition sensor.h:48
A sensor pointer that may be null plus the last value it published, stored inline.
Base class for all switches.
Definition switch.h:43
uint8_t type
bool state
Definition fan.h:2
@ AREA_KIND_DETECTION
Definition ld600x.h:48
@ AREA_KIND_INTERFERENCE
Definition ld600x.h:48
@ BUTTON_GET_LOW_POWER_MODE
Definition ld600x.h:70
@ BUTTON_CLEAR_INTERFERENCE
Definition ld600x.h:63
@ BUTTON_GET_Z_RANGE
Definition ld600x.h:68
@ BUTTON_GET_TRIGGER_SPEED
Definition ld600x.h:67
@ BUTTON_AUTO_INTERFERENCE
Definition ld600x.h:61
@ BUTTON_GET_LOW_POWER_SLEEP_TIME
Definition ld600x.h:71
@ BUTTON_RESET_UNATTENDED
Definition ld600x.h:72
@ BUTTON_RESET_DETECTION_AREA
Definition ld600x.h:64
@ BUTTON_GET_INSTALLATION
Definition ld600x.h:69
@ BUTTON_GET_SENSITIVITY
Definition ld600x.h:66
@ BUTTON_APPLY_AREA
Definition ld600x.h:60
std::array< sensor::Sensor *, AREA_AXIS_COUNT > AreaSensors
Definition ld600x.h:86
uint32_t value
Definition hal.cpp:41
const void size_t len
Definition hal.h:68
static void uint32_t
std::array< uint8_t, CMD_MAX_DATA_LEN > data
Definition ld600x.h:230
sensor::Sensor * dop_idx
Definition ld600x.h:80
sensor::SensorWithDedup< int32_t > cluster_id
Definition ld600x.h:82