Adafruit VL53L4CD User Manual

UM2931

User manual

A guide to using the VL53L4CD Ultra Lite Driver (ULD)

Introduction

The VL53L4CD is a state of the art, Time-of-Flight (ToF), laser-ranging sensor enhancing the ST FlightSense product family.
Housed in a miniature reflowable package, it integrates a SPAD array, physical infrared filters, and an integrated firmware to
achieve the best ranging performance in various ambient lighting conditions with a range of cover glass materials.

The purpose of this user manual is to handle the VL53L4CD Time-of-Flight sensor, using the Ultra Lite Driver (ULD) API. It
describes the main functions to program the device, the calibrations, and the output results.

Figure 1. VL53L4CD module

References:

1. VL53L4CD datasheet (DS13812)

UM2931 - Rev 1 - September 2021
For further information contact your local STMicroelectronics sales office.

www.st.com

1 Functional description

1.1 System overview

The VL53L4CD system is composed of a hardware module and the Ultra Lite Driver software (VL53L4CD 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.

UM2931

Functional description

Figure 2. VL53L4CD system overview

1.2

Schematics and I2C configuration

The communication between driver and firmware is handled by I2C, with a capability of operating up to 1 MHz
(Fast Mode Plus). The implementation requires pull-ups on the SCL and SDA lines. Refer to the VL53L4CD
datasheet (DS13812) for more information.

By default, the sensor is programmed to run on I2C Fast Mode (up to 400 kHz). The Fast Mode Plus (up to
1 MHz) can be enabled using a platform compilation key in the file platform.h:

#define VL53L4CD_I2C_FAST_MODE_PLUS

The VL53L4CD device has a default I2C address of 0x52. However, it is possible to change the default address
to avoid conflict with other devices, or facilitate adding multiple VL53L4CD modules to the system for a greater
system Field of View. The I2C address can be reprogrammed using function VL53L4CD_SetI2CAddress().

The following figure represents the required connection to have multiple sensors on a single I2C bus. For the
schematics, please refer to the VL53L4CD datasheet.

UM2931 - Rev 1

page 2/15

Figure 3. Multiple sensors on I2C bus

UM2931

Schematics and I2C configuration

The host hardware design must ensure the sensor XSHUT pins can be controlled individually. Each XSHUT pin
must be connected to a host MCU GPIO pin.

To change the I2C address, the host must :

1. Put the device in HW standby by setting the XSHUT pin low on all the VL53L4CD devices

2. Raise the XSHUT pin of one of the VL53L4CD (e.g. current_tof)

3. Call VL53LX_SetDeviceAddress(current_tof, newAddress) to program the new address

4. Repeat the steps from [2 to 3] to change the address of all ToFs.

UM2931 - Rev 1

page 3/15

2 Package content and data flow

2.1 Driver architecture and content

The VL53L4CD Ultra Lite driver package is composed of four folders. The driver is located in folder /
VL53L4CD_ULD_API. The following figure represents the driver architecture.

Figure 4. Driver architecture

UM2931

Package content and data flow

User also needs to implement two files located into the /Platform folder. The proposed platform is an empty
dummy, and must be filled with dedicated functions.

Note: Platform.h file contains mandatory macros to use ULD. All the file content is mandatory to correctly use the ULD.

2.2 Calibrations

To benefit from the full performance of the sensor, the VL53L4CD driver includes two calibration functions (offset
and crosstalk) which need to be run once at the production line. These calibration procedures have to be run to
compensate for device-to-device variation (i.e. when the absolute measured distance is not the same from one
device to another) and the presence of the cover glass that may affect the device ranging performances.

2.2.1 Calibration order

Calibration data, stored in the host system, have to be loaded in the VL53L4CD sensor at each startup using
a dedicated driver function. The calibration sequence order is important. Offset calibration should be run first
followed by crosstalk calibration. The two calibrations may be run sequentially one after the other, or may be
run individually. When run individually, make sure the offset data have been programmed into the sensor before
running crosstalk calibration.

2.2.2 Offset calibration procedure

Offset corresponds to the difference between real distance and measured distance. A default offset is
programmed into the sensor, but a calibration may be required to improve accuracy.

To perform the calibration, ST recommends to use a 17 % reflective target at 100 mm from the device in dark
conditions, and call function VL53L4CD_CalibrateOffset (). The function finds the offset, applies the offset, and
returns the offset correction value. It takes a few seconds to be performed. Offset calibration must be performed
before Xtalk calibration. The following table shows the available settings for running offset calibration.

UM2931 - Rev 1

Table 1. Available settings for running offset calibration

Setting Min Proposed by ST Max

Distance [mm] 50 100 255

Number of samples 5 20 255

page 4/15

UM2931

Calibrations

Note: Increasing the number of samples increases the accuracy, but also increases the time for calibration. The time

relative to number of samples is linear, and values follow the approximate timeout:

• 5 samples ≈ 750 milliseconds

• 10 samples ≈ 1000 milliseconds

• 20 samples ≈ 1500 milliseconds

Users can also call functions VL53L4CD_GetOffset() and VL53L4CD_SetOffset() to get the programmed value, or
set a new one.

2.2.3 Xtalk calibration procedure

For aesthetic and protective purposes, a protective window can be added on top of the module. Due to this cover
glass, a part of the light is reflected and returned to the receiver, causing a Xtalk phenomenon. Depending on the
cover glass quality, the amount of return signal may be significant and may affect sensor performances, as shown
in the following figure.

Figure 5. Impact on ranging with several Xtalk

The VL53L4CD has a built-in correction that allows the Xtalk compensation. The calibration needs to be
performed on a 17 % reflective target. Offset calibration needs to be performed before Xtalk calibration.

The calibration distance depends on the cover glass quality. The distance should correspond to the maximum
ranging distance without under-ranging. This point can be found doing a full sweep, with a target from near to far,
getting the ranging distance vs target distance.

UM2931 - Rev 1

page 5/15

UM2931

Calibrations

Figure 6. Valid area for running Xtalk calibration

The calibration is performed calling function VL53L4CD_CalibrateXtalk(). The function finds the xtalk, applies the
xtalk, and returns the xtalk correction value. It takes a few seconds to be performed. The following table shows
the available settings for running Xtalk calibration.

Table 2. Available settings for running Xtalk calibration

Setting

Distance [mm]

Number of samples 5 20 255

Depends on customer

Min Proposed by ST Max

cover glass

Depends on customer

cover glass

Depends on customer

cover glass

Note: Increasing the number of samples increases the accuracy, but also increases the time for calibration. The time

relative to number of samples is linear, and values follow the approximate timeout:

• 5 samples ≈ 750 milliseconds

• 10 samples ≈ 1000 milliseconds

• 20 samples ≈ 1500 milliseconds

Users can also call functions VL53L4CD_GetXtalk() and VL53L4CD_SetXtalk() to get the programmed value, or
set a new one.

UM2931 - Rev 1

page 6/15

2.3 Ranging flow

The following figure shows the typical ranging flow to use the VL53L4CD sensor.

UM2931

Ranging flow

Figure 7. Ranging flow

2.4 Example of configurations

The VL53L4CD sensor can be configured to achieve many usecases. There are several examples of
configurations. Best performances can be reached using a high Timing Budget. The average power consumption
during ranging can be reduced by changing the InterMeasurement.

Table 3. Example of VL53L4CD configurations

Usecase Timing budget (ms) InterMeasurement (ms)

Fast ranging 10 0

High accuracy 200 0

Low power 50 1000

UM2931 - Rev 1

page 7/15

3 Available features

The VL53L4CD ULD API contains several functions in order to tune the sensor, depending of the usecase. All
functions available in the driver are described in the sections below.

3.1 Initialization

Initialization is the first thing to do to use the VL53L4CD sensor. This operation requires to power on the sensor,
then call the function VL53L4CD_SensorInit(). It performs a boot routine, and prepares the sensor.

3.2 Range timing

The range timing is a single function which allows the user to define the VCSEL timeout and the ranging
frequency of the sensor. It is composed of two elements:

• The Timing budget: It corresponds to the VCSEL enabled time. The user can choose a value between 10 ms
and 200 ms. If the InterMeasurement is set to 0, the VCSEL is always enabled, so the TimingBudget is
equal to the ranging period between consecutive measurements.

• The InterMeasurement: It allows the user to define the time between two consecutive measurements.
To use the InterMeasurement, the user needs to set a value greater than the TimingBudget. When the
TimingBudget is consumed, the device goes into low power mode until the InterMeasurement is reached. A
value set to 0 disables the InterMeasurement.

The following figure shows the difference between TimingBudget and InterMeasurement, if the InterMeasurement
is greater than TimingBudget.

UM2931

Available features

Figure 8. TimingBudget and InterMeasurement (not equal to 0)

If the InterMeasurement is set to 0, the TimingBudget defines the ranging measurements period, as shown in the
following figure.

Figure 9. TimingBudget and InterMeasurement (equal to 0)

UM2931 - Rev 1

Increasing the timing budget increases the number of photons emitted for a single measurement, so it improves
the measurement accuracy and maximum ranging distance.

page 8/15

The InterMeasurement can be used to reduce the power consumption. The VL53L4CD power consumption
depends of the duty cycle Timing Budget/InterMeasurement, so a high InterMeasurement allows to have a low
power consumption.

The minimum and maximum value of each timing is defined in the following table.

Table 4. Minimum and maximum range timing

Timing Min (ms) Default (ms) Max (ms)

TimingBudget 10 50 200

InterMeasurement

TimingBudget (or 0 to disable

the feature)

3.3 Sigma and signal thresholds

Two thresholds can be used to improve accuracy or maximum ranging distance.

The sigma corresponds to the standard deviation of the returned pulse. If the computed sigma is above the
programmed value, the result status in structure 'VL53L4CD_Result_t' will be equal to 2 instead of 0. The value
can be changed using function VL53L4CD_SetSigmaThreshold(). The default value is 15 mm, minimum is 0 mm
(no threshold), and maximum is 16383 mm.

The signal corresponds to the minimal number of photons to consider a valid distance. If the computed signal
is below the programmed value, the result status in structure 'VL53L4CD_Result_t' will be equal to 1 instead of

0. The value can be changed using function VL53L4CD_SetSignalThreshold(). The default value is 1024 kcps,

minimum is 0 kcps (no threshold), and maximum is 65535 kcps.

The best accuracy can be reached using a low sigma and a high signal. But it also reduces the maximum ranging
distance. Benefits of the two thresholds are shown in the following table.

UM2931

Sigma and signal thresholds

0 5000

Table 5. Sigma and signal thresholds change effect

Limit Action

Sigma threshold

Signal threshold

Effect on standard

deviation

Increase limit - +

Decrease limit + -

Increase limit + -

Decrease limit - +

Effect on maximum ranging

3.4 Detection thresholds and detection windows

In addition to the regular ranging capability, the sensor can be programmed to detect an object under certain
predefined criteria. If programmed condition are met, an interrupt is raised on PIN GPIO1. This mechanism allows
to trigger interrupts only in particular conditions. The available detection condition usecases include:

• Below a distance threshold

• Above a distance threshold

• Within two distance thresholds

• Outside of two distance thresholds

The thresholds can be changed using function VL53L4CD_SetDetectionThresholds(). By default there are no
thresholds programmed.

Note: The detection threshold needs to be used with InterMeasurement enabled (not equal to 0).

distance

UM2931 - Rev 1

page 9/15

3.5 Temperature update

Ambient temperature has an effect on ranging accuracy. In order to ensure the best performances, a temperature
update needs to be applied to the sensor. This update needs to be performed when the temperature might have
changed by more than 8 degrees Celsius.

A dedicated function named ‘VL53L4CD_Start_Temperature_Update()’ has to be used. The function can
only be used if the sensor is not ranging. Otherwise, the ranging needs to be stopped using function
'VL53L4CD_StopRanging()'. After calling this function, the ranging can restart normally.

UM2931

Temperature update

UM2931 - Rev 1

page 10/15

4 Ranging results

The VL53L4CD ULD API contains several functions in order to tune the sensor, depending on the usecase. All
functions available in the driver are described in the following sections.

4.1 Getting ranging results

During the ranging session, there are two ways to know if new ranging data are available :

• Polling mode: Continuously use of function VL53L4CD_CheckForDataReady(). The argument gives if a new
data is ready.

• Interrupt mode: Wait for a physical interrupt on PIN GPIO1

4.2 Available data

An extensive list of data are output from the VL53L4CD. The following table explains the parameters available to
the user.

Table 6. Description of available output using VL53L4CD sensor

UM2931

Ranging results

Element Format Unit Description

Status unsigned 8 bits None

Distance unsigned 16 bits Millimeter Measured distance of the target in millimeters.

Ambient rate unsigned 16 bits Kcps

Signal unsigned 16 bits Kcps

Number of SPADs

enabled

Sigma unsigned 16 bits Millimeter

unsigned 16 bits None

Measurements validity. See Table 7. List of

available status for more information.

Ambient rate measurement performed on the

return array, with no active photon emission, to

measure the ambient signal rate due to noise.

Quantity of photons measured during the VCSEL

pulse.

Number of SPADs enabled for the current

measurement. A far or low reflective target will

activate more SPADs.

Sigma estimator for the noise in the reported

target distance.

UM2931 - Rev 1

page 11/15

4.3 Results interpretation

The data returned by the VL53L4CD can be filtered in order to take into account the measurement status. A new
status is computed for each new measurement. If the sensor is not able to measure a correct distance due to
environment conditions, an invalid status is reported. The following table gives the list of available status.

Status Gravity Description

0 None Returned distance is valid

1 Warning

2 Warning

3 Error Measured distance is below detection threshold

4 Error Phase out of valid limit

5 Error Hardware fail

6 Warning Phase valid but no wrap around check performed

7 Error Wrapped target, phase does not match

8 Error Processing fail

9 Error Xtalk signal fail

10 Error Interrupt error

11 Error Merged target

12 Error Too low signal

255 Error Other error (e.g boot error)

UM2931

Results interpretation

Table 7. List of available status

Sigma is above the defined threshold (see Section 3.3 Sigma and

signal thresholds)

Signal is below the defined threshold (see Section 3.3 Sigma and

signal thresholds)

UM2931 - Rev 1

page 12/15

Revision history

UM2931

Table 8. Document revision history

Date Version Changes

16-Sep-2021 1 Initial release

UM2931 - Rev 1

page 13/15

UM2931

Contents

Contents

1 Functional description .............................................................2

1.1 System overview ...............................................................2

1.2 Schematics and I2C configuration ................................................2

2 Package content and data flow.....................................................4

2.1 Driver architecture and content ...................................................4

2.2 Calibrations ...................................................................4

2.2.1 Calibration order .........................................................4

2.2.2 Offset calibration procedure ................................................4

2.2.3 Xtalk calibration procedure .................................................5

2.3 Ranging flow ..................................................................7

2.4 Example of configurations .......................................................7

3 Available features .................................................................8

3.1 Initialization ...................................................................8

3.2 Range timing ..................................................................8

3.3 Sigma and signal thresholds .....................................................9

3.4 Detection thresholds and detection windows........................................9

3.5 Temperature update ...........................................................10

4 Ranging results...................................................................11

4.1 Getting ranging results .........................................................11

4.2 Available data ................................................................11

4.3 Results interpretation ..........................................................12

Revision history .......................................................................13

Contents ..............................................................................14

UM2931 - Rev 1

page 14/15

UM2931

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

UM2931 - Rev 1

page 15/15