A guide for using the VL53L8CX, low-power, high-performance Time-of-Flight multizone ranging sensor

The VL53L8CX system is composed of a hardware module and the ultra lite driver software (VL53L8CX 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.

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.

The communication between driver and firmware is handled by the I²C or SPI. The maximum capability of the I²C is 1 MHz, and the maximum capability of the SPI is 3 MHz. The implementation of each communication protocol requires pull ups as described into the VL53L8CX datasheet.

The VL53L8CX device has a default I²C address of 0x52. However, it is possible to change the default address to avoid conflicts with other devices, or to facilitate adding multiple VL53L8CX modules to the system for a greater system FoV. The I²C address can be changed using the vl53l8cx_set_i2c_address() function. To use the SPI, the multisensor is wired using an independent follower configuration (the NCS pin).

To allow a device to have its I²C address changed without affecting others on the I²C bus, it is important to disable the I²C 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 I²C address changed.
4. Program the I²C address to the device using the function set_i2c_address() function.
5. Pull up the LPn pin of the device not being reprogrammed.

All devices should now be available on the I²C bus. Repeat the above steps for all the devices in the system that require a new I²C address.

The VL53L8CX ULD package is composed of four folders. The driver is located in the folder /VL53L8CX_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 "vl53l8cx_plugin" (e.g vl53l8cx_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.

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.

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 VL53L8CX module is self-calibrated, and can be used without any additional calibration.

Crosstalk calibration may be required if the module is protected by a cover glass. The VL53L8CX is immune to crosstalk beyond 60 cm thanks to a histogram algorithm. However, at short distances below 60 cm, Xtalk 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 Xtalk plugin (optional). The user needs to use the file ‘vl53l8cx_plugin_xtalk’.

The crosstalk can be calibrated once, and data can be saved so it can be reused later. A target at a 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 to adapt the crosstalk calibration, as proposed in the following table.

• 1 sample ≈ 1 second
• 4 samples ≈ 2.5 seconds
• 16 samples ≈ 8.5 seconds

The calibration is performed using the function vl53l8cx_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.

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.

The VL53L8CX ULD API 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.

Initialization must be done before using the VL53L8CX sensor. This operation requires the user to:

1. Power on the sensor (VDDIO, AVDD, CORE_1V8, and LPn pins set to High
2. Call the function vl53l8cx_init(). The function copies the firmware (~84 Kbytes) to the module. This is done by loading the code over the I²C/SPI interface, and performing a boot routine to complete the initialization.

To reset the device, the following pins need to be toggled:

1. Set pins VDDIO, AVDD, and CORE_1V8 to low.
2. Wait 10 ms.
3. Set pins VDDIO, AVDD, and CORE_1V8 to high.

The resolution corresponds to the number of available zones. The VL53L8CX sensor has two possible resolutions: 4x4 (16 zones) and 8x8 (64 zones). By default the sensor is programmed in 4x4.

The function vl53l8cx_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 I²C/SPI bus when the results are read.

Ranging frequency can be used to change the measurement frequency. As the maximum frequency is different between 4x4 and 8x8 resolutions, use this functionality after choosing a resolution. The minimum and maximum allowed values are listed in the following table.

Ranging frequency can be updated using the function vl53l8cx_set_ranging_frequency_hz(). By default, the ranging frequency is set to 1 Hz.

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 vl53l8cx_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 vl53l8cx_set_ranging_mode().

Integration time is a feature only available using the autonomous ranging mode (refer to Ranging mode). It allows the user to change the time while VCSEL is enabled. Changing integration time if the 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.

The sum of all integration times + 1 ms overhead must be lower than the measurement period. Otherwise, the ranging period is automatically increased.

Power modes can be used to reduce the power consumption when the device is not used. The VL53L8CX 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.
• Deep sleep: The device is set in ultra-low power. In this mode, the sensor consumes a few microamps of current. However, the firmware, configuration, and calibration data are completely lost. The user needs to set the device in wake-up mode and reconfigure the sensor to start streaming.

The power mode can be changed using the function vl53l8cx_set_power_mode(). The default mode is wake-up.

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 a 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.

Sharpener can be changed using the function vl53l8cx_set_sharpener_percent(). The allowed values are between 0% and 99%. The default value is 1%.

The VL53L8CX 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 the function vl53l8cx_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.

The VL53L8CX can measure up to four targets per zone. The user can configure the number of targets returned by the sensor.

The selection is not possible from the driver; it has to be done in the ‘platform.h’ file. The macro VL53L8CX_NB_ TARGET_PER_ZONE needs to be set to a value between 1 and 4. The target order described in Target order directly impacts the order of detected target. By default, the sensor only outputs a maximum of one target per zone.

The Xtalk margin is an additional feature only available using the plugin Xtalk. The .c and .f files 'vl53l8cx_plugin_xtalk' need to be used.

The margin is used to change the detection threshold when a cover glass is present on the top of the sensor. The threshold can be increased to ensure that the cover glass is never detected, after setting crosstalk calibration data. For example, the user can run a crosstalk calibration on one single device, and reuse the same calibration data for all other devices. The Xtalk margin can be used to tune the crosstalk correction. The figure below represents the Xtalk margin.

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 ‘vl53l8cx_plugin_detection_thresholds’ need to be used.

The feature can be used to trigger an interrupt to pin A1 (INT) when conditions defined by the user are met. There are three possible configurations:

• Resolution 4x4: using one threshold per zone (a total of 16 thresholds)
• Resolution 4x4: using two thresholds per zone (a total of 32 thresholds)
• Resolution 8x8: using one threshold per zone (a 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 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. The user does not need to set the format; it is automatically handled by the API.
• Mathematic operation: only used for 4x4 – 2 threshold combinations per zone. The user can set a combination using several thresholds in one zone.

The interrupt autostop feature is used to abort the ranging session during a measurement. By default, the sensor cannot be stopped during a measurement, because the frame measurements need to be completed. However, by using autostop, the frame measurements are aborted when an interrupt is triggered.

The autostop feature is useful when it is combined with a detection threshold. When a target is detected, the current measurement is automatically aborted. Autostop can be used in a customer state machine to switch quickly to another sensor configuration.

An interrupt autostop feature can be enabled by using the function vl53l8cx_set_detection_threshold_auto_stop(). After a measurement is aborted, it is recommended to stop the sensor by using the function vl53l8cx_stop_ranging().

The VL53L8CX 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 ‘vl53l8cx_plugin_motion_indicator’.

The motion indicator is initialized using the vl53l8cx_motion_indicator_init() function. To change the sensor resolution, update the motion indicator resolution using the dedicated function: vl53l8cx_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.

An external trigger source can be used to synchronize the ToF ranging acquisitions for applications where there may be interference concerns. Such interferences include multiple VL53L8CX devices or IR image sensors within close proximity, or any other electronics emitting 940 nm IR light. When the external synchronization is enabled, the SYNC pin is configured as an input and the VL53L8CX waits for a rising edge on the SYNC pin to start the next single ranging acquisition. To use this feature, the SYNC pin (B1) must be connected to an external trigger source as described in the product datasheet.

External synchronization is only available in autonomous mode. There are no specific timing requirements for using the external synchronization. However, the VL53L8CX ranging frequency should be set higher than the external trigger signal frequency to ensure that each ranging acquisition has completed prior to the next external trigger event. The timing of the synchronized single ranging acquisition period follows the integration time in autonomous mode, as defined by the user.

The external synchronization can be enabled or disabled by using the function vl53l8cx_set_external_sync_pin_enable(). Ranging can be started using the function vl53l8cx_start_ranging(). The sensor waits for the external SYNC signal to trigger the next measurement process. To stop the sensor, the user must assert a stop condition in the system, and then on the next external SYNC pin assertion, the vl53l8cx_stop_ranging() function should be executed.

A typical flow for using the external synchronization pin is shown below in Figure 14 External synchronization flow.

The ranging performance is affected by temperature variations. The VL53L8CX sensor embeds a temperature compensation that is calibrated once when streaming starts. However, if the temperature evolves, the compensation may not be aligned with the new temperature. To avoid this issue, the customer can run a periodic temperature compensation by using an auto VHV. The periodic temperature calibration takes a few milliseconds to run. The user can define the period.

To use this feature, the customer needs to:

• Call the function vl53l8cx_set_VHV_repeat_count().
• Then, give the number of frames between every new calibration as the argument.

If the argument is 0, the compensation is disabled.

An extensive list of target and environment data may be output during ranging activities. The following table describes the parameters available to the user.

By default, all VL53L8CX outputs are enabled. If needed, the user can disable some sensor outputs.

Disabling measurements is not available on the driver; it must be performed in the ‘platform.h’ file. The user can declare the following macros to disable outputs:

#define VL53L8CX_DISABLE_AMBIENT_PER_SPAD
#define VL53L8CX_DISABLE_NB_SPADS_ENABLED
#define VL53L8CX_DISABLE_NB_TARGET_DETECTED
#define VL53L8CX_DISABLE_SIGNAL_PER_SPAD
#define VL53L8CX_DISABLE_RANGE_SIGMA_MM
#define VL53L8CX_DISABLE_DISTANCE_MM
#define VL53L8CX_DISABLE_TARGET_STATUS
#define VL53L8CX_DISABLE_REFLECTANCE_PERCENT
#define VL53L8CX_DISABLE_MOTION_INDICATOR

Consequently, the fields are not declared in the results structure, and the data is not transferred to the host. The RAM size and I²C/SPI size are reduced.

To ensure data consistency, ST always recommends keeping the ‘number of targets detected’ and ‘target status’ enabled. This filters the measurements depending on the target status (refer to Results interpretation).

During the ranging session, there are two ways to know if new ranging data is available:

• Polling mode: Continuously uses function vl53l8cx_check_data_ready(). It detects a new stream count returned by the sensor.
• Interrupt mode: Waits for an interrupt raised on pin A1 (INT). The interrupt is automatically cleared after ~100 μs.

When new data is ready, the results can be read using function vl53l8cx_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.

After transferring the ranging data through the I²C/SPI, 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: VL53L8CX

#define VL53L8CX_USE_RAW_FORMAT

The data returned by the VL53L8CX can be filtered to take into account the target status. The status indicates the measurement validity. The full status list is described in the following table.

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 the 50% confidence level.

When an error occurs using the VL53L8CX sensor, the driver returns a specific error. The following table lists the possible errors.