ST VL53L3CX Manual de usuario
Introduction
VL53L3CX is a Time-of-Flight (ToF) ranging sensor module.
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
VL53L3CX bare driver.
VL53L3CX Time-of-Flight ranging module with multi object detection
UM2778
User manual
UM2778 - Rev 1 - September 2020
For further information contact your local STMicroelectronics sales office.
www.st.com
1VL53L3CX system overview
VL53L3CX system is composed of the VL53L3CX 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. VL53L3CX system
Host VL53L3CX System
VL53L3CX
module
VL53L3CX
Driver
I2C
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 VL53L3CX 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.
UM2778
VL53L3CX system overview
UM2778 - Rev 1 page 2/25
2Ranging functional description
This section briefly describes the functional capabilities of VL53L3CX 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. This
process 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 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.
UM2778
Ranging functional description
UM2778 - Rev 1 page 3/25
Figure 2. VL53L3CX ranging sequence overview
HANDSHAKE
HANDSHAKE
HANDSHAKE
HANDSHAKE
Init
Range1
Power Up &
XSHUT
released
Boot
Ranging Start
Range2
Range3
Get Range1 Data
Setup range 3
Clear interrupt range 1
Interrupt raised
Interrupt raised
AND
Interrupt
cleared
Get Range2 Data
Interrupt raised
Setup range 4
Clear interrupt range 2
AND
Interrupt raised
AND
Range4
Range5
Interrupt raised
AND
Interrupt raised
AND
Range6
Interrupt
cleared
Interrupt
cleared
Interrupt
cleared
Interrupt
cleared
Data
processing
Data
processing
Get Range3 Data
Setup range 5
Clear interrupt range3
Data
processing
Get Range4 Data
Setup range 6
Clear interrupt range4
Data
processing
Bare Driver
internal action
Key
VL53L3CX
internal action
Host action
HANDSHAKE
Get and Ignore
ranging data
Clear interrupt init
Setup range 2
HANDSHAKE
Interrupt
cleared
Get Range5 Data
Setup range 7
Clear interrupt range5
Data
processing
Handshake sequence allows the computation of internal parameters and apply them for next range.
UM2778
Ranging sequence
UM2778 - Rev 1 page 4/25
The handshake must be performed by the user of the bare driver. The delay to enable a new ranging after a new
measurement has been received is key to overall 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 Chapter 5.1:
Timing budget on page 14. Host can decide to change timing budget either to synchronize on the application or to
increase ranging accuracy.
In the following figure, the “Boot”, “SW standby” and “Init” lasts 40ms. This time is needed to perform a correct
initialization of the device, and it is independent from the platform or the used timing budget. The first range,
“Range1”, is not valid, being the wrap-around check not possible. This means that the first valid ranging value is
“Range2”, available after 40 ms plus two time the timing budget duration.
Figure 3. Ranging sequence and timing targets
Get Range2
Get Range3
DataInit
Start
POWER
SUPPLY
XSHUT
PIN
Range1Boot
Get Range1
40ms
Ranging
Timing
Budget
Ranging
Timing
Budget
NOT TO SCALE
Ranging
Timing
Budget
INTERRUPT
PIN
HOST
DRIVER
CALLS
Setup range3
Clear interrupt1
Setup range1
Clear interrupt
SW
standby
Setup range4
Clear interrupt2
HW
standby
SYSTEM
STATE Range3Range2Init
UM2778
Timing considerations
UM2778 - Rev 1 page 5/25
3Bare driver basic functions description
This section describes the driver functions calls flow that should be followed to perform a ranging measurement
using the VL53L3CX.
The VL53L3CX driver are used in two classes of applications:
• Factory applications used for device calibration, typically at end product manufacturing test (factory flow)
• Field applications, which gather all end-user applications using the VL53L3CX device (ranging flow)
3.1 Bare driver
Bare driver factory flow is illustrated in the following figure.
Figure 4. VL53L3CX API ranging flow (factory)
Host calls driver
function
DataInit
()
PerformRefSpadManagement()
PerformOffsetCalibration()
WaitDeviceBooted()
PerformXtalkCalibration()
Key
Host calls Optional
driver function
GetCalibrationData()
Save part calibration data
Bare driver ranging flow is illustrated in the following figure.
UM2778
Bare driver basic functions description
UM2778 - Rev 1 page 6/25
Figure 5. VL53L3CX 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
UM2778
Bare driver
UM2778 - Rev 1 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().
UM2778
System initialization
UM2778 - Rev 1 page 8/25
4Ranging with VL53L3CX
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 polling on an 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 on 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 is going 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
In continuous mode, 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.
UM2778
Ranging with VL53L3CX
UM2778 - Rev 1 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. 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 ambient light measured by the sensor. 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)
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 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.
• ExtendedRange: forced to 0.
UM2778
Ranging data structures
UM2778 - Rev 1 page 10/25
Tabla de contenidos
Otros manuales de Accesorios de ST
ST
ST LPS331AP Instrucciones de instalación y funcionamiento
ST
ST LPS22HB Instrucciones de instalación y funcionamiento
ST
ST X-CUBE-MEMS1 Manual de usuario
ST
ST X-NUCLEO-53L1A2 Manual de usuario
ST
ST X-NUCLEO-53L3A2 Manual de usuario
ST
ST VL53L1X API Manual de usuario
ST
ST LIS331AL Manual de usuario
ST
ST VL53L7CH Manual de usuario
ST
ST VL6180 Manual de usuario
ST
ST LPS25H Instrucciones de instalación y funcionamiento
