drivers/vl53l1x: add VL53L1X ToF ranging sensor driver

[gschorcht]

Contribution description

This PR adds a device driver for ST VL53L1X Time-of-Flight laser-ranging sensor which allows accurate and fast ranging up to 4 m at a frequency of up to 50 Hz. It is a complete rework of PR #10363 and uses the ST VL53L1X ULD API (STSW-IMG009) as a package instead of the ST VL53L1X API (STSW-IMG007) that was used in PR #10363.

There are two variants of the driver which differ in functionality and size:

Module Name	Driver	Short Description
vl53l1x_basic	Basic Driver	Minimum functionality at small size
vl53l1x	Default Driver	Complete functionality at acceptable size

The vl53l1x_basic driver variant is the smallest driver variant which provides only some basic functions such as the distance measurement and the data-ready interrupt.

The vl53l1x driver variant (default) is a compromise of size and functionality. It provides the application with most functionality of the sensor. The driver can be used when memory requirements are important and most of the functionality should be used.

Both driver variants use the ST VL53L1X ULD API (STSW-IMG009) as vendor code, provide SAUL capabilities and data-ready interrupt functionality. The vl53l1x driver variant allows to use threshold interrupts.

Function / Property	vl53l1x_basic	vl53l1x
Distance results in mm	X	X
Signal rate results in kcps		X
Measurement status information		X
SAUL capability	X	X
Distance mode configuration		X
Timing budget configuration		X
Inter-measurement period configuration		X
Region of Interest (ROI) configuration		X
Data-ready interrupts (ranging mode)	X	X
Threshold interrupts (detection mode)		X
Power on/off functions		X
SHUTDOWN pin support		X
Calibration functions		X [1]
Size on reference platform in kByte [2]	0.9	2.2

[1] These functions are available by using the ST VL53L1X ULD API directly.
[2] Reference platform: STM32F411RE

Testing procedure

The driver variants can be tested by using the test application with different modules where the standard variant vl53l1x is used by default:

make flash -C tests/driver_vl53l1x BOARD=...

To use the vl53l1x_basic driver variant, define it in it the make command:

DRIVER=vl53l1x_basic make flash -C tests/driver_vl53l1x BOARD=...

If the configuration parameter VL53L1X_PARAM_PIN_INT is defined, e.g.,

CFLAGS='-DVL53L1X_PARAM_PIN_INT=\(GPIO\(0,\1\)' make flash -C tests/driver_vl53l1x BOARD=...

interrupts are used to get data instead of polling for new data. In the case of the vl53l1x driver variant, threshold interrupts are configured.

In all cases, the sensor is configured with following default parameters:

• timing budget of 50 ms
• intermeasurement period of 100 ms

Test Output

main(): This is RIOT! (Version: 2025.10-devel-92-g72169-drivers/vl53l1x/st_uld_api_pkg)
VL53L1X Time-of-Flight distance sensor

Initializing VL53L1X sensor
[OK]
old ROI [x_size=16, y_size=16]
new ROI [x_size=8, y_size=8]
distance=1717 [mm] status=0 signal=2448 [kcps] ambient=1984 [kcps]
distance=840 [mm] status=7 signal=7456 [kcps] ambient=1816 [kcps]
distance=151 [mm] status=0 signal=19360 [kcps] ambient=1312 [kcps]
distance=157 [mm] status=0 signal=19368 [kcps] ambient=1552 [kcps]
distance=134 [mm] status=0 signal=20664 [kcps] ambient=1576 [kcps]
distance=105 [mm] status=0 signal=20208 [kcps] ambient=992 [kcps]
distance=96 [mm] status=0 signal=15632 [kcps] ambient=768 [kcps]
distance=78 [mm] status=0 signal=22048 [kcps] ambient=632 [kcps]
distance=64 [mm] status=0 signal=17496 [kcps] ambient=256 [kcps]
distance=37 [mm] status=0 signal=7432 [kcps] ambient=40 [kcps]
distance=34 [mm] status=0 signal=18984 [kcps] ambient=32 [kcps]
distance=23 [mm] status=0 signal=20696 [kcps] ambient=16 [kcps]
distance=19 [mm] status=0 signal=25616 [kcps] ambient=8 [kcps]
distance=5 [mm] status=0 signal=43328 [kcps] ambient=16 [kcps]
distance=1 [mm] status=0 signal=62368 [kcps] ambient=24 [kcps]
distance=0 [mm] status=0 signal=20040 [kcps] ambient=8 [kcps]
distance=0 [mm] status=0 signal=25376 [kcps] ambient=8 [kcps]
distance=1 [mm] status=0 signal=64104 [kcps] ambient=8 [kcps]
distance=0 [mm] status=0 signal=64504 [kcps] ambient=0 [kcps]
distance=0 [mm] status=0 signal=58904 [kcps] ambient=8 [kcps]
distance=0 [mm] status=0 signal=1240 [kcps] ambient=8 [kcps]
distance=0 [mm] status=0 signal=30504 [kcps] ambient=8 [kcps]
distance=0 [mm] status=0 signal=7064 [kcps] ambient=16 [kcps]
distance=4 [mm] status=0 signal=44976 [kcps] ambient=16 [kcps]
distance=23 [mm] status=0 signal=18248 [kcps] ambient=16 [kcps]
distance=45 [mm] status=0 signal=11472 [kcps] ambient=32 [kcps]
distance=52 [mm] status=0 signal=17664 [kcps] ambient=80 [kcps]
distance=72 [mm] status=0 signal=18440 [kcps] ambient=224 [kcps]
distance=84 [mm] status=0 signal=11792 [kcps] ambient=216 [kcps]
distance=114 [mm] status=0 signal=18584 [kcps] ambient=360 [kcps]
distance=133 [mm] status=0 signal=18848 [kcps] ambient=272 [kcps]
distance=147 [mm] status=0 signal=18456 [kcps] ambient=272 [kcps]
distance=171 [mm] status=0 signal=9032 [kcps] ambient=712 [kcps]
distance=1746 [mm] status=0 signal=1888 [kcps] ambient=2000 [kcps]
distance=1759 [mm] status=0 signal=2200 [kcps] ambient=2024 [kcps]
distance=1758 [mm] status=0 signal=1952 [kcps] ambient=2080 [kcps]
distance=1769 [mm] status=0 signal=2216 [kcps] ambient=2064 [kcps]
distance=1752 [mm] status=0 signal=2072 [kcps] ambient=2088 [kcps]
distance=1772 [mm] status=0 signal=2880 [kcps] ambient=2024 [kcps]

Issues/PRs references

This PR is a complete rework of PR #10363.

[riot-ci]

Murdock results

✔️ PASSED

7216905 fixup! pkg/driver_vl53l1x_st_api: add ST VL53L1X ULD API as package

Success	Failures	Total	Runtime
10573	0	10573	12m:18s

Artifacts

• Documentation preview

[crasbe]

Is this Ready for Review? :)

[gschorcht]

Is this Ready for Review? :)

I think so.

[gschorcht]

@crasbe BTW, the rework was motivated by the request to pull the 11 thousands line file vl53l1x_register_map.h as a package, which was not as easy. The reason for this is that the old driver version either used the very complex and extensive ST API driver package or implemented the basic functions itself based on the Pololu code. In the latter case, the file ‘vl53l1x_register_map.h’ was required.

For the current implementation, the ST Ultra-Light Driver API is used as a package that provides important functions with significantly lower memory requirements. Instead of implementing the basic functions in the driver itself, the ST Ultra-Light Driver API is now always used as a package, even for the driver variant vl53l1x_basic.

[crasbe]

I did not intend that you have to fully rework the PR, sorry 😅

This is just an initial transfer of the review comments from the last PR.

[gschorcht]

I did not intend that you have to fully rework the PR

That's fine, because the driver is now much less complex.