ST UM3038 Time of Flight Multizone Ranging Sensor User Manual
- October 27, 2023
- ST
Table of Contents
- Introduction
- Acronyms and abbreviations
- Functional description
- Package content and data flow
- Available features
- Ranging results
- define VL53L7CX_DISABLE_AMBIENT_PER_SPAD
- define VL53L7CX_DISABLE_NB_SPADS_ENABLED
- define VL53L7CX_DISABLE_NB_TARGET_DETECTED
- define VL53L7CX_DISABLE_SIGNAL_PER_SPAD
- define VL53L7CX_DISABLE_RANGE_SIGMA_MM
- define VL53L7CX_DISABLE_DISTANCE_MM
- define VL53L7CX_DISABLE_TARGET_STATUS
- define VL53L7CX_DISABLE_REFLECTANCE_PERCENT
- define VL53L7CX_DISABLE_MOTION_INDICATOR
- References
- Read User Manual Online (PDF format)
- Download This Manual (PDF format)
UM3038 Time of Flight Multizone Ranging Sensor
**User Manual
**
UM3038 User manual
A guide to using the VL53L7CX Time-of-Flight multizone ranging sensor with
90° FoV
Introduction
The purpose of this user manual is to explain how to handle the VL53L7CX Time-
of-Flight (ToF) sensor, using the ultra lite driver (ULD) API. It describes
the main functions to program the device, the calibrations, and the output
results.
Specially designed for applications requiring an ultrawide FoV, the VL53L7CX
Time-of-Flight sensor offers a 90° diagonal FoV. Based on ST’s FlightSense
technology, the VL53L7CX incorporates an efficient metasurface lens (DOE)
placed on the laser emitter enabling the projection of a 60° x 60° square FoV
onto the scene.
Its multizone capability provides a matrix of 8×8 zones (64 zones) and can
work at fast speeds (60 Hz) up to 350 cm.
Thanks to the autonomous mode with programmable distance threshold combined to
the ultrawide FoV, the VL53L7CX is perfect for any application requiring low-
power user detection. ST’s patented algorithms and innovative module
construction allow the VL53L7CX to detect, in each zone, multiple objects
within the FoV with depth understanding. ST histogram algorithms ensure cover
glass crosstalk immunity beyond 60 cm.
Derived from the VL53L5CX, the pinouts and drivers of both sensors are
compatible, which ensures a simple migration from one sensor to the other.
Like all Time-of-Flight (ToF) sensors based on ST’s FlightSense technology,
the VL53L7CX records, in each zone, an absolute distance regardless of the
target color and reflectance.
Housed in a miniature reflowable package that integrates a SPAD array, the
VL53L7CX achieves the best ranging performance in various ambient lighting
conditions, and for a wide range of cover glass materials.
All of ST’s ToF sensors integrate a VCSEL that emits a fully invisible 940 nm
IR light, which is totally safe for the eyes (Class 1 certification).
The VL53L7CX is the perfect sensor for any application requiring ultrawide FoV
like robotics, smart speakers, video projectors, content management. The
combination of the multizone capability and the 90° FoV can enhance new use-
cases like gesture recognition, SLAM for robotics, and low power system
activation for smart building.
Figure 1. VL53L7CX sensor module
References
VL53L7CX datasheet (DS13865).
Acronyms and abbreviations
Acronym/abbreviation | Definition |
---|---|
DOE | diffractive optical element |
FoV | field of view |
I2C | inter-integrated cirduit (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
Functional description
2.1 System overview
The VL53L7CX system is composed of a hardware module and the ultra lite
driver software (VL53L7CX 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. VL53L7CX 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. As a consequence, 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. VL53L7CX effective orientation
2.3 Schematics and I2C configuration
The communication between driver and firmware is handled by I2C, with a
capability of operating up to 1 MHz. The implementation requires pull-ups on
the SCL and SDA lines. Please see VL53L7CX datasheet for more information.
The VL53L7CX device has a default I2C address of 0x52. However, it is possible
to change the default address to avoid conflicts with other devices, or
facilitate adding multiple VL53L7CX modules to the system for a greater system
FoV. The I2C address can be changed using the vl53l7cx_set_i2c_address()
function.
Figure 4. Multiple sensors on I2C bus
To allow a device to have its I2C address changed without affecting others
on the I2C bus, it is important to disable the I2C communication of the
devices not being changed. The procedure is the following one :
- Power up the system as normal.
- Pull down the LPn pin of the device that will not have its address changed.
- Pull up the LPn pin of the device that has the I2C address changed.
- Program the I2C address to the device using function set_i2c_address() function.
- 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 VL53L7CX devices in the system that require a new I2C address.
Package content and data flow
3.1 Driver architecture and content
The VL53L7CX ULD package is composed of four folders. The driver is located
in the folder / VL53L7CX_ULD_API.
The driver is composed of mandatory and optional files. Optional files are
plugins used to extend ULD features. Each plugin starts with the word
“vl53l7cx_plugin” (e.g vl53l7cx_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 5. 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: Plat form h file contains mandatory macros to use the ULD. All the
file content is mandatory to correctly use the ULD.
3.2 Calibration flow
Note: 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 VL53L7CX module is self-
calibrated, and can be used without any additional calibration.
Xtalk calibration may be required if the module is protected by a coverglass.
The VL53L7CX is immune to xtalk beyond 60 cm thanks to an histogram algorithm,
but at short distances below 60 cm, xtalk can be larger than the actual
returned signal, giving a false target reading or making targets appear closer
than they really are. All xtalk calibration functions are included in a xtalk
plugin (optional). The user needs to use the file `vl53l7cx_plugin_xtalk’.
The xtalk can be calibrated once, and data can be saved to be re-used 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
Xtalk calibration, as proposed in the following table.
Table 1. Available settings for calibration
Setting | Min | Proposed by ST | 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 function vl53l7cx_calibrate_xtalk(). This
function can be used at any time. However, the sensor must be initialized
first. The following figure represents the Xtalk calibration flow.
Figure 6. Xtalk calibration flow
3.3 Ranging flow
The following figure represents the ranging flow used to get measurements.
Xtalk 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 7. Ranging flow using VL53L7CX
Available features
The VL53L7CX ULD API includes several functions which allow the user to tune
the sensor, depending on the usecase. All functions available for the driver
are described in the following sections.
4.1 Initialization
Initialization must be done before using the VL53L7CX sensor. This operation
requires the user to:
- Power on the sensor (VDDIO, AVDD, LPn pins set to High, and pin I2C_RST set to 0)
- Call the function vl53l7cx_init(). The function copies the firmware (~84 kbytes) to the module by loading the code over the I2C 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:
- Set pins VDDIO, AVDD, and LPn pins to low.
- Wait 10 ms.
- Set pins VDDIO, AVDD, and LPn pins to high. Toggling only I2C_RST pin resets the I2C communication.
4.3 Resolution
The resolution corresponds to the number of available zones. The VL53L7CX
sensor has two possible resolutions: 4×4 (16 zones) and 8×8 (64 zones). By
default the sensor is programmed in 4×4.
The function vl53l7cx_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 bus when results are
read.
4.4 Ranging frequency
Ranging frequency can be used to change the measurement frequency. As the
maximum frequency is different between 4×4 and 8×8 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] |
---|---|---|
4×4 | 1 | 60 |
8×8 | 1 | 15 |
Ranging frequency can be updated using function
vl53l7cx_set_ranging_frequency_hz(). By default, the ranging frequency is set
to 1 Hz.
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 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 function vl53l7cx_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 function vl53l7cx_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 4×4 and 8×8 resolutions.
Resolution 4×4 is composed of one integration time, and 8×8 resolution is
composed of four integration times. The following figures represent the VCSEL
emission for both resolutions.
Figure 8. Integration time for 4×4 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.
4.7 Power modes
Power modes can be used to reduce the power consumption when the device is not
used. The VL53L7CX can operate in one of the following power modes:
- Wake-up: The device is set in HP idle (high power), waiting for instructions.
- Sleep: The device is set in LP idle (low power), the low power state. The device cannot be used until set in Wake-up mode. This mode retains the firmware and the configuration.
The power mode can be changed using function vl53l7cx_set_power_mode(). The
default mode is Wake-up.
Note If the user wants to change the power mode, the device must not be
in a ranging state.
4.8 Sharpener
The signal returned from a target is not a clean pulse with sharp edges. The
edges slope away and may affect the distances reported in adjacent zones. The
sharpener is used to remove some or all of the signal caused by veiling glare.
The example shown in the following figure represents a close target at 100 mm
centered in the FoV, and another target, further behind at 500 mm. Depending
on the sharpener value, the close target may appear in more zones than the
real one.
Figure 10. Example of scene using several sharpener values
Sharpener can be changed using function vl53l7cx_set_sharpener_percent().
The allowed values are between 0 % and 99 %. The default value is 5 %.
4.9 Target order
The VL53L7CX can measure several targets per zone. Thanks to the histogram
processing, the host is able to choose the order of reported targets. There
are two options:
- Closest: The closest target is the first reported
- Strongest: The strongest target is the first reported
The target order can be changed using function vl53l7cx_set_target_order().
The default order is Strongest.
The example in the following figure represents the detection of two targets.
One at 100 mm with a low reflectance, and one at 700 mm with a high
reflectance.
Figure 11. Example of histogram with 2 targets
4.10 Multiple targets per zone
The VL53L7CX can measure up to four targets per zone. The user can configure
the number of targets returned by the sensor.
Note The minimum distance between two targets to be detected is 600 mm.
The selection is not possible from the driver; it has to be done in the
platform.h’ file. The macro VL53L7CX_NB_ TARGET_PER_ZONE needs to be set to a value between 1 and 4. The target order described in Section 4.9 Target order directly impacts the order of detected target. By default, the sensor only outputs a maximum of one target per zone. **Note** An increased number of targets per zone increases the required RAM size. **4.11 Xtalk margin** The Xtalk margin is an additional feature only available using the plugin Xtalk. The .c and .f files ‘vl53l7cx_plugin_xtalk’ need to be used. The margin is used to change the detection threshold when a cover lass is present on the top of the sensor. The threshold can be increased to ensure that the coverless is never detected, after setting X talk calibration data. For example, the user can run a Xwalk calibration on one single device, and re-use the same calibration data for all other devices. The X talk margin can be used to tune the X talk correction. The figure below represents the Xwalk margin. **Figure 12. X talk margin 4.12 Detection thresholds** In addition to the regular ranging capabilities, the sensor can be programmed to detect an object under certain predefined criteria. This feature is available using the plugin “detection thresholds”, which is an option not included by default in the API. The files called
vl53l7cx_plugin_detection_thresholds’ need to be used. The feature can be
used to trigger an interrupt to pin A3 (INT) when conditions defined by the
user are met. There are three possible configurations:
- Resolution 4×4: using 1 threshold per zone (total of 16 thresholds)
- Resolution 4×4: using 2 thresholds per zone (total of 32 thresholds)
- Resolution 8×8: using 1 threshold per zone (total of 64 thresholds)
Whatever the configuration used, the procedure for creating thresholds and the
RAM size are the same.
For each threshold combination, several fields need to be filled:
- Zone id: id of the selected zone (refer to Section 2.2 Effective orientation)
- Measurement: measurement to catch (distance, signal, number of SPADs, …)
- Type: windows of measurements (in windows, out of windows, below low threshold, …)
- Low threshold: low threshold user for trigger. User does not need to set the format, it is automatically handled by the API.
- High threshold: high threshold user for trigger. User does not need to set the format, it is automatically handled by the API.
- Mathematic operation: only used for 4×4 2 threshold combinations per zone. The user can set a combination using several thresholds in one zone.
4.13 Motion indicator
The VL53L7CX sensor has an embedded Firmware feature allowing motion
detection in a scene. The motion indicator is computed between sequential
frames. This option is available using the plugin
vl53l7cx_plugin_motion_indicator’. The motion indicator is initialized using the vl53l7cx_motion_indicator_init() function. If the user wants to change the sensor resolution, he must update the motion indicator resolution using the dedicated function: vl53l7cx_motion_indicator_set_resolution(). The user may also change the minimum and maximum distances for detecting motion. The difference between the minimum and maximum distances cannot be greater than 1500 mm. By default, distances are initialized with values between 400 mm and 1500 mm. Results are stored in the field
motion indicator’. In this field, the array
`motion’ gives a value containing the motion intensity per zone. A high value
indicates high motion variation between frames. A typical movement gives a
value between 100 and 500. This sensitivity depends on the integration time,
target distance, and target reflectance.
An ideal combination for low power applications is the use of the motion
indicator with Autonomous ranging mode, and detection thresholds programmed on
the motion. This allows detection of movement variations in the FoV with
minimum power consumption.
Ranging results
5.1 Available data
An extensive list of target and environment data may be output during ranging
activities. The following table describes the parameters available to the
user.
Table 3. Available output using VL53L7CX sensor
Element | Nb bytes (RAM) | Unit | Description |
---|---|---|---|
Ambient per SPAD | 256 | Kcps/SPAD | Ambient rate measurement performed on the |
SPAD array, with no active photon emission, to measure the ambient signal rate
due to noise.
Number of targets detected| 64| None| Number of detected targets in the
current zone.This value should be the first one to check to know a measurement
validity.
Number of SPADs enabled| 256| None| Number of SPADs enabled for the current
measurement. A far or low reflective target will activate more SPADs.
Signal per SPAD| 256 x nb targets programmed| Kcps/SPAD| Quantity of photons
measured during the VCSEL pulse.
Range sigma| 128 x nb targets programmed| Millimeter| Sigma estimator for the
noise in the reported
target distance.
Distance| 128 x nb targets programmed| Millimeter| Target distance
Target status| 64 x nb targets programmed| None| Measurements validity. See
Section 5.5 Results interpretation for more information.
Reflectance| 64 x number targets programmed| Percent| Estimated target
reflectance in percent
Motion indicator| 140| None| Structure containing the motion indicator
results.
The field ‘motion’ contains the motion intensity.
Note: For several elements (signal per sped, sigma, …) access to data is
different if user has programmed more than 1 target per zone (see Section 4.10
Multiple targets per zone). See example codes for more information.
5.2 Customize output selection
By default, all VL53L7CX outputs are enabled. If needed, the user can disable
some sensor output. Disabling measurements is not available on the driver; it
must be performed in the `platform’s’ file. The user can declare the following
macros to disable outputs:
define VL53L7CX_DISABLE_AMBIENT_PER_SPAD
define VL53L7CX_DISABLE_NB_SPADS_ENABLED
define VL53L7CX_DISABLE_NB_TARGET_DETECTED
define VL53L7CX_DISABLE_SIGNAL_PER_SPAD
define VL53L7CX_DISABLE_RANGE_SIGMA_MM
define VL53L7CX_DISABLE_DISTANCE_MM
define VL53L7CX_DISABLE_TARGET_STATUS
define VL53L7CX_DISABLE_REFLECTANCE_PERCENT
define VL53L7CX_DISABLE_MOTION_INDICATOR
Consequently, the fields are not be declared in the results structure, and the
data is not transferred to the host. The RAM size and I2C size are reduced. To
ensure data consistency, ST recommends to always keep number of target detected’ and
target status’ enabled. It allows filtering the measurements
depending of the target status (refer to Section 5.5 Results interpretation).
5.3 Getting ranging results
During the ranging session, there are two ways to know if new ranging data
is available:
- Polling mode: Continuously uses function vl53l7cx_check_data_ready(). It detects a new stream count returned by the sensor.
- Interrupt mode: Waits for an interrupt raised on pin A3 (GPIO1). The interrupt is automatically cleared after ~100 s.
When new data is ready, the results can be read using function
vl53l7cx_get_ranging_data(). It returns an updated structure containing all
selected output. As the device is asynchronous, there is no interrupt to clear
to continue the ranging session.
This feature is available for both continuous and autonomous ranging modes.
5.4 Using raw firmware format
After transferring ranging data through I2C, there is a conversion between
the firmware format and the host format. This operation is typically performed
to have a ranging distance in millimeters as a default output of the sensor.
If the user wants to use the firmware format, the following macro must be
defined in the platform file:
#define VL53L7CX_USE_RAW_FORMAT
5.5 Results interpretation
The data returned by the VL53L7CX can be filtered in order to take into
account the target status. The status indicates the measurement validity. The
full status list is described in the following table.
Target status | Description |
---|---|
0 | Ranging data are not updated |
1 | Signal rate too low on SPAD array |
2 | Target phase |
3 | Sigma estimator too high |
4 | Target consistency failed |
5 | Range valid |
6 | Wrap around not performed (Typically the first range) |
7 | Rate consistency failed |
8 | Signal rate too low for the current target |
9 | Range valid with large pulse (may be due to a merged target) |
10 | Range valid, but no target detected at previous range |
11 | Measurement consistency failed |
12 | Target blurred by another one, due to sharpener |
13 | Target detected but inconsistent data. Frequently happens for secondary |
targets.
255| No target detected (only if number of target detected is enabled)
To have consistent data, the user needs to filter invalid target status. To
give a confidence rating, a target with status 5 is considered as 100 % valid.
A status of 6 or 9 can be considered with a confidence value of 50 %. All
other statuses are below 50 % confidence level.
5.6 Driver errors
When an error occurs using VL53L7CX sensor, the driver returns a specific
error. The following table lists the possible errors.
Table 5. List of errors available using the driver
Target status | Description |
---|---|
0 | No error |
127 | User programmed an incorrect setting (unknown resolution, ranging |
frequency too high, …)
255| Major error. Usually a timeout error, due to an I2C error.
other| Combination of multiple errors described above
Note More error codes can be implemented by the host using the platform
files.
Revision history
Table 6. Document revision history
Date | Version | Changes |
---|---|---|
2-Aug-22 | 1 | Initial release |
2-Sep-22 | 2 | Updated Section Introduction Added note about minimum distance |
between targets to Section 4.10 Multiple targets per zone
IMPORTANT NOTICE 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 acknowledgment.
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, 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.
© 2022 STMicroelectronics All rights reserved
References
- STMicroelectronics: Our technology starts with you
- STMicroelectronics Trademark List - STMicroelectronics
Read User Manual Online (PDF format)
Read User Manual Online (PDF format) >>