ST VL53L1X API User Manual

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 Low-
power 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 use-
cases 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

ST VL53L1X API Specifications

General

Brand	ST
Model	VL53L1X API
Category	Control Unit
Language	English

Summary

Introduction

Acronyms and Abbreviations

VL53L1X System Overview

Ranging API Functional Description

Distance Ranging Description

Describes the autonomous ranging process and host interaction for distance measurement.

Distance Threshold Detection Description

Explains how to detect objects based on predefined distance criteria using specific functions.

Timing Considerations

Details timing budget (TB) and inter-measurement period (IMP) for measurement accuracy and power.

API Function Call Flow

Calibration Flow

Outlines the sequence of API calls for sensor calibration during manufacturing.

Ranging Flow

Describes the sequence of API calls for distance measurements and object detection.

Mandatory Functions

Sensor Boot

Explains the VL53L1X_BootState function to verify sensor boot-up before I2C access.

Sensor Initialization

Describes the VL53L1X_SensorInit function for initializing the sensor with default configuration.

Start Measurement

Details the VL53L1X_StartRanging function to initiate a distance measurement.

Optional Functions

Wait for Data Ready Notification

Explains methods for receiving notifications when ranging data is ready (polling or interrupt).

Get Ranging Data

Describes functions like GetRangeStatus and GetDistance to retrieve measurement results.

Clear Interrupt

Explains the VL53L1X_ClearInterrupt function to reset the interrupt for new data events.

Stop Measurement

Details the VL53L1X_Stop function to halt ongoing ranging operations.

Setting Distance Mode

Describes how to set distance modes (Short/Long) affecting range and ambient light performance.

Inter-Measurement Period

Explains setting the time between ranging operations (IMP) and its relation to timing budget.

Setting the Timing Budget

Details setting the timing budget (TB) for measurement accuracy and power consumption.

Setting Threshold and Detection Mode

Configures detection criteria and interrupts based on distance thresholds and window modes.

Setting ROI

Explains how to program the Region of Interest (ROI) to reduce FoV and SPAD usage.

Ranging Example Pseudo Code

Calibration Functions

Offset Calibration

Covers running, getting, and setting offset calibration for device-to-device variations.

Crosstalk Calibration

Details crosstalk calibration to compensate for cover glass effects on ranging performance.

Crosstalk Calibration Procedure

Details the step-by-step procedure for performing crosstalk calibration.

Setting Crosstalk Calibration Data

Explains how to apply the calibrated crosstalk value to the sensor.

Range Status Interpretation

Reducing Driver Size

Function Descriptions

Get SW Version

Returns the software driver version.

Set I2C Address

Sets the sensor's I2C address for multi-device applications.

Sensor Initialization

Loads configuration values to initialize the sensor.

Clear Interrupt

Clears the interrupt flag after data reading to arm the next event.

Set Interrupt Polarity

Programs the interrupt polarity (active high or low).

Get Interrupt Polarity

Returns the current interrupt polarity setting.

Start Ranging

Starts the continuous distance ranging operation.

Stop Ranging

Stops the ongoing ranging operation.

Check For Data Ready

Checks if new ranging data is available by polling a register.

Set Timing Budget

Programs the timing budget in milliseconds for measurements.

Get Timing Budget

Returns the current timing budget in milliseconds.

Set Distance Mode

Sets the distance mode (Short or Long) affecting range and performance.

Get Distance Mode

Returns the current distance mode setting.

Set Inter-Measurement Period

Programs the inter-measurement period in milliseconds.

Get Inter-Measurement Period

Returns the current inter-measurement period in milliseconds.

Boot State

Returns the boot state of the device (booted or not).

Get Sensor ID

Returns the sensor ID, which should be 0xEEAC.

Get Distance

Returns the measured distance in millimeters.

Get Signal Per SPAD

Gives the returned signal per SPAD in kcps/SPAD.

Get Ambient Per SPAD

Returns the ambient per SPAD in kcps/SPAD.

Get Signal Rate

Gives the returned signal in kcps.

Get SPAD Number

Returns the current number of enabled SPADs.

Get Ambient Rate

Returns the ambient rate in kcps.

Get Range Status

Returns the ranging status error code.

Set Offset

Programs the offset correction value in millimeters.

Get Offset

Returns the programmed offset correction value in millimeters.

Set Crosstalk

Programs the crosstalk correction value in cps.

Get Crosstalk

Returns the current programmed crosstalk correction value in cps.

Set Distance Threshold

Programs the threshold detection mode and criteria.

Get Distance Threshold Window

Returns the window detection mode (below, above, out, in).

Get Distance Threshold Low

Returns the low distance threshold in millimeters.

Get Distance Threshold High

Returns the high distance threshold in millimeters.

Set ROI

Programs the Region of Interest (ROI) width and height.

Get ROI XY

Returns the current ROI width and height.

Set Signal Threshold

Programs a new signal threshold in kcps.

Get Signal Threshold

Returns the current signal threshold in kcps.

Set Sigma Threshold

Programs a new sigma threshold in millimeters.

Get Sigma Threshold

Returns the current sigma threshold in millimeters.

Start Temperature Update

Performs temperature calibration or update.

API Structure

Revision History