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 multiobject 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)
•VL53L1 Application Note to describe performances (AN5573)
UM2133 - Rev 6 - October 2020
For further information contact your local STMicroelectronics sales office.
www.st.com
1VL53L1 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
2Ranging functional description
This section briefly describes the functional capabilities of the VL53L1 ranging device.
2.1Ranging 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.2Ranging 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.3Timing 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.4Region-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
3Description 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.2System initialization
The following sections show the API function calls required to perform the system initialization, before starting a
measurement.
3.2.1Wait 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.2DataInit
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.3StaticInit
The VL53L1_StaticInit() function allows device settings, specific for a given use case, to be loaded.
3.2.4Preset 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
4Ranging with the VL53L1
4.1Starting a measurement
The VL53L1_StartMeasurement() function must be called to start a measurement.
4.2Waiting 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.1Driver 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.2Host 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.3Using 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.3Getting 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.1Getting 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.2Getting 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.4Stopping 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.5Single 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.6MultiRangingData 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
0VL53L1_RANGESTATUS_RANGE_VALIDRanging measurement is valid
1VL53L1_RANGESTATUS_SIGMA_FAIL
2VL53L1_RANGESTATUS_SIGNAL_FAIL
VL53L1_RANGESTATUS_RANGE_VALID_MIN_RANG
3
4VL53L1_RANGESTATUS_OUTOFBOUNDS_FAILRaised when the range result is out of bounds.
5VL53L1_RANGESTATUS_HARDWARE_FAILRaised in case of HW or VCSEL failure
VL53L1_RANGESTATUS_RANGE_VALID_NO_WRAP
6
7VL53L1_RANGESTATUS_WRAP_TARGET_FAILWrapped target not matching phases
8VL53L1_RANGESTATUS_PROCESSING_FAIL
9VL53L1_RANGESTATUS_XTALK_SIGNAL_FAIL
10VL53L1_RANGESTATUS_SYNCRONISATION_INTRaised once after start, ranging value has to be ignored.
RangeStatus stringComment
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
ValueRangeStatus stringComment
11
12
13VL53L1_RANGESTATUS_MIN_RANGE_FAIL
14VL53L1_RANGESTATUS_RANGE_INVALIDThe reported range is invalid, ignore it
255VL53L1_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
Loading...
+ 25 hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.