ST VL53L7CH User manual

Introduction
The purpose of this user manual is to explain how to handle the VL53L7CH and VL53L8CH Time-of-Flight (ToF) sensors, using
the ultra light driver (ULD) API. It describes the main functions to program the device, the calibrations, and the output results.
The CNH data transform STMicroelectronics Time-of-Flight ranging sensor into a versatile optical sensor, which can enable
endless AI-based applications. This CNH raw data sent to the host, on top of the standard ranging data, opens the door to many
new applications beyond simple distance measurements. From solid material (carpet, wood, glass, mirror...) to gas or liquid
(water, oil, chemical...), it becomes possible to detect the location and the size of a cup in a coffee machine or beverage
dispenser, to sense the floor material for robotics, and develop advanced shape, motion, or hand posture recognition.
Figure 1. VL53L7CH and VL53L8CH sensor modules
References
VL53L7CH datasheet (DS14309)
VL53L8CH datasheet (DS14310)
A guide for using the artificial intelligence enabler VL53L7CH and VL53L8CH
multizone Time-of-Flight (ToF) sensors
UM3183
User manual
UM3183 - Rev 1 - June 2023
For further information contact your local STMicroelectronics sales office.
www.st.com

1 Acronyms and abbreviations
Acronym/abbreviation Definition
CNH compact normalized histogram
DOE diffractive optical element
FoV field of view
I2C inter-integrated circuit (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
UM3183
Acronyms and abbreviations
UM3183 - Rev 1 page 2/24

2 Functional description
2.1 System overview
The system is composed of a hardware module and the ultra light driver software (VL53LMZ ULD) running on a
host (see figure below). The hardware module contains the ToF sensor. STMicroelectronics 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. 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. Consequently, 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. Module effective orientation
UM3183
Functional description
UM3183 - Rev 1 page 3/24

2.3 Schematics and I2C/SPI configuration
The communication between driver and firmware is handled by the I2C for both sensors, with a maximum speed
of 1 MHz. In addition, the VL53L8CH also has the possibility to communicate with SPI. In this case, the maximum
SPI speed is 3 MHz. The implementation of each communication protocol requires pull-ups as described in the
product datasheets.
The devices have a default I2C address of 0x52. However, it is possible to change the default address to avoid
conflicts with other devices, or to facilitate adding multiple modules to the system for a greater system FoV. The
I2C address can be changed using the vl53lmz_set_i2c_address() function. To use the SPI, the multisensor is
wired using an independent slave configuration (the NCS pin).
In order to change the device I2C address without affecting others on the I2C bus, it is important to disable the
I2C communication of the devices not being changed. The procedure is as follows:
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 vl53lmz_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 devices in the system that
require a new I2C address.
Figure 4. Multiple sensors on I2C bus
UM3183
Schematics and I2C/SPI configuration
UM3183 - Rev 1 page 4/24

Figure 5. Multiple sensors on SPI
UM3183
Schematics and I2C/SPI configuration
UM3183 - Rev 1 page 5/24

3 Package content and data flow
3.1 Driver architecture and content
The driver package is composed of four folders. The driver is located in the folder /VL53LMZ_ULD_API.
The driver is composed of mandatory and optional files. Optional files are plugins used to extend the ULD
features. Each plugin starts with the word "vl53lmz_plugin" (e.g vl53lmz_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 6. 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.
UM3183
Package content and data flow
UM3183 - Rev 1 page 6/24

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 Time-of-Flight modules are
self-calibrated, and can be used without any additional calibration.
Xtalk calibration may be required if the module is protected by a cover glass. The sensors are immune to
crosstalk beyond 60 cm thanks to a histogram algorithm. However, at short distances below 60 cm, crosstalk can
be larger than the actual returned signal. This gives a false target reading or makes targets appear closer than
they really are. All crosstalk calibration functions are included in a crosstalk plugin (optional). The user needs to
use the file ‘vl53lmz_plugin_xtalk’.
The crosstalk can be calibrated once, and data can be saved so it can be reused 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 crosstalk calibration, as
proposed in the following table.
Table 1. Available settings for calibration
Setting Min Proposed by
STMicroelectronics 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 the function vl53lmz_calibrate_xtalk(). This function can be used at any time.
However, the sensor must be initialized first. The following figure represents the crosstalk calibration flow.
Figure 7. Xtalk calibration flow
UM3183
Calibration flow
UM3183 - Rev 1 page 7/24

3.3 Ranging flow
The following figure represents the ranging flow used to get measurements. Crosstalk 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 8. Typical ranging flow
UM3183
Ranging flow
UM3183 - Rev 1 page 8/24

4 Available features
The sensor driver includes several functions, which allow the user to tune the sensor, depending on the use case.
All the functions available for the driver are described in the following sections.
4.1 Initialization
Initialization must be done before using the Time-of-Flight sensor. This operation requires the user to:
1. Power on the sensor
– For VL53L7CH: VDDIO, AVDD, LPn pins set to high
– For VL53L8CH: VDDIO, AVDD, CORE_1V8 pins set to high
2. Call the function vl53lmz_init(). The function copies the firmware (~84 Kbytes) to the module. This is done by
loading the code over the I2C/SPI interface, and performing a boot routine to complete the initialization.
4.2 Sensor reset management
To reset the device, the following pins need to be toggled:
1. Set pins VDDIO, and AVDD (and CORE_1V8 for VL53L8CH) to low.
2. Wait 10 ms.
3. Set pins VDDIO, and AVDD (and CORE_1V8 for VL53L8CH) 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 VL53L7CH and VL53L8CH sensors have two
possible resolutions: 4x4 (16 zones) and 8x8 (64 zones). By default the sensor is programmed in 4x4.
The function vl53lmz_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/SPI bus when the 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 the function vl53lmz_set_ranging_frequency_hz(). By default, the
ranging frequency is set to 1 Hz.
UM3183
Available features
UM3183 - Rev 1 page 9/24

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 the 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 the function
vl53lmz_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 the function vl53lmz_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 9. Integration time for 4x4 autonomous
Figure 10. 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 is automatically increased to fit the integration time value.
UM3183
Ranging mode
UM3183 - Rev 1 page 10/24