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

[finger563]

Summary

Adds espp::Vl53l5cx, a driver for the VL53L5CX 4x4 / 8x8 multizone time-of-flight sensor, to the vl53l component next to the existing VL53L4CD/CX driver (both talk I2C with 16-bit register addresses and share BasePeripheral plus the component scaffolding).

• The sensor has no firmware in ROM: initialize() (run by the constructor by default) reboots it and uploads ST's ~84 KB firmware, then configures it through the DCI command interface. About two seconds at 400 kHz; the sensor supports 1 MHz.
• The logic is a port of ST's Ultra Lite Driver 1.1.2 (BSD-3-Clause, as redistributed by stm32duino/VL53L5CX); the firmware / default configuration / crosstalk blobs are generated from its vl53l5cx_buffers.h and keep the license in their file headers. The component README has a license note.
• API: resolution, ranging frequency (validated against the resolution), integration time, sharpener, target order, ranging mode, power mode, I2C address change; start_ranging() / stop_ranging(), is_data_ready() polling, get_ranging_data() into a RangingData (distance, sigma, signal / ambient rates, SPAD count, reflectance, target count and target status per zone, row-major); the motion indicator plugin.
• One target per zone (the ULD default). The crosstalk calibration and detection threshold plugins are documented follow-ups.
• components/vl53l/vl53l5cx_example (Kconfig: pins, I2C clock, resolution, frequency) prints the distance grid; docs pages, Doxyfile and the CI build matrix are updated.

Notes for review: BasePeripheral::write_many_to_register stages each write on the stack, so the driver chunks writes to 512 bytes; the I2C device timeout has to cover those and the ~1.4 KB frame reads (the example uses 100 ms).

WebUSB console (second commit)

A separate example next to the first one, so the sensor can be watched and driven from a browser over the dispatcher / stream_frame protocol:

• Protocol vl53l5cx_protocol.hpp (module id 10, protocol espp.vl53l5cx v1, standard-library only, host test components/vl53l/test/vl53l5cx_protocol_host_test.cpp): every setting (resolution, frequency, integration time, sharpener, target order, ranging mode, power mode, motion indicator window, I2C address), start / stop / initialize, a per-transport frame stream (every Nth frame), GET_FRAME, and a STATUS snapshot (settings read back from the sensor when idle, cached while ranging).
• Service espp::Vl53l5cxService (vl53l5cx_service.hpp): the application owns the one poll loop and hands each frame to every instance through on_frame(), so the vendor (WebUSB) and CDC (Web Serial) transports share one sensor and one mutex.
• Example components/vl53l/vl53l5cx_webapp_example (ESP32-S3 / ESP32-P4; Kconfig: pins, part, boot resolution / frequency, ranging at boot, P4 USB port): the sensor service plus the standard System / Monitor / OTA / CoreDump services on both transports, OTA + coredump partition layout, like the MCP266 webapp example.
• Web app components/vl53l/web/vl53l5cx_console.html: live 3D view (zones at their measured position in the field of view as a surface, or a bar height field), coloured by distance / signal / ambient / sigma / reflectance / status, numeric grid, per-zone details, motion indicator, all settings, start / stop / initialize, CSV export. Shares the byte-identical discovery / connection / navigation / hand-back blocks with the other consoles (the node test list is extended). New apps-index category sensors.
• Docs: web apps page, module id table, distance sensor pages; Doxyfile; READMEs; CI entry (esp32s3, manager off).
• espp::UsbDevice fix (third commit): on the ESP32-P4 the full-speed port (Config::port 0) enumerated on GPIO 26 / 27, because IDF leaves USB-OTG 1.1 on the second internal FS PHY while the dev kits' USB-C (and the USB-Serial-JTAG console) is on GPIO 24 / 25. New Config::fs_phy (default 0) selects the PHY pads; the example defaults the P4 dev kits to the full-speed port.

Test plan

• components/vl53l/vl53l5cx_example builds for esp32s3 (IDF 6.1), no warnings
• components/vl53l/example (VL53L4) still builds
• cppcheck with the CI flags is clean on the new sources
• Hardware: VL53L5CX breakout on an ESP32-P4-WIFI6 dev kit (init 2.1 s, 8x8 @ 15 Hz, 4x4 @ ~56 Hz, motion indicator, recovery after a host reset mid-frame)
• vl53l5cx_webapp_example builds for esp32s3 and esp32p4 (IDF 6.1, manager off), boots on the P4 kit (sensor ranging, TinyUSB on the high-speed port)
• node components/dispatcher/web/test/resolve_module_id_test.js and vl53l5cx_protocol_host_test pass; doc/generate_apps_index.py accepts the new page
• Web app rendered in Chrome with a synthetic 8x8 frame (surface + bars views, grid, zone details, motion panel)
• Protocol against the device over its CDC (Web Serial) interface on the P4 kit: discovery, every request incl. error paths, 4x4 @ 30 Hz streaming with no sequence gaps, 8x8 @ 15 Hz with divider 3 + motion indicator, snapshot, re-initialize, live STATUS while ranging
• Web app connected through the browser chooser (WebUSB and Web Serial) on the P4 kit; screenshots / recording in the comment below
• VL53L7CX firmware image (Config::variant): bundled from the same ULD source, not tested on hardware (no part available)

🤖 Generated with Claude Code

https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

5 open findings

• initialize() proceeds when is_alive() returns false but does not set ec (i.e., wrong device… · New
• The loop intends to drop an 8-byte NVM header, but it copies OFFSET_BUFFER_SIZE - 4 bytes from… · New
• header_config stores the number of enabled output blocks as i + 1, but i is the loop index… · New
• poll_for_answer() indexes temp_buffer_[pos] without validating pos < size. While current call… · New
• The header[0] != 255 condition causes one valid frame to be skipped whenever the device stream… · New

What changed in this PR

Adds a new espp::Vl53l5cx multizone ToF driver (VL53L5CX) alongside the existing VL53L4 driver, including an ESP-IDF example and documentation/CI wiring.

Changes:

• Introduces components/vl53l/include/vl53l5cx.hpp + src/vl53l5cx.cpp implementing firmware upload, DCI configuration, ranging, and motion indicator support.
• Adds a dedicated vl53l5cx_example project (Kconfig + main) and hooks it into Doxygen and CI builds.
• Adds Sphinx docs pages for the VL53L5CX driver and example; updates component README and manifest metadata.

File	Description
doc/​en/​distance_sensors/​vl53l5cx_example.md	Exposes the example README in the docs tree.
doc/​en/​distance_sensors/​vl53l5cx.rst	New VL53L5CX docs landing page + API include.
doc/​en/​distance_sensors/​index.rst	Adds VL53L5CX to the distance sensors doc index.
doc/​Doxyfile	Includes the new example + header in Doxygen input.
components/​vl53l/​vl53l5cx_example/​**	New standalone ESP-IDF example project for VL53L5CX.
components/​vl53l/​src/​vl53l5cx_firmware.hpp	Declares bundled firmware/config blob symbols and sizes.
components/​vl53l/​src/​vl53l5cx.cpp	Implements the VL53L5CX driver logic (ULD port).
components/​vl53l/​include/​vl53l5cx.hpp	Public driver API/types/configuration for VL53L5CX.
components/​vl53l/​idf_component.yml	Updates description/tags and registers the new example.
components/​vl53l/​README.md	Documents both drivers and adds VL53L5CX license note.
components/​vl53l/​CMakeLists.txt	Ensures src/ is compiled into the vl53l component.
.github/​workflows/​build.yml	Adds the new example to the CI build matrix.

🧠 Review effort: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Unsynchronized status reads, insufficient transfer timeouts and failure-path state handling need correction.

2 open findings

• Synchronize status flags to prevent data races · New
• Derive I2C timeout from transfer size and bus clock · New

5 resolved since last review

• header_config stores the number of enabled output blocks as i + 1, but i is the loop index…
• The loop intends to drop an 8-byte NVM header, but it copies OFFSET_BUFFER_SIZE - 4 bytes from…
• initialize() proceeds when is_alive() returns false but does not set ec (i.e., wrong device…
• The header[0] != 255 condition causes one valid frame to be skipped whenever the device stream…
• poll_for_answer() indexes temp_buffer_[pos] without validating pos < size. While current call…

Previously missed (4)

In code that hasn't changed since last review

Restore register page after failed ID probe

components/​vl53l/​src/​vl53l5cx.cpp:236

If either ID read fails after selecting page 0, short-circuit evaluation skips the page-2 restore. Calling this health check on an initialized sensor can leave subsequent frame reads and DCI commands accessing the wrong register page after the bus recovers. Always attempt to restore page 2, preserving the original error if the probe failed.

Restore register page after failed power-register read

components/​vl53l/​src/​vl53l5cx.cpp:490

If selecting page 0 succeeds but reading the power register fails, this return skips the page-2 restoration below. Subsequent DCI commands and frame reads then access the wrong register page even after the I2C fault clears. Attempt the restore on this error path with a separate error code so the original failure is preserved.

Restore register page after xshut-bypass failure

components/​vl53l/​src/​vl53l5cx.cpp:893

If selecting page 0 succeeds but the xshut-bypass write fails, this error path does not restore page 2. Retrying start_ranging() then begins with a DCI resolution read against the wrong page, so a transient I2C failure can prevent recovery. Attempt the page-2 restore before returning, preserving the original error.

Preserve ranging state when stop or cleanup fails

components/​vl53l/​src/​vl53l5cx.cpp:931

If a stop-command write fails or the MCU-stop poll times out, stopping has not been confirmed, but this still clears ranging_. Subsequent frame reads are rejected and configuration setters bypass their while-ranging guard even though the sensor may still be active. Preserve the ranging state on failure; only clear it after a successful stop and cleanup.

🧠 Review effort: Balanced

[finger563]

The four "previously missed" items are fixed in f646e5d as well: is_alive(), get_power_mode() and start_ranging() restore register page 2 on their failure paths (original error preserved), and stop_ranging() keeps ranging_ set unless the stop and cleanup were confirmed.

[Copilot]

🔵 Needs a closer look

Address-change callbacks and error-recovery paths have unresolved correctness issues.

0 open findings

2 resolved since last review

• Derive I2C timeout from transfer size and bus clock
• Synchronize status flags to prevent data races

Previously missed (3)

In code that hasn't changed since last review

Incoming error prevents recovery after successful retry

components/​vl53l/​src/​vl53l5cx.cpp:107

Clear the incoming error before this read. The separate-write/read fallback selected by this driver's Config leaves ec unchanged on success (components/base_peripheral/include/base_peripheral.hpp:333–344). After a transient read failure, retrying is_data_ready() or get_ranging_data() with the same error-code variable therefore still returns false even when both I2C callbacks succeed. Clearing it here allows recovery while retaining any new transfer error.

Page restoration skipped when cleanup write fails

components/​vl53l/​src/​vl53l5cx.cpp:950

If a cleanup write to 0x14, 0x15 or 0x09 fails after selecting page 0, this short-circuit chain skips restoring page 2. Subsequent frame reads or a stop retry then access the wrong register page, even after a transient I2C failure clears. Attempt the final page restore independently and preserve the first cleanup error.

Address-aware callbacks ignored for configurable I2C addresses

components/​vl53l/​vl53l5cx_example/​main/​vl53l5cx_example.cpp:52

These adapters ignore the callback address and stay bound to 0x29 (components/i2c/include/i2c.hpp:872–892). If a caller uses this setup with set_i2c_address(), the sensor changes address, but the final page-restoration write and later transfers still target 0x29 and fail. Use address-aware bus callbacks here; the bus already has the required timeout. Also document the callback requirement on set_i2c_address() so callers do not use fixed-device adapters for address changes.

🧠 Review effort: Balanced

[finger563]

Round 3's three "previously missed" items are fixed in 2c22f41: write_multi / read_multi clear the incoming error code (the base class's separate write / read path only sets it); stop_ranging() restores register page 2 independently of the cleanup writes and reports the first error; the example uses address-aware bus callbacks (lambdas over I2c::write / I2c::read) and the Config / set_i2c_address() docs state that the callbacks must honour their address argument.

[Copilot]

🔵 Needs a closer look

The firmware-driven hardware port still needs device validation and human review, with power-mode reporting and address-change recovery issues unresolved.

0 open findings

Previously missed (2)

In code that hasn't changed since last review

Restore page 2 when address write fails

components/​vl53l/​src/​vl53l5cx.cpp:492

If selecting page 0 succeeds but the address write fails before changing the address, this return leaves the sensor on page 0. Later DCI and frame operations assume page 2, so they access the wrong registers even after the bus recovers. Attempt to restore page 2 on this failure path, using a separate error code to preserve the original failure.

Accept 0x05 as a valid wakeup power mode

components/​vl53l/​src/​vl53l5cx.cpp:514

start_ranging() writes 0x05 to register 0x09 to enable xshut bypass, but this switch accepts only 0x04 and 0x02. Reading back the awake-with-bypass value therefore sets an I/O error in get_power_mode() during normal ranging. Accept 0x05 as WAKEUP too.

🧠 Review effort: Balanced

[finger563]

Round 4's two "previously missed" items are fixed in 1951aad: set_i2c_address() restores register page 2 on the old address when the address write fails, and get_power_mode() accepts 0x05 (awake + xshut bypass during ranging) as WAKEUP.

[Copilot]

🔵 Needs a closer look

Firmware initialization, ranging and motion-indicator behavior still need hardware validation and final human review.

0 open findings

Previously missed (1)

In code that hasn't changed since last review

Correct default DCI_INT_TIME from 10 ms to 5 ms

components/​vl53l/​include/​vl53l5cx.hpp:183

The bundled configuration sets DCI_INT_TIME (0x545C) to 10,000 microseconds, and initialize() does not override it. The default integration time is therefore 10 ms, not 5 ms. Please correct this value so callers do not underestimate the integration budget, particularly with four integrations per 8x8 frame.

🧠 Review effort: Balanced

[finger563]

Round 5's item is fixed in a0d9c38: the bundled default configuration sets DCI_INT_TIME to 10 000 µs, so the initialize() doc now says 10 ms (verified against the blob bytes at 0x545C).

[Copilot]

🔵 Needs a closer look

The sensor-protocol port needs the planned hardware validation of initialization, ranging, and motion detection, followed by human review.

0 open findings

🧠 Review effort: Balanced

[finger563]

Hardware-tested on an ESP32-P4-WIFI6 dev kit with a VL53L5CX breakout (I2C 400 kHz, SDA 7 / SCL 8): initialize in 2.1 s, 8x8 at 15 Hz (96 frames in 6.4 s), plausible scene distances 0.43 .. 2.8 m; a reset while ranging recovers through the new identity-probe retry. Two fixes came out of it (f9a72f7, and this push): the MCU boot wait is the newer ULD's (the old 0x06 == 0 check could pass before the MCU was up and the first firmware command then failed with error 0x9f), and the first transaction after a host reset is retried. VL53L7CX support (same ids, different firmware) is selected by Config::variant; untested on an L7CX. Remaining test-plan items: 4x4 @ 60 Hz and the motion indicator.

[finger563]

Remaining test-plan items done on the same P4 kit: 4x4 @ 60 Hz (416 frames in 7.4 s, ~56 Hz with console printing in the loop) and the motion indicator (new Kconfig option in the example; 16 aggregates, low values on a static scene). Everything in the test plan is now hardware-verified on a VL53L5CX; the VL53L7CX path is untested.

[finger563]

VL53L5CX console media for the docs (live data from the VL53L5CX on the ESP32-P4-WIFI6 dev kit, 8x8 @ 15 Hz, replayed through the page).

Surface view (zones at their measured positions in the field of view, coloured by distance on the fixed sensor scale):

Bars view (height = distance, hovered zone's details in the Zone panel):

Live (orbit, bars, colour by signal):