VL53L0X API Specification: VL53L0X Measurement Functions

VL53L0X API

VL53L0X Measurement Functions

Functions used for the measurements. More...

Functions

VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleMeasurement (VL53L0X_DEV Dev)
 Single shot measurement. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_PerformRefCalibration (VL53L0X_DEV Dev, uint8_t *pVhvSettings, uint8_t *pPhaseCal)
 Perform Reference Calibration. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_PerformXTalkMeasurement (VL53L0X_DEV Dev, uint32_t TimeoutMs, FixPoint1616_t *pXtalkPerSpad, uint8_t *pAmbientTooHigh)
 Perform XTalk Measurement. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_PerformXTalkCalibration (VL53L0X_DEV Dev, FixPoint1616_t XTalkCalDistance, FixPoint1616_t *pXTalkCompensationRateMegaCps)
 Perform XTalk Calibration. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_PerformOffsetCalibration (VL53L0X_DEV Dev, FixPoint1616_t CalDistanceMilliMeter, int32_t *pOffsetMicroMeter)
 Perform Offset Calibration. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_StartMeasurement (VL53L0X_DEV Dev)
 Start device measurement. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_StopMeasurement (VL53L0X_DEV Dev)
 Stop device measurement. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_GetMeasurementDataReady (VL53L0X_DEV Dev, uint8_t *pMeasurementDataReady)
 Return Measurement Data Ready. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_WaitDeviceReadyForNewMeasurement (VL53L0X_DEV Dev, uint32_t MaxLoop)
 Wait for device ready for a new measurement command. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_GetMeasurementRefSignal (VL53L0X_DEV Dev, FixPoint1616_t *pMeasurementRefSignal)
 Retrieve the Reference Signal after a measurements. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_GetRangingMeasurementData (VL53L0X_DEV Dev, VL53L0X_RangingMeasurementData_t *pRangingMeasurementData)
 Retrieve the measurements from device for a given setup. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_GetHistogramMeasurementData (VL53L0X_DEV Dev, VL53L0X_HistogramMeasurementData_t *pHistogramMeasurementData)
 Retrieve the measurements from device for a given setup. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleRangingMeasurement (VL53L0X_DEV Dev, VL53L0X_RangingMeasurementData_t *pRangingMeasurementData)
 Performs a single ranging measurement and retrieve the ranging measurement data. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleHistogramMeasurement (VL53L0X_DEV Dev, VL53L0X_HistogramMeasurementData_t *pHistogramMeasurementData)
 Performs a single histogram measurement and retrieve the histogram measurement data Is equivalent to VL53L0X_PerformSingleMeasurement + VL53L0X_GetHistogramMeasurementData. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_SetNumberOfROIZones (VL53L0X_DEV Dev, uint8_t NumberOfROIZones)
 Set the number of ROI Zones to be used for a specific Device. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_GetNumberOfROIZones (VL53L0X_DEV Dev, uint8_t *pNumberOfROIZones)
 Get the number of ROI Zones managed by the Device. More...
 
VL53L0X_API VL53L0X_Error VL53L0X_GetMaxNumberOfROIZones (VL53L0X_DEV Dev, uint8_t *pMaxNumberOfROIZones)
 Get the Maximum number of ROI Zones managed by the Device. More...
 

Detailed Description

Functions used for the measurements.

Function Documentation

VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleMeasurement ( VL53L0X_DEV  Dev)

Single shot measurement.

Function Description
Perform simple measurement sequence (Start measure, Wait measure to end, and returns when measurement is done). Once function returns, user can get valid data by calling VL53L0X_GetRangingMeasurement or VL53L0X_GetHistogramMeasurement depending on defined measurement mode User should Clear the interrupt in case this are enabled by using the function VL53L0X_ClearInterruptMask().
Warning
This function is a blocking function
Note
This function Access to the device
Parameters
DevDevice Handle
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_PerformRefCalibration ( VL53L0X_DEV  Dev,
uint8_t pVhvSettings,
uint8_t pPhaseCal 
)

Perform Reference Calibration.

Perform a reference calibration of the Device. This function should be run from time to time before doing a ranging measurement. This function will launch a special ranging measurement, so if interrupt are enable an interrupt will be done. This function will clear the interrupt generated automatically.

Warning
This function is a blocking function
Note
This function Access to the device
Parameters
DevDevice Handle
pVhvSettingsPointer to vhv settings parameter.
pPhaseCalPointer to PhaseCal parameter.
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_PerformXTalkMeasurement ( VL53L0X_DEV  Dev,
uint32_t  TimeoutMs,
FixPoint1616_t pXtalkPerSpad,
uint8_t pAmbientTooHigh 
)

Perform XTalk Measurement.

Measures the current cross talk from glass in front of the sensor. This functions performs a histogram measurement and uses the results to measure the crosstalk. For the function to be successful, there must be no target in front of the sensor.

Warning
This function is a blocking function
This function is not supported when the final range vcsel clock period is set below 10 PCLKS.
Note
This function Access to the device
Parameters
DevDevice Handle
TimeoutMsHistogram measurement duration.
pXtalkPerSpadOutput parameter containing the crosstalk measurement result, in MCPS/Spad. Format fixpoint 16:16.
pAmbientTooHighOutput parameter which indicate that pXtalkPerSpad is not good if the Ambient is too high.
Returns
VL53L0X_ERROR_NONE Success
VL53L0X_ERROR_INVALID_PARAMS vcsel clock period not supported for this operation. Must not be less than 10PCLKS.
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_PerformXTalkCalibration ( VL53L0X_DEV  Dev,
FixPoint1616_t  XTalkCalDistance,
FixPoint1616_t pXTalkCompensationRateMegaCps 
)

Perform XTalk Calibration.

Perform a XTalk calibration of the Device. This function will launch a ranging measurement, if interrupts are enabled an interrupt will be done. This function will clear the interrupt generated automatically. This function will program a new value for the XTalk compensation and it will enable the cross talk before exit. This function will disable the VL53L0X_CHECKENABLE_RANGE_IGNORE_THRESHOLD.

Warning
This function is a blocking function
Note
This function Access to the device
This function change the device mode to VL53L0X_DEVICEMODE_SINGLE_RANGING
Parameters
DevDevice Handle
XTalkCalDistanceXTalkCalDistance value used for the XTalk computation.
pXTalkCompensationRateMegaCpsPointer to new XTalkCompensation value.
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_PerformOffsetCalibration ( VL53L0X_DEV  Dev,
FixPoint1616_t  CalDistanceMilliMeter,
int32_t pOffsetMicroMeter 
)

Perform Offset Calibration.

Perform a Offset calibration of the Device. This function will launch a ranging measurement, if interrupts are enabled an interrupt will be done. This function will clear the interrupt generated automatically. This function will program a new value for the Offset calibration value This function will disable the VL53L0X_CHECKENABLE_RANGE_IGNORE_THRESHOLD.

Warning
This function is a blocking function
Note
This function Access to the device
This function does not change the device mode.
Parameters
DevDevice Handle
CalDistanceMilliMeterCalibration distance value used for the offset compensation.
pOffsetMicroMeterPointer to new Offset value computed by the function.
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_StartMeasurement ( VL53L0X_DEV  Dev)

Start device measurement.

Started measurement will depend on device parameters set through VL53L0X_SetParameters() This is a non-blocking function. This function will change the VL53L0X_State from VL53L0X_STATE_IDLE to VL53L0X_STATE_RUNNING.

Note
This function Access to the device
Parameters
DevDevice Handle
Returns
VL53L0X_ERROR_NONE Success
VL53L0X_ERROR_MODE_NOT_SUPPORTED This error occurs when DeviceMode programmed with VL53L0X_SetDeviceMode is not in the supported list: Supported mode are: VL53L0X_DEVICEMODE_SINGLE_RANGING, VL53L0X_DEVICEMODE_CONTINUOUS_RANGING, VL53L0X_DEVICEMODE_CONTINUOUS_TIMED_RANGING
VL53L0X_ERROR_TIME_OUT Time out on start measurement
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_StopMeasurement ( VL53L0X_DEV  Dev)

Stop device measurement.

Will set the device in standby mode at end of current measurement
Not necessary in single mode as device shall return automatically in standby mode at end of measurement. This function will change the VL53L0X_State from VL53L0X_STATE_RUNNING to VL53L0X_STATE_IDLE.

Note
This function Access to the device
Parameters
DevDevice Handle
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_GetMeasurementDataReady ( VL53L0X_DEV  Dev,
uint8_t pMeasurementDataReady 
)

Return Measurement Data Ready.

Function Description
This function indicate that a measurement data is ready. This function check if interrupt mode is used then check is done accordingly. If perform function clear the interrupt, this function will not work, like in case of VL53L0X_PerformSingleRangingMeasurement(). The previous function is blocking function, VL53L0X_GetMeasurementDataReady is used for non-blocking capture.
Note
This function Access to the device
Parameters
DevDevice Handle
pMeasurementDataReadyPointer to Measurement Data Ready. 0=data not ready, 1 = data ready
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_WaitDeviceReadyForNewMeasurement ( VL53L0X_DEV  Dev,
uint32_t  MaxLoop 
)

Wait for device ready for a new measurement command.

Blocking function.

Note
This function is not Implemented
Parameters
DevDevice Handle
MaxLoopMax Number of polling loop (timeout).
Returns
VL53L0X_ERROR_NOT_IMPLEMENTED Not implemented
VL53L0X_API VL53L0X_Error VL53L0X_GetMeasurementRefSignal ( VL53L0X_DEV  Dev,
FixPoint1616_t pMeasurementRefSignal 
)

Retrieve the Reference Signal after a measurements.

Function Description
Get Reference Signal from last successful Ranging measurement This function return a valid value after that you call the VL53L0X_GetRangingMeasurementData().
Note
This function Access to the device
Parameters
DevDevice Handle
pMeasurementRefSignalPointer to the Ref Signal to fill up.
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_GetRangingMeasurementData ( VL53L0X_DEV  Dev,
VL53L0X_RangingMeasurementData_t pRangingMeasurementData 
)

Retrieve the measurements from device for a given setup.

Function Description
Get data from last successful Ranging measurement
Warning
USER should take care about VL53L0X_GetNumberOfROIZones() before get data. PAL will fill a NumberOfROIZones times the corresponding data structure used in the measurement function.
Note
This function Access to the device
Parameters
DevDevice Handle
pRangingMeasurementDataPointer to the data structure to fill up.
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_GetHistogramMeasurementData ( VL53L0X_DEV  Dev,
VL53L0X_HistogramMeasurementData_t pHistogramMeasurementData 
)

Retrieve the measurements from device for a given setup.

Function Description
Get data from last successful Histogram measurement
Warning
USER should take care about VL53L0X_GetNumberOfROIZones() before get data. PAL will fill a NumberOfROIZones times the corresponding data structure used in the measurement function.
Note
This function is not Implemented
Parameters
DevDevice Handle
pHistogramMeasurementDataPointer to the histogram data structure.
Returns
VL53L0X_ERROR_NOT_IMPLEMENTED Not implemented
VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleRangingMeasurement ( VL53L0X_DEV  Dev,
VL53L0X_RangingMeasurementData_t pRangingMeasurementData 
)

Performs a single ranging measurement and retrieve the ranging measurement data.

Function Description
This function will change the device mode to VL53L0X_DEVICEMODE_SINGLE_RANGING with VL53L0X_SetDeviceMode(), It performs measurement with VL53L0X_PerformSingleMeasurement() It get data from last successful Ranging measurement with VL53L0X_GetRangingMeasurementData. Finally it clear the interrupt with VL53L0X_ClearInterruptMask().
Note
This function Access to the device
This function change the device mode to VL53L0X_DEVICEMODE_SINGLE_RANGING
Parameters
DevDevice Handle
pRangingMeasurementDataPointer to the data structure to fill up.
Returns
VL53L0X_ERROR_NONE Success
"Other error code" See VL53L0X_Error
VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleHistogramMeasurement ( VL53L0X_DEV  Dev,
VL53L0X_HistogramMeasurementData_t pHistogramMeasurementData 
)

Performs a single histogram measurement and retrieve the histogram measurement data Is equivalent to VL53L0X_PerformSingleMeasurement + VL53L0X_GetHistogramMeasurementData.

Function Description
Get data from last successful Ranging measurement. This function will clear the interrupt in case of these are enabled.
Note
This function is not Implemented
Parameters
DevDevice Handle
pHistogramMeasurementDataPointer to the data structure to fill up.
Returns
VL53L0X_ERROR_NOT_IMPLEMENTED Not implemented
VL53L0X_API VL53L0X_Error VL53L0X_SetNumberOfROIZones ( VL53L0X_DEV  Dev,
uint8_t  NumberOfROIZones 
)

Set the number of ROI Zones to be used for a specific Device.

Function Description
Set the number of ROI Zones to be used for a specific Device. The programmed value should be less than the max number of ROI Zones given with VL53L0X_GetMaxNumberOfROIZones(). This version of API manage only one zone.
Parameters
DevDevice Handle
NumberOfROIZonesNumber of ROI Zones to be used for a specific Device.
Returns
VL53L0X_ERROR_NONE Success
VL53L0X_ERROR_INVALID_PARAMS This error is returned if NumberOfROIZones != 1
VL53L0X_API VL53L0X_Error VL53L0X_GetNumberOfROIZones ( VL53L0X_DEV  Dev,
uint8_t pNumberOfROIZones 
)

Get the number of ROI Zones managed by the Device.

Function Description
Get number of ROI Zones managed by the Device USER should take care about VL53L0X_GetNumberOfROIZones() before get data after a perform measurement. PAL will fill a NumberOfROIZones times the corresponding data structure used in the measurement function.
Note
This function doesn't Access to the device
Parameters
DevDevice Handle
pNumberOfROIZonesPointer to the Number of ROI Zones value.
Returns
VL53L0X_ERROR_NONE Success
VL53L0X_API VL53L0X_Error VL53L0X_GetMaxNumberOfROIZones ( VL53L0X_DEV  Dev,
uint8_t pMaxNumberOfROIZones 
)

Get the Maximum number of ROI Zones managed by the Device.

Function Description
Get Maximum number of ROI Zones managed by the Device.
Note
This function doesn't Access to the device
Parameters
DevDevice Handle
pMaxNumberOfROIZonesPointer to the Maximum Number of ROI Zones value.
Returns
VL53L0X_ERROR_NONE Success