ST UM2884 User manual

Introduction
The purpose of this user manual is to explain how to handle the VL53L5CX Time-of-Flight (ToF) sensor, using the ultra lite driver
(ULD) API. It describes the main functions to program the device, the calibrations, and the output results.
The VL53L5CX is a state of the art, ToF, multizone ranging sensor enhancing the ST FlightSense product family. Housed in
a miniature reflowable package, it integrates a SPAD array, physical infrared filters, and diffractive optical elements (DOE) to
achieve the best ranging performance in various ambient lighting conditions with a range of cover glass materials.
Multizone distance measurements are possible up to 8x8 zones with a wide 63 ° diagonal field of view (FoV) which can be
reduced by software. Each zone of the VL53L5CX measures the distance of the target up to 4 meters, at a maximum frequency
of 60 Hz.
Thanks to ST Histogram patented algorithms, the VL53L5CX is able to detect different objects within the FoV. The Histogram
also provides immunity to cover glass crosstalk beyond 60 cm.
Figure 1. VL53L5CX sensor module
References
1. VL53L5CX datasheet (DS13754)
A guide to using the VL53L5CX multizone Time-of-Flight ranging sensor with
wide field of view Ultra Lite Driver (ULD)
UM2884
User manual
UM2884 - Rev 2 - August 2021
For further information contact your local STMicroelectronics sales office.
www.st.com

1Acronyms and abbreviations
Acronym/abbreviation Definition
DOE diffractive optical element
FoV field of view
I2C inter-integrated cirduit (serial bus)
Kcps/SPAD Kilo-count per second per spad (unit used to quantify the
number of photons into the SPAD array)
RAM random access memory
SCL serial clock line
SDA serial data
SPAD single photon avalanche diode
ToF Time-of-Flight
ULD ultra lite driver
VCSEL vertical cavity surface emitting diode
Xtalk crosstalk
UM2884
Acronyms and abbreviations
UM2884 - Rev 2 page 2/19

2Functional description
2.1 System overview
The VL53L5CX system is composed of a hardware module and the ultra lite driver software (VL53L5CX ULD)
running on a host (see figure below). The hardware module contains the ToF sensor. ST delivers the software
driver which is referred to in this document as "the driver". This document describes the functions of the driver
which are accessible to the host. These functions control the sensor and get the ranging data.
Figure 2. VL53L5CX system overview
2.2 Effective orientation
The module includes a lens over the RX aperture which flips (horizontally and vertically) the captured image of the
target. As a consequence, the zone identified as zone 0 in the bottom left of the SPAD array is illuminated by a
target located at the top right-hand side of the scene.
Figure 3. VL53L5CX effective orientation
UM2884
Functional description
UM2884 - Rev 2 page 3/19

2.3 Schematics and I2C configuration
The communication between driver and firmware is handled by I2C, with a capability of operating up to 1 MHz.
The implementation requires pull-ups on the SCL and SDA lines. Please see VL53L5CX datasheet for more
information.
The VL53L5CX device has a default I2C address of 0x52. However, it is possible to change the default address
to avoid conflicts with other devices, or facilitate adding multiple VL53L5CX modules to the system for a greater
system FoV. The I2C address can be changed using vl53l5cx_set_i2c_address() function.
Figure 4. Multiple sensors on I2C bus
To allow a device to have its I2C address changed without affecting others on the I2C bus, it is important to
disable the I2C communication of the devices not being changed. The procedure is the following one :
1. Power up the system as normal.
2. Pull down the LPn pin of the device that will not have its address changed.
3. Pull up the LPn pin of the device that has the I2C address changed.
4. Program the I2C address to the device using function set_i2c_address() function.
5. Pull up the LPn pin of the device not being reprogrammed.
All devices should now be available on the I2C bus. Repeat the above steps for all the VL53L5CX devices in the
system that require a new I2C address.
UM2884
Schematics and I2C configuration
UM2884 - Rev 2 page 4/19

3Package content and data flow
3.1 Driver architecture and content
The VL53L5CX ULD package is composed of four folders. The driver is located in folder /VL53L5CX_ULD_API.
The driver is composed of mandatory and optional files. Optional files are plugins used to extend ULD features.
Each plugin starts with the word “vl53l5cx_plugin” (e.g vl53l5cx_plugin_xtalk.h). If the user does not want
the proposed plugins, they can be removed without impacting the other driver features. The following figure
represents the mandatory files and the optional plugins.
Figure 5. Driver architecture
The user also needs to implement two files located in the /Platform folder. The proposed platform is an empty
shell, and must be filled with dedicated functions.
Note: Platform.h file contains mandatory macros to use the ULD. All the file content is mandatory to correctly use the
ULD.
UM2884
Package content and data flow
UM2884 - Rev 2 page 5/19

3.2 Calibration flow
Crosstalk (xtalk) is defined as the amount of signal received on the SPAD array which is due to VCSEL light
reflection inside the protective window (cover glass) added on top of the module. The VL53L5CX module is
self-calibrated, and can be used without any additional calibration.
Xtalk calibration may be required if the module is protected by a coverglass. The VL53L5CX is immune to xtalk
beyond 60 cm thanks to an histogram algorithm, but at short distances below 60 cm, xtalk can be larger than the
actual returned signal, giving a false target reading or making targets appear closer than they really are. All xtalk
calibration functions are included in a xtalk plugin (optional). The user needs to use the file ‘vl53l5cx_plugin_xtalk’.
The xtalk can be calibrated once, and data can be saved to be re-used later. A target at fixed distance, with a
known reflectance is required. The minimum distance required is 600 mm, and the target must cover the whole
FoV. Depending on the setup, the user can modify settings in order to adapt the Xtalk calibration, as proposed in
the following table.
Table 1. Available settings for calibration
Setting Min Proposed by ST Max
Distance [mm] 600 600 3000
Number of samples 1 4 16
Reflectance [%] 1 3 99
Note: Increasing the number of samples increases the accuracy, but it also increases the time for calibration. The time
relative to the number of samples is linear, and values follow the approximate timeout:
• 1 sample ≈ 1 second
• 4 samples ≈ 2.5 seconds
• 16 samples ≈ 8.5 seconds
The calibration is performed using function vl53l5cx_calibrate_xtalk(). This function can be used at any time.
However, the sensor must be initialized first. The following figure represents the Xtalk calibration flow.
Figure 6. Xtalk calibration flow
UM2884
Calibration flow
UM2884 - Rev 2 page 6/19

3.3 Ranging flow
The following figure represents the ranging flow used to get measurements. Xtalk calibration and optional function
calls must be used before starting the ranging session. The get/set functions cannot be used during a ranging
session, and 'on-the-fly' programming is not supported.
Figure 7. Ranging flow using VL53L5CX
UM2884
Ranging flow
UM2884 - Rev 2 page 7/19

4Available features
The VL53L5CX ULD API includes several functions which allow the user to tune the sensor, depending on the
usecase. All functions available for the driver are described in the following sections.
4.1 Initialization
Initialization must be done before using the VL53L5CX sensor. This operation requires the user to:
1. Power on the sensor (VDDIO, AVDD, LPn pins set to High, and pin I2C_RST set to 0)
2. Call the function vl53l5cx_init(). The function copies the firmware (~84 kbytes) to the module by loading the
code over the I2C interface and performing a boot routine to complete the initialization.
4.2 Sensor reset management
To reset the device, the following pins needs to be toggled:
1. Set pins VDDIO, AVDD, and LPn pins to low.
2. Wait 10 ms.
3. Set pins VDDIO, AVDD, and LPn pins to high.
Note: Toggling only I2C_RST pin resets the I2C communication.
4.3 Resolution
The resolution corresponds to the number of available zones. The VL53L5CX sensor has two possible
resolutions: 4x4 (16 zones) and 8x8 (64 zones). By default the sensor is programmed in 4x4.
The function vl53l5cx_set_resolution() allows the user to change the resolution. As the ranging frequency
depends on the resolution, this function must be used before updating the ranging frequency. Moreover, changing
the resolution also increases the traffic size on the I2C bus when results are read.
4.4 Ranging frequency
Ranging frequency can be used to change the measurement frequency. As the maximum frequency is different
between 4x4 and 8x8 resolutions, this function needs to be used after choosing a resolution. The minimum and
maximum allowed values are listed in the following table.
Table 2. Minimum and maximum ranging frequencies
Resolution Min ranging frequency [Hz] Max ranging frequency [Hz]
4x4 1 60
8x8 1 15
Ranging frequency can be updated using function vl53l5cx_set_ranging_frequency_hz(). By default, the ranging
frequency is set to 1 Hz.
UM2884
Available features
UM2884 - Rev 2 page 8/19

4.5 Ranging mode
Ranging mode allows the user to choose between ranging in high performance or low power consumption.
There are two modes proposed:
• Continuous: The device continuously grabs frames with a ranging frequency defined by user. The VCSEL
is enabled during all ranging, so maximum ranging distance and ambient immunity are better. This mode is
advised for fast ranging measurements or high performances.
• Autonomous: This is the default mode. The device continuously grabs frames with a ranging frequency
defined by the user. The VCSEL is enabled during a period defined by the user, using function
vl53l5cx_set_integration_time_ms(). As the VCSEL is not always enabled, the power consumption is
reduced. The benefits are more obvious with a reduced ranging frequency. This mode is advised for low
power applications.
The ranging mode can be changed using function vl53l5cx_set_ranging_mode().
4.6 Integration time
Integration time is a feature only available using Autonomous ranging mode (refer to Section 4.5 Ranging
mode). It allows the user to change the time while VCSEL is enabled. Changing integration time if Ranging mode
is set to continuous has no effect. The default integration time is set to 5 ms.
The effect of integration time is different for 4x4 and 8x8 resolutions. Resolution 4x4 is composed of one
integration time, and 8x8 resolution is composed of four integration times. The following figures represent the
VCSEL emission for both resolutions.
Figure 8. Integration time for 4x4 autonomous
Figure 9. Integration time for 8x8 autonomous
The sum of all integration times + 1 ms overhead must be lower than the measurement period, otherwise the
ranging period will be automatically increased.
UM2884
Ranging mode
UM2884 - Rev 2 page 9/19

4.7 Power modes
Power modes can be used to reduce the power consumption when the device is not used. The VL53L5CX can
operate in one of the following power modes:
• Wake-up: The device is set in HP idle (high power), waiting for instructions.
• Sleep: The device is set in LP idle (low power), the low power state. The device cannot be used until set in
Wake-up mode. This mode retains the firmware and the configuration.
The power mode can be changed using function vl53l5cx_set_power_mode(). The default mode is Wake-up.
Note: If the user wants to change the power mode, the device must not be in a ranging state.
4.8 Sharpener
The signal returned from a target is not a clean pulse with sharp edges. The edges slope away and may affect the
distances reported in adjacent zones. The sharpener is used to remove some or all of the signal caused by veiling
glare.
The example shown in the following figure represents a close target at 100 mm centered in the FoV, and another
target, further behind at 500 mm. Depending on the sharpener value, the close target may appear in more zones
than the real one.
Figure 10. Example of scene using several sharpener values
Sharpener can be changed using function vl53l5cx_set_sharpener_percent(). The allowed values are between
0 % and 99 %. The default is 5 %.
UM2884
Power modes
UM2884 - Rev 2 page 10/19

4.9 Target order
The VL53L5CX can measure several targets per zone. Thanks to the histogram processing, the host is able to
choose the order of reported targets. There are two options:
• Closest: The closest target is the first reported
• Strongest: The strongest target is the first reported
The target order can be changed using function vl53l5cx_set_target_order(). The default order is Strongest.
The example in the following figure represents the detection of two targets. One at 100 mm with a low reflectance,
and one at 500 mm with a high reflectance.
Figure 11. Example of histogram with 2 targets
4.10 Multiple targets per zone
The VL53L5CX can measure up to four targets per zone. The user can configure the number of targets returned
by the sensor.
The selection is not possible from the driver; it has to be done in the ‘platform.h’ file. The macro
VL53L5CX_NB_ TARGET_PER_ZONE needs to be set to a value between 1 and 4. The target order described
in Section 4.9 Target order will directly impact the order of detected target. By default, the sensor only outputs a
maximum of one target per zone.
Note: An increased number of targets per zone will increase the required RAM size.
4.11 Xtalk margin
The Xtalk margin is an additional feature only available using the plugin Xtalk. The .c and .f files
'vl53l5cx_plugin_xtalk' need to be used.
The margin is used to change the detection threshold when a coverglass is present on the top of the sensor. The
threshold can be increased to ensure that the coverglass is never detected, after setting Xtalk calibration data.
For example, the user can run a Xtalk calibration on one single device, and re-use the same calibration data for
all other devices. The Xtalk margin can be used to tune the Xtalk correction. The figure below represents the Xtalk
margin.
Figure 12. Xtalk margin
UM2884
Target order
UM2884 - Rev 2 page 11/19

4.12 Detection thresholds
In addition to the regular ranging capabilities, the sensor can be programmed to detect an object under certain
predefined criteria. This feature is available using the plugin "detection thresholds", which is an option not
included by default in the API. The files called ‘vl53l5cx_plugin_detection_thresholds’ need to be used.
The feature can be used to trigger an interrupt to pin A3 (INT) when conditions defined by the user are met. There
are three possible configurations:
• Resolution 4x4: using 1 threshold per zone (total of 16 thresholds)
• Resolution 4x4: using 2 thresholds per zone (total of 32 thresholds)
• Resolution 8x8: using 1 threshold per zone (total of 64 thresholds)
Whatever the configuration used, the procedure for creating thresholds and the RAM size are the same. For each
threshold combination, several fields need to be filled:
• Zone id: id of the selected zone (refer to Section 2.2 Effective orientation)
• Measurement: measurement to catch (distance, signal, number of SPADs, …)
• Type: windows of measurements (in windows, out of windows, below low threshold, …)
• Low threshold: low threshold user for trigger. User does not need to set the format, it is automatically
handled by the API.
• High threshold: high threshold user for trigger. User does not need to set the format, it is automatically
handled by the API.
• Mathematic operation: only used for 4x4 – 2 threshold combinations per zone. The user can set a
combination using several thresholds in one zone.
4.13 Motion indicator
The VL53L5CX sensor has an embedded Firmware feature allowing motion detection in a scene. The
motion indicator is computed between sequential frames. This option is available using the plugin
‘vl53l5cx_plugin_motion_indicator’.
The motion indicator is initialized using the vl53l5cx_motion_indicator_init() function. If the user wants to
change the sensor resolution, he must update the motion indicator resolution using the dedicated function:
vl53l5cx_motion_indicator_set_resolution().
The user may also change the minimum and maximum distances for detecting motion. The difference between
the minimum and maximum distances cannot be greater than 1500 mm. By default, distances are initialized with
values between 400 mm and 1500 mm.
Results are stored in the field ‘motion_indicator’. In this field, the array ‘motion’ gives a value containing the
motion intensity per zone. A high value indicates high motion variation between frames. A typical movement
gives a value between 100 and 500. This sensitivity depends on the integration time, target distance, and target
reflectance.
An ideal combination for low power applications is the use of the motion indicator with Autonomous ranging mode,
and detection thresholds programmed on the motion. This allows detection of movement variations in the FoV
with minimum power consumption.
UM2884
Detection thresholds
UM2884 - Rev 2 page 12/19

5Ranging results
5.1 Available data
An extensive list of target and environment data may be output during ranging activities. The following table
describes the parameters available to the user.
Table 3. Available output using VL53L5CX sensor
Element Nb bytes (RAM) Unit Description
Ambient per SPAD 256 Kcps/SPAD
Ambient rate measurement performed on the
SPAD array, with no active photon emission, to
measure the ambient signal rate due to noise.
Number of targets
detected 64 None
Number of detected targets in the current zone.
This value should be the first one to check to
know a measurement validity.
Number of SPADs
enabled 256 None
Number of SPADs enabled for the current
measurement. A far or low reflective target will
activate more SPADs.
Signal per SPAD 256 x nb targets
programmed Kcps/SPAD Quantity of photons measured during the VCSEL pulse.
Range sigma 128 x nb targets
programmed Millimeter Sigma estimator for the noise in the reported target distance.
Distance 128 x nb targets
programmed Millimeter Target distance
Target status 64 x nb targets
programmed None Measurements validity. See Section 5.5 Results interpretation for more information.
Reflectance 64 x number targets
programmed Percent Estimated target reflectance in percent
Motion indicator 140 None Structure containing the motion indicator results.
The field 'motion' contains the motion intensity.
Note: For several elements (signal per spad, sigma, …) access to data is different if user has programmed more than
1 target per zone (see Section 4.10 Multiple targets per zone). See example codes for more information.
5.2 Customize output selection
By default, all VL53L5CX outputs are enabled. If needed, the user can disable some sensor output.
Disabling measurements is not available on the driver; it must be performed in the ‘platform.h’ file. The user can
declare the following macros to disable outputs:
#define VL53L5CX_DISABLE_AMBIENT_PER_SPAD
#define VL53L5CX_DISABLE_NB_SPADS_ENABLED
#define VL53L5CX_DISABLE_NB_TARGET_DETECTED
#define VL53L5CX_DISABLE_SIGNAL_PER_SPAD
#define VL53L5CX_DISABLE_RANGE_SIGMA_MM
#define VL53L5CX_DISABLE_DISTANCE_MM
#define VL53L5CX_DISABLE_TARGET_STATUS
#define VL53L5CX_DISABLE_REFLECTANCE_PERCENT
#define VL53L5CX_DISABLE_MOTION_INDICATOR
Consequently, the fields will not be declared in the results structure, and the data will not be transferred to the
host. The RAM size and I2C size are reduced.
To ensure data consistency, ST recommends to always keep ‘number of target detected’ and ‘target status’
enabled. It allows filtering the measurements depending of the target status (refer to Section 5.5 Results
interpretation).
UM2884
Ranging results
UM2884 - Rev 2 page 13/19

5.3 Getting ranging results
During the ranging session, there are two ways to know if new ranging data is available:
• Polling mode: Continuously uses function vl53l5cx_check_data_ready(). It will detect a new stream count
returned by the sensor.
• Interrupt mode: Waits for an interrupt raised on pin A3 (GPIO1). The interrupt is automatically cleared after
~100 μs.
When new data is ready, the results can be read using function vl53l5cx_get_ranging_data(). It will return an
updated structure containing all selected output. As the device is asynchronous, there is no interrupt to clear to
continue the ranging session.
This feature is available for both Continuous and Autonomous ranging modes.
5.4 Using raw firmware format
After transferring ranging data through I2C, there is a conversion between the firmware format and the host
format. This operation is typically performed to have a ranging distance in millimeters as a default output of the
sensor. If the user wants to use the firmware format, the following macro must be defined in the platform file:
#define VL53L5CX_USE_RAW_FORMAT
5.5 Results interpretation
The data returned by the VL53L5CX can be filtered in order to take into account the target status. The status
indicates the measurement validity. The full status list is described in the following table.
Table 4. List of available target status
Target status Description
0 Ranging data are not updated
1 Signal rate too low on SPAD array
2 Target phase
3 Sigma estimator too high
4 Target consistency failed
5 Range valid
6 Wrap around not performed (Typically the first range)
7 Rate consistency failed
8 Signal rate too low for the current target
9 Range valid with large pulse (may be due to a merged target)
10 Range valid, but no target detected at previous range
11 Measurement consistency failed
12 Target blurred by another one, due to sharpener
13 Target detected but inconsistent data. Frequently happens for secondary targets.
255 No target detected (only if number of target detected is enabled)
To have consistent data, the user needs to filter invalid target status. To give a confidence rating, a target with
status 5 is considered as 100 % valid. A status of 6 or 9 can be considered with a confidence value of 50 %. All
other statuses are below 50 % confidence level.
UM2884
Getting ranging results
UM2884 - Rev 2 page 14/19

5.6 Driver errors
When an error occurs using VL53L5CX sensor, the driver returns a specific error. The following table lists the
possible errors.
Table 5. List of errors available using the driver
Target status Description
0 No error
127 User programmed an incorrect setting (unknown resolution, ranging frequency too
high, …)
255 Major error. Usually a timeout error, due to an I2C error.
other Combination of multiple errors described above
Note: More error codes can be implemented by the host using the platform files.
UM2884
Driver errors
UM2884 - Rev 2 page 15/19

Revision history
Table 6. Document revision history
Date Version Changes
21-Jun-2021 1 Initial release
30-Aug-2021 2 Added Section 5.4 Using raw firmware format
Added new target status 13 in Table 4. List of available target status
UM2884
UM2884 - Rev 2 page 16/19

Contents
1Acronyms and abbreviations ......................................................2
2Functional description .............................................................3
2.1 System overview ...............................................................3
2.2 Effective orientation ............................................................3
2.3 Schematics and I2C configuration ................................................4
3Package content and data flow.....................................................5
3.1 Driver architecture and content ...................................................5
3.2 Calibration flow ................................................................6
3.3 Ranging flow ..................................................................7
4Available features .................................................................8
4.1 Initialization ...................................................................8
4.2 Sensor reset management.......................................................8
4.3 Resolution ....................................................................8
4.4 Ranging frequency .............................................................8
4.5 Ranging mode .................................................................9
4.6 Integration time ................................................................9
4.7 Power modes.................................................................10
4.8 Sharpener ...................................................................10
4.9 Target order ..................................................................11
4.10 Multiple targets per zone .......................................................11
4.11 Xtalk margin ..................................................................11
4.12 Detection thresholds ...........................................................12
4.13 Motion indicator ...............................................................12
5Ranging results...................................................................13
5.1 Available data ................................................................13
5.2 Customize output selection .....................................................13
5.3 Getting ranging results .........................................................14
5.4 Using raw firmware format ......................................................14
5.5 Results interpretation ..........................................................14
UM2884
Contents
UM2884 - Rev 2 page 17/19

5.6 Driver errors..................................................................15
Revision history .......................................................................16
Contents ..............................................................................17
UM2884
Contents
UM2884 - Rev 2 page 18/19

IMPORTANT NOTICE – PLEASE READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST
products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST
products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of
Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www.st.com/trademarks. All other product or service
names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2021 STMicroelectronics – All rights reserved
UM2884
UM2884 - Rev 2 page 19/19