STMicroelectronics VL53L1 User Manual

UM2133
User manual
Time-of-Flight long-distance ranging sensor with advanced multi-zone and multi-
object detection

Introduction

This user manual is applicable for VL53L1 devices. The VL53L1 is a long distance ranging sensor with multi-zone and multi­object detection (see VL53L1 Datasheet).
The purpose of this User Manual is to describe the possible integration models, and for each of them, the set of functions to call to get ranging data using the VL53L1 bare driver.
Figure 1. VL53L1 ranging sensor module

References

VL53L1 Datasheet (DS11786)
UM2133 - Rev 6 - October 2020 For further information contact your local STMicroelectronics sales office.
www.st.com

1 VL53L1 system overview

Host
VL53L1 System
VL53L1
module
VL53L1
Driver
I2C
The VL53L1 system is composed of the VL53L1 module and a driver running on a host.
UM2133
VL53L1 system overview
Figure 2. VL53L1 system
There are two possible integration models for VL53L1 devices, depending on whether the host is a Linux host or not. ST delivers drivers for both of those integration models:
For the non-Linux host, ST delivers a bare-metal driver, referred to as “bare driver” in this document.
For the Linux host, ST delivers a Linux driver
Those drivers allow the user to control the device, to perform processing and output a data structure with ranging values accessible to the host.
This document describes the driver functions accessible to the host, which are used to control the device and get ranging data, for integration with non-Linux hosts.
A separate user manual (UM2326) describes the Linux host integration.
Note: The present document describes the implemented and validated functions.
Any other function available in the drivers should not be used if not described in this document.
The bare driver is provided to be integrated into non-Linux hosts, typically microcontrollers with:
limited memory and computing resources
without OS (bare metal)
or with a small footprint real-time OS
The bare driver is an implementation of a set of functions which uses the VL53L1 device. It makes minimal assumptions regarding OS integration and services. The sequencing of actions, execution/threading model, platform adaptation, and device structure allocation are not part of the bare driver implementation but are left open to the integrator.
The sequencing of bare driver calls must follow a set of rules, defined in this document.
UM2133 - Rev 6
page 2/37

2 Ranging functional description

This section briefly describes the functional capabilities of the VL53L1 ranging device.

2.1 Ranging preset modes

Four ranging preset modes can be used with the VL53L1 bare driver:
1. Ranging mode: This mode aims to get single or multiple (up to 4) object ranging distances.
2. MultiZones scanning mode: This mode allows the multiple region-of-interest (16 maximum per default, and up to 169) to be continuously scanned. It also allows each region-of-interest (ROI) ranging value to be reported one by one. ROI number and sizes are defined by the user before ranging is started.
3. Autonomous mode: This mode allows a programmable inter-measurement period to be periodically scanned. Ranging is done without involvement from the host, allowing the host to go into a low-power state. The host only wakes up upon a measurement interrupt. Programming criteria (distance and/or signal thresholds) allow the device to trigger an interrupt to the host only when the measurement is within the programmed criteria.
4. Lite ranging mode: This mode is obsolete.
Selection of the ranging preset modes is made using the driver function described in Section 3.2.4 Preset mode.
Note: Ranging and MultiZones modes are based on histogram processing
UM2133
Ranging functional description

2.2 Ranging sequence

For all modes, except autonomous mode, the device runs with a handshake mechanism, based on a standard interrupt management scheme.
After each ranging, the host retrieves the ranging data and enables the next ranging by clearing the interrupt. This process is what is referred to as the handshake mechanism.
Next ranging is then triggered if the current one is finished and if the host has cleared the previous pending interrupt.
The interrupt mechanism allows the faster data transfer, without loosing any ranging value due to communication or asynchronism issues. During the handshake phase, the host performs some data processing.
The ranging sequence is functionally described in Figure 3. VL53L1 ranging sequence overview below.
UM2133 - Rev 6
page 3/37
Figure 3. VL53L1 ranging sequence overview
UM2133
Ranging sequence
UM2133 - Rev 6
page 4/37
UM2133
Timing considerations
The handshake sequence allows internal parameters to be computed and applied to the next range.
The handshake must be performed by the user of the bare driver. It is very important to keep the delay as low as possible to enable ranging after a new measurement has been received by the host application. This maintains the desired measurement rate.
Note: Autonomous mode does not require the host to perform any action to continue to range. If the host is too slow to
retrieve a measurement, the data are lost.
Note: In autonomous mode, there is no interrupt raised after init.

2.3 Timing considerations

The timings are presented in Figure 4. VL53L1 Ranging sequence and timing targets.
The host can get the latest available ranging during the ranging timing budget of the current range.
In all modes except Autonomous mode, if a delay to clear the interrupt is introduced by the host, the next ranging will be stopped until the pending interrupt is cleared.
Note: The timings in Figure 4. VL53L1 Ranging sequence and timing targets are example timings and can vary
depending on the user implementation.
The host can change the default timing budget by using a dedicated driver function described in
Section 5.4 Timing budget.
The host can decide to change the timing budget either to synchronize ranging with application, or to increase ranging accuracy.
Note: If tuning parameter to improve accuracy (VL53L1_TUNINGPARM_PHASECAL_PATCH_POWER) is used, the
“init” time can go up to 300 ms.
In the Figure 4. VL53L1 Ranging sequence and timing targets, the “Boot”, “SW standby” and “Init” lasts 40 ms. This time is needed to perform a correct initialization of the device, and it is independent of the platform or the used timing budget. The first range, “Range1”, is not valid, since the wrap-around check is not possible. This means that the first valid ranging value is “Range2”, available after 40 ms, plus twice the timing budget duration.
Figure 4. VL53L1 Ranging sequence and timing targets

2.4 Region-of-interest (ROI)

The user can get a ranging result on a specific part of the field of view (FoV), using ROIs.
A driver function is dedicated to this setup (see Section 5.1 Single ROI).
UM2133 - Rev 6
page 5/37

3 Description of basic bare driver functions

This section describes the driver function call flows that should be followed to perform a ranging measurement using the VL53L1.
The VL53L1 drivers are used in two classes of applications:
Factory applications (factory flow): this flow is used for device calibration, typically when a product is tested at the end of manufacturing.
Field applications (ranging flow): this flow gathers all end user applications using the VL53L1 device.
UM2133
Description of basic bare driver functions
3.1

Bare driver

The bare driver factory flow is described in the following figure.
Figure 5. L53L1 API calibration flow (factory)
UM2133 - Rev 6
The bare driver ranging flow is described in Figure 6. VL53L1 API ranging flow (field). Please note that between the SetCalibrationData() and StartMeasurement(), some important functions are shown as an example, but the list is not complete. Parameters such as timing budget, offset correction mode, or smudge correction, can be set at this time as well.
page 6/37
Figure 6. VL53L1 API ranging flow (field)
UM2133
Bare driver
UM2133 - Rev 6
page 7/37
UM2133
System initialization

3.2 System initialization

The following sections show the API function calls required to perform the system initialization, before starting a measurement.

3.2.1 Wait for boot

The VL53L1_WaitDeviceBooted() function ensures that the device is booted and ready.
It is not mandatory to call this function.
Note: This function blocks the host execution. This function should not block for more than 4 ms, assuming 400 kHz
I2C and 2 ms latency per transaction.

3.2.2 DataInit

The VL53L1_DataInit() function is called only once, to perform the device initialization after the device is reset.
After calling the VL53L1_DataInit() function, the calibration data must be loaded using the function VL53L1_SetCalibrationData().

3.2.3 StaticInit

The VL53L1_StaticInit() function allows device settings, specific for a given use case, to be loaded.

3.2.4 Preset mode

The VL53L1_SetPresetMode() function allows one preset mode to be chosen.
The following preset modes are available using this driver revision:
VL53L1_PRESETMODE_RANGING
VL53L1_PRESETMODE_MULTIZONES_SCANNING
VL53L1_PRESETMODE_LITE_RANGING (Obsolete)
VL53L1_PRESETMODE_AUTONOMOUS
The default preset mode is VL53L1_PRESETMODE_RANGING.
UM2133 - Rev 6
page 8/37

4 Ranging with the VL53L1

4.1 Starting a measurement

The VL53L1_StartMeasurement() function must be called to start a measurement.

4.2 Waiting for a result: polling or using an interrupt

To check if a measurement is available, the host can:
Call a polling function
Poll on a driver function
Use a physical interrupt

4.2.1 Driver polling to get the result status

The function VL53L1_WaitMeasurementDataReady() polls on an internal status until a measurement is ready.
Note: This function is a blocking function since internal polling is performed.

4.2.2 Host polling to get the result status

The host can poll on the function VL53L1_GetMeasurementDataReady() to know when a new measurement is ready.
Note: This function is not a blocking function.
UM2133
Ranging with the VL53L1

4.2.3 Using a physical interrupt

An alternative and preferred way to get the ranging status is to use the physical interrupt output. By default, the GPIO1 goes low when a new measurement is ready.
This pin is an output pin only; there is no input interrupt pin on this device.
The interrupt must be cleared by calling the driver function: VL53L1_ClearInterruptAndStartMeasurement().

4.3 Getting a measurement

Depending on the selected mode, the hardware collects a single data measurement or a set of data measurements per ranging loop:
In autonomous mode, only a single measurement is reported per ranging.
In ranging mode, multiple objects can be detected per ranging, and data measurements are reported per object
In multizone scanning mode, multiple zones of the FoV are scanned, and data measurements are reported per zone.
The bare driver provides two functions to select whether single ranging data or multiple ranging data are returned:
The “Get a single data” function is only available in autonomous mode. This function should not be used in ranging and multizone scanning modes.
The “Get multiple data” function is only available in ranging and multizone scanning modes. This function should not be used in autonomous mode.
Note: Two consecutive calls to get a measurement function is not allowed if the interrupt is not cleared between the
two calls.

4.3.1 Getting a single ranging value

The VL53L1_GetRangingMeasurementData() can be used to get a single ranging data.
When calling this function to get the device ranging results, a structure called VL53L1_RangingMeasurementData_t is returned.
This structure is described in Section 4.5 Single ranging measurement data structure.
UM2133 - Rev 6
page 9/37

4.3.2 Getting multiple ranging values

The VL53L1_GetMultiRangingData() can be used to get multiple ranging data.
When calling this function to get the device multiple ranging results, a structure called VL53L1_MultipleRangingData_t is returned.
This structure is described in Section 5 Description of additional driver functions.

4.4 Stopping a measurement

In continuous mode, the host can stop the measurement by calling the VL53L1_StopMeasurement() function.
If the stop request occurs during a range measurement, the measurement is aborted immediately.

4.5 Single ranging measurement data structure

The VL53L1_RangingMeasurementData_t structure is composed of:
TimeStamp: not implemented
StreamCount: this 8-bit integer gives a counter incremented at each range. The value first starts at 0, incrementing to 255, and then incrementing from 128 to 255.
RangingQualityLevel: not implemented
SignalRateRtnMegaCps: this value is the return signal rate in MegaCountPer Second (MCPS). This is a
16.16 fixed point value.To obtain a real value, it should be divided by 65536.
AmbientRateRtnMegaCps: this value is the return ambient rate (in MCPS). It is a 16.16 fixed point value, which is effectively a measure of the infrared light. To obtain a real value, it should be divided by 65536.
EffectiveSpadRtnCount: this is a16-bit integer that returns the effective SPAD count for the current ranging. To obtain a real value, it should be divided by 256.
SigmaMilliMeter: this 16.16 fixed point value is an estimation of the standard deviation of the current ranging, expressed in millimeters. To obtain a real value, it should be divided by 65536.
RangeMilliMeter: this is a 16-bit integer giving the range distance in millimeters.
RangeFractionalPart: not implemented
RangeStatus: this is an 8-bit integer giving the range status for the current measurement. Value = 0 means the ranging is valid (refer to Table 1. Range status).
ExtendedRange: this is a 8-bit integer indicating if the range has been unwrapped (only for long distances, using Ranging Mode)
UM2133
Stopping a measurement

4.6 MultiRangingData structure

When using ranging or multizone scanning modes, the returned structure is called: VL53L1_MultiRangingData_t and contains the following data:
TimeStamp: not implemented
StreamCount: this 8-bit integer gives a counter incremented at each range. The value first starts at 0, incrementing to 255, and then incrementing from 128 to 255.
RoiNumber: this is an 8-bit integer value that gives the ROI the range data is related to.
NumberOfObjectsFound: this 8-bit integer value gives the number of objects found in the current ROI.
RoiStatus: it gives the status of the current ROI. The value of this field can be 0, 1 or 2, for “invalid ROI”, “valid ROI”, “valid and last ROI” respectively. This is mainly used to flag the last ROI for synchronization, when the scanning mode is used.
RangeData[VL53L1_MAX_RANGE_RESULTS]: this is a table structure of type VL53L1_TargetRangeData_t, giving the results per ROI (see description below for more details). The maximum number of objects is given by VL53L1_MAX_RANGE_RESULTS and, by default, is equal to four.
HasXtalkValueChanged: this 8-bit integer value indicates if the crosstalk value has been changed.
EffectiveSpadRtnCount: this is a16-bit integer that returns the effective SPAD count for the current ranging. To obtain a real value, it should be divided by 256.
DmaxMilliMeter: this is a 16-bit integer. When the target is not detected, and the ranging is valid (range status 255 only), no object can be detected between zero and dmax. This value can help the host algorithm when no valid ranging data is found.
UM2133 - Rev 6
page 10/37
UM2133
MultiRangingData structure
RecommendedDistanceMode: this is a value with VL53L1_DistanceModes type. It indicates the distance mode that is recommended based on the ranging conditions, in order to get the best accuracy, focusing on the detected objects.
The VL53L1_TargetRangeData_t structure is composed of:
RangingQualityLevel: not implemented.
RangeMaxMilliMeter: this a 16-bit integer, giving the larger detected distance.
RangeMinMilliMeter: this is a 16-bit integer, giving the smaller detected distance.
SignalRateRtnMegaCps: this value is the return signal rate in MegaCountPer Second (MCPS). This is a
16.16 fixed point value. To obtain a real value, it should be divided by 65536.
AmbientRateRtnMegaCps: this value is the return ambient rate (in MCPS). It is a 16.16 fixed point value, which is effectively a measure of the amount of light hitting the SPAD matrix. To obtain a real value, it should be divided by 65536.
SigmaMilliMeter: this 16.16 fixed point value is an estimation of the standard deviation of the current ranging, expressed in millimeters. To obtain a real value, it should be divided by 65536.
RangeMilliMeter: this is a 16-bit integer giving the range distance in millimeters.
RangeFractionalPart: not implemented.
RangeStatus: this is an 8-bit integer giving the range status for the current measurement. Value = 0 means the ranging is valid (refer to Table 1. Range status).
For the multi ranging data structure only (ranging and multizones scanning modes), a particular behavior is implemented when the target is not detected. If the target is not detected, and the measurement is valid, the following values are reported into the VL53L1_TargetRangeData_t structure:
RangeMaxMilliMeter: forced to 8191.
RangeMinMilliMeter: forced to 8191.
SignalRateRtnMegaCps: forced to 0.
AmbientRateRtnMegaCps: the ambient rate value is normally computed.
SigmaMilliMeter: forced to 0.
RangeMilliMeter: forced to 8191.
RangeStatus: forced to 255.
Table 1. Range status
Value
0 VL53L1_RANGESTATUS_RANGE_VALID Ranging measurement is valid
1 VL53L1_RANGESTATUS_SIGMA_FAIL
2 VL53L1_RANGESTATUS_SIGNAL_FAIL
VL53L1_RANGESTATUS_RANGE_VALID_MIN_RANG
3
4 VL53L1_RANGESTATUS_OUTOFBOUNDS_FAIL Raised when the range result is out of bounds.
5 VL53L1_RANGESTATUS_HARDWARE_FAIL Raised in case of HW or VCSEL failure
VL53L1_RANGESTATUS_RANGE_VALID_NO_WRAP
6
7 VL53L1_RANGESTATUS_WRAP_TARGET_FAIL Wrapped target not matching phases
8 VL53L1_RANGESTATUS_PROCESSING_FAIL
9 VL53L1_RANGESTATUS_XTALK_SIGNAL_FAIL
10 VL53L1_RANGESTATUS_SYNCRONISATION_INT Raised once after start, ranging value has to be ignored.
RangeStatus string Comment
Raised if sigma estimator check is above the internal
defined threshold. Sigma estimator gives qualitative
Raised in autonomous mode only if signal value is
Raised in autonomous mode only if ranging is below a
E_CLIPPED
_CHECK_FAIL
Internal algorithm underflow or overflow in autonomous
Raised in autonomous modes when signal is below the
information about the signal.
below the internally defined threshold.
threshold defined in the tuning parameter.
No wraparound check has been done
ranging.
crosstalk threshold.
UM2133 - Rev 6
page 11/37
UM2133
MultiRangingData structure
Value RangeStatus string Comment
11
12
13 VL53L1_RANGESTATUS_MIN_RANGE_FAIL
14 VL53L1_RANGESTATUS_RANGE_INVALID The reported range is invalid, ignore it
255 VL53L1_RANGESTATUS_NONE
VL53L1_RANGESTATUS_RANGE_VALID_MERGED_
PULSE
VL53L1_RANGESTATUS_TARGET_PRESENT_LACK_
OF_SIGNAL
Note: The very first measurement does not include a wraparound check. This ranging measurement should be
discarded. When VL53L1_PRESETMODE_AUTONOMOUS is used, the driver deletes the first ranging value.
Note: Range status 1 is often caused by noisy measurements. sigma estimator is strongly impacted by the SNR of the
treated signals.
Note: Range status 4 is raised when some error on the measurement reference occurs. This can cause outliers as
negative measurements or extremely high ranging values.
Raised in ranging and multizone scanning modes only.
Range is OK, but the distance reported is the result of
multiple targets merged together.
Indicates that there is a target, but the signal is too low
to report ranging
Programmed ROI is not valid, selected ROI is out of the
SPAD array.
Single ranging value: ranging is not updated, ignore
reported value
Multiple ranging values: target not detected.
UM2133 - Rev 6
page 12/37
+ 25 hidden pages