ST / VL53L1X_mbed

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   X_NUCLEO_COMMON ST_INTERFACES

Dependents:   X_NUCLEO_53L1A1_mbed X_NUCLEO_53L1A1_mbed VL53L1X_Ranging_With_Standalone_Satellite_MbedOS X_NUCLEO_53L1A1

Embed: (wiki syntax)

« Back to documentation index

VL53L1X Class Reference
Public Member Functions

VL53L1X Class Reference

Class representing a VL53L1 sensor component. More...

#include <VL53L1X_Class.h>

Public Member Functions

 VL53L1X (VL53L1X_DevI2C *i2c, DigitalOut *pin, PinName pin_gpio1, uint8_t dev_addr=VL53L1X_DEFAULT_DEVICE_ADDRESS)
 Constructor.
 VL53L1X (VL53L1X_DevI2C *i2c, Stmpe1600DigiOut *pin, PinName pin_gpio1, uint8_t dev_addr=VL53L1X_DEFAULT_DEVICE_ADDRESS)
 Constructor 2 (STMPE1600DigiOut)
virtual ~VL53L1X ()
 Destructor.
virtual void vl53l1_on (void)
 PowerOn the sensor.
virtual void vl53l1_off (void)
 PowerOff the sensor.
VL53L1X_ERROR init_sensor (uint8_t address)
 Initialize the sensor with default values.
virtual int init (void *init)
 One time device initialization.
int handle_irq (uint16_t *distance)
 Interrupt handling func to be called by user after an INT is occurred.
int start_measurement (void(*fptr)(void))
 Start the measure indicated by operating mode.
int stop_measurement ()
 Stop the currently running measure indicate by operating_mode.
int get_measurement (uint16_t *distance)
 Get results for the measure.
void enable_interrupt_measure_detection_irq (void)
 Enable interrupt measure IRQ.
void disable_interrupt_measure_detection_irq (void)
 Disable interrupt measure IRQ.
void attach_interrupt_measure_detection_irq (void(*fptr)(void))
 Attach a function to call when an interrupt is detected, i.e.
virtual int get_distance (uint32_t *piData)
 Get ranging result and only that.
VL53L1X_ERROR vl53l1x_get_sw_version (VL53L1X_Version_t *pVersion)
 This function returns the SW driver version.
VL53L1X_ERROR vl53l1x_set_i2c_address (uint8_t new_address)
 This function sets the sensor I2C address used in case multiple devices application, default address 0x52.
VL53L1X_ERROR vl53l1x_sensor_init ()
 This function loads the 135 bytes default values to initialize the sensor.
VL53L1X_ERROR vl53l1x_clear_interrupt ()
 This function clears the interrupt, to be called after a ranging data reading to arm the interrupt for the next data ready event.
VL53L1X_ERROR vl53l1x_set_interrupt_polarity (uint8_t IntPol)
 This function programs the interrupt polarity
1=active high (default), 0=active low.
VL53L1X_ERROR vl53l1x_get_interrupt_polarity (uint8_t *pIntPol)
 This function returns the current interrupt polarity
1=active high (default), 0=active low.
VL53L1X_ERROR vl53l1x_start_ranging ()
 This function starts the ranging distance operation
The ranging operation is continuous.
VL53L1X_ERROR vl53l1x_stop_ranging ()
 This function stops the ranging.
VL53L1X_ERROR vl53l1x_check_for_data_ready (uint8_t *isDataReady)
 This function checks if the new ranging data is available by polling the dedicated register.
VL53L1X_ERROR vl53l1x_set_timing_budget_in_ms (uint16_t TimingBudgetInMs)
 This function programs the timing budget in ms.
VL53L1X_ERROR vl53l1x_get_timing_budget_in_ms (uint16_t *pTimingBudgetInMs)
 This function returns the current timing budget in ms.
VL53L1X_ERROR vl53l1x_set_distance_mode (uint16_t DistanceMode)
 This function programs the distance mode (1=short, 2=long(default)).
VL53L1X_ERROR vl53l1x_get_distance_mode (uint16_t *pDistanceMode)
 This function returns the current distance mode (1=short, 2=long).
VL53L1X_ERROR vl53l1x_set_inter_measurement_in_ms (uint16_t InterMeasurementInMs)
 This function programs the Intermeasurement period in ms
Intermeasurement period must be >/= timing budget.
VL53L1X_ERROR vl53l1x_get_inter_measurement_in_ms (uint16_t *pIM)
 This function returns the Intermeasurement period in ms.
VL53L1X_ERROR vl53l1x_boot_state (uint8_t *state)
 This function returns the boot state of the device (1:booted, 0:not booted)
VL53L1X_ERROR vl53l1x_get_sensor_id (uint16_t *id)
 This function returns the sensor id, sensor Id must be 0xEEAC.
VL53L1X_ERROR vl53l1x_get_distance (uint16_t *distance)
 This function returns the distance measured by the sensor in mm.
VL53L1X_ERROR vl53l1x_get_signal_per_spad (uint16_t *signalPerSp)
 This function returns the returned signal per SPAD in kcps/SPAD.
VL53L1X_ERROR vl53l1x_get_ambient_per_spad (uint16_t *amb)
 This function returns the ambient per SPAD in kcps/SPAD.
VL53L1X_ERROR vl53l1x_get_signal_rate (uint16_t *signalRate)
 This function returns the returned signal in kcps.
VL53L1X_ERROR vl53l1x_get_spad_nb (uint16_t *spNb)
 This function returns the current number of enabled SPADs.
VL53L1X_ERROR vl53l1x_get_ambient_rate (uint16_t *ambRate)
 This function returns the ambient rate in kcps.
VL53L1X_ERROR vl53l1x_get_range_status (uint8_t *rangeStatus)
 This function returns the ranging status error
(0:no error, 1:sigma failed, 2:signal failed, ..., 7:wrap-around)
VL53L1X_ERROR vl53l1x_set_offset (int16_t OffsetValue)
 This function programs the offset correction in mm.
VL53L1X_ERROR vl53l1x_get_offset (int16_t *Offset)
 This function returns the programmed offset correction value in mm.
VL53L1X_ERROR vl53l1x_set_xtalk (uint16_t XtalkValue)
 This function programs the xtalk correction value in cps (Count Per Second).
VL53L1X_ERROR vl53l1x_get_xtalk (uint16_t *Xtalk)
 This function returns the current programmed xtalk correction value in cps.
VL53L1X_ERROR vl53l1x_set_distance_threshold (uint16_t ThreshLow, uint16_t ThreshHigh, uint8_t Window, uint8_t IntOnNoTarget)
 This function programs the threshold detection mode
Example:
vl53l1x_set_distance_threshold(dev,100,300,0,1): Below 100
vl53l1x_set_distance_threshold(dev,100,300,1,1): Above 300
vl53l1x_set_distance_threshold(dev,100,300,2,1): Out of window
vl53l1x_set_distance_threshold(dev,100,300,3,1): In window
.
VL53L1X_ERROR vl53l1x_get_distance_threshold_window (uint16_t *window)
 This function returns the window detection mode (0=below; 1=above; 2=out; 3=in)
VL53L1X_ERROR vl53l1x_get_distance_threshold_low (uint16_t *low)
 This function returns the low threshold in mm.
VL53L1X_ERROR vl53l1x_get_distance_threshold_high (uint16_t *high)
 This function returns the high threshold in mm.
VL53L1X_ERROR vl53l1x_set_roi (uint16_t X, uint16_t Y)
 This function programs the ROI (Region of Interest)
The ROI position is centered, only the ROI size can be reprogrammed.
VL53L1X_ERROR vl53l1x_get_roi_xy (uint16_t *ROI_X, uint16_t *ROI_Y)
 This function returns width X and height Y.
VL53L1X_ERROR vl53l1x_set_signal_threshold (uint16_t signal)
 This function programs a new signal threshold in kcps (default=1024 kcps
.
VL53L1X_ERROR vl53l1x_get_signal_threshold (uint16_t *signal)
 This function returns the current signal threshold in kcps.
VL53L1X_ERROR vl53l1x_set_sigma_threshold (uint16_t sigma)
 This function programs a new sigma threshold in mm (default=15 mm)
VL53L1X_ERROR vl53l1x_get_sigma_threshold (uint16_t *signal)
 This function returns the current sigma threshold in mm.
VL53L1X_ERROR vl53l1x_start_temperature_update ()
 This function performs the temperature calibration.
int8_t vl53l1x_calibrate_offset (uint16_t TargetDistInMm, int16_t *offset)
 This function performs the offset calibration.
int8_t vl53l1x_calibrate_xtalk (uint16_t TargetDistInMm, uint16_t *xtalk)
 This function performs the xtalk calibration.

Detailed Description

Class representing a VL53L1 sensor component.

Definition at line 139 of file VL53L1X_Class.h.

Constructor & Destructor Documentation

VL53L1X ( VL53L1X_DevI2C *  i2c,
DigitalOut *  pin,
PinName  pin_gpio1,
uint8_t  dev_addr = VL53L1X_DEFAULT_DEVICE_ADDRESS 
)

Constructor.

Parameters:
[in]&i2cdevice I2C to be used for communication
[in]&pin_gpio1pin Mbed InterruptIn PinName to be used as component GPIO_1 INT
[in]DevAddrdevice address, 0x52 by default

Definition at line 147 of file VL53L1X_Class.h.

VL53L1X ( VL53L1X_DevI2C *  i2c,
Stmpe1600DigiOut *  pin,
PinName  pin_gpio1,
uint8_t  dev_addr = VL53L1X_DEFAULT_DEVICE_ADDRESS 
)

Constructor 2 (STMPE1600DigiOut)

Parameters:
[in]i2cdevice I2C to be used for communication
[in]&pinGpio Expander STMPE1600DigiOut pin to be used as component GPIO_0 CE
[in]pin_gpio1pin Mbed InterruptIn PinName to be used as component GPIO_1 INT
[in]deviceaddress, 0x29 by default

Definition at line 167 of file VL53L1X_Class.h.

virtual ~VL53L1X (  ) [virtual]

Destructor.

Definition at line 184 of file VL53L1X_Class.h.

Member Function Documentation

void attach_interrupt_measure_detection_irq ( void(*)(void)  fptr )

Attach a function to call when an interrupt is detected, i.e.

measurement is ready

Parameters:
[in]fptrpointer to call back function to be called whenever an interrupt occours
Returns:
0 on Success

Definition at line 379 of file VL53L1X_Class.h.

void disable_interrupt_measure_detection_irq ( void   )

Disable interrupt measure IRQ.

Returns:
0 on Success

Definition at line 369 of file VL53L1X_Class.h.

void enable_interrupt_measure_detection_irq ( void   )

Enable interrupt measure IRQ.

Returns:
0 on Success

Definition at line 359 of file VL53L1X_Class.h.

virtual int get_distance ( uint32_t *  piData ) [virtual]

Get ranging result and only that.

Parameters:
pRange_mmPointer to range distance
Returns:
0 on success

Definition at line 389 of file VL53L1X_Class.h.

int get_measurement ( uint16_t *  distance )

Get results for the measure.

Parameters:
[out]Datapointer to the distance_data to read data in to
Returns:
0 on Success

Definition at line 1054 of file VL53L1X_Class.cpp.

int handle_irq ( uint16_t *  distance )

Interrupt handling func to be called by user after an INT is occurred.

Parameters:
[out]Datapointer to the distance to read data in to
Returns:
0 on Success

Definition at line 1046 of file VL53L1X_Class.cpp.

virtual int init ( void *  init ) [virtual]

One time device initialization.

Parameters:
void
Returns:
0 on success, CALIBRATION_WARNING if failed

Definition at line 296 of file VL53L1X_Class.h.

VL53L1X_ERROR init_sensor ( uint8_t  address )

Initialize the sensor with default values.

Returns:
0 on Success

Definition at line 264 of file VL53L1X_Class.h.

int start_measurement ( void(*)(void)  fptr )

Start the measure indicated by operating mode.

Parameters:
[in]fptrspecifies call back function must be !NULL in case of interrupt measure
Returns:
0 on Success

Definition at line 1064 of file VL53L1X_Class.cpp.

int stop_measurement (  )

Stop the currently running measure indicate by operating_mode.

Returns:
0 on Success

Definition at line 1087 of file VL53L1X_Class.cpp.

virtual void vl53l1_off ( void   ) [virtual]

PowerOff the sensor.

Returns:
void

Definition at line 229 of file VL53L1X_Class.h.

virtual void vl53l1_on ( void   ) [virtual]

PowerOn the sensor.

Returns:
void

Definition at line 206 of file VL53L1X_Class.h.

VL53L1X_ERROR vl53l1x_boot_state ( uint8_t *  state )

This function returns the boot state of the device (1:booted, 0:not booted)

Definition at line 396 of file VL53L1X_Class.cpp.

int8_t vl53l1x_calibrate_offset ( uint16_t  TargetDistInMm,
int16_t *  offset 
)

This function performs the offset calibration.


The function returns the offset value found and programs the offset compensation into the device.

Parameters:
TargetDistInMmtarget distance in mm, ST recommended 100 mm Target reflectance = grey17%
Returns:
0:success, !=0: failed
offset pointer contains the offset found in mm

Definition at line 745 of file VL53L1X_Class.cpp.

int8_t vl53l1x_calibrate_xtalk ( uint16_t  TargetDistInMm,
uint16_t *  xtalk 
)

This function performs the xtalk calibration.


The function returns the xtalk value found and programs the xtalk compensation to the device

Parameters:
TargetDistInMmtarget distance in mm
The target distance : the distance where the sensor start to "under range"
due to the influence of the photons reflected back from the cover glass becoming strong
It's also called inflection point
Target reflectance = grey 17%
Returns:
0: success, !=0: failed
xtalk pointer contains the xtalk value found in cps (number of photons in count per second)

Definition at line 773 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_check_for_data_ready ( uint8_t *  isDataReady )

This function checks if the new ranging data is available by polling the dedicated register.

Parameters:
:isDataReady==0 -> not ready; isDataReady==1 -> ready

Definition at line 155 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_clear_interrupt (  )

This function clears the interrupt, to be called after a ranging data reading to arm the interrupt for the next data ready event.

Definition at line 102 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_ambient_per_spad ( uint16_t *  amb )

This function returns the ambient per SPAD in kcps/SPAD.

Definition at line 443 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_ambient_rate ( uint16_t *  ambRate )

This function returns the ambient rate in kcps.

Definition at line 479 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_distance ( uint16_t *  distance )

This function returns the distance measured by the sensor in mm.

Definition at line 418 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_distance_mode ( uint16_t *  pDistanceMode )

This function returns the current distance mode (1=short, 2=long).

Definition at line 353 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_distance_threshold_high ( uint16_t *  high )

This function returns the high threshold in mm.

Definition at line 641 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_distance_threshold_low ( uint16_t *  low )

This function returns the low threshold in mm.

Definition at line 631 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_distance_threshold_window ( uint16_t *  window )

This function returns the window detection mode (0=below; 1=above; 2=out; 3=in)

Definition at line 621 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_inter_measurement_in_ms ( uint16_t *  pIM )

This function returns the Intermeasurement period in ms.

Definition at line 381 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_interrupt_polarity ( uint8_t *  pIntPol )

This function returns the current interrupt polarity
1=active high (default), 0=active low.

Definition at line 124 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_offset ( int16_t *  Offset )

This function returns the programmed offset correction value in mm.

Definition at line 560 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_range_status ( uint8_t *  rangeStatus )

This function returns the ranging status error
(0:no error, 1:sigma failed, 2:signal failed, ..., 7:wrap-around)

Definition at line 490 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_roi_xy ( uint16_t *  ROI_X,
uint16_t *  ROI_Y 
)

This function returns width X and height Y.

Definition at line 670 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_sensor_id ( uint16_t *  id )

This function returns the sensor id, sensor Id must be 0xEEAC.

Definition at line 407 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_sigma_threshold ( uint16_t *  signal )

This function returns the current sigma threshold in mm.

Definition at line 713 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_signal_per_spad ( uint16_t *  signalPerSp )

This function returns the returned signal per SPAD in kcps/SPAD.

With kcps stands for Kilo Count Per Second

Definition at line 429 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_signal_rate ( uint16_t *  signalRate )

This function returns the returned signal in kcps.

Definition at line 455 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_signal_threshold ( uint16_t *  signal )

This function returns the current signal threshold in kcps.

Definition at line 689 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_spad_nb ( uint16_t *  spNb )

This function returns the current number of enabled SPADs.

Definition at line 467 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_sw_version ( VL53L1X_Version_t *  pVersion )

This function returns the SW driver version.

Definition at line 50 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_timing_budget_in_ms ( uint16_t *  pTimingBudgetInMs )

This function returns the current timing budget in ms.

Definition at line 276 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_get_xtalk ( uint16_t *  Xtalk )

This function returns the current programmed xtalk correction value in cps.

Definition at line 588 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_sensor_init (  )

This function loads the 135 bytes default values to initialize the sensor.

Parameters:
devDevice address
Returns:
0:success, != 0:failed

Definition at line 71 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_distance_mode ( uint16_t  DistanceMode )

This function programs the distance mode (1=short, 2=long(default)).

Short mode max distance is limited to 1.3 m but better ambient immunity.
Long mode can range up to 4 m in the dark with 200 ms timing budget.

Definition at line 318 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_distance_threshold ( uint16_t  ThreshLow,
uint16_t  ThreshHigh,
uint8_t  Window,
uint8_t  IntOnNoTarget 
)

This function programs the threshold detection mode
Example:
vl53l1x_set_distance_threshold(dev,100,300,0,1): Below 100
vl53l1x_set_distance_threshold(dev,100,300,1,1): Above 300
vl53l1x_set_distance_threshold(dev,100,300,2,1): Out of window
vl53l1x_set_distance_threshold(dev,100,300,3,1): In window
.

Parameters:
dev: device address
ThreshLow(inmm) : the threshold under which one the device raises an interrupt if Window = 0
ThreshHigh(inmm) : the threshold above which one the device raises an interrupt if Window = 1
Windowdetection mode : 0=below, 1=above, 2=out, 3=in
IntOnNoTarget= 1 (No longer used - just use 1)

Definition at line 599 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_i2c_address ( uint8_t  new_address )

This function sets the sensor I2C address used in case multiple devices application, default address 0x52.

Definition at line 61 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_inter_measurement_in_ms ( uint16_t  InterMeasurementInMs )

This function programs the Intermeasurement period in ms
Intermeasurement period must be >/= timing budget.

This condition is not checked by the API, the customer has the duty to check the condition. Default = 100 ms

Definition at line 367 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_interrupt_polarity ( uint8_t  IntPol )

This function programs the interrupt polarity
1=active high (default), 0=active low.

Definition at line 111 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_offset ( int16_t  OffsetValue )

This function programs the offset correction in mm.

Parameters:
OffsetValue:theoffset correction value to program in mm

Definition at line 546 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_roi ( uint16_t  X,
uint16_t  Y 
)

This function programs the ROI (Region of Interest)
The ROI position is centered, only the ROI size can be reprogrammed.


The smallest acceptable ROI size = 4

Parameters:
X:ROIWidth; Y=ROI Height

Definition at line 651 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_sigma_threshold ( uint16_t  sigma )

This function programs a new sigma threshold in mm (default=15 mm)

Definition at line 701 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_signal_threshold ( uint16_t  signal )

This function programs a new signal threshold in kcps (default=1024 kcps
.

Definition at line 681 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_timing_budget_in_ms ( uint16_t  TimingBudgetInMs )

This function programs the timing budget in ms.

Predefined values = 15, 20, 33, 50, 100(default), 200, 500.

Definition at line 174 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_set_xtalk ( uint16_t  XtalkValue )

This function programs the xtalk correction value in cps (Count Per Second).


This is the number of photons reflected back from the cover glass in cps.

Definition at line 572 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_start_ranging (  )

This function starts the ranging distance operation
The ranging operation is continuous.

The clear interrupt has to be done after each get data to allow the interrupt to raise when the next data is ready
1=active high (default), 0=active low, use SetInterruptPolarity() to change the interrupt polarity if required.

Definition at line 137 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_start_temperature_update (  )

This function performs the temperature calibration.

It is recommended to call this function any time the temperature might have changed by more than 8 deg C without sensor ranging activity for an extended period.

Definition at line 724 of file VL53L1X_Class.cpp.

VL53L1X_ERROR vl53l1x_stop_ranging (  )

This function stops the ranging.

Definition at line 145 of file VL53L1X_Class.cpp.

Generated on Thu Jul 14 2022 15:41:19 by  doxygen 1.7.2