ST Expansion SW Team / Vl6180

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:   VL6180_Board

Dependents:   X_NUCLEO_6180

Embed: (wiki syntax)

« Back to documentation index

VL6180 Class Reference
Public Member Functions | Protected Attributes

VL6180 Class Reference

Class representing a VL6180 sensor component. More...

#include <vl6180_class.h>

Inherits RangeSensor.

Public Member Functions

 VL6180 (vl6180_DevI2C *i2c, DigitalOut *pin, PinName pin_gpio1, uint8_t dev_addr=VL53L1X_DEFAULT_DEVICE_ADDRESS)
 Constructor.
 VL6180 (vl6180_DevI2C *i2c, Stmpe1600DigiOut *pin, PinName pin_gpio1, uint8_t dev_addr=VL53L1X_DEFAULT_DEVICE_ADDRESS)
 Constructor 2 (STMPE1600DigiOut)
virtual ~VL6180 ()
 Destructor.
virtual void VL53L1_On (void)
 PowerOn the sensor.
virtual void VL53L1_Off (void)
 PowerOff the sensor.
VL6180_ERROR InitSensor (uint8_t address)
 Initialize the sensor with default values.
virtual int init (void *init)
 One time device initialization.
int init_sensor (uint8_t new_addr)
 Initialize the sensor with default values.
virtual int read_id (uint8_t *id)
 Getting the ID of the component.
virtual int get_distance (uint32_t *piData)
 Get ranging result and only that.
VL6180_ERROR vl6180_GetSWVersion (VL6180_Version_t *pVersion)
 Run a single ALS measurement in single shot polling mode.
VL6180_ERROR vl6180_SetI2CAddress (uint8_t new_address)
 This function sets the sensor I2C address used in case multiple devices application, default address 0x52.
VL6180_ERROR vl6180_SensorInit ()
 This function loads the 135 bytes default values to initialize the sensor.
VL6180_ERROR vl6180_ClearInterrupt ()
 This function clears the interrupt, to be called after a ranging data reading to arm the interrupt for the next data ready event.
VL6180_ERROR vl6180_SetInterruptPolarity (uint8_t IntPol)
 This function programs the interrupt polarity
1=active high (default), 0=active low.
VL6180_ERROR vl6180_GetInterruptPolarity (uint8_t *pIntPol)
 This function returns the current interrupt polarity
1=active high (default), 0=active low.
VL6180_ERROR vl6180_StartRanging ()
 This function starts the ranging distance operation
The ranging operation is continuous.
VL6180_ERROR vl6180_StopRanging ()
 This function stops the ranging.
VL6180_ERROR vl6180_SetTimingBudgetInMs (uint16_t TimingBudgetInMs)
 This function programs the timing budget in ms.
VL6180_ERROR vl6180_GetTimingBudgetInMs (uint16_t *pTimingBudgetInMs)
 This function returns the current timing budget in ms.
VL6180_ERROR vl6180_SetDistanceMode (uint16_t DistanceMode)
 This function programs the distance mode (1=short, 2=long(default)).
VL6180_ERROR vl6180_GetDistanceMode (uint16_t *pDistanceMode)
 This function returns the current distance mode (1=short, 2=long).
VL6180_ERROR vl6180_SetInterMeasurementInMs (uint16_t InterMeasurementInMs)
 This function programs the Intermeasurement period in ms
Intermeasurement period must be >/= timing budget.
VL6180_ERROR vl6180_GetInterMeasurementInMs (uint16_t *pIM)
 This function returns the Intermeasurement period in ms.
VL6180_ERROR vl6180_BootState (uint8_t *state)
 This function returns the boot state of the device (1:booted, 0:not booted)
VL6180_ERROR vl6180_GetSensorId (uint16_t *id)
 This function returns the sensor id, sensor Id must be 0xEEAC.
VL6180_ERROR vl6180_GetDistance (uint16_t *distance)
 This function returns the distance measured by the sensor in mm.
VL6180_ERROR VL53L1X_GetSignalPerSpad (uint16_t *signalPerSp)
 This function returns the returned signal per SPAD in kcps/SPAD.
VL6180_ERROR VL53L1X_GetAmbientPerSpad (uint16_t *amb)
 This function returns the ambient per SPAD in kcps/SPAD.
VL6180_ERROR VL53L1X_GetSignalRate (uint16_t *signalRate)
 This function returns the returned signal in kcps.
VL6180_ERROR VL53L1X_GetSpadNb (uint16_t *spNb)
 This function returns the current number of enabled SPADs.
VL6180_ERROR VL53L1X_GetAmbientRate (uint16_t *ambRate)
 This function returns the ambient rate in kcps.
VL6180_ERROR VL53L1X_GetRangeStatus (uint8_t *rangeStatus)
 This function returns the ranging status error
(0:no error, 1:sigma failed, 2:signal failed, ..., 7:wrap-around)
VL6180_ERROR VL53L1X_SetOffset (int16_t OffsetValue)
 This function programs the offset correction in mm.
VL6180_ERROR VL53L1X_GetOffset (int16_t *Offset)
 This function returns the programmed offset correction value in mm.
VL6180_ERROR VL53L1X_SetXtalk (uint16_t XtalkValue)
 This function programs the xtalk correction value in cps (Count Per Second).
VL6180_ERROR VL53L1X_GetXtalk (uint16_t *Xtalk)
 This function returns the current programmed xtalk correction value in cps.
VL6180_ERROR vl6180_SetDistanceThreshold (uint16_t ThreshLow, uint16_t ThreshHigh, uint8_t Window, uint8_t IntOnNoTarget)
 This function programs the threshold detection mode
Example:
VL53L1X_SetDistanceThreshold(dev,100,300,0,1): Below 100
VL53L1X_SetDistanceThreshold(dev,100,300,1,1): Above 300
VL53L1X_SetDistanceThreshold(dev,100,300,2,1): Out of window
VL53L1X_SetDistanceThreshold(dev,100,300,3,1): In window
.
VL6180_ERROR vl6180_GetDistanceThresholdWindow (uint16_t *window)
 This function returns the window detection mode (0=below; 1=above; 2=out; 3=in)
VL6180_ERROR vl6180_GetDistanceThresholdLow (uint16_t *low)
 This function returns the low threshold in mm.
VL6180_ERROR vl6180_GetDistanceThresholdHigh (uint16_t *high)
 This function returns the high threshold in mm.
VL6180_ERROR VL53L1X_SetROI (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.
VL6180_ERROR VL53L1X_GetROI_XY (uint16_t *ROI_X, uint16_t *ROI_Y)
 This function returns width X and height Y.
VL6180_ERROR VL53L1X_SetSignalThreshold (uint16_t signal)
 This function programs a new signal threshold in kcps (default=1024 kcps
.
VL6180_ERROR VL53L1X_GetSignalThreshold (uint16_t *signal)
 This function returns the current signal threshold in kcps.
VL6180_ERROR VL53L1X_SetSigmaThreshold (uint16_t sigma)
 This function programs a new sigma threshold in mm (default=15 mm)
VL6180_ERROR VL53L1X_GetSigmaThreshold (uint16_t *signal)
 This function returns the current sigma threshold in mm.
VL6180_ERROR VL53L1X_StartTemperatureUpdate ()
 This function performs the temperature calibration.
VL6180_ERROR vl6180_WaitDeviceBooted (VL6180Dev_t dev)
 Wait for device booted after chip enable (hardware standby)
VL6180_ERROR vl6180_Prepare (VL6180Dev_t dev)
 Prepare device for operation.
VL6180_ERROR vl6180_RangePollMeasurement (VL6180Dev_t dev, VL6180_RangeData_t *pRangeData)
 Single shot Range measurement in polling mode.

Protected Attributes

VL6180Dev_t MyDevice
 * Digital out pin */

Detailed Description

Class representing a VL6180 sensor component.

Definition at line 148 of file vl6180_class.h.

Constructor & Destructor Documentation

VL6180 ( vl6180_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 162 of file vl6180_class.h.

VL6180 ( vl6180_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 182 of file vl6180_class.h.

virtual ~VL6180 (  ) [virtual]

Destructor.

Definition at line 199 of file vl6180_class.h.

Member Function Documentation

virtual int get_distance ( uint32_t *  piData ) [virtual]

Get ranging result and only that.

Parameters:
pRange_mmPointer to range distance
Returns:
0 on success

Implements RangeSensor.

Definition at line 353 of file vl6180_class.h.

virtual int init ( void *  init ) [virtual]

One time device initialization.

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

Implements Component.

Definition at line 303 of file vl6180_class.h.

int init_sensor ( uint8_t  new_addr )

Initialize the sensor with default values.

Returns:
"0" on success

Definition at line 100 of file vl6180_class.cpp.

VL6180_ERROR InitSensor ( uint8_t  address )

Initialize the sensor with default values.

Returns:
0 on Success

Definition at line 279 of file vl6180_class.h.

virtual int read_id ( uint8_t *  id ) [virtual]

Getting the ID of the component.

Parameters:
[out]idpointer to an allocated variable to store the ID into.
Return values:
0in case of success, an error code otherwise.

Implements Component.

Definition at line 318 of file vl6180_class.h.

virtual void VL53L1_Off ( void   ) [virtual]

PowerOff the sensor.

Returns:
void

Definition at line 244 of file vl6180_class.h.

virtual void VL53L1_On ( void   ) [virtual]

PowerOn the sensor.

Returns:
void

Definition at line 221 of file vl6180_class.h.

VL6180_ERROR VL53L1X_GetAmbientPerSpad ( uint16_t *  amb )

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

VL6180_ERROR VL53L1X_GetAmbientRate ( uint16_t *  ambRate )

This function returns the ambient rate in kcps.

VL6180_ERROR VL53L1X_GetOffset ( int16_t *  Offset )

This function returns the programmed offset correction value in mm.

VL6180_ERROR VL53L1X_GetRangeStatus ( uint8_t *  rangeStatus )

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

VL6180_ERROR VL53L1X_GetROI_XY ( uint16_t *  ROI_X,
uint16_t *  ROI_Y 
)

This function returns width X and height Y.

VL6180_ERROR VL53L1X_GetSigmaThreshold ( uint16_t *  signal )

This function returns the current sigma threshold in mm.

VL6180_ERROR VL53L1X_GetSignalPerSpad ( uint16_t *  signalPerSp )

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

With kcps stands for Kilo Count Per Second

VL6180_ERROR VL53L1X_GetSignalRate ( uint16_t *  signalRate )

This function returns the returned signal in kcps.

VL6180_ERROR VL53L1X_GetSignalThreshold ( uint16_t *  signal )

This function returns the current signal threshold in kcps.

VL6180_ERROR VL53L1X_GetSpadNb ( uint16_t *  spNb )

This function returns the current number of enabled SPADs.

VL6180_ERROR VL53L1X_GetXtalk ( uint16_t *  Xtalk )

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

VL6180_ERROR VL53L1X_SetOffset ( int16_t  OffsetValue )

This function programs the offset correction in mm.

Parameters:
OffsetValue:theoffset correction value to program in mm
VL6180_ERROR VL53L1X_SetROI ( 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
VL6180_ERROR VL53L1X_SetSigmaThreshold ( uint16_t  sigma )

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

VL6180_ERROR VL53L1X_SetSignalThreshold ( uint16_t  signal )

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

VL6180_ERROR VL53L1X_SetXtalk ( 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.

VL6180_ERROR VL53L1X_StartTemperatureUpdate (  )

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.

VL6180_ERROR vl6180_BootState ( uint8_t *  state )

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

VL6180_ERROR vl6180_ClearInterrupt (  )

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 117 of file vl6180_class.cpp.

VL6180_ERROR vl6180_GetDistance ( uint16_t *  distance )

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

VL6180_ERROR vl6180_GetDistanceMode ( uint16_t *  pDistanceMode )

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

VL6180_ERROR vl6180_GetDistanceThresholdHigh ( uint16_t *  high )

This function returns the high threshold in mm.

VL6180_ERROR vl6180_GetDistanceThresholdLow ( uint16_t *  low )

This function returns the low threshold in mm.

VL6180_ERROR vl6180_GetDistanceThresholdWindow ( uint16_t *  window )

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

VL6180_ERROR vl6180_GetInterMeasurementInMs ( uint16_t *  pIM )

This function returns the Intermeasurement period in ms.

VL6180_ERROR vl6180_GetInterruptPolarity ( uint8_t *  pIntPol )

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

Definition at line 211 of file vl6180_class.cpp.

VL6180_ERROR vl6180_GetSensorId ( uint16_t *  id )

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

VL6180_ERROR vl6180_GetSWVersion ( VL6180_Version_t *  pVersion )

Run a single ALS measurement in single shot polling mode.

Function Description
Kick off a new single shot ALS then wait new measurement ready to retrieve it ( polling system interrupt status register for als)
ALS must be prepared by a first call to VL6180x_Prepare()

Should not be used in continuous or interrupt mode it will break it and create hazard in start/stop
Parameters:
devThe device
pAlsDataAls data structure to fill up VL6180x_AlsData_t
Returns:
0 on success This function returns the SW driver version

Definition at line 71 of file vl6180_class.cpp.

VL6180_ERROR vl6180_GetTimingBudgetInMs ( uint16_t *  pTimingBudgetInMs )

This function returns the current timing budget in ms.

VL6180_ERROR vl6180_Prepare ( VL6180Dev_t  dev )

Prepare device for operation.

Function Description
Does static initialization and reprogram common default settings
Device is prepared for new measure, ready single shot ranging typical polling operation
After prepare user can :
  • Call other API function to set other settings
  • Configure the interrupt pins, etc...
  • Then start ranging operations in single shot or continuous mode
Parameters:
devThe device
Returns:
0 on success

Definition at line 184 of file vl6180_class.cpp.

VL6180_ERROR vl6180_RangePollMeasurement ( VL6180Dev_t  dev,
VL6180_RangeData_t *  pRangeData 
)

Single shot Range measurement in polling mode.

Function Description
Kick off a new single shot range then wait for ready to retrieve it by polling interrupt status
Ranging must be prepared by a first call to VL6180_Prepare() and it is safer to clear very first poll call
This function reference VL6180_PollDelay(dev) porting macro/call on each polling loop, but PollDelay(dev) may never be called if measure in ready on first poll loop
Should not be use in continuous mode operation as it will stop it and cause stop/start misbehaviour

This function clears Range Interrupt status , but not error one. For that uses VL6180_ClearErrorInterrupt()
This range error is not related VL6180_RangeData_t::errorStatus that refer measure status
Parameters:
devThe device
pRangeDataWill be populated with the result ranging data VL6180_RangeData_t
Returns:
0 on success , RANGE_ERROR if device reports an error case in it status (not cleared) use
See also:
VL6180_RangeData_t

Definition at line 192 of file vl6180_class.cpp.

VL6180_ERROR vl6180_SensorInit (  )

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

Parameters:
devDevice address
Returns:
0:success, != 0:failed
VL6180_ERROR vl6180_SetDistanceMode ( 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.

VL6180_ERROR vl6180_SetDistanceThreshold ( uint16_t  ThreshLow,
uint16_t  ThreshHigh,
uint8_t  Window,
uint8_t  IntOnNoTarget 
)

This function programs the threshold detection mode
Example:
VL53L1X_SetDistanceThreshold(dev,100,300,0,1): Below 100
VL53L1X_SetDistanceThreshold(dev,100,300,1,1): Above 300
VL53L1X_SetDistanceThreshold(dev,100,300,2,1): Out of window
VL53L1X_SetDistanceThreshold(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)
VL6180_ERROR vl6180_SetI2CAddress ( uint8_t  new_address )

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

Definition at line 82 of file vl6180_class.cpp.

VL6180_ERROR vl6180_SetInterMeasurementInMs ( 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

VL6180_ERROR vl6180_SetInterruptPolarity ( uint8_t  IntPol )

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

Definition at line 172 of file vl6180_class.cpp.

VL6180_ERROR vl6180_SetTimingBudgetInMs ( uint16_t  TimingBudgetInMs )

This function programs the timing budget in ms.

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

VL6180_ERROR vl6180_StartRanging (  )

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.

VL6180_ERROR vl6180_StopRanging (  )

This function stops the ranging.

VL6180_ERROR vl6180_WaitDeviceBooted ( VL6180Dev_t  dev )

Wait for device booted after chip enable (hardware standby)

Function Description
After Chip enable Application you can also simply wait at least 1ms to ensure device is ready
Warning:
After device chip enable (gpio0) de-asserted user must wait gpio1 to get asserted (hardware standby). or wait at least 400usec prior to do any low level access or api call .

This function implements polling for standby but you must ensure 400usec from chip enable passed

Warning:
Calling this function if device is not fresh out of reset will result in an indefinite loop
Parameters:
devThe device
Returns:
0 on success

Definition at line 128 of file vl6180_class.cpp.

Field Documentation

VL6180Dev_t MyDevice [protected]

* Digital out pin */

Definition at line 711 of file vl6180_class.h.

Generated on Tue Nov 29 2022 20:47:36 by  doxygen 1.7.2