ST VL53L4CX User manual

Introduction
The VL53L4CX is a Time-of-Flight (ToF) sensor, specifically designed for long range, multitarget detection, providing very
accurate distance measurement up to 6 m with excellent results over short distances.
The purpose of this user manual is to describe the integration model and the set of functions to call to get ranging data using the
VL53L4CX bare driver.
A guide to using the VL53L4CX Time-of-Flight sensor with extended distance
measurement
UM2923
User manual
UM2923 - Rev 2 - June 2022
For further information contact your local STMicroelectronics sales office.
www.st.com

1VL53L4CX system overview
The VL53L4CX system is composed of the VL53L4CX module and a driver running on the host.
This document describes the driver functions accessible to the host, to control the device and get the ranging data
for integration with non-Linux hosts.
Figure 1. VL53L4CX system
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 an implementation of a set of functions required to use the VL53L4CX device. It makes minimal
assumptions on the OS integration and services. As such, sequencing of actions, execution/threading model,
platform adaptation, and device structures allocation are not part of the bare driver implementation but left open to
the integrator.
The sequencing of bare driver calls must follow a set of rules, defined in this document.
UM2923
VL53L4CX system overview
UM2923 - Rev 2 page 2/25

2Ranging functional description
This section briefly describes the functional capabilities of VL53L4CX ranging device.
2.1 Ranging sequence
The device is running with a handshake mechanism, based on a standard interrupt management scheme.
After each ranging, the host acquires the ranging data and enables the next ranging by clearing the interrupt. An
interrupt is raised when a valid range is available. This process is referred to as the handshake mechanism.
Next ranging is then triggered when the current one is finished, and the host has cleared the previous pending
interrupt.
The interrupt mechanism allows faster data transfer, without losing 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 the figure below.
UM2923
Ranging functional description
UM2923 - Rev 2 page 3/25

Figure 2. VL53L4CX ranging sequence overview
UM2923
Ranging sequence
UM2923 - Rev 2 page 4/25

Handshake sequence allows the computation of internal parameters and apply them for next range.
The handshake must be performed by the user of the bare driver. Minimizing the delay in enabling a new ranging
after a new measurement has been received is key to maximizing the system measurement rate
2.2 Timing considerations
Timings are presented in Figure 3. Ranging sequence and timing targets.
The host can get the latest available ranging during the duration (ranging timing budget) of the current range.
If a delay to clear the interrupt is introduced by the host, the next ranging will be stalled until the pending interrupt
is cleared.
Note: Timings indicated in Figure 3. Ranging sequence and timing targets are typical timings.
The host can change the default timing budget by using a dedicated driver function described in
Section 5.1 Timing budget. The host can change the timing budget either to synchronize on the application,
or to increase ranging accuracy.
In the following figure, the “Boot”, “SW standby” and “Init” lasts 85 ms. This time is needed to initialize the device,
and is independent for the platform or the ranging timing budget. The first range, “Range1”, is the wrap-around
check, and is not valid. This means that the first valid ranging value is “Range2”, available after 85 ms plus twice
the timing budget duration.
Figure 3. Ranging sequence and timing targets
UM2923
Timing considerations
UM2923 - Rev 2 page 5/25

3Bare driver basic functions description
This section describes the driver function calls flow that should be followed to perform a ranging measurement
using the VL53L4CX.
The VL53L4CX driver is used in two classes of applications:
• Factory applications used for device calibration, typically at the end of product manufacturing test (factory
flow)
• Field applications, which include all end-user applications using the VL53L4CX device (ranging flow)
3.1 Bare driver
Bare driver factory flow is illustrated in the following figure.
Figure 4. VL53L4CX API ranging flow (factory)
Host calls driver
function
DataInit ()
PerformRefSpadManagement()
PerformOffsetCalibration()
WaitDeviceBooted()
PerformXtalkCalibration()
Key
Host calls Optional
driver function
GetCalibrationData()
Save part calibration data
Note: The calibration flow changes the distance mode. It is mandatory to call the SetDistanceMode() function if you
want to use the sensor just after a calibration.
Bare driver ranging flow is illustrated in the following figure.
UM2923
Bare driver basic functions description
UM2923 - Rev 2 page 6/25

Figure 5. VL53L4CX API ranging flow (field)
WaitMeasurementDataReady()
Interrupt received
StopMeasurement()
Host calls driver
function
Host action
GetMeasurementDataReady()
DataInit ()
StartMeasurement()
SetCalibrationData()
Interrupt mode
Host polling mode
Polling/
interrupt
Continue
?CONTINUE
Data result Driver internal
action
Checks
interrupt status
ClearInterruptAndStartMeasurement()
Clears
interrupt
Enables next
ranging
GetMultiRangingData()
Data
Polls on
interrupt status
Driver polling mode
WaitDeviceBooted()
SetDistanceMode()
Key
Host calls Optional
driver function
UM2923
Bare driver
UM2923 - Rev 2 page 7/25

3.2 System initialization
The following section shows the API functions calls required to perform the system initialization, before starting a
measurement.
3.2.1 Wait for boot
VL53LX_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 frequency
• 2 ms latency per transaction
3.2.2 Data init
The VL53LX_DataInit() function must be called each time the device exits from the “initial boot” state. It performs
device initialization. After calling the VL53LX_DataInit() function the calibration data have to be loaded using the
function VL53LX_SetCalibrationData().
UM2923
System initialization
UM2923 - Rev 2 page 8/25

4Ranging with VL53L4CX
On non-Linux hosts, the user of the bare driver sequences calls to the driver in a way that is appropriate to the
application needs, the platform capabilities and the bare driver call sequence rules.
4.1 Start a measurement
VL53LX_StartMeasurement() function must be called to start a measurement.
4.2 Wait for a result: polling or interrupt
There are 3 ways to know that a measurement is available. The host can:
1. call a polling function
2. poll on a driver function
3. wait for a physical interrupt
4.2.1 Driver polling to get the result status
The function VL53LX_WaitMeasurementDataReady() is polls the internal status until a measurement is ready.
Note: This function is blocking, as internal polling is performed.
4.2.2 Host polling to get the result status
Host can poll using the function VL53LX_GetMeasurementDataReady(), to know when a new measurement is
ready.
This function is not blocking.
4.2.3 Using physical interrupt
An alternative and preferred way to get the ranging status is to use the physical interrupt output. By default,
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.
Interrupt must be cleared by calling driver function VL53LX_ClearInterruptAndStartMeasurement().
4.3 Get measurement
Multiple objects can be detected per ranging, and measurement data is reported per object
VL53LX_GetMultiRangingData() can be used to get ranging data when multiple objects are in the field of view.
When calling this function to get the device multiple ranging results, a structure called
VL53LX_MultiRangingData_t is returned.
4.4 Stop a measurement
The host can stop the measurement by calling VL53LX_StopMeasurement() function.
If the stop request occurs during a range measurement, then the measurement is aborted immediately.
UM2923
Ranging with VL53L4CX
UM2923 - Rev 2 page 9/25

4.5 Ranging data structures
The structure named VL53LX_MultiRangingData_t contains the following data applicable to all targets detected:
• TimeStamp: not implemented.
• StreamCount: this 8-bit integer gives a counter incremented at each range. This 8-bit integer gives a counter
incremented at each range. The value starts at 0, incrementing 1 by 1 up to 255. When it reaches 255, it
starts again from 128 to 255.
• NumberOfObjectsFound: 8-bit integer value that gives the number of objects found.
• RangeData[VL53LX_MAX_RANGE_RESULTS]: a table of structure of type VL53LX_TargetRangeData_t.
The maximum number of targets is given by VL53LX_MAX_RANGE_RESULTS, and is by default equal to 4.
• HasXtalkValueChanged: 8-bit integer value that indicates if the crosstalk value has been changed.
• EffectiveSpadRtnCount: 16-bit integer that returns the effective single photon avalanche diode (SPAD) count
for the current ranging. To obtain real value it should be divided by 256.
One structure per target detected (up to 4 by default) called VL53LX_TargetRangeData_t which contains the
following specific results for each target detected.
• RangeMaxMilliMeter: is a 16-bit integer, indicating the larger detected distance.
• RangeMinMilliMeter: is a 16-bit integer, indicating the smaller detected distance.
• SignalRateRtnMegaCps: this value is the return signal rate in MegaCountPer Second (MCPS), this is a
16.16 fix point value. To obtain the real value it should be divided by 65536.
• AmbientRateRtnMegaCps: this value is the return ambient rate (in MCPS), this is a 16.16 fix point value,
which is effectively a measure of the amount of light hitting the SPAD matrix. To obtain the real value it
should be divided by 65536.
• SigmaMilliMeter: this 16.16 fix point value is an estimation of the standard deviation of the current ranging,
expressed in millimeter. To obtain the real value it should be divided by 65536.
• RangeMilliMeter: is a 16-bit integer indicating the range distance in millimeter.
• RangeStatus: this is a 8-bit integer indicating the range status for the current measurement. Value = 0
means ranging is valid. See Table 1. Range Status.
• ExtendedRange: this is a 8-bit integer indicating if the range has been unwrapped (only for long distances)
If the target is not detected, and the measurement is valid, the following values are reported in the
VL53LX_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.
• RangeStatus: forced to 0.
UM2923
Ranging data structures
UM2923 - Rev 2 page 10/25