ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
vl53l0x_sensor.cpp
Go to the documentation of this file.
1#include "vl53l0x_sensor.h"
2#include "esphome/core/log.h"
3
4#include <algorithm>
5#include <cinttypes>
6
7/*
8 * Most of the code in this integration is based on the VL53L0x library
9 * by Pololu (Pololu Corporation), which in turn is based on the VL53L0X
10 * API from ST.
11 *
12 * For more information about licensing, please view the included LICENSE.txt file
13 * in the vl53l0x integration directory.
14 */
15
17
18ESPHOME_LOG_TAG(TAG, "vl53l0x");
19
20std::list<VL53L0XSensor *> VL53L0XSensor::vl53_sensors; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
21bool VL53L0XSensor::enable_pin_setup_complete = false; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
22
24
26 LOG_SENSOR("", "VL53L0X", this);
27 LOG_UPDATE_INTERVAL(this);
28 LOG_I2C_DEVICE(this);
29 if (this->enable_pin_ != nullptr) {
30 LOG_PIN(" Enable Pin: ", this->enable_pin_);
31 }
32 ESP_LOGCONFIG(TAG,
33 " Timeout: %" PRIu32 "%s\n"
34 " Timing Budget %" PRIu32 "us ",
35 this->timeout_us_, this->timeout_us_ > 0 ? LOG_STR_LITERAL("us") : LOG_STR_LITERAL(" (no timeout)"),
37}
38
41 for (auto &vl53_sensor : vl53_sensors) {
42 if (vl53_sensor->enable_pin_ != nullptr) {
43 // Set enable pin as OUTPUT and disable the enable pin to force vl53 to HW Standby mode
44 vl53_sensor->enable_pin_->setup();
45 vl53_sensor->enable_pin_->digital_write(false);
46 }
47 }
49 }
50
51 if (this->enable_pin_ != nullptr) {
52 // Enable the enable pin to cause FW boot (to get back to 0x29 default address)
53 this->enable_pin_->digital_write(true);
55 }
56
57 // Save the i2c address we want and force it to use the default 0x29
58 // until we finish setup, then re-address to final desired address.
59 uint8_t final_address = address_;
60 this->set_i2c_address(0x29);
61
62 reg(0x89) |= 0x01;
63 reg(0x88) = 0x00;
64
65 reg(0x80) = 0x01;
66 reg(0xFF) = 0x01;
67 reg(0x00) = 0x00;
68 this->stop_variable_ = reg(0x91).get();
69
70 reg(0x00) = 0x01;
71 reg(0xFF) = 0x00;
72 reg(0x80) = 0x00;
73 reg(0x60) |= 0x12;
74 if (this->long_range_)
75 this->signal_rate_limit_ = 0.1;
76 auto rate_value = static_cast<uint16_t>(signal_rate_limit_ * 128);
77 write_byte_16(0x44, rate_value);
78
79 reg(0x01) = 0xFF;
80
81 // getSpadInfo()
82 reg(0x80) = 0x01;
83 reg(0xFF) = 0x01;
84 reg(0x00) = 0x00;
85 reg(0xFF) = 0x06;
86 reg(0x83) |= 0x04;
87 reg(0xFF) = 0x07;
88 reg(0x81) = 0x01;
89 reg(0x80) = 0x01;
90 reg(0x94) = 0x6B;
91 reg(0x83) = 0x00;
92
93 uint32_t timeout_start_us = micros();
94 while (reg(0x83).get() == 0x00) {
95 if (this->timeout_us_ > 0 && (micros() - timeout_start_us > this->timeout_us_)) {
96 ESP_LOGE(TAG, "'%s' - setup timeout", LOG_STR_ARG(this->get_log_name()));
97 this->mark_failed();
98 return;
99 }
100 yield();
101 }
102
103 reg(0x83) = 0x01;
104 uint8_t tmp = reg(0x92).get();
105 uint8_t spad_count = tmp & 0x7F;
106 bool spad_type_is_aperture = tmp & 0x80;
107
108 reg(0x81) = 0x00;
109 reg(0xFF) = 0x06;
110 reg(0x83) &= ~0x04;
111 reg(0xFF) = 0x01;
112 reg(0x00) = 0x01;
113 reg(0xFF) = 0x00;
114 reg(0x80) = 0x00;
115
116 uint8_t ref_spad_map[6] = {};
117 this->read_bytes(0xB0, ref_spad_map, 6);
118
119 reg(0xFF) = 0x01;
120 reg(0x4F) = 0x00;
121 reg(0x4E) = 0x2C;
122 reg(0xFF) = 0x00;
123 reg(0xB6) = 0xB4;
124
125 uint8_t first_spad_to_enable = spad_type_is_aperture ? 12 : 0;
126 uint8_t spads_enabled = 0;
127 for (int i = 0; i < 48; i++) {
128 uint8_t &val = ref_spad_map[i / 8];
129 uint8_t mask = 1 << (i % 8);
130
131 if (i < first_spad_to_enable || spads_enabled == spad_count) {
132 val &= ~mask;
133 } else if (val & mask) {
134 spads_enabled += 1;
135 }
136 }
137
138 this->write_bytes(0xB0, ref_spad_map, 6);
139
140 reg(0xFF) = 0x01;
141 reg(0x00) = 0x00;
142 reg(0xFF) = 0x00;
143 reg(0x09) = 0x00;
144 reg(0x10) = 0x00;
145 reg(0x11) = 0x00;
146 reg(0x24) = 0x01;
147 reg(0x25) = 0xFF;
148 reg(0x75) = 0x00;
149 reg(0xFF) = 0x01;
150 reg(0x4E) = 0x2C;
151 reg(0x48) = 0x00;
152 reg(0x30) = 0x20;
153 reg(0xFF) = 0x00;
154 if (this->long_range_) {
155 reg(0x30) = 0x07; // WAS 0x09
156 } else {
157 reg(0x30) = 0x09;
158 }
159 reg(0x54) = 0x00;
160 reg(0x31) = 0x04;
161 reg(0x32) = 0x03;
162 reg(0x40) = 0x83;
163 reg(0x46) = 0x25;
164 reg(0x60) = 0x00;
165 reg(0x27) = 0x00;
166 reg(0x50) = 0x06;
167 reg(0x51) = 0x00;
168 reg(0x52) = 0x96;
169 reg(0x56) = 0x08;
170 if (this->long_range_) {
171 reg(0x57) = 0x50; // was 0x30
172 } else {
173 reg(0x57) = 0x30;
174 }
175 reg(0x61) = 0x00;
176 reg(0x62) = 0x00;
177 reg(0x64) = 0x00;
178 reg(0x65) = 0x00;
179 reg(0x66) = 0xA0;
180 reg(0xFF) = 0x01;
181 reg(0x22) = 0x32;
182 reg(0x47) = 0x14;
183 reg(0x49) = 0xFF;
184 reg(0x4A) = 0x00;
185 reg(0xFF) = 0x00;
186 reg(0x7A) = 0x0A;
187 reg(0x7B) = 0x00;
188 reg(0x78) = 0x21;
189 reg(0xFF) = 0x01;
190 reg(0x23) = 0x34;
191 reg(0x42) = 0x00;
192 reg(0x44) = 0xFF;
193 reg(0x45) = 0x26;
194 reg(0x46) = 0x05;
195 reg(0x40) = 0x40;
196 reg(0x0E) = 0x06;
197 reg(0x20) = 0x1A;
198 reg(0x43) = 0x40;
199 reg(0xFF) = 0x00;
200 reg(0x34) = 0x03;
201 reg(0x35) = 0x44;
202 reg(0xFF) = 0x01;
203 reg(0x31) = 0x04;
204 reg(0x4B) = 0x09;
205 reg(0x4C) = 0x05;
206 reg(0x4D) = 0x04;
207 reg(0xFF) = 0x00;
208 reg(0x44) = 0x00;
209 reg(0x45) = 0x20;
210 reg(0x47) = 0x08;
211 if (this->long_range_) {
212 reg(0x48) = 0x48; // was 0x28
213 } else {
214 reg(0x48) = 0x28;
215 }
216 reg(0x67) = 0x00;
217 reg(0x70) = 0x04;
218 reg(0x71) = 0x01;
219 reg(0x72) = 0xFE;
220 reg(0x76) = 0x00;
221 reg(0x77) = 0x00;
222 reg(0xFF) = 0x01;
223 reg(0x0D) = 0x01;
224 reg(0xFF) = 0x00;
225 reg(0x80) = 0x01;
226 reg(0x01) = 0xF8;
227 reg(0xFF) = 0x01;
228 reg(0x8E) = 0x01;
229 reg(0x00) = 0x01;
230 reg(0xFF) = 0x00;
231 reg(0x80) = 0x00;
232
233 reg(0x0A) = 0x04;
234 reg(0x84) &= ~0x10;
235 reg(0x0B) = 0x01;
236
237 if (this->measurement_timing_budget_us_ == 0) {
239 }
240
241 reg(0x01) = 0xE8;
243 reg(0x01) = 0x01;
244
246 ESP_LOGW(TAG, "1st reference calibration failed!");
247 this->mark_failed();
248 return;
249 }
250 reg(0x01) = 0x02;
252 ESP_LOGW(TAG, "2nd reference calibration failed!");
253 this->mark_failed();
254 return;
255 }
256 reg(0x01) = 0xE8;
257
258 // Set the sensor to the desired final address
259 // The following is different for VL53L0X vs VL53L1X
260 // I2C_SXXXX_DEVICE_ADDRESS = 0x8A for VL53L0X
261 // I2C_SXXXX__DEVICE_ADDRESS = 0x0001 for VL53L1X
262 reg(0x8A) = final_address & 0x7F;
263 this->set_i2c_address(final_address);
264}
265
267 if (this->initiated_read_ || this->waiting_for_interrupt_) {
268 this->publish_state(NAN);
269 this->status_momentary_warning(5000);
270 ESP_LOGW(TAG, "%s - update called before prior reading complete - initiated:%d waiting_for_interrupt:%d",
271 LOG_STR_ARG(this->get_log_name()), this->initiated_read_, this->waiting_for_interrupt_);
272 // A measurement gets its timing budget plus one more interval; one still pending after that is stalled
273 const uint32_t interval_ms = std::max<uint32_t>(this->get_update_interval(), 1);
274 const uint32_t grace = std::min<uint32_t>(this->measurement_timing_budget_us_ / 1000 / interval_ms + 1, UINT8_MAX);
275 if (this->pending_updates_ < grace) {
276 this->pending_updates_++;
277 return;
278 }
279 reg(0x0B) = 0x01;
280 }
281 this->pending_updates_ = 0;
282
283 // initiate single shot measurement
284 reg(0x80) = 0x01;
285 reg(0xFF) = 0x01;
286
287 reg(0x00) = 0x00;
288 reg(0x91) = this->stop_variable_;
289 reg(0x00) = 0x01;
290 reg(0xFF) = 0x00;
291 reg(0x80) = 0x00;
292
293 reg(0x00) = 0x01;
294 this->waiting_for_interrupt_ = false;
295 this->initiated_read_ = true;
296 // wait for timeout
297}
298
300 // A failed read must not advance the state: it reads as 0, which looks like a finished measurement
301 uint8_t value;
302 if (this->initiated_read_) {
303 if (!this->read_byte(0x00, &value))
304 return;
305 if (!(value & 0x01)) {
306 // done
307 // wait until reg(0x13) & 0x07 is set
308 this->initiated_read_ = false;
309 this->waiting_for_interrupt_ = true;
310 }
311 }
312 if (this->waiting_for_interrupt_) {
313 if (!this->read_byte(0x13, &value))
314 return;
315 if (value & 0x07) {
316 uint16_t range_mm = 0;
317 const bool ok = this->read_byte_16(0x14 + 10, &range_mm);
318 reg(0x0B) = 0x01;
319 this->waiting_for_interrupt_ = false;
320 if (!ok) {
321 this->publish_state(NAN);
322 this->status_momentary_warning(5000);
323 return;
324 }
325
326 if (range_mm >= 8190) {
327 ESP_LOGD(TAG, "'%s' - Distance is out of range, please move the target closer",
328 LOG_STR_ARG(this->get_log_name()));
329 this->publish_state(NAN);
330 return;
331 }
332
333 float range_m = range_mm / 1e3f;
334 ESP_LOGD(TAG, "'%s' - Got distance %.3f m", LOG_STR_ARG(this->get_log_name()), range_m);
335 this->publish_state(range_m);
336 }
337 }
338}
339
341 SequenceStepEnables enables{};
342 SequenceStepTimeouts timeouts{};
343
344 uint16_t start_overhead = 1910;
345 uint16_t end_overhead = 960;
346 uint16_t msrc_overhead = 660;
347 uint16_t tcc_overhead = 590;
348 uint16_t dss_overhead = 690;
349 uint16_t pre_range_overhead = 660;
350 uint16_t final_range_overhead = 550;
351
352 // "Start and end overhead times always present"
353 uint32_t budget_us = start_overhead + end_overhead;
354
356 get_sequence_step_timeouts_(&enables, &timeouts);
357
358 if (enables.tcc)
359 budget_us += (timeouts.msrc_dss_tcc_us + tcc_overhead);
360
361 if (enables.dss) {
362 budget_us += 2 * (timeouts.msrc_dss_tcc_us + dss_overhead);
363 } else if (enables.msrc) {
364 budget_us += (timeouts.msrc_dss_tcc_us + msrc_overhead);
365 }
366
367 if (enables.pre_range)
368 budget_us += (timeouts.pre_range_us + pre_range_overhead);
369
370 if (enables.final_range)
371 budget_us += (timeouts.final_range_us + final_range_overhead);
372
373 measurement_timing_budget_us_ = budget_us; // store for internal reuse
374 return budget_us;
375}
376
378 SequenceStepEnables enables{};
379 SequenceStepTimeouts timeouts{};
380
381 uint16_t start_overhead = 1320; // note that this is different than the value in get_
382 uint16_t end_overhead = 960;
383 uint16_t msrc_overhead = 660;
384 uint16_t tcc_overhead = 590;
385 uint16_t dss_overhead = 690;
386 uint16_t pre_range_overhead = 660;
387 uint16_t final_range_overhead = 550;
388
389 uint32_t min_timing_budget = 20000;
390
391 if (budget_us < min_timing_budget) {
392 return false;
393 }
394
395 uint32_t used_budget_us = start_overhead + end_overhead;
396
398 get_sequence_step_timeouts_(&enables, &timeouts);
399
400 if (enables.tcc) {
401 used_budget_us += (timeouts.msrc_dss_tcc_us + tcc_overhead);
402 }
403
404 if (enables.dss) {
405 used_budget_us += 2 * (timeouts.msrc_dss_tcc_us + dss_overhead);
406 } else if (enables.msrc) {
407 used_budget_us += (timeouts.msrc_dss_tcc_us + msrc_overhead);
408 }
409
410 if (enables.pre_range) {
411 used_budget_us += (timeouts.pre_range_us + pre_range_overhead);
412 }
413
414 if (enables.final_range) {
415 used_budget_us += final_range_overhead;
416
417 // "Note that the final range timeout is determined by the timing
418 // budget and the sum of all other timeouts within the sequence.
419 // If there is no room for the final range timeout, then an error
420 // will be set. Otherwise the remaining time will be applied to
421 // the final range."
422
423 if (used_budget_us > budget_us) {
424 // "Requested timeout too big."
425 return false;
426 }
427
428 uint32_t final_range_timeout_us = budget_us - used_budget_us;
429
430 // set_sequence_step_timeout() begin
431 // (SequenceStepId == VL53L0X_SEQUENCESTEP_FINAL_RANGE)
432
433 // "For the final range timeout, the pre-range timeout
434 // must be added. To do this both final and pre-range
435 // timeouts must be expressed in macro periods MClks
436 // because they have different vcsel periods."
437
438 uint16_t final_range_timeout_mclks =
439 timeout_microseconds_to_mclks_(final_range_timeout_us, timeouts.final_range_vcsel_period_pclks);
440
441 if (enables.pre_range) {
442 final_range_timeout_mclks += timeouts.pre_range_mclks;
443 }
444
445 write_byte_16(0x71, encode_timeout_(final_range_timeout_mclks));
446
447 // set_sequence_step_timeout() end
448
449 measurement_timing_budget_us_ = budget_us; // store for internal reuse
450 }
451 return true;
452}
453
455 uint8_t sequence_config = reg(0x01).get();
456 enables->tcc = (sequence_config >> 4) & 0x1;
457 enables->dss = (sequence_config >> 3) & 0x1;
458 enables->msrc = (sequence_config >> 2) & 0x1;
459 enables->pre_range = (sequence_config >> 6) & 0x1;
460 enables->final_range = (sequence_config >> 7) & 0x1;
461}
462
488
490 uint8_t vcsel;
492 vcsel = reg(0x50).get();
493 } else if (type == VCSEL_PERIOD_FINAL_RANGE) {
494 vcsel = reg(0x70).get();
495 } else {
496 return 255;
497 }
498
499 return (vcsel + 1) << 1;
500}
501
502uint32_t VL53L0XSensor::get_macro_period_(uint8_t vcsel_period_pclks) {
503 return ((2304UL * vcsel_period_pclks * 1655UL) + 500UL) / 1000UL;
504}
505
506uint32_t VL53L0XSensor::timeout_mclks_to_microseconds_(uint16_t timeout_period_mclks, uint8_t vcsel_period_pclks) {
507 uint32_t macro_period_ns = get_macro_period_(vcsel_period_pclks);
508 return ((timeout_period_mclks * macro_period_ns) + (macro_period_ns / 2)) / 1000;
509}
510
511uint32_t VL53L0XSensor::timeout_microseconds_to_mclks_(uint32_t timeout_period_us, uint8_t vcsel_period_pclks) {
512 uint32_t macro_period_ns = get_macro_period_(vcsel_period_pclks);
513 return (((timeout_period_us * 1000) + (macro_period_ns / 2)) / macro_period_ns);
514}
515
516uint16_t VL53L0XSensor::decode_timeout_(uint16_t reg_val) {
517 // format: "(LSByte * 2^MSByte) + 1"
518 uint8_t msb = (reg_val >> 8) & 0xFF;
519 uint8_t lsb = (reg_val >> 0) & 0xFF;
520 return (uint16_t(lsb) << msb) + 1;
521}
522
523uint16_t VL53L0XSensor::encode_timeout_(uint16_t timeout_mclks) {
524 // format: "(LSByte * 2^MSByte) + 1"
525 uint32_t ls_byte = 0;
526 uint16_t ms_byte = 0;
527
528 if (timeout_mclks <= 0)
529 return 0;
530
531 ls_byte = timeout_mclks - 1;
532
533 while ((ls_byte & 0xFFFFFF00) > 0) {
534 ls_byte >>= 1;
535 ms_byte++;
536 }
537
538 return (ms_byte << 8) | (ls_byte & 0xFF);
539}
540
542 reg(0x00) = 0x01 | vhv_init_byte; // VL53L0X_REG_SYSRANGE_MODE_START_STOP
543
544 uint32_t start = millis();
545 while ((reg(0x13).get() & 0x07) == 0) {
546 if (millis() - start > 1000)
547 return false;
548 yield();
549 }
550
551 reg(0x0B) = 0x01;
552 reg(0x00) = 0x00;
553
554 return true;
555}
556
557} // namespace esphome::vl53l0x
void mark_failed()
Mark this component as failed.
void status_momentary_warning(uint32_t length=5000)
Set warning status flag and clear it after length ms.
const LogString * get_log_name() const
Get the name for a "%s" log argument (LOG_STR_ARG).
virtual void digital_write(bool value)=0
virtual uint32_t get_update_interval() const
Get the update interval in ms of this sensor.
uint8_t address_
store the address of the device on the bus
Definition i2c.h:327
bool read_byte(uint8_t a_register, uint8_t *data)
Definition i2c.h:272
bool read_byte_16(uint8_t a_register, uint16_t *data)
Definition i2c.h:281
I2CRegister reg(uint8_t a_register)
calls the I2CRegister constructor
Definition i2c.h:164
void set_i2c_address(uint8_t address)
We store the address of the device on the bus.
Definition i2c.h:151
bool write_bytes(uint8_t a_register, const uint8_t *data, uint8_t len) const
Definition i2c.h:298
bool write_byte_16(uint8_t a_register, uint16_t data) const
Definition i2c.cpp:118
bool read_bytes(uint8_t a_register, uint8_t *data, uint8_t len)
Compat APIs All methods below have been added for compatibility reasons.
Definition i2c.h:249
uint8_t get() const
returns the register value
Definition i2c.cpp:143
void publish_state(float state)
Publish a new state to the front-end.
Definition sensor.cpp:65
uint32_t timeout_mclks_to_microseconds_(uint16_t timeout_period_mclks, uint8_t vcsel_period_pclks)
void get_sequence_step_enables_(SequenceStepEnables *enables)
bool perform_single_ref_calibration_(uint8_t vhv_init_byte)
uint16_t decode_timeout_(uint16_t reg_val)
uint32_t timeout_microseconds_to_mclks_(uint32_t timeout_period_us, uint8_t vcsel_period_pclks)
static std::list< VL53L0XSensor * > vl53_sensors
void get_sequence_step_timeouts_(SequenceStepEnables const *enables, SequenceStepTimeouts *timeouts)
bool set_measurement_timing_budget_(uint32_t budget_us)
uint32_t get_macro_period_(uint8_t vcsel_period_pclks)
uint8_t get_vcsel_pulse_period_(VcselPeriodType type)
uint16_t encode_timeout_(uint16_t timeout_mclks)
void yield(void)
uint8_t type
mopeka_std_values val[3]
ESPHOME_LOG_TAG(TAG, "vl53l0x")
uint32_t value
Definition hal.cpp:41
void IRAM_ATTR HOT delayMicroseconds(uint32_t us)
Definition hal.cpp:48
uint32_t IRAM_ATTR HOT micros()
Definition hal.cpp:43
uint32_t IRAM_ATTR HOT millis()
Definition hal.cpp:25
static void uint32_t