Skip to content

vl53l: fix sensor model mismatch — component supports VL53L4CD/VL53L4CX, not VL53L0X #613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

vl53l: fix sensor model mismatch — component supports VL53L4CD/VL53L4CX, not VL53L0X #613

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1ac2fb9
Initial plan
Copilot Apr 19, 2026
cc856d5
Fix VL53L model ID mismatch: correct sensor docs from VL53L0X to VL53…
Copilot Apr 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions components/vl53l/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,18 @@
[![Badge](https://components.espressif.com/components/espp/vl53l/badge.svg)](https://components.espressif.com/components/espp/vl53l)

The
[Vl53L0X](https://www.st.com/en/imaging-and-photonics-solutions/vl53l0x.html) is
a Time-of-Flight (ToF) distance sensor. It is a sensor that can measure distance
from a target object without touching it. The sensor uses a laser to send a
pulse of light and measures the time it takes for the light to reflect back to
the sensor. The sensor can measure distance up to 2 meters with a resolution of
1mm. Because of the way the sensor works, it is able to measure multiple
distances at the same time.
[VL53L4CD](https://www.st.com/en/imaging-and-photonics-solutions/vl53l4cd.html)
(and [VL53L4CX](https://www.st.com/en/imaging-and-photonics-solutions/vl53l4cx.html))
is a Time-of-Flight (ToF) distance sensor. It is a sensor that can measure
distance from a target object without touching it. The sensor uses a laser to
send a pulse of light and measures the time it takes for the light to reflect
back to the sensor. The sensor can measure distance up to 1.3 meters (VL53L4CD)
or up to 6 meters (VL53L4CX) with a resolution of 1mm.

> **Note:** This component is designed for the **VL53L4CD** and **VL53L4CX**
> sensors, which use a 16-bit register addressing scheme. It is **not**
> compatible with the older VL53L0X or VL53L1X sensors, which use a different
> register map and communication protocol.

The sensor can struggle with outdoor use, as sunlight can interfere with the
sensor's ability to measure distance. The sensor is also not able to measure
Expand All @@ -18,5 +23,5 @@ distance through glass or other transparent materials.
## Example

The [example](./example) shows the use of the `Vl53l` component to communicate
with a VL53L0X time-of-flight distance sensor.
with a VL53L4CD time-of-flight distance sensor.

12 changes: 9 additions & 3 deletions components/vl53l/example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# VL53LXX Example

This example shows the use of the `Vl53l` component to communicate with a VL53L0X
This example shows the use of the `Vl53l` component to communicate with a VL53L4CD
time-of-flight distance sensor.

The example initializes the sensor, configures it, and then reads the distance
Expand All @@ -14,8 +14,14 @@ This example is designed to work with any ESP32 which has I2C pins exposed, but
is pre-configured to run on QtPy boards such as the QtPy ESP32 Pico and QtPy
ESP32-S3.

It requires that you have a time of flight distance sensor dev board, such as
the [VL53L0X dev board from Adafruit](https://www.adafruit.com/product/3317).
It requires that you have a VL53L4CD or VL53L4CX time of flight distance sensor
dev board, such as the [VL53L4CD breakout from
Adafruit](https://www.adafruit.com/product/5396).

> **Note:** This component is **not** compatible with the VL53L0X sensor. If you
> have a VL53L0X (e.g., WHADDA WPSE337 or the Adafruit VL53L0X breakout), you
> will need a different driver, as VL53L0X uses a different register addressing
> scheme.

![image](https://github.com/user-attachments/assets/47f7f64a-ad55-4529-9851-5283fc57bcb8)

Expand Down
43 changes: 25 additions & 18 deletions components/vl53l/include/vl53l.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,20 @@
namespace espp {
using vl53l_register_t = uint16_t;

/// \brief VL53LXXX Time-of-Flight Distance Sensor
/// \brief VL53L4CD / VL53L4CX Time-of-Flight Distance Sensor
/// \details
/// The VL53LXX is a new generation Time-of-Flight (ToF) laser-ranging module
/// housed in the smallest package on the market today, providing accurate
/// distance measurement whatever the target reflectances unlike conventional
/// technologies. It can measure absolute distances up to 2m, setting a new
/// benchmark in ranging performance levels, opening the door to various new
/// applications.
/// \see https://www.st.com/en/imaging-and-photonics-solutions/vl53l1x.html
/// \see https://www.st.com/en/imaging-and-photonics-solutions/vl53l4CD.html
/// \see https://www.st.com/en/imaging-and-photonics-solutions/vl53l4CX.html
/// The VL53L4CD and VL53L4CX are Time-of-Flight (ToF) laser-ranging modules
/// that provide accurate distance measurement regardless of target reflectance.
/// The VL53L4CD measures distances up to 1.3 m and the VL53L4CX up to 6 m,
/// both with 1 mm resolution.
///
/// \note
/// This driver uses a 16-bit register addressing scheme as required by the
/// VL53L4CD and VL53L4CX. It is \b not compatible with the VL53L0X or
/// VL53L1X sensors, which use a different (8-bit) register map.
///
/// \see https://www.st.com/en/imaging-and-photonics-solutions/vl53l4cd.html
/// \see https://www.st.com/en/imaging-and-photonics-solutions/vl53l4cx.html
///
/// \note
/// For an official Arduino library, see
Expand Down Expand Up @@ -115,7 +118,7 @@ class Vl53l : public espp::BasePeripheral<vl53l_register_t, true> {
/// \brief Get the ModelInfo
/// \param ec Error code if unsuccessful
/// \return ModelInfo
/// \see VL53L0X_GetModelID
/// \see VL53L4CD UM2931 section 3.2.4
ModelInfo get_model_info(std::error_code &ec) {
uint8_t data[2];
if (!read_reg(Register::IDENTIFICATION_MODEL_ID, data, 2, ec)) {
Expand All @@ -125,10 +128,13 @@ class Vl53l : public espp::BasePeripheral<vl53l_register_t, true> {
info.model_id = data[0];
info.module_type = data[1];
logger_.debug("Model ID: {:#04x}, Module Type: {:#04x}", info.model_id, info.module_type);
if (info.model_id != MODEL_ID || info.module_type != MODULE_TYPE) {
logger_.error("Model ID ({:#04x}) or Module Type ({:#04x}) does not match expected values "
"({:#04x}, {:#04x})",
info.model_id, info.module_type, MODEL_ID, MODULE_TYPE);
if (info.model_id != MODEL_ID || (info.module_type != MODULE_TYPE_CD &&
info.module_type != MODULE_TYPE_CX)) {
logger_.warn("Model ID ({:#04x}) or Module Type ({:#04x}) does not match expected values "
"for VL53L4CD ({:#04x}, {:#04x}) or VL53L4CX ({:#04x}, {:#04x}). "
"Ensure you are using a VL53L4CD or VL53L4CX sensor.",
info.model_id, info.module_type, MODEL_ID, MODULE_TYPE_CD, MODEL_ID,
MODULE_TYPE_CX);
}
return info;
}
Expand Down Expand Up @@ -531,8 +537,9 @@ class Vl53l : public espp::BasePeripheral<vl53l_register_t, true> {
}

protected:
static constexpr uint8_t MODEL_ID = 0xEB;
static constexpr uint8_t MODULE_TYPE = 0xAA;
static constexpr uint8_t MODEL_ID = 0xEB; ///< Model ID for VL53L4CD and VL53L4CX
static constexpr uint8_t MODULE_TYPE_CD = 0xAA; ///< Module type for VL53L4CD
static constexpr uint8_t MODULE_TYPE_CX = 0x10; ///< Module type for VL53L4CX

static constexpr int MIN_TIMING_BUDGET_US = 10000; // 10 ms
static constexpr int MAX_TIMING_BUDGET_US = 200000; // 200 ms
Expand Down Expand Up @@ -710,7 +717,7 @@ class Vl53l : public espp::BasePeripheral<vl53l_register_t, true> {
if (!write_reg(Register::SYSTEM_SEQUENCE_CONFIG, 0x00, ec)) {
return false;
}
// write 0x0500 to 0x0024 (VL53L0X_REG_FINAL_RANGE_CONFIG_MIN_COUNT_RATE_RTN_LIMIT?)
// write 0x0500 to RANGE_CONFIG_MIN_COUNT_RATE_RTN_LIMIT_MCPS (0x0066)
uint16_t val = 0x0005;
if (!write_reg(Register::RANGE_CONFIG_MIN_COUNT_RATE_RTN_LIMIT_MCPS, (uint8_t *)&val, 2, ec)) {
return false;
Expand Down
23 changes: 15 additions & 8 deletions doc/en/distance_sensors/vl53l.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,21 @@
VL53LXX ToF Distance Sensor
***************************

The `Vl53L0X
<https://www.st.com/en/imaging-and-photonics-solutions/vl53l0x.html>`_ is a
Time-of-Flight (ToF) distance sensor. It is a sensor that can measure distance
from a target object without touching it. The sensor uses a laser to send a
pulse of light and measures the time it takes for the light to reflect back to
the sensor. The sensor can measure distance up to 2 meters with a resolution of
1mm. Because of the way the sensor works, it is able to measure multiple
distances at the same time.
The `VL53L4CD
<https://www.st.com/en/imaging-and-photonics-solutions/vl53l4cd.html>`_ and
`VL53L4CX
<https://www.st.com/en/imaging-and-photonics-solutions/vl53l4cx.html>`_ are
Time-of-Flight (ToF) distance sensors. They can measure distance from a target
object without touching it. The sensors use a laser to send a pulse of light
and measure the time it takes for the light to reflect back. The VL53L4CD can
measure absolute distances up to 1.3 meters, while the VL53L4CX can reach up
to 6 meters, both with 1mm resolution.

.. note::

This component supports the **VL53L4CD** and **VL53L4CX** sensors, which
use a 16-bit register addressing scheme. It is **not** compatible with the
older VL53L0X or VL53L1X sensors, which use a different register map.

The sensor can struggle with outdoor use, as sunlight can interfere with the
sensor's ability to measure distance. The sensor is also not able to measure
Expand Down
Loading