vl53l0x

VL53L0X Time-of-Flight ranging sensor library.

Author Rob Jansen, Copyright © 2025..2025, all rights reserved.
Adapted-by
Compiler 2.5r9

Description

Libray for the VL53L0X Time-of-Flight ranging sensor. It is controlled 
             using the IIC interface at a maximum speed of 400 kHz.


Sources

Based on the vl53l0x-arduino: https://github.com/pololu/vl53l0x-arduino
         Datasheet STMicroelectronics  VL53L0X DS11555 - Rev 6


Notes

The main program must initialize the used - default - IIC interface 
         with a maximum speed of 400 kHz and with a I2C_HARDWARE_TIMEOUT 
         defined. 


Dependencies

No dependency found



Summary

Global variables/contants

Procedures

Private

Functions

Private

API details

Global variables/contants

Procedures

  • vl53l0x_set_timeout(word in timeout)

     
    Set the response timeout. The response of the VL53L0X depends on the settings
    that are used. The timeout given is in ms. Timeout must be > 0 and < 10_000.
    Default after initialization is 250 ms.
     
    

  • vl53l0x_start_continuous(dword in period_ms)

    Start continuous ranging measurements. If period_ms (optional) is 0 or not
    given, continuous back-to-back mode is used (the sensor takes measurements as
    often as possible); otherwise, continuous timed mode is used, with the given
    inter-measurement period in milliseconds determining how often the sensor
    takes a measurement. Based on VL53L0X_StartMeasurement().
    
    

  • vl53l0x_stop_continuous()

    Stop continuous measurements. Based on VL53L0X_StopMeasurement().
    
    

  • vl53l0x_set_iic_address(byte in address)

     
    Set the IIC address of the VL53L0X to the given address.
    The default after power up is: VL53L0X_IIC_DEFAULT_ADDRESS
     
    

Private

Functions

  • vl53l0x_get_iic_address() return byte

     
    Get the IIC address of the VL53L0X module.
     
    

  • vl53l0x_get_signal_rate_limit() return word

     
    Get the return signal rate limit check value in 100 * MCPS
    The rate limit is returned in 100 * MCPS. Reason for using 100 * MCPS is 
    that we do not need to use float but instead use word.
     
    

  • vl53l0x_get_timeout() return word

     
    Get the current response timeout in ms. 
     
    

  • vl53l0x_set_vcsel_pulse_period(byte in type, byte in period_pclks) return bit

     
    Set the VCSEL (vertical cavity surface emitting laser) pulse period for the
    given period type (pre-range or final range) to the given value in PCLKs.
    Longer periods seem to increase the potential range of the sensor.
    Valid values of period_pcklks are (even numbers only):
    ) VL53L0X_VCSEL_PERIOD_PRE_RANGE:  12 to 18 (initialized default: 14)
    ) VL53L0X_VCSEL_PERIOD_FINAL_RANGE: 8 to 14 (initialized default: 10)
    Based on VL53L0X_set_vcsel_pulse_period().
    Returns TRUE when succesful.
     
    

  • vl53l0x_get_measurement_timing_budget() return dword

    Get the measurement timing budget in microseconds. Based on 
    VL53L0X_get_measurement_timing_budget_micro_seconds().
    
    

  • vl53l0x_set_measurement_timing_budget(dword in budget_us) return bit

    Set the measurement timing budget in microseconds, which is the time allowed
    for one measurement; the ST API and this library take care of splitting the
    timing budget among the sub-steps in the ranging sequence. A longer timing
    budget allows for more accurate measurements. Increasing the budget by a
    factor of N decreases the range measurement standard deviation by a factor
    of sqrt(N). Defaults to about 33 milliseconds; the minimum is 20 ms.
    based on VL53L0X_set_measurement_timing_budget_micro_seconds()
    Returns TRUE when succesfull.
    
    

  • vl53l0x_read_range_single_mil() return word

    Performs a single-shot range measurement and returns the reading in mil.
    Calls vl53l0x_read_range_single_millimeters() and converts it to mil.
    
    

  • vl53l0x_timeout_occured() return bit

     
    Returns TRUE if a timeout occured in one of the read functions or in case of
    timeout on the IIC bus if the IIC timeout is defined. Value is cleared after
    a call to this function. 
     
    

  • vl53l0x_init() return bit

    Initialize sensor using sequence based on VL53L0X_DataInit(),
    VL53L0X_StaticInit(), and VL53L0X_PerformRefCalibration().
    This function does not perform reference SPAD calibration
    (VL53L0X_PerformRefSpadManagement()), since the API user manual says that it
    is performed by ST on the bare modules. It seems like that should work well
    enough unless a cover glass is added. We use the 2V8 mode since at power up 
    the module is in 1V8 mode. At initialization the module ID is checked.
    Returns TRUE if initialization was succesful.
    
    

  • vl53l0x_read_range_continuous_millimeters() return word

    Returns a range reading in millimeters when continuous mode is active
    (readRangeSingleMillimeters() also calls this function after starting a
    single-shot range measurement).
    
    

  • vl53l0x_valid_module() return bit

    Check presence of correct module. Returns TRUE when valid.
    
    

  • vl53l0x_read_range_single_millimeters() return word

    Performs a single-shot range measurement and returns the reading in
    millimeters. Based on VL53L0X_PerformSingleRangingMeasurement().
    
    

  • vl53l0x_get_vcsel_pulse_period(byte in type) return byte

    Get the VCSEL pulse period in PCLKs for the given period type. Based on 
    VL53L0X_get_vcsel_pulse_period().
    
    

  • vl53l0x_set_signal_rate_limit(word in rate_limit) return bit

     
    Set the return signal rate limit check value in units of MCPS (million counts
    per second). "This represents the amplitude of the signal reflected from the
    target and detected by the device"; setting this limit presumably determines
    the minimum measurement necessary for the sensor to report a valid reading.
    Setting a lower limit increases the potential range of the sensor but also
    seems to increase the likelihood of getting an inaccurate reading because of
    unwanted reflections from objects other than the intended target.
    The rate limit is given in 100 * MCPS and must be < 51_200. Reason for
    using 100 * MCPS is that we do not need to use float but instead use word.
    Defaults to 25 (= 0.25 MCPS) as initialized by the ST API and this library.
    Returns TRUE when succesful.
     
    

  • vl53l0x_read_range_continuous_mil() return word

    Returns a range reading in mil when continuous mode is active. Calls
    vl53l0x_read_range_continuous_millimeters() and converts it to mils.
    
    

Private

Related samples

Here are the list of samples which use this library:

16f1311516f13115_vl53l0x_continuous.jal
16f182516f1825_vl53l0x_single.jal
16f182516f1825_vl53l0x_continuous.jal