feat(vl53l): VL53L5CX multizone ToF driver (espp::Vl53l5cx)

.github/workflows/build.yml

@@ -380,6 +380,8 @@ jobs:
           target: esp32p4
         - path: 'components/vl53l/example'
           target: esp32s3
+        - path: 'components/vl53l/vl53l5cx_example'
+          target: esp32s3
         - path: 'components/wdi/ble_example'
           target: esp32s3
         - path: 'components/wdi/ble_central_example'

components/vl53l/CMakeLists.txt

@@ -1,4 +1,6 @@
 idf_component_register(
   INCLUDE_DIRS "include"
+  # src: the VL53L5CX driver and its firmware image (~84 KB of .rodata)
+  SRC_DIRS "src"
   REQUIRES "base_peripheral"
   )

components/vl53l/README.md

@@ -2,26 +2,65 @@
 
 [![Badge](https://components.espressif.com/components/espp/vl53l/badge.svg)](https://components.espressif.com/components/espp/vl53l)
 
-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))
-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.
+Drivers for ST's VL53L Time-of-Flight (ToF) sensors that talk over I2C with
+16-bit register addresses:
 
-> **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.
+| Class | Sensors | What it measures |
+| --- | --- | --- |
+| `espp::Vl53l` (`vl53l.hpp`) | VL53L4CD, VL53L4CX | one distance, up to 1.3 m (CD) or 6 m (CX), 1 mm resolution |
+| `espp::Vl53l5cx` (`vl53l5cx.hpp`) | VL53L5CX | a 4x4 or 8x8 grid of distances up to 4 m over a 63° diagonal field of view, at up to 60 Hz (4x4) or 15 Hz (8x8) |
 
-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
-distance through glass or other transparent materials.
+The sensors use a laser to send a pulse of light and measure the time it takes
+for the light to reflect back. They can struggle outdoors, as sunlight
+interferes with the measurement, and cannot measure through glass or other
+transparent materials.
 
-## Example
+> **Note:** Neither driver is compatible with the older VL53L0X or VL53L1X
+> sensors, which use a different (8-bit) register map and communication
+> protocol.
 
-The [example](./example) shows the use of the `Vl53l` component to communicate
-with a VL53L4CD time-of-flight distance sensor.
+## VL53L4CD / VL53L4CX (`espp::Vl53l`)
 
+Single-zone ranging: timing budget, inter-measurement period, continuous or
+autonomous mode, data-ready polling and interrupt clearing.
+
+## VL53L5CX (`espp::Vl53l5cx`)
+
+Multizone ranging. The sensor has no firmware in ROM: `initialize()` (run by
+the constructor by default) reboots it and uploads the ~84 KB VL53L5CX firmware
+over I2C, which takes about two seconds at 400 kHz (the sensor supports 1 MHz
+Fast Mode Plus). The driver then offers:
+
+- resolution (4x4 / 8x8), ranging frequency, integration time, sharpener,
+  target order (closest / strongest), ranging mode (continuous / autonomous),
+  power mode, I2C address change;
+- `start_ranging()` / `stop_ranging()`, `is_data_ready()` polling and
+  `get_ranging_data()`, which fills a `RangingData` with, per zone, the
+  distance, sigma, signal and ambient rates, SPAD count, reflectance estimate,
+  number of targets and a target status (5 and 9 mean a valid range);
+- the motion indicator (`enable_motion_indicator()`).
+
+Zones are reported in row-major order (`zone = row * width + col`); see ST's
+UM2884 for the physical orientation of zone 0. One target per zone is
+supported (the ULD default). The crosstalk calibration and detection threshold
+plugins of ST's driver are not ported yet; the default crosstalk shape is
+loaded.
+
+The I2C device's transaction timeout must cover the driver's longest transfers
+(512-byte firmware chunks, ~1.4 KB result frames): a few tens of milliseconds
+at 400 kHz, more at 100 kHz.
+
+### License note
+
+The VL53L5CX firmware image and default configuration (`src/vl53l5cx_firmware.cpp`)
+and the sensor sequences in `src/vl53l5cx.cpp` come from STMicroelectronics'
+VL53L5CX Ultra Lite Driver (ULD 1.1.2, as redistributed by
+[stm32duino/VL53L5CX](https://github.com/stm32duino/VL53L5CX)) and are
+redistributed under their BSD-3-Clause license (see the file headers). The
+rest of the component is MIT like the rest of espp.
+
+## Examples
+
+- [example](./example): `Vl53l` with a VL53L4CD, printing the distance.
+- [vl53l5cx_example](./vl53l5cx_example): `Vl53l5cx` printing the 8x8 grid of
+  distances at 15 Hz.

components/vl53l/idf_component.yml

@@ -1,21 +1,24 @@
 ## IDF Component Manager Manifest File
 license: "MIT"
-description: "VL53L Time of Flight (ToF) Distance Sensor component for ESP-IDF"
+description: "VL53L Time of Flight (ToF) sensor components for ESP-IDF: VL53L4CD / VL53L4CX distance sensors and the VL53L5CX multizone (4x4 / 8x8) sensor"
 url: "https://github.com/esp-cpp/espp/tree/main/components/vl53l"
 repository: "git://github.com/esp-cpp/espp.git"
 maintainers:
   - William Emfinger <waemfinger@gmail.com>
 documentation: "https://esp-cpp.github.io/espp/distance_sensors/vl53l.html"
 examples:
   - path: example
+  - path: vl53l5cx_example
 tags:
   - cpp
   - Component
   - Sensing
   - VL53L
+  - VL53L5CX
   - ToF
   - Time-of-Flight
   - Distance
+  - Multizone
   - Laser
 dependencies:
   idf: