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
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:
-
state New 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:
-
state New 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_data Pointer 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
- Call other API function to set other settings
- 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_int Select 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_status Pointer 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_data Pointer 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_data Will 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:
-
low scaled low Threshold ptr can be NULL if not needed high scaled 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_data Will 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_m ECE factor M in M/D factor_d ECE 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:
-
enable State 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_msec Requires 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:
-
low raw low threshold set to raw register high raw 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:
-
mode A 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:
-
low Low threshold in mm high High threshold in mm safe_hold Use 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_loop Max 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:
-
IntFunction The interrupt functionality to use one of :
GPIOx_SELECT_OFF
GPIOx_SELECT_GPIO_INTERRUPT_OUTPUTActiveHigh The 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()
- Set Group hold : VL6180x_SetGroupParamHold()
- Parameters:
-
scaling Scaling 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.
Generated on Wed Jul 13 2022 19:35:41 by 1.7.2