Library to handle the X-NUCLEO-6180XA1 Proximity and ambient light sensor expansion board based on VL6180X.
Dependencies: X_NUCLEO_COMMON ST_INTERFACES
Dependents: HelloWorld_6180XA1 SunTracker_BLE Servo_6180XA1 BLE_HR_Light ... more
Fork of X_NUCLEO_6180XA1 by
API init functions. More...
Functions | |
int | wait_device_booted () |
Wait for device booted after chip enable (hardware standby) | |
virtual int | init (void *NewAddr) |
One time device initialization. | |
int | setup_gpio_1 (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 MaxConTime_msec) |
Set maximum convergence time. | |
int | range_poll_measurement (VL6180X_RangeData_t *pRangeData) |
Single shot Range measurement in polling mode. | |
int | _range_get_measurement_if_ready (VL6180X_RangeData_t *pRangeData) |
Check for measure readiness and get it if ready. | |
int | range_get_measurement (VL6180X_RangeData_t *pRangeData) |
Retrieve range measurements set from device. | |
virtual int | get_distance (uint32_t *pi_data) |
Get a single distance measure result. | |
int | range_config_interrupt (uint8_t ConfigGpioInt) |
Configure ranging interrupt reported to application. | |
int | range_get_interrupt_status (uint8_t *pIntStatus) |
Return ranging error interrupt status. | |
int | als_poll_measurement (VL6180X_AlsData_t *pAlsData) |
Run a single ALS measurement in single shot polling mode. | |
int | als_get_measurement (VL6180X_AlsData_t *pAlsData) |
Get actual ALS measurement. | |
int | als_config_interrupt (uint8_t ConfigGpioInt) |
Configure ALS interrupts provide to application. | |
int | als_set_integration_period (uint16_t period_ms) |
Set ALS integration period. | |
int | als_set_inter_measurement_period (uint16_t intermeasurement_period_ms) |
Set ALS "inter-measurement period". | |
int | als_set_analogue_gain (uint8_t gain) |
Set ALS analog gain code. | |
int | als_set_thresholds (uint16_t lux_threshold_low, uint16_t lux_threshold_high) |
Set thresholds for ALS continuous mode. | |
int | als_get_interrupt_status (uint8_t *pIntStatus) |
Read ALS interrupt status. | |
int | static_init () |
Low level ranging and ALS register static settings (you should call VL6180X_Prepare() function instead) | |
int | range_wait_device_ready (int MaxLoop) |
Wait for device to be ready (before a new ranging command can be issued by application) | |
int | range_set_inter_meas_period (uint32_t InterMeasTime_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 SafeHold) |
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 FactorM, uint16_t FactorD) |
Set Early Convergence Estimate ratio. | |
int | range_set_ece_state (int enable) |
Set Early Convergence Estimate state (See SYSRANGE_RANGE_CHECK_ENABLES register) | |
int | flter_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 | d_max_set_state (int state) |
Set activation state of DMax computation. | |
int | d_max_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()) | |
int | start_measurement (operating_mode_t operating_mode, void(*fptr)(void), uint16_t low, uint16_t high) |
Start the measure indicated by operating mode. | |
int | handle_irq (operating_mode_t operating_mode, measure_data_t *Data) |
Interrupt handling func to be called by user after an INT is occourred. | |
int | get_measurement (operating_mode_t operating_mode, measure_data_t *Data) |
Get results for the measure indicated by operating mode. | |
int | stop_measurement (operating_mode_t operating_mode) |
Stop the currently running measure indicate by operating_mode. | |
Variables | |
struct VL6180XDevData_t | SingleVL6180XDevData |
the unique driver data When single device driver is active | |
static const uint16_t ScalerLookUP[] | ROMABLE_DATA = { 253, 127, 84} |
ScalerLookUP scaling factor-1 to register RANGE_SCALER lookup. |
Detailed Description
API init functions.
Wrapper functions.
API init functions
Function Documentation
int _range_get_measurement_if_ready | ( | VL6180X_RangeData_t * | pRangeData ) | [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:
-
pRangeData 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,
int als_config_interrupt | ( | uint8_t | ConfigGpioInt ) | [inherited] |
Configure ALS interrupts provide to application.
- Parameters:
-
ConfigGpioInt 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 may return INVALID_PARAMS for invalid mode
int als_get_interrupt_status | ( | uint8_t * | pIntStatus ) | [inherited] |
int als_get_measurement | ( | VL6180X_AlsData_t * | pAlsData ) | [inherited] |
Get actual ALS measurement.
- Function Description
- Can be called after success status polling or in interrupt mode to retrieve ALS measurement from device
This function doesn't perform any data ready check !
- Parameters:
-
pAlsData Pointer to measurement struct VL6180X_AlsData_t
- Returns:
- 0 on success
int als_poll_measurement | ( | VL6180X_AlsData_t * | pAlsData ) | [inherited] |
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:
-
dev The device pAlsData Als data structure to fill up VL6180X_AlsData_t
- Returns:
- 0 on success
int als_set_analogue_gain | ( | uint8_t | gain ) | [inherited] |
int als_set_integration_period | ( | uint16_t | period_ms ) | [inherited] |
int als_set_inter_measurement_period | ( | uint16_t | intermeasurement_period_ms ) | [inherited] |
Set ALS "inter-measurement period".
- Function Description
- The so call data-sheet "inter measurement period" is actually an extra inter-measurement delay
- Parameters:
-
intermeasurement_period_ms Inter measurement time in milli second
- Warning:
- applied value is clipped to 2550 ms
- Returns:
- 0 on success if value is
int als_set_thresholds | ( | uint16_t | lux_threshold_low, |
uint16_t | lux_threshold_high | ||
) | [inherited] |
Set thresholds for ALS continuous mode.
- Warning:
- Threshold are raw device value not lux!
- Function Description
- Basically value programmed in SYSALS_THRESH_LOW and SYSALS_THRESH_HIGH registers
- Parameters:
-
low ALS low raw threshold for SYSALS_THRESH_LOW high ALS high raw threshold for SYSALS_THRESH_HIGH
- Returns:
- 0 on success
Definition at line 2660 of file VL6180X.cpp.
int d_max_get_state | ( | ) | [inherited] |
int d_max_set_state | ( | int | state ) | [inherited] |
int filter_get_state | ( | ) | [inherited] |
int flter_set_state | ( | int | state ) | [inherited] |
virtual int get_distance | ( | uint32_t * | pi_data ) | [virtual, inherited] |
Get a single distance measure result.
- Function Description
- It can be called after having initialized a component. It start a single distance measure in polling mode and wait until the measure is finisched. The function block until the measure is finished, it can blocks indefinitely in case the measure never ends for any reason
- Parameters:
-
pi_data Pointer to distance
- Returns:
- 0 on success
int get_measurement | ( | operating_mode_t | operating_mode, |
measure_data_t * | Data | ||
) | [inherited] |
Get results for the measure indicated by operating mode.
- Parameters:
-
[in] operating_mode specifies requested measure results [out] Data pointer to the measure_data_t structure to read data in to
- Returns:
- 0 on Success
Definition at line 3248 of file VL6180X.cpp.
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
int handle_irq | ( | operating_mode_t | operating_mode, |
measure_data_t * | Data | ||
) | [inherited] |
Interrupt handling func to be called by user after an INT is occourred.
- Parameters:
-
[in] opeating_mode indicating the in progress measure [out] Data pointer to the measure_data_t structure to read data in to
- Returns:
- 0 on Success
Definition at line 3155 of file VL6180X.cpp.
virtual int init | ( | void * | NewAddr ) | [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
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
int range_config_interrupt | ( | uint8_t | ConfigGpioInt ) | [inherited] |
Configure ranging interrupt reported to application.
- Parameters:
-
ConfigGpioInt 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
int range_get_interrupt_status | ( | uint8_t * | pIntStatus ) | [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:
-
pIntStatus Pointer to status variable to update
- Returns:
- 0 on success
int range_get_measurement | ( | VL6180X_RangeData_t * | pRangeData ) | [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:
-
pRangeData Pointer to the data structure to fill up
- Returns:
- 0 on success
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
int range_poll_measurement | ( | VL6180X_RangeData_t * | pRangeData ) | [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:
-
pRangeData 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
int range_set_ece_factor | ( | uint16_t | FactorM, |
uint16_t | FactorD | ||
) | [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:
-
FactorM ECE factor M in M/D FactorD ECE factor D in M/D
- Returns:
- 0 on success. <0 on error. >0 on warning
int range_set_ece_state | ( | int | enable ) | [inherited] |
int range_set_inter_meas_period | ( | uint32_t | InterMeasTime_msec ) | [inherited] |
int range_set_max_convergence_time | ( | uint8_t | MaxConTime_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:
-
MaxConTime_msec
- Returns:
- 0 on success. <0 on error. >0 for calibration warning status
int range_set_raw_thresholds | ( | uint8_t | low, |
uint8_t | high | ||
) | [inherited] |
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
int range_set_thresholds | ( | uint16_t | low, |
uint16_t | high, | ||
int | SafeHold | ||
) | [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 SafeHold Use of group parameters hold to surround threshold programming.
- Returns:
- 0 On success
int range_start_continuous_mode | ( | ) | [inherited] |
int range_start_single_shot | ( | ) | [inherited] |
int range_wait_device_ready | ( | int | MaxLoop ) | [inherited] |
Wait for device to be ready (before a new ranging command can be issued by application)
- Parameters:
-
MaxLoop 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
int setup_gpio_1 | ( | 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
int start_measurement | ( | operating_mode_t | operating_mode, |
void(*)(void) | fptr, | ||
uint16_t | low, | ||
uint16_t | high | ||
) | [inherited] |
Start the measure indicated by operating mode.
- Parameters:
-
[in] operating_mode specifies requested measure [in] fptr specifies call back function must be !NULL in case of interrupt measure [in] low specifies measure low threashold in Lux or in mm according to measure [in] high specifies measure high threashold in Lux or in mm according to measure
- Returns:
- 0 on Success
Definition at line 2692 of file VL6180X.cpp.
int static_init | ( | ) | [inherited] |
int stop_measurement | ( | operating_mode_t | operating_mode ) | [inherited] |
Stop the currently running measure indicate by operating_mode.
- Parameters:
-
[in] operating_mode specifies requested measure to stop
- Returns:
- 0 on Success
Definition at line 3474 of file VL6180X.cpp.
int upscale_get_scaling | ( | ) | [inherited] |
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.
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 VL6180X_Prepare() re-using these function can hold indefinitely
- Parameters:
-
void
- Returns:
- 0 on success
Variable Documentation
const uint16_t AlsGainLookUp [8] ROMABLE_DATA = { 253, 127, 84} [static] |
ScalerLookUP scaling factor-1 to register RANGE_SCALER lookup.
Als Code gain to fix point gain lookup.
scaling factor to Upper limit look up
Definition at line 167 of file VL6180X.cpp.
struct VL6180XDevData_t VL6180X_DEV_DATA_ATTR SingleVL6180XDevData |
{ .EceFactorM = DEF_ECE_FACTOR_M, .EceFactorD = DEF_ECE_FACTOR_D, #ifdef VL6180X_HAVE_UPSCALE_DATA .UpscaleFactor = DEF_UPSCALE, #endif #ifdef VL6180X_HAVE_ALS_DATA .IntegrationPeriod = DEF_INT_PEFRIOD, .AlsGainCode = DEF_ALS_GAIN, .AlsScaler = DEF_ALS_SCALER, #endif #ifdef VL6180X_HAVE_DMAX_RANGING .DMaxEnable = DEF_DMAX_ENABLE, #endif }
the unique driver data When single device driver is active
Definition at line 239 of file VL6180X.cpp.
Generated on Wed Jul 13 2022 23:03:14 by 1.7.2