Introduction
The purpose of this user manual is to describe the main functions of the VL53L1X ultra lite driver (ULD) to program the
VL53L1X sensor for ranging distances and detecting objects.
The VL53L1X ULD is an optimized version of the initial VL53L1X driver. The table below indicates the main differences between
the two drivers. For example, in the the VL53L1X ULD, the API contains only four files instead of 35, and the code footprint is
much smaller (2.3 KB vs. 9 KB in Flash).
The VL53L1X is the third generation of long distance ranging, Time-of-Flight sensors. Please refer to the VL53L1X datasheet for
more details.
Figure 1. VL53L1X sensor module
Table 1. Main differences between VL53L1X API and VL53L1X ULD API
VL53L1X API VL53L1X ULD API
Code footprint in Flash 9 KB 2.3 KB
Number of files 35 4
Timing budget (ms) [20 - 500] [15, 20, 33, 50, 100, 200, 500]
ROI position configuration Flexible (center and corner) Centered only
Fast ranging 100 Hz Yes No (66 Hz max.)
Dynamic SPAD selection (DSS)
(1)
No Yes
1. DSS is an internal operation which consists of adapting dynamically the number of active SPADs according to the quantity of returned
photons. This avoids saturating the SPAD receiver. DSS is executed at the beginning of each ranging operation.
A guide to using the VL53L1X ultra lite driver
UM2510
User manual
UM2510 - Rev 1 - December 2018
For further information contact your local STMicroelectronics sales office.
www.st.com
1 Acronyms and abbreviations
Table 2. Acronyms and abbreviations
Acronym/abbreviation Definition
API application programming interface
cps counts per second
DSS dynamic SPAD selection
FMT final module test
FoV field of view
I2C inter-integrated circuit (serial bus)
IR infrared radiation
IMP inter-measurement period
kcps kilo counts per second
NVM non volatile memory
ROI region of interest
SPAD single photon avalanche diode
TB timing budget
ToF Time-of-Flight
ULD ultra lite driver
VCSEL vertical cavity surface-emitting laser
xcd crosstalk calibration distance
xtalk crosstalk
UM2510
Acronyms and abbreviations
UM2510 - Rev 1
page 2/26
2 VL53L1X system overview
The VL53L1X system is composed of a hardware module and an ultra lite software driver (VL53L1X_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. VL53L1X system overview
UM2510
VL53L1X system overview
UM2510 - Rev 1
page 3/26
3 Ranging API functional description
This section gives a functional description of the ranging operations and describes the call flow to be followed to
perform a ranging measurement using the VL53L1X sensor.
3.1 Distance ranging description
The sensor ranges continuously and autonomously with a programmable inter-measurement period.
Autonomously means that ranging is made without involvement from the host. This allows the host to be in a Lowpower state (energy saving). The host is only woken up upon measurement interrupts when ranging data are
available. There is no need to issue a new start command to enable new ranging, however a clear interrupt is
required after getting ranging data to enable the next interrupt event. Otherwise, the device ranges continuously
and no interrupt event occurs to notify the user of the availability of new ranging data once the sensor finishes the
ranging sequence.
Note: In this user manual, the term interrupt may designate a physical interrupt on the GPIO1 pin or a “software”
interrupt which is a value change in the GPIO__TIO_HV_STATUS register.
3.2 Distance threshold detection description
In addition to the regular ranging capability, the sensor can be programmed to detect an object under certain
predefined criteria by using the function VL53LX_SetDistanceThreshold (). The available detection condition usecases include:
• Object under a certain distance
• Objet beyond a certain distance
• Object within a window limited by a near and far threshold
• Object out of a window limited by a near and far threshold
3.3 Timing considerations
The timing budget (TB) is the time required for the device to make one distance measurement. Increasing the TB
improves the measurement reliability but also increases power consumption. So, there is a trade-off between
measurement accuracy and power consumption. In the VL53L1X_ULD driver, the TB values available are [15, 20,
33, 50, 100, 200, 500 ms].
The inter-measurement period (IMP) is the time between two consecutive measurements. The IMP must be
greater than or equal to the TB otherwise the actual IMP is double the expected value. Note that there is no
automatic check in the VL53L1X_ULD driver, so the user has to verify this condition when setting the IMP.
Figure 3. Ranging sequence and timings
UM2510
Ranging API functional description
UM2510 - Rev 1
page 4/26
3.4 API function call flow
The VL53L1X_ULD driver is used in the following two use cases:
• Calibration flow is used to calibrate the sensor. Such calibration is done during manufacturing. The
calibration data must be stored in the host sytem and sent to the sensor during the bootup stage.
• Ranging flow is used for distance measurements or object detection operations in the application software.
3.4.1 Calibration flow
Figure 4. Calibration flow
UM2510
API function call flow
UM2510 - Rev 1
page 5/26
3.4.2 Ranging flow
Figure 5. Ranging flow
3.5 Mandatory functions
Mandatory functions include:
• VL53L1X_BootState
• VL53L1X_SensorInit
• VL53L1X_StartRanging
• VL53L1X_CheckForDataReady
• VL53L1X_GetDistance
• VL53L1X_ClearInterrupt
• VL53L1X_Stop
3.5.1 Sensor boot
The VL53L1X_BootState function is used to check that the sensor has booted. It is strongly recommended to
ensure that the sensor finishes booting before the first I2C access.
3.5.2 Sensor init
The VL53L1X_SensorInit function is called once to initialize the sensor with a default configuration. With this
default configuration, the sensor ranges at 10 Hz in Long-distance mode.
3.5.3 Start a measurement
The VL53L1X_StartRanging function is used to make a distance measurement.
UM2510
Mandatory functions
UM2510 - Rev 1
page 6/26
3.5.4 Wait for notification ranging data to be ready
There are two ways to receive notification that ranging data are ready:
• The host can poll a register value change. This is done by using the VL53L1X_CheckForDataReady which
returns “1” when new ranging data are ready.
• The host can wait for a physical interrupt event. The interrupt event can be triggered at the GPIO1 pin. The
interrupt polarity can be set by the VL53L1X_SetInterruptPolarity function. This changes the interruption
transition (from high to low or from low to high)
3.5.5 Get ranging data
Each type of ranging data has its own get ranging data functions. The VL53L1X_GetRangeStatus and
VL53L1X_GetDistance are the main get ranging data functions. If required, other ranging data parameters can be
read, for example, return signal, ambient rate, etc.
3.5.6 Clear interrupt
Use the VL53L1X_ClearInterrupt function to clear the interrupt. It is strongly recommanded to clear the interrupt to
enable the next interrupt event when new ranging data are ready.
3.5.7 Stop the measurement
Ranging occurs continuously. To stop the current ranging operation, the user can use the stop command,
VL53L1X_Stop (). If the stop command is issue during the ranging operation, the sensor completes the current
ranging operation before stopping.
3.6 Optional functions
3.6.1 Setting distance mode
Two distance modes are available: Short and Long (default). Short mode has better ambient light immunity but
the maximum distance measurable is limited to 1.3 m. Long distance mode ranges up to 4 m but is less
performant under ambient light.
Use the function VL53L1X_SetDistanceMode (dev, DM) to set the distance mode. For Short mode, DM = 1 and
for Long mode, DM = 2.
VL53L1X_GetDistanceMode returns the current distance mode.
3.6.2 Inter-measurement period
The inter-measurement period (IMP) is the time between two ranging operations (see Section 3.3 Timing
considerations).
Use the VL53L1X_SetInterMeasurementInMs function to set the intermeasurement period in milliseconds.
VL53L1X_GetIntermeasurementInMs returns the curent IMP. The default IMP is 100 ms.
The IMP must be greater than or equal to the TB otherwise the start of ranging is missed and the
intermeaurement period is effectively doubled. The user has to verify the TB and the intermeasurement period as
there is no automatic check in the API.
3.6.3 Setting the timing budget
The TB is the time required by the sensor to make one distance measurement (see Section 3.3 Timing
considerations).
Use the VL53L1X_SetTimingBudget function to set the TB in milliseconds. The TB values available are [15, 20,
33, 50, 100, 200, 500]. This function must be called after VL53L1X_SetDistanceMode.
Note: 15 ms only works with Short distance mode. 100 ms is the default value.
The TB can be adjusted to improve the standard deviation (SD) of the measurement. Increasing the TB,
decreases the SD but increases the power consumption. For example, VL53L1X_SetTimingBudgetInMs (&dev,
50) sets the TB to 50 ms. VL5L31X_GetTimingBudget returns the current TB.
UM2510
Optional functions
UM2510 - Rev 1
page 7/26
3.6.4 Setting threshold and detection mode
In addition to the regular ranging features, the sensor also has the capability to detect a target with predefined
detection criteria. When the preconfigured criteria are matched the sensor raises an interrupt and returns the
distance.
Use the VL53L1X_ERROR VL53L1X_SetDistanceThreshold (dev, ThreshLow, ThreshHigh, Window,
IntOnNoTarget) to configure the detection criteria.
• ThreshLow is the low distance threshold in millimeters
• ThreshHigh is the high distance threshold in millimeters
• Window :
– Window = 0: Below a certain distance
◦ If object distance > ThreshLow or no object found: no report
◦ If object distance < ThreshLow and object found: report
– Window = 1: Beyond a certain distance
◦ If object distance < ThreshHigh or no object found: no report
◦ If object distance > ThreshHigh and object found: report
– Window = 2: Out of distance range (min/max), "out of Window"
◦ ThreshLow < object distance < ThreshHigh: no report
◦ ThreshLow > object distance > ThreshHigh: report
– Window = 3: Within the distance range (min/max), "inside Window"
◦ ThreshLow > object distance > ThreshHigh: no report
◦ ThreshLow < object distance < ThreshHigh: report
• IntOnNoTarget is no longer used, set to 1
To go back to the regular ranging mode, write 0x20 to the 0x46 register (8 bits).
3.6.5 Setting ROI
The receiving SPAD array of the sensor consists of 16x16 SPADs which cover the full FoV.
It is possible to program a smaller ROI, with a smaller number of SPADs, to reduce the FoV for applications which
require a narrow FoV.
Use the function VL53L1X_SetROI (dev, X, Y).
• X is the ROI width from 4 to 16, if X < 4 the Firmware limits the width to 4
• Y is the ROI height from 4 to 16, if Y < 4 the Firmware limits the height to 4
VL53L1X_GetROI returns the current ROI.
Note: Lowering the number of SPADs limits the maximum ranging distance. Some experimentation is required.
UM2510
Optional functions
UM2510 - Rev 1
page 8/26
Loading...