diff --git a/components/vl53l/README.md b/components/vl53l/README.md index 5c1c330f0..efe33ed0e 100644 --- a/components/vl53l/README.md +++ b/components/vl53l/README.md @@ -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 @@ -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. diff --git a/components/vl53l/example/README.md b/components/vl53l/example/README.md index ae5569b9f..0aeb54c6e 100644 --- a/components/vl53l/example/README.md +++ b/components/vl53l/example/README.md @@ -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 @@ -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) diff --git a/components/vl53l/include/vl53l.hpp b/components/vl53l/include/vl53l.hpp index 0d40b74a8..4790c17f5 100644 --- a/components/vl53l/include/vl53l.hpp +++ b/components/vl53l/include/vl53l.hpp @@ -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 @@ -115,7 +118,7 @@ class Vl53l : public espp::BasePeripheral { /// \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)) { @@ -125,10 +128,13 @@ class Vl53l : public espp::BasePeripheral { 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; } @@ -531,8 +537,9 @@ class Vl53l : public espp::BasePeripheral { } 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 @@ -710,7 +717,7 @@ class Vl53l : public espp::BasePeripheral { 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; diff --git a/doc/en/distance_sensors/vl53l.rst b/doc/en/distance_sensors/vl53l.rst index e722ac1c3..e637c0d1b 100644 --- a/doc/en/distance_sensors/vl53l.rst +++ b/doc/en/distance_sensors/vl53l.rst @@ -1,14 +1,21 @@ VL53LXX ToF Distance Sensor *************************** -The `Vl53L0X -`_ 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 +`_ and +`VL53L4CX +`_ 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