Updates to follow mbed SDK coding style guidelines.

Dependencies:   ST_INTERFACES X_NUCLEO_COMMON

Dependents:   53L0A1_Satellites_with_Interrupts_OS5 Display_53L0A1_OS5

Fork of X_NUCLEO_53L0A1 by ST

Embed: (wiki syntax)

« Back to documentation index

Init functions

Init functions

Wrapper functions. More...

Functions

int wait_device_booted ()
 Wait for device booted after chip enable (hardware standby)
virtual int init (void *init)
 One time device initialization.
int setup_gpio1 (uint8_t InitFunction, int ActiveHigh)
 Configure GPIO1 function and set polarity.
int prepare ()
 Prepare device for operation.
int range_start_continuous_mode ()
 Start continuous ranging mode.
int range_start_single_shot ()
 Start single shot ranging measure.
int range_set_max_convergence_time (uint8_t max_con_time_msec)
 Set maximum convergence time.
int range_poll_measurement (VL53L0X_RangingMeasurementData_t *p_range_data)
 Single shot Range measurement in polling mode.
int range_get_measurement_if_ready (VL53L0X_RangingMeasurementData_t *p_range_data)
 Check for measure readiness and get it if ready.
int range_get_measurement (VL53L0X_RangingMeasurementData_t *p_range_data)
 Retrieve range measurements set from device.
virtual int get_distance (uint32_t *p_data)
 Get ranging result and only that.
int range_config_interrupt (uint8_t config_gpio_int)
 Configure ranging interrupt reported to application.
int range_get_interrupt_status (uint8_t *p_status)
 Return ranging error interrupt status.
int static_init ()
 Low level ranging and ALS register static settings (you should call VL6180x_Prepare() function instead)
int range_wait_device_deady (int max_loop)
 Wait for device to be ready (before a new ranging command can be issued by application)
int range_set_inter_meas_period (uint32_t inter_meas_time_msec)
 Program Inter measurement period (used only in continuous mode)
int upscale_set_scaling (uint8_t scaling)
 Set device ranging scaling factor.
int upscale_get_scaling ()
 Get current ranging scaling factor.
uint16_t get_upper_limit ()
 Get the maximal distance for actual scaling.
int range_set_thresholds (uint16_t low, uint16_t high, int safe_hold)
 Apply low and high ranging thresholds that are considered only in continuous mode.
int range_get_thresholds (uint16_t *low, uint16_t *high)
 Get scaled high and low threshold from device.
int range_set_raw_thresholds (uint8_t low, uint8_t high)
 Set ranging raw thresholds (scaling not considered so not recommended to use it)
int range_set_ece_factor (uint16_t factor_m, uint16_t factor_d)
 Set Early Convergence Estimate ratio.
int range_set_ece_state (int enable)
 Set Early Convergence Estimate state (See SYSRANGE_RANGE_CHECK_ENABLES register)
int filter_set_state (int state)
 Set activation state of the wrap around filter.
int filter_get_state ()
 Get activation state of the wrap around filter.
int dmax_set_state (int state)
 Set activation state of DMax computation.
int dmax_get_state ()
 Get activation state of DMax computation.
int range_set_system_mode (uint8_t mode)
 Set ranging mode and start/stop measure (use high level functions instead : VL6180x_RangeStartSingleShot() or VL6180x_RangeStartContinuousMode())

Detailed Description

Wrapper functions.

API init functions


Function Documentation

int dmax_get_state (  ) [inherited]

Get activation state of DMax computation.

Returns:
Filter enabled or not, when filter is not supported it always returns 0S

Definition at line 950 of file vl53l0x_class.h.

int dmax_set_state ( int  state ) [inherited]

Set activation state of DMax computation.

Parameters:
stateNew activation state (0=off, otherwise on)
Returns:
0 on success

Definition at line 941 of file vl53l0x_class.h.

int filter_get_state (  ) [inherited]

Get activation state of the wrap around filter.

Returns:
Filter enabled or not, when filter is not supported it always returns 0S

Definition at line 931 of file vl53l0x_class.h.

int filter_set_state ( int  state ) [inherited]

Set activation state of the wrap around filter.

Parameters:
stateNew activation state (0=off, otherwise on)
Returns:
0 on success

Definition at line 922 of file vl53l0x_class.h.

virtual int get_distance ( uint32_t *  p_data ) [virtual, inherited]

Get ranging result and only that.

Function Description
Unlike VL6180x_RangeGetMeasurement() this function only retrieves the range in millimeter
It does any required up-scale translation
It can be called after success status polling or in interrupt mode
Warning:
these function is not doing wrap around filtering
This function doesn't perform any data ready check!
Parameters:
p_dataPointer to range distance
Returns:
0 on success

Definition at line 687 of file vl53l0x_class.h.

uint16_t get_upper_limit (  ) [inherited]

Get the maximal distance for actual scaling.

Function Description
Do not use prior to VL6180x_Prepare() or at least VL6180x_InitData()

Any range value more than the value returned by this function is to be considered as "no target detected" or "no target in detectable range"

Warning:
The maximal distance depends on the scaling
Returns:
The maximal range limit for actual mode and scaling

Definition at line 836 of file vl53l0x_class.h.

virtual int init ( void *  init ) [virtual, inherited]

One time device initialization.

To be called once and only once after device is brought out of reset (Chip enable) and booted see VL6180x_WaitDeviceBooted()

Function Description
When not used after a fresh device "power up" or reset, it may return CALIBRATION_WARNING meaning wrong calibration data may have been fetched from device that can result in ranging offset error
If application cannot execute device reset or need to run VL6180x_InitData multiple time then it must ensure proper offset calibration saving and restore on its own by using VL6180x_GetOffsetCalibrationData() on first power up and then VL6180x_SetOffsetCalibrationData() all all subsequent init
Parameters:
void
Returns:
0 on success, CALIBRATION_WARNING if failed

Definition at line 497 of file vl53l0x_class.h.

int prepare (  ) [inherited]

Prepare device for operation.

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

Definition at line 537 of file vl53l0x_class.h.

int range_config_interrupt ( uint8_t  config_gpio_int ) [inherited]

Configure ranging interrupt reported to application.

Parameters:
config_gpio_intSelect ranging report
select one (and only one) of:
CONFIG_GPIO_INTERRUPT_DISABLED
CONFIG_GPIO_INTERRUPT_LEVEL_LOW
CONFIG_GPIO_INTERRUPT_LEVEL_HIGH
CONFIG_GPIO_INTERRUPT_OUT_OF_WINDOW
CONFIG_GPIO_INTERRUPT_NEW_SAMPLE_READY
Returns:
0 on success

Definition at line 718 of file vl53l0x_class.h.

int range_get_interrupt_status ( uint8_t *  p_status ) [inherited]

Return ranging error interrupt status.

Function Description
Appropriate Interrupt report must have been selected first by VL6180x_RangeConfigInterrupt() or VL6180x_Prepare()

Can be used in polling loop to wait for a given ranging event or in interrupt to read the trigger
Events triggers are :
RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD
RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD
RES_INT_STAT_GPIO_OUT_OF_WINDOW
(RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD|RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD) RES_INT_STAT_GPIO_NEW_SAMPLE_READY

See also:
IntrStatus_t
Parameters:
p_statusPointer to status variable to update
Returns:
0 on success

Definition at line 750 of file vl53l0x_class.h.

int range_get_measurement ( VL53L0X_RangingMeasurementData_t *  p_range_data ) [inherited]

Retrieve range measurements set from device.

Function Description
The measurement is made of range_mm status and error code VL6180x_RangeData_t
Based on configuration selected extra measures are included.
Warning:
should not be used in continuous if wrap around filter is active
Does not perform any wait nor check for result availability or validity.
See also:
VL6180x_RangeGetResult for "range only" measurement
Parameters:
p_range_dataPointer to the data structure to fill up
Returns:
0 on success

Definition at line 669 of file vl53l0x_class.h.

int range_get_measurement_if_ready ( VL53L0X_RangingMeasurementData_t *  p_range_data ) [inherited]

Check for measure readiness and get it if ready.

Function Description
Using this function is an alternative to VL6180x_RangePollMeasurement() to avoid polling operation. This is suitable for applications where host CPU is triggered on a interrupt (not from VL6180X) to perform ranging operation. In this scenario, we assume that the very first ranging operation is triggered by a call to VL6180x_RangeStartSingleShot(). Then, host CPU regularly calls VL6180x_RangeGetMeasurementIfReady() to get a distance measure if ready. In case the distance is not ready, host may get it at the next call.
Warning:
This function does not re-start a new measurement : this is up to the host CPU to do it.
This function clears Range Interrupt for measure ready , but not error interrupts. For that, uses VL6180x_ClearErrorInterrupt()
Parameters:
p_range_dataWill be populated with the result ranging data if available
Returns:
0 when measure is ready pRange data is updated (untouched when not ready), >0 for warning and NOT_READY if measurement not yet ready, <0 for error RANGE_ERROR if device report an error,

Definition at line 650 of file vl53l0x_class.h.

int range_get_thresholds ( uint16_t *  low,
uint16_t *  high 
) [inherited]

Get scaled high and low threshold from device.

Function Description
Due to scaling factor, the returned value may be different from what has been programmed first (precision lost). For instance VL6180x_RangeSetThresholds(dev,11,22) with scale 3 will read back 9 ((11/3)x3) and 21 ((22/3)x3).
Parameters:
lowscaled low Threshold ptr can be NULL if not needed
highscaled High Threshold ptr can be NULL if not needed
Returns:
0 on success, return value is undefined if both low and high are NULL
Warning:
return value is undefined if both low and high are NULL

Definition at line 875 of file vl53l0x_class.h.

int range_poll_measurement ( VL53L0X_RangingMeasurementData_t *  p_range_data ) [inherited]

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 VL6180x_Prepare() and it is safer to clear very first poll call
This function reference VL6180x_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 VL6180x_ClearErrorInterrupt()
This range error is not related VL6180x_RangeData_t::errorStatus that refer measure status
Parameters:
p_range_dataWill be populated with the result ranging data VL6180x_RangeData_t
Returns:
0 on success , RANGE_ERROR if device reports an error case in it status (not cleared) use
See also:
VL6180x_RangeData_t

Definition at line 629 of file vl53l0x_class.h.

int range_set_ece_factor ( uint16_t  factor_m,
uint16_t  factor_d 
) [inherited]

Set Early Convergence Estimate ratio.

Function Description
For more information on ECE check datasheet
Warning:
May return a calibration warning in some use cases
Parameters:
factor_mECE factor M in M/D
factor_dECE factor D in M/D
Returns:
0 on success. <0 on error. >0 on warning

Definition at line 902 of file vl53l0x_class.h.

int range_set_ece_state ( int  enable ) [inherited]

Set Early Convergence Estimate state (See SYSRANGE_RANGE_CHECK_ENABLES register)

Parameters:
enableState to be set 0=disabled, otherwise enabled
Returns:
0 on success

Definition at line 912 of file vl53l0x_class.h.

int range_set_inter_meas_period ( uint32_t  inter_meas_time_msec ) [inherited]

Program Inter measurement period (used only in continuous mode)

Function Description
When trying to set too long time, it returns INVALID_PARAMS
Parameters:
inter_meas_time_msecRequires inter-measurement time in msec
Returns:
0 on success

Definition at line 786 of file vl53l0x_class.h.

int range_set_max_convergence_time ( uint8_t  max_con_time_msec ) [inherited]

Set maximum convergence time.

Function Description
Setting a low convergence time can impact maximal detectable distance. Refer to VL6180x Datasheet Table 7 : Typical range convergence time. A typical value for up to x3 scaling is 50 ms
Parameters:
max_con_time_msec
Returns:
0 on success. <0 on error. >0 for calibration warning status

Definition at line 607 of file vl53l0x_class.h.

int range_set_raw_thresholds ( uint8_t  low,
uint8_t  high 
) [inherited]

Set ranging raw thresholds (scaling not considered so not recommended to use it)

Parameters:
lowraw low threshold set to raw register
highraw high threshold set to raw register
Returns:
0 on success

Definition at line 887 of file vl53l0x_class.h.

int range_set_system_mode ( uint8_t  mode ) [inherited]

Set ranging mode and start/stop measure (use high level functions instead : VL6180x_RangeStartSingleShot() or VL6180x_RangeStartContinuousMode())

Function Description
When used outside scope of known polling single shot stopped state,
user must ensure the device state is "idle" before to issue a new command.
Parameters:
modeA combination of working mode (MODE_SINGLESHOT or MODE_CONTINUOUS) and start/stop condition (MODE_START_STOP)
Returns:
0 on success

Definition at line 965 of file vl53l0x_class.h.

int range_set_thresholds ( uint16_t  low,
uint16_t  high,
int  safe_hold 
) [inherited]

Apply low and high ranging thresholds that are considered only in continuous mode.

Function Description
This function programs low and high ranging thresholds that are considered in continuous mode : interrupt will be raised only when an object is detected at a distance inside this [low:high] range. The function takes care of applying current scaling factor if any.
To be safe, in continuous operation, thresholds must be changed under "group parameter hold" cover. Group hold can be activated/deactivated directly in the function or externally (then set 0) using /a VL6180x_SetGroupParamHold() function.
Parameters:
lowLow threshold in mm
highHigh threshold in mm
safe_holdUse of group parameters hold to surround threshold programming.
Returns:
0 On success

Definition at line 857 of file vl53l0x_class.h.

int range_start_continuous_mode (  ) [inherited]

Start continuous ranging mode.

End user should ensure device is in idle state and not already running

Returns:
0 on success

Definition at line 572 of file vl53l0x_class.h.

int range_start_single_shot (  ) [inherited]

Start single shot ranging measure.

End user should ensure device is in idle state and not already running

Returns:
0 on success

Definition at line 591 of file vl53l0x_class.h.

int range_wait_device_deady ( int  max_loop ) [inherited]

Wait for device to be ready (before a new ranging command can be issued by application)

Parameters:
max_loopMax Number of i2c polling loop see msec_2_i2cloop
Returns:
0 on success. <0 when fail
VL6180x_ErrCode_t::TIME_OUT for time out
VL6180x_ErrCode_t::INVALID_PARAMS if MaxLop<1

Definition at line 772 of file vl53l0x_class.h.

int setup_gpio1 ( uint8_t  InitFunction,
int  ActiveHigh 
) [inherited]

Configure GPIO1 function and set polarity.

Function Description
To be used prior to arm single shot measure or start continuous mode.

The function uses VL6180x_SetupGPIOx() for setting gpio 1.

Warning:
changing polarity can generate a spurious interrupt on pins. It sets an interrupt flags condition that must be cleared to avoid polling hangs.
It is safe to run VL6180x_ClearAllInterrupt() just after.
Parameters:
IntFunctionThe interrupt functionality to use one of :
GPIOx_SELECT_OFF
GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT
ActiveHighThe interrupt line polarity see IntrPol_e use INTR_POL_LOW (falling edge) or INTR_POL_HIGH (rising edge)
Returns:
0 on success

Definition at line 519 of file vl53l0x_class.h.

int static_init (  ) [inherited]

Low level ranging and ALS register static settings (you should call VL6180x_Prepare() function instead)

Returns:
0 on success

Definition at line 760 of file vl53l0x_class.h.

int upscale_get_scaling (  ) [inherited]

Get current ranging scaling factor.

Returns:
The current scaling factor

Definition at line 820 of file vl53l0x_class.h.

int upscale_set_scaling ( uint8_t  scaling ) [inherited]

Set device ranging scaling factor.

Function Description
The ranging scaling factor is applied on the raw distance measured by the device to increase operating ranging at the price of the precision. Changing the scaling factor when device is not in f/w standby state (free running) is not safe. It can be source of spurious interrupt, wrongly scaled range etc ...
Warning:
__This function doesns't update high/low threshold and other programmed settings linked to scaling factor__. To ensure proper operation, threshold and scaling changes should be done following this procedure:
  • Set Group hold : VL6180x_SetGroupParamHold()
  • Get Threshold VL6180x_RangeGetThresholds()
  • Change scaling : VL6180x_UpscaleSetScaling()
  • Set Threshold : VL6180x_RangeSetThresholds()
  • Unset Group Hold : VL6180x_SetGroupParamHold()
Parameters:
scalingScaling factor to apply (1,2 or 3)
Returns:
0 on success when up-scale support is not configured it fail for any scaling than the one statically configured.

Definition at line 810 of file vl53l0x_class.h.

int wait_device_booted (  ) [inherited]

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:
if device get prepared VL53L0X_Prepare() re-using these function can hold indefinitely
Parameters:
void
Returns:
0 on success

Definition at line 475 of file vl53l0x_class.h.