vl53l1_api.h

00001 
00002 /* SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause */
00003 /******************************************************************************
00004  * Copyright (c) 2020, STMicroelectronics - All Rights Reserved
00005 
00006  This file is part of VL53L1 and is dual licensed,
00007  either GPL-2.0+
00008  or 'BSD 3-clause "New" or "Revised" License' , at your option.
00009  ******************************************************************************
00010  */
00011 
00012 #ifndef _VL53L1_API_H_
00013 #define _VL53L1_API_H_
00014 
00015 #include "vl53l1_api_strings.h"
00016 #include "vl53l1_api_core.h"
00017 #include "vl53l1_preset_setup.h"
00018 
00019 #ifdef __cplusplus
00020 extern "C"
00021 {
00022 #endif
00023 
00024 #if !defined(VL53L1DevDataGet)
00025 #warning "PALDevDataGet is deprecated define VL53L1DevDataGet instead"
00026 #define VL53L1DevDataGet(Dev, field) (Dev->Data.field)
00027 #endif
00028 
00029 #if !defined(VL53L1DevDataSet)
00030 #warning "PALDevDataSet is deprecated define VL53L1DevDataSet instead"
00031 #define VL53L1DevDataSet(Dev, field, data) ((Dev->Data.field) = (data))
00032 #endif
00033 
00034 /** @defgroup VL53L1_cut11_group VL53L1 cut1.1 Function Definition
00035  *  @brief    VL53L1 cut1.1 Function Definition
00036  *  @{
00037  */
00038 
00039 /** @defgroup VL53L1_general_group VL53L1 General Functions
00040  *  @brief    General functions and definitions
00041  *  @{
00042  */
00043 
00044 /**
00045  * @brief Return the VL53L1 driver Version
00046  *
00047  * @note This function doesn't access to the device
00048  *
00049  * @param   pVersion              Rer to current driver Version
00050  * @return  VL53L1_ERROR_NONE     Success
00051  * @return  "Other error code"    See ::VL53L1_Error
00052  */
00053 VL53L1_Error VL53L1_GetVersion(VL53L1_Version_t *pVersion);
00054 
00055 /**
00056  * @brief Reads the Product Revision for a for given Device
00057  * This function can be used to distinguish cut1.0 from cut1.1.
00058  *
00059  * @param   Dev                 Device Handle
00060  * @param   pProductRevisionMajor  Pointer to Product Revision Major
00061  * for a given Device
00062  * @param   pProductRevisionMinor  Pointer to Product Revision Minor
00063  * for a given Device
00064  * @return  VL53L1_ERROR_NONE        Success
00065  * @return  "Other error code"    See ::VL53L1_Error
00066  */
00067 VL53L1_Error VL53L1_GetProductRevision(VL53L1_DEV Dev,
00068     uint8_t *pProductRevisionMajor, uint8_t *pProductRevisionMinor);
00069 
00070 /**
00071  * @brief Reads the Device information for given Device
00072  *
00073  * @note This function Access to the device
00074  *
00075  * @param   Dev                 Device Handle
00076  * @param   pVL53L1_DeviceInfo  Pointer to current device info for a given
00077  *  Device
00078  * @return  VL53L1_ERROR_NONE   Success
00079  * @return  "Other error code"  See ::VL53L1_Error
00080  */
00081 VL53L1_Error VL53L1_GetDeviceInfo(VL53L1_DEV Dev,
00082     VL53L1_DeviceInfo_t *pVL53L1_DeviceInfo);
00083 
00084 /**
00085  * @brief Reads the Device unique identifier
00086  *
00087  * @note This function Access to the device
00088  *
00089  * @param   Dev                 Device Handle
00090  * @param   pUid                Pointer to current device unique ID
00091  * @return  VL53L1_ERROR_NONE   Success
00092  * @return  "Other error code"  See ::VL53L1_Error
00093  */
00094 VL53L1_Error VL53L1_GetUID(VL53L1_DEV Dev, uint64_t *pUid);
00095 
00096 /**
00097  * @brief Human readable Range Status string for a given RangeStatus
00098  *
00099  * @note This function doesn't access to the device
00100  *
00101  * @param   RangeStatus         The RangeStatus code as stored on
00102  * @a VL53L1_RangingMeasurementData_t
00103  * @param   pRangeStatusString  The returned RangeStatus string. Shall be
00104  * defined as char buf[VL53L1_MAX_STRING_LENGTH]
00105  * @return  VL53L1_ERROR_NONE   Success
00106  * @return  "Other error code"  See ::VL53L1_Error
00107  */
00108 VL53L1_Error VL53L1_GetRangeStatusString(uint8_t RangeStatus,
00109     char *pRangeStatusString);
00110 
00111 /**
00112  * @brief Human readable error string for driver error status
00113  *
00114  * @note This function doesn't access to the device
00115  *
00116  * @param   PalErrorCode       The error code as stored on @a VL53L1_Error
00117  * @param   pPalErrorString    The error string corresponding to the
00118  * PalErrorCode. Shall be defined as char buf[VL53L1_MAX_STRING_LENGTH]
00119  * @return  VL53L1_ERROR_NONE  Success
00120  * @return  "Other error code" See ::VL53L1_Error
00121  */
00122 VL53L1_Error VL53L1_GetPalErrorString(VL53L1_Error PalErrorCode,
00123     char *pPalErrorString);
00124 
00125 /**
00126  * @brief Human readable driver State string
00127  *
00128  * @note This function doesn't access to the device
00129  *
00130  * @param   PalStateCode          The State code as stored on @a VL53L1_State
00131  * @param   pPalStateString       The State string corresponding to the
00132  * PalStateCode. Shall be defined as char buf[VL53L1_MAX_STRING_LENGTH]
00133  * @return  VL53L1_ERROR_NONE     Success
00134  * @return  "Other error code"    See ::VL53L1_Error
00135  */
00136 VL53L1_Error VL53L1_GetPalStateString(VL53L1_State PalStateCode,
00137     char *pPalStateString);
00138 
00139 /**
00140  * @brief Reads the internal state of the driver for a given Device
00141  *
00142  * @note This function doesn't access to the device
00143  *
00144  * @param   Dev                   Device Handle
00145  * @param   pPalState             Pointer to current state of the PAL for a
00146  * given Device
00147  * @return  VL53L1_ERROR_NONE     Success
00148  * @return  "Other error code"    See ::VL53L1_Error
00149  */
00150 VL53L1_Error VL53L1_GetPalState(VL53L1_DEV Dev,
00151     VL53L1_State *pPalState);
00152 
00153 
00154 
00155 /** @} VL53L1_general_group */
00156 
00157 /** @defgroup VL53L1_init_group VL53L1 Init Functions
00158  *  @brief    VL53L1 Init Functions
00159  *  @{
00160  */
00161 
00162 /**
00163  * @brief Set new device address
00164  *
00165  * After completion the device will answer to the new address programmed.
00166  * This function should be called when several devices are used in parallel
00167  * before start programming the sensor.
00168  * When a single device us used, there is no need to call this function.
00169  *
00170  * When it is requested for multi devices system this function MUST be called
00171  * prior to VL53L1_DataInit()
00172  *
00173  * @note This function Access to the device
00174  *
00175  * @param   Dev                   Device Handle
00176  * @param   DeviceAddress         The new Device address
00177  * @return  VL53L1_ERROR_NONE     Success
00178  * @return  "Other error code"    See ::VL53L1_Error
00179  */
00180 VL53L1_Error VL53L1_SetDeviceAddress(VL53L1_DEV Dev,
00181     uint8_t DeviceAddress);
00182 
00183 /**
00184  *
00185  * @brief One time device initialization
00186  *
00187  * To be called after device has been powered on and booted
00188  * see @a VL53L1_WaitDeviceBooted()
00189  *
00190  * @par Function Description
00191  * When not used after a fresh device "power up", it may return
00192  * @a #VL53L1_ERROR_CALIBRATION_WARNING meaning wrong calibration data
00193  * may have been fetched from device that can result in ranging offset error\n
00194  * If VL53L1_DataInit is called several times then the application must restore
00195  * calibration calling @a VL53L1_SetOffsetCalibrationData()
00196  * It implies application has gathered calibration data thanks to
00197  * @a VL53L1_GetOffsetCalibrationData() after an initial calibration stage.
00198  * This function will change the VL53L1_State from VL53L1_STATE_POWERDOWN to
00199  * VL53L1_STATE_WAIT_STATICINIT.
00200  *
00201  * @note This function Access to the device
00202  *
00203  * @param   Dev                   Device Handle
00204  * @return  VL53L1_ERROR_NONE     Success
00205  * @return  "Other error code"    See ::VL53L1_Error
00206  */
00207 VL53L1_Error VL53L1_DataInit(VL53L1_DEV Dev);
00208 
00209 
00210 /**
00211  * @brief Do basic device init (and eventually patch loading)
00212  * This function will change the VL53L1_State from
00213  * VL53L1_STATE_WAIT_STATICINIT to VL53L1_STATE_IDLE.
00214  * In this stage all default setting will be applied.
00215  *
00216  * @note This function Access to the device
00217  *
00218  * @param   Dev                   Device Handle
00219  * @return  VL53L1_ERROR_NONE     Success
00220  * @return  "Other error code"    See ::VL53L1_Error
00221  */
00222 VL53L1_Error VL53L1_StaticInit(VL53L1_DEV Dev);
00223 
00224 /**
00225  * @brief Wait for device booted after chip enable (hardware standby)
00226  * This function can be run only when VL53L1_State is VL53L1_STATE_POWERDOWN.
00227  *
00228  * @param   Dev                   Device Handle
00229  * @return  VL53L1_ERROR_NONE     Success
00230  * @return  "Other error code"    See ::VL53L1_Error
00231  *
00232  */
00233 VL53L1_Error VL53L1_WaitDeviceBooted(VL53L1_DEV Dev);
00234 
00235 
00236 /** @} VL53L1_init_group */
00237 
00238 /** @defgroup VL53L1_parameters_group VL53L1 Parameters Functions
00239  *  @brief    Functions used to prepare and setup the device
00240  *  @{
00241  */
00242 
00243 /**
00244  * @brief  Set a new Preset Mode
00245  * @par Function Description
00246  * Set device to a new Operating Mode (High speed ranging, Multi objects ...)
00247  *
00248  * @note This function doesn't Access to the device
00249  *
00250  * @warning This function change the timing budget to 16 ms and the inter-
00251  * measurement period to 1000 ms. Also the VL53L1_DISTANCEMODE_LONG is used.
00252  *
00253  * @param   Dev                   Device Handle
00254  * @param   PresetMode            New Preset mode to apply
00255  * <br>Valid values are:
00256  */
00257 /**
00258  * @li VL53L1_PRESETMODE_MULTIZONES_SCANNING
00259  * @li VL53L1_PRESETMODE_RANGING
00260  * @li VL53L1_PRESETMODE_AUTONOMOUS
00261  * @li VL53L1_PRESETMODE_LOWPOWER_AUTONOMOUS
00262  * @li VL53L1_PRESETMODE_LITE_RANGING
00263  * @li VL53L1_PRESETMODE_OLT
00264  */
00265 /**
00266  *
00267  * @return  VL53L1_ERROR_NONE               Success
00268  * @return  VL53L1_ERROR_MODE_NOT_SUPPORTED This error occurs when PresetMode is
00269  *                                          not in the supported list
00270  */
00271 VL53L1_Error VL53L1_SetPresetMode(VL53L1_DEV Dev,
00272         VL53L1_PresetModes PresetMode);
00273 
00274 /**
00275  * @brief  Get current Preset Mode
00276  * @par Function Description
00277  * Get actual mode of the device(ranging, histogram ...)
00278  *
00279  * @note This function doesn't Access to the device
00280  *
00281  * @param   Dev                   Device Handle
00282  * @param   pPresetMode           Pointer to current apply mode value
00283  *
00284  * @return  VL53L1_ERROR_NONE                   Success
00285  * @return  VL53L1_ERROR_MODE_NOT_SUPPORTED     This error occurs when
00286  * DeviceMode is not in the supported list
00287  */
00288 VL53L1_Error VL53L1_GetPresetMode(VL53L1_DEV Dev,
00289         VL53L1_PresetModes *pPresetMode);
00290 
00291 
00292 /**
00293  * @brief  Set the distance mode
00294  * @par Function Description
00295  * Set the distance mode to be used for the next ranging.<br>
00296  * The modes Short, Medium and Long are used to optimize the ranging accuracy
00297  * in a specific range of distance.<br> The user select one of these modes to
00298  * select the distance range. <br>
00299  * Two additional modes are supported: AUTO and AUTO_LITE the difference between
00300  * these modes is the following.<br>
00301  * The mode AUTO take into account both the ranging distance (RangeMilliMeter)
00302  * and the dmax distance (DmaxMilliMeter).<br> The algorithm uses the ranging
00303  * distance when the range status is ok and uses the dmax distance when the
00304  * range status is not ok.<br>
00305  * The AUTO_LITE take into account only the ranging distance, so nothing is done
00306  * in case of range error i.e. the distance mode will not be changed.
00307  * @note This function doesn't Access to the device
00308  *
00309  * @warning This function should be called after @a VL53L1_SetPresetMode().
00310 
00311  * @param   Dev                   Device Handle
00312  * @param   DistanceMode          Distance mode to apply valid values are:
00313  * @li VL53L1_DISTANCEMODE_SHORT
00314  * @li VL53L1_DISTANCEMODE_MEDIUM
00315  * @li VL53L1_DISTANCEMODE_LONG
00316  * @li VL53L1_DISTANCEMODE_AUTO_LITE
00317  * @li VL53L1_DISTANCEMODE_AUTO
00318  * @return  VL53L1_ERROR_NONE               Success
00319  * @return  VL53L1_ERROR_MODE_NOT_SUPPORTED This error occurs when DistanceMode
00320  *                                          is not in the supported list
00321  * @return  "Other error code"              See ::VL53L1_Error
00322  */
00323 VL53L1_Error VL53L1_SetDistanceMode(VL53L1_DEV Dev,
00324         VL53L1_DistanceModes DistanceMode);
00325 
00326 /**
00327  * @brief  Get the distance mode
00328  * @par Function Description
00329  * Get the distance mode used for the next ranging.
00330  *
00331  * @param   Dev                   Device Handle
00332  * @param   *pDistanceMode        Pointer to Distance mode
00333  * @return  VL53L1_ERROR_NONE            Success
00334  * @return  "Other error code"           See ::VL53L1_Error
00335  */
00336 VL53L1_Error VL53L1_GetDistanceMode(VL53L1_DEV Dev,
00337         VL53L1_DistanceModes *pDistanceMode);
00338 
00339 
00340 /**
00341  * @brief  Set the output mode
00342  * @par Function Description
00343  * Set the output mode to be used for the next ranging. The output mode is used
00344  * to select, in case of multiple objects, which one will be used in
00345  * function @a VL53L1_GetRangingMeasurementData().
00346  * VL53L1_SetOutputMode also sets the object used by automatic
00347  * distance mode algorithm when @a VL53L1_SetDistanceMode() is
00348  * set to automatic mode.
00349  *
00350  * @note This function doesn't Access to the device
00351  *
00352  * @warning This function should be called after @a VL53L1_SetPresetMode().
00353 
00354  * @param   Dev                   Device Handle
00355  * @param   OutputMode            Output mode to apply valid values are:
00356  * @li VL53L1_OUTPUTMODE_NEAREST
00357  * @li VL53L1_OUTPUTMODE_STRONGEST
00358  *
00359  * @return  VL53L1_ERROR_NONE               Success
00360  * @return  VL53L1_ERROR_MODE_NOT_SUPPORTED This error occurs when OutputMode
00361  *                                          is not in the supported list
00362  * @return  "Other error code"              See ::VL53L1_Error
00363  */
00364 VL53L1_Error VL53L1_SetOutputMode(VL53L1_DEV Dev,
00365         VL53L1_OutputModes OutputMode);
00366 
00367 /**
00368  * @brief  Get the output mode
00369  * @par Function Description
00370  * Get the output mode used for the next ranging.
00371  *
00372  * @param   Dev                   Device Handle
00373  * @param   *pOutputMode          Pointer to Output mode
00374  * @return  VL53L1_ERROR_NONE     Success
00375  * @return  "Other error code"    See ::VL53L1_Error
00376  */
00377 VL53L1_Error VL53L1_GetOutputMode(VL53L1_DEV Dev,
00378         VL53L1_OutputModes *pOutputMode);
00379 
00380 
00381 /**
00382  * @brief Set Ranging Timing Budget in microseconds
00383  *
00384  * @par Function Description
00385  * Defines the maximum time allowed by the user to the device to run a
00386  * full ranging sequence for the current mode (ranging, histogram, ASL ...)
00387  *
00388  * @param   Dev                                Device Handle
00389  * @param MeasurementTimingBudgetMicroSeconds  Max measurement time in
00390  * microseconds.
00391  * @return  VL53L1_ERROR_NONE            Success
00392  * @return  VL53L1_ERROR_INVALID_PARAMS  Error timing parameter not
00393  *                                       supported.
00394  *                                       The maximum accepted value for the
00395  *                                       computed timing budget is 10 seconds
00396  *                                       the minimum value depends on the preset
00397  *                                       mode selected.
00398  * @return  "Other error code"           See ::VL53L1_Error
00399  */
00400 VL53L1_Error VL53L1_SetMeasurementTimingBudgetMicroSeconds(
00401     VL53L1_DEV Dev, uint32_t MeasurementTimingBudgetMicroSeconds);
00402 
00403 /**
00404  * @brief Get Ranging Timing Budget in microseconds
00405  *
00406  * @par Function Description
00407  * Returns the programmed the maximum time allowed by the user to the
00408  * device to run a full ranging sequence for the current mode
00409  * (ranging, histogram, ASL ...)
00410  *
00411  * @param   Dev                                    Device Handle
00412  * @param   pMeasurementTimingBudgetMicroSeconds   Max measurement time in
00413  * microseconds.
00414  * @return  VL53L1_ERROR_NONE            Success
00415  * @return  "Other error code"           See ::VL53L1_Error
00416  */
00417 VL53L1_Error VL53L1_GetMeasurementTimingBudgetMicroSeconds(
00418     VL53L1_DEV Dev, uint32_t *pMeasurementTimingBudgetMicroSeconds);
00419 
00420 
00421 /**
00422  * Program continuous mode Inter-Measurement period in milliseconds
00423  *
00424  * @par Function Description
00425  * When trying to set too short time return  INVALID_PARAMS minimal value
00426  *
00427  * @param   Dev                                  Device Handle
00428  * @param   InterMeasurementPeriodMilliSeconds   Inter-Measurement Period in ms.
00429  *  this value should be greater than the duration set in
00430  *  @a VL53L1_SetMeasurementTimingBudgetMicroSeconds() to ensure smooth ranging
00431  *  operation.
00432  * @return  VL53L1_ERROR_NONE            Success
00433  * @return  "Other error code"           See ::VL53L1_Error
00434  */
00435 VL53L1_Error VL53L1_SetInterMeasurementPeriodMilliSeconds(
00436     VL53L1_DEV Dev, uint32_t InterMeasurementPeriodMilliSeconds);
00437 
00438 /**
00439  * Get continuous mode Inter-Measurement period in milliseconds
00440  *
00441  * @par Function Description
00442  *
00443  * @param   Dev                                  Device Handle
00444  * @param   pInterMeasurementPeriodMilliSeconds  Pointer to programmed
00445  *  Inter-Measurement Period in milliseconds.
00446  * @return  VL53L1_ERROR_NONE
00447  */
00448 VL53L1_Error VL53L1_GetInterMeasurementPeriodMilliSeconds(
00449     VL53L1_DEV Dev, uint32_t *pInterMeasurementPeriodMilliSeconds);
00450 
00451 /**
00452  * @brief  target reflectance for Dmax setting
00453  * @par Function Description
00454  * Allow user to set the value for target reflectance @ 940nm to calculate the
00455  * ambient DMAX values for. Set to 50% by default by @a VL53L1_DataInit()
00456  *
00457  * @param   Dev                   Device Handle
00458  * @param   DmaxReflectance       Reflectance % in 16.16 fixed point
00459  * @return  VL53L1_ERROR_NONE     Success
00460  * @return  VL53L1_ERROR_INVALID_PARAMS     in case input value is not in range
00461  * from 0 to 100. Note that this is a fix point value so the max value is
00462  * 100 * 65536.
00463  * @return  "Other error code"    See ::VL53L1_Error
00464  */
00465 VL53L1_Error VL53L1_SetDmaxReflectance(VL53L1_DEV Dev,
00466         FixPoint1616_t DmaxReflectance);
00467 
00468 /**
00469  * @brief  Get target reflectance for Dmax
00470  * @par Function Description
00471  * Retrieves the value for target reflectance @ 940nm to calculate the
00472  * ambient DMAX values for. Set to 50% by default by @a VL53L1_DataInit()
00473  *
00474  * @param   Dev                   Device Handle
00475  * @param   pDmaxReflectance      pointer to Reflectance % in 16.16 fixed point
00476  * @return  VL53L1_ERROR_NONE     Success
00477  * @return  "Other error code"    See ::VL53L1_Error
00478  */
00479 VL53L1_Error VL53L1_GetDmaxReflectance(VL53L1_DEV Dev,
00480         FixPoint1616_t *pDmaxReflectance);
00481 /**
00482  * @brief Set function for ambient Dmax mode
00483  *
00484  *
00485  * @param    Dev                  Device Handle
00486  * @param    DmaxMode             DMAX mode to be used in ranging
00487  *
00488  * @return   VL53L1_ERROR_NONE    Success
00489  * @return  "Other error code"    See ::VL53L1_Error
00490  */
00491 
00492 
00493 VL53L1_Error VL53L1_SetDmaxMode(VL53L1_DEV Dev,
00494         VL53L1_DeviceDmaxModes DmaxMode);
00495 
00496 /**
00497  * @brief Get function for ambient Dmax mode
00498  *
00499  * @param   Dev              Device Handle
00500  * @param   pDmaxMode        output pointer to DMAX mode currently in use
00501  *
00502  * @return   VL53L1_ERROR_NONE    Success
00503  * @return  "Other error code"    See ::VL53L1_Error
00504  */
00505 
00506 VL53L1_Error VL53L1_GetDmaxMode(VL53L1_DEV Dev,
00507     VL53L1_DeviceDmaxModes *pDmaxMode);
00508 
00509 /** @} VL53L1_parameters_group */
00510 
00511 
00512 /** @defgroup VL53L1_limitcheck_group VL53L1 Limit Check Functions
00513  *  @brief    Functions used for the Limit checks
00514  *  @{
00515  */
00516 
00517 
00518 
00519 /**
00520  * @brief  Get the number of the check limit managed by a given Device
00521  *
00522  * @par Function Description
00523  * This function give the number of the check limit managed by the Device
00524  *
00525  * @param   pNumberOfLimitCheck           Pointer to the number of check limit.
00526  * @return  VL53L1_ERROR_NONE            Success
00527  * @return  "Other error code"           See ::VL53L1_Error
00528  */
00529 VL53L1_Error VL53L1_GetNumberOfLimitCheck(
00530     uint16_t *pNumberOfLimitCheck);
00531 
00532 /**
00533  * @brief  Return a description string for a given limit check number
00534  *
00535  * @par Function Description
00536  * This function returns a description string for a given limit check number.
00537  * The limit check is identified with the LimitCheckId.
00538  *
00539  * @param   LimitCheckId                  Limit Check ID
00540  * (0<= LimitCheckId < VL53L1_GetNumberOfLimitCheck() ).
00541  * @param   pLimitCheckString             Pointer to the description string of
00542  * the given check limit. Shall be defined as char buf[VL53L1_MAX_STRING_LENGTH]
00543  * @return  VL53L1_ERROR_NONE            Success
00544  * @return  "Other error code"           See ::VL53L1_Error
00545  */
00546 VL53L1_Error VL53L1_GetLimitCheckInfo(uint16_t LimitCheckId,
00547     char *pLimitCheckString);
00548 
00549 /**
00550  * @brief  Return a the Status of the specified check limit
00551  *
00552  * @par Function Description
00553  * This function returns the Status of the specified check limit.
00554  * The value indicate if the check is fail or not.
00555  * The limit check is identified with the LimitCheckId.
00556  *
00557  * @param   Dev                           Device Handle
00558  * @param   LimitCheckId                  Limit Check ID
00559  (0<= LimitCheckId < VL53L1_GetNumberOfLimitCheck() ).
00560  * @param   pLimitCheckStatus             Pointer to the
00561  Limit Check Status of the given check limit.
00562  * LimitCheckStatus :
00563  * 0 the check is not fail or not enabled
00564  * 1 the check if fail
00565  *
00566  * <p><ul>
00567  *    <li>VL53L1_CHECKENABLE_SIGMA_FINAL_RANGE: the sigma indicate the quality
00568  *    of the measure. The more it is little the better it is.
00569  *    The status is 1 when current sigma is greater then the limit.</li>
00570  *    <li>VL53L1_CHECKENABLE_SIGNAL_RATE_FINAL_RANGE: the signal rate indicate
00571  *    the strength of the returned signal. The more it is big the better it is.
00572  *    The status is 1 when current signal is lower then the limit.</li>
00573  * </ul></p>
00574  *
00575  *
00576  * @return  VL53L1_ERROR_NONE            Success
00577  * @return  "Other error code"           See ::VL53L1_Error
00578  */
00579 VL53L1_Error VL53L1_GetLimitCheckStatus(VL53L1_DEV Dev,
00580     uint16_t LimitCheckId, uint8_t *pLimitCheckStatus);
00581 
00582 /**
00583  * @brief  Enable/Disable a specific limit check
00584  *
00585  * @par Function Description
00586  * This function Enable/Disable a specific limit check.
00587  * The limit check is identified with the LimitCheckId.
00588  *
00589  * @note This function doesn't Access to the device
00590  *
00591  * @param   Dev                           Device Handle
00592  * @param   LimitCheckId                  Limit Check ID
00593  *  (0<= LimitCheckId < VL53L1_GetNumberOfLimitCheck() ).
00594  * @param   LimitCheckEnable
00595  * @li set LimitCheckEnable=1 enables the LimitCheckId limit
00596  * @li set LimitCheckEnable=0 disables the LimitCheckId limit
00597  * @return  VL53L1_ERROR_NONE            Success
00598  * @return  VL53L1_ERROR_INVALID_PARAMS   This error is returned
00599  *  when LimitCheckId value is out of range.
00600  * @return  "Other error code"           See ::VL53L1_Error
00601  */
00602 VL53L1_Error VL53L1_SetLimitCheckEnable(VL53L1_DEV Dev,
00603     uint16_t LimitCheckId, uint8_t LimitCheckEnable);
00604 
00605 /**
00606  * @brief  Get specific limit check enable state
00607  *
00608  * @par Function Description
00609  * This function get the enable state of a specific limit check.
00610  * The limit check is identified with the LimitCheckId.
00611  *
00612  * @note This function Access to the device
00613  *
00614  * @param   Dev                           Device Handle
00615  * @param   LimitCheckId                  Limit Check ID
00616  *  (0<= LimitCheckId < VL53L1_GetNumberOfLimitCheck() ).
00617  * @param   pLimitCheckEnable             Pointer to the check limit enable
00618  * value.
00619  * @li if 1 the check limit corresponding to LimitCheckId is Enabled
00620  * @li if 0 the check limit corresponding to LimitCheckId is disabled
00621  * @return  VL53L1_ERROR_NONE            Success
00622  * @return  VL53L1_ERROR_INVALID_PARAMS   This error is returned
00623  *  when LimitCheckId value is out of range.
00624  * @return  "Other error code"           See ::VL53L1_Error
00625  */
00626 VL53L1_Error VL53L1_GetLimitCheckEnable(VL53L1_DEV Dev,
00627     uint16_t LimitCheckId, uint8_t *pLimitCheckEnable);
00628 
00629 /**
00630  * @brief  Set a specific limit check value
00631  *
00632  * @par Function Description
00633  * This function set a specific limit check value.
00634  * The limit check is identified with the LimitCheckId.
00635  *
00636  * @note Note that the value written with that function will not be applied if
00637  * the limit is not enabled. In other words this function will not enable the
00638  * limit but change only the value. In case the limit is not enabled the value
00639  * is saved internally and applied with VL53L1_SetLimitCheckEnable.
00640  *
00641  * @param   Dev                           Device Handle
00642  * @param   LimitCheckId                  Limit Check ID
00643  *  (0<= LimitCheckId < VL53L1_GetNumberOfLimitCheck() ).
00644  * @param   LimitCheckValue               Limit check Value for a given
00645  * LimitCheckId
00646  * @return  VL53L1_ERROR_NONE            Success
00647  * @return  "Other error code"           See ::VL53L1_Error
00648  */
00649 VL53L1_Error VL53L1_SetLimitCheckValue(VL53L1_DEV Dev,
00650     uint16_t LimitCheckId, FixPoint1616_t LimitCheckValue);
00651 
00652 /**
00653  * @brief  Get a specific limit check value
00654  *
00655  * @par Function Description
00656  * This function get a specific limit check value from device then it updates
00657  * internal values and check enables.
00658  * The limit check is identified with the LimitCheckId.
00659  *
00660  * @note This function get the current value from device if zero then the value
00661  * returned is the one stored by the user, but in that case the check is store
00662  * as disabled. If the value from device is not zero, this is returned and set
00663  * into the memory at the same way that user call VL53L1_SetLimitCheckValue()
00664  *
00665  * @param   Dev                           Device Handle
00666  * @param   LimitCheckId                  Limit Check ID
00667  *  (0<= LimitCheckId < VL53L1_GetNumberOfLimitCheck() ).
00668  * @param   pLimitCheckValue              Pointer to Limit
00669  *  check Value for a given LimitCheckId.
00670  * @return  VL53L1_ERROR_NONE            Success
00671  * @return  "Other error code"           See ::VL53L1_Error
00672  */
00673 VL53L1_Error VL53L1_GetLimitCheckValue(VL53L1_DEV Dev,
00674     uint16_t LimitCheckId, FixPoint1616_t *pLimitCheckValue);
00675 
00676 /**
00677  * @brief  Get the current value of the signal used for the limit check
00678  *
00679  * @par Function Description
00680  * This function get a the current value of the signal used for the limit check.
00681  * To obtain the latest value you should run a valid ranging before.
00682  * The value reported is linked to the limit check identified with the
00683  * LimitCheckId.
00684  *
00685  * @param   Dev                           Device Handle
00686  * @param   LimitCheckId                  Limit Check ID
00687  *  (0<= LimitCheckId < VL53L1_GetNumberOfLimitCheck() ).
00688  * @param   pLimitCheckCurrent            Pointer to current Value for a
00689  * given LimitCheckId.
00690  * @return  VL53L1_ERROR_NONE            Success
00691  * @return  "Other error code"           See ::VL53L1_Error
00692  */
00693 VL53L1_Error VL53L1_GetLimitCheckCurrent(VL53L1_DEV Dev,
00694     uint16_t LimitCheckId, FixPoint1616_t *pLimitCheckCurrent);
00695 
00696 /** @} VL53L1_limitcheck_group */
00697 
00698 
00699 
00700 /** @defgroup VL53L1_ROI_group VL53L1 ROI Functions
00701  *  @brief    Functions used to select ROIs
00702  *  @{
00703  */
00704 
00705 /**
00706  * @brief Get the Maximum number of ROI Zones managed by the Device
00707  *
00708  * @par Function Description
00709  * Get Maximum number of ROI Zones managed by the Device.
00710  *
00711  * @note The number of Zone depends on the preset mode used so to have the
00712  * right number this function should be call after @a VL53L1_SetPresetMode()
00713  * @note This function doesn't Access to the device
00714  *
00715  * @param   Dev                    Device Handle
00716  * @param   pMaxNumberOfROI   Pointer to the Maximum Number
00717  *  of ROI Zones value.
00718  * @return  VL53L1_ERROR_NONE        Success
00719  * @return  "Other error code"       See ::VL53L1_Error
00720  */
00721 VL53L1_Error VL53L1_GetMaxNumberOfROI(VL53L1_DEV Dev,
00722     uint8_t *pMaxNumberOfROI);
00723 /**
00724  * @brief Set the ROI  to be used for ranging
00725  *
00726  * @par Function Description
00727  * The user defined ROIs are rectangles described as per the following system
00728  * from the Top Left corner to the Bottom Right corner.
00729  * <br>Minimal ROI size is 4x4 spads
00730  * @image html roi_coord.png
00731  *
00732  * @param   Dev                      Device Handle
00733  * @param   pRoiConfig               Pointer to the Structure containing all the
00734  * ROI to be used.
00735  * @return  VL53L1_ERROR_NONE            Success
00736  * @return  "Other error code"           See ::VL53L1_Error
00737  */
00738 VL53L1_Error VL53L1_SetROI(VL53L1_DEV Dev,
00739         VL53L1_RoiConfig_t *pRoiConfig);
00740 
00741 /**
00742  * @brief Get the ROI managed by the Device
00743  *
00744  * @par Function Description
00745  * Get the ROI managed by the Device
00746  *
00747  * @param   Dev                   Device Handle
00748  * @param   pRoiConfig            Pointer to the Structure containing all the
00749  * ROI to be used.
00750  * @return  VL53L1_ERROR_NONE            Success
00751  * @return  "Other error code"           See ::VL53L1_Error
00752  */
00753 VL53L1_Error VL53L1_GetROI(VL53L1_DEV Dev,
00754         VL53L1_RoiConfig_t *pRoiConfig);
00755 
00756 /** @} VL53L1_ROI_group */
00757 
00758 /* \internal */
00759 /** @defgroup VL53L1_sequencestep_group VL53L1 Sequence Step Functions
00760  *  @brief    Functions used to select Steps done on each ranging
00761  *  @{
00762  */
00763 
00764 /**
00765  * @brief Gets number of sequence steps managed by the API.
00766  *
00767  * @par Function Description
00768  * This function retrieves the number of sequence steps currently managed
00769  * by the API
00770  *
00771  * @note This function Accesses the device
00772  *
00773  * @param   Dev                          Device Handle
00774  * @param   pNumberOfSequenceSteps       Out parameter reporting the number of
00775  *                                       sequence steps.
00776  * @return  VL53L1_ERROR_NONE            Success
00777  * @return  "Other error code"           See ::VL53L1_Error
00778  */
00779 VL53L1_Error VL53L1_GetNumberOfSequenceSteps(VL53L1_DEV Dev,
00780     uint8_t *pNumberOfSequenceSteps);
00781 
00782 /**
00783  * @brief Gets the name of a given sequence step.
00784  *
00785  * @par Function Description
00786  * This function retrieves the name of sequence steps corresponding to
00787  * SequenceStepId.
00788  *
00789  * @note This function doesn't Accesses the device
00790  *
00791  * @param   SequenceStepId               Sequence step identifier.
00792  * @param   pSequenceStepsString         Pointer to Info string. Shall be
00793  * defined as char buf[VL53L1_MAX_STRING_LENGTH]
00794  * @return  VL53L1_ERROR_NONE            Success
00795  * @return  "Other error code"           See ::VL53L1_Error
00796  */
00797 VL53L1_Error VL53L1_GetSequenceStepsInfo(
00798     VL53L1_SequenceStepId SequenceStepId, char *pSequenceStepsString);
00799 
00800 
00801 
00802 /**
00803  * @brief Sets the (on/off) state of a requested sequence step.
00804  *
00805  * @par Function Description
00806  * This function enables/disables a requested sequence step.
00807  *
00808  * @note This function Accesses the device
00809  *
00810  * @param   Dev                          Device Handle
00811  * @param   SequenceStepId           Sequence step identifier.
00812  * @param   SequenceStepEnabled          Demanded state {0=Off,1=On}
00813  *                                       is enabled.
00814  * @return  VL53L1_ERROR_NONE            Success
00815  * @return  VL53L1_ERROR_INVALID_PARAMS  Error SequenceStepId parameter not
00816  *                                       supported.
00817  * @return  "Other error code"           See ::VL53L1_Error
00818  */
00819 VL53L1_Error VL53L1_SetSequenceStepEnable(VL53L1_DEV Dev,
00820     VL53L1_SequenceStepId SequenceStepId, uint8_t SequenceStepEnabled);
00821 
00822 /**
00823  * @brief Gets the (on/off) state of a requested sequence step.
00824  *
00825  * @par Function Description
00826  * This function retrieves the state of a requested sequence step, i.e. on/off.
00827  *
00828  * @note This function Accesses the device
00829  *
00830  * @param   Dev                    Device Handle
00831  * @param   SequenceStepId         Sequence step identifier.
00832  * @param   pSequenceStepEnabled   Out parameter reporting if the sequence step
00833  *                                 is enabled {0=Off,1=On}.
00834  * @return  VL53L1_ERROR_NONE            Success
00835  * @return  VL53L1_ERROR_INVALID_PARAMS  Error SequenceStepId parameter not
00836  *                                       supported.
00837  * @return  "Other error code"           See ::VL53L1_Error
00838  */
00839 VL53L1_Error VL53L1_GetSequenceStepEnable(VL53L1_DEV Dev,
00840     VL53L1_SequenceStepId SequenceStepId, uint8_t *pSequenceStepEnabled);
00841 
00842 
00843 /** @} VL53L1_sequencestep_group */
00844 /* \endinternal */
00845 
00846 
00847 
00848 /** @defgroup VL53L1_measurement_group VL53L1 Measurement Functions
00849  *  @brief    Functions used for the measurements
00850  *  @{
00851  */
00852 
00853 /**
00854  * @brief Start device measurement
00855  *
00856  * @details Started measurement will depend on preset parameters set through
00857  * @a VL53L1_SetPreseMode()
00858  * This function will change the VL53L1_State from VL53L1_STATE_IDLE to
00859  * VL53L1_STATE_RUNNING.
00860  *
00861  * @note This function Access to the device
00862  *
00863  * @param   Dev                  Device Handle
00864  * @return  VL53L1_ERROR_NONE                  Success
00865  * @return  VL53L1_ERROR_MODE_NOT_SUPPORTED    This error occurs when
00866  * PresetMode programmed with @a VL53L1_SetPresetMode
00867  * @return  VL53L1_ERROR_TIME_OUT    Time out on start measurement
00868  * @return  VL53L1_ERROR_INVALID_PARAMS This error might occur in timed mode
00869  * when inter measurement period is smaller or too close to the timing budget.
00870  * In such case measurements are not started and user must correct the timings
00871  * passed to @a VL53L1_SetMeasurementTimingBudgetMicroSeconds() and
00872  * @a VL53L1_SetInterMeasurementPeriodMilliSeconds() functions.
00873  * @return  "Other error code"   See ::VL53L1_Error
00874  */
00875 VL53L1_Error VL53L1_StartMeasurement(VL53L1_DEV Dev);
00876 
00877 /**
00878  * @brief Stop device measurement
00879  *
00880  * @details Will set the device in standby mode at end of current measurement\n
00881  *          Not necessary in single mode as device shall return automatically
00882  *          in standby mode at end of measurement.
00883  *          This function will change the VL53L1_State from VL53L1_STATE_RUNNING
00884  *          to VL53L1_STATE_IDLE.
00885  *
00886  * @note This function Access to the device
00887  *
00888  * @param   Dev                  Device Handle
00889  * @return  VL53L1_ERROR_NONE    Success
00890  * @return  "Other error code"   See ::VL53L1_Error
00891  */
00892 VL53L1_Error VL53L1_StopMeasurement(VL53L1_DEV Dev);
00893 
00894 /**
00895  * @brief Clear the Interrupt flag and start new measurement
00896  * *
00897  * @note This function Access to the device
00898  *
00899  * @param   Dev                  Device Handle
00900  * @return  VL53L1_ERROR_NONE    Success
00901  * @return  "Other error code"   See ::VL53L1_Error
00902  */
00903 VL53L1_Error VL53L1_ClearInterruptAndStartMeasurement(VL53L1_DEV Dev);
00904 
00905 /**
00906  * @brief Return Measurement Data Ready
00907  *
00908  * @par Function Description
00909  * This function indicate that a measurement data is ready.
00910  * This function is used for non-blocking capture.
00911  *
00912  * @note This function Access to the device
00913  *
00914  * @param   Dev                    Device Handle
00915  * @param   pMeasurementDataReady  Pointer to Measurement Data Ready.
00916  * 0 = data not ready, 1 = data ready
00917  * @return  VL53L1_ERROR_NONE      Success
00918  * @return  "Other error code"     See ::VL53L1_Error
00919  */
00920 VL53L1_Error VL53L1_GetMeasurementDataReady(VL53L1_DEV Dev,
00921     uint8_t *pMeasurementDataReady);
00922 
00923 /**
00924  * @brief Wait for measurement data ready.
00925  * Blocking function.
00926  * Note that the timeout is given by:
00927  * VL53L1_RANGE_COMPLETION_POLLING_TIMEOUT_MS defined in def.h
00928  *
00929  *
00930  * @note This function Access to the device
00931  *
00932  * @param   Dev      Device Handle
00933  * @return  VL53L1_ERROR_NONE        Success
00934  * @return  VL53L1_ERROR_TIME_OUT In case of timeout
00935  */
00936 VL53L1_Error VL53L1_WaitMeasurementDataReady(VL53L1_DEV Dev);
00937 
00938 
00939 /**
00940  * @brief Retrieve the measurements from device for a given setup
00941  *
00942  * @par Function Description
00943  * Get data from last successful Ranging measurement
00944  */
00945 /**
00946  * @warning this function will return only the first ROI data and only the
00947  * first object. For multi objects or multi ROI use:
00948  * @a Vl53L1_GetMultiRangingData.
00949  * In case of RANGING only one output is given, this can
00950  * be selected with the help of @a VL53L1_SetOutputMode()
00951  * In case of MULTIZONES_SCANNING and error will be raised because not
00952  * supported in that function.
00953  */
00954 /**
00955  *
00956  * @warning USER must call @a VL53L1_ClearInterruptAndStartMeasurement() prior
00957  * to call again this function
00958  *
00959  * @note This function Access to the device
00960  *
00961  * @note The first valid value returned by this function will have a range
00962  * status equal to VL53L1_RANGESTATUS_RANGE_VALID_NO_WRAP_CHECK which means that
00963  * the data is valid but no wrap around check have been done. User should take
00964  * care about that.
00965  *
00966  * @param   Dev                      Device Handle
00967  * @param   pRangingMeasurementData  Pointer to the data structure to fill up.
00968  * @return  VL53L1_ERROR_NONE        Success
00969  * @return  VL53L1_ERROR_MODE_NOT_SUPPORTED    in case of MULTIZONES_SCANNING
00970  * @return  "Other error code"       See ::VL53L1_Error
00971  */
00972 VL53L1_Error VL53L1_GetRangingMeasurementData(VL53L1_DEV Dev,
00973     VL53L1_RangingMeasurementData_t *pRangingMeasurementData);
00974 
00975 /**
00976  * @brief Retrieve all ROI's measurements from device for a given setup
00977  *
00978  * @par Function Description
00979  * Get data from last successful Ranging measurement
00980  * @warning USER should take care about  @a VL53L1_GetNumberOfROI()
00981  * before get data.
00982  * Bare driver will fill a NumberOfROI times the corresponding data
00983  * structure used in the measurement function.
00984  *
00985  * @warning USER must call @a VL53L1_ClearInterruptAndStartMeasurement() prior
00986  * to call again this function
00987  *
00988  * @note This function Access to the device
00989  *
00990  * @note The first valid value returned by this function will have a range
00991  * status equal to VL53L1_RANGESTATUS_RANGE_VALID_NO_WRAP_CHECK which means that
00992  * the data is valid but no wrap around check have been done. User should take
00993  * care about that.
00994  *
00995  * @param   Dev                      Device Handle
00996  * @param   pMultiRangingData        Pointer to the data structure to fill up.
00997  * @return  VL53L1_ERROR_NONE        Success
00998  * @return  "Other error code"       See ::VL53L1_Error
00999  */
01000 VL53L1_Error VL53L1_GetMultiRangingData(VL53L1_DEV Dev,
01001         VL53L1_MultiRangingData_t *pMultiRangingData);
01002 
01003 /**
01004  * @brief Get Additional Data
01005  *
01006  * @par Function Description
01007  * This function is used to get lld debugging data on the last histogram
01008  * measurement. shall be called when a new measurement is ready (interrupt or
01009  * positive VL53L1_GetMeasurementDataReady() polling) and before a call to
01010  * VL53L1_ClearInterruptAndStartMeasurement(). Depending on the PresetMode
01011  * currently set parts of the returned data structure may be not relevant.
01012  *
01013  * @param   Dev                      Device Handle
01014  * @param   pAdditionalData          Pointer to Additional data
01015  * @return  VL53L1_ERROR_NONE        Success
01016  * @return  "Other error code"       See ::VL53L1_Error
01017  */
01018 VL53L1_Error VL53L1_GetAdditionalData(VL53L1_DEV Dev,
01019         VL53L1_AdditionalData_t *pAdditionalData);
01020 
01021 
01022 /** @} VL53L1_measurement_group */
01023 
01024 /** @defgroup VL53L1_Calibration_group VL53L1 Calibration Functions
01025  *  @brief    Functions used for Calibration
01026  *  @{
01027  */
01028 
01029 
01030 /**
01031  * @brief Set Tuning Parameter value for a given parameter ID
01032  *
01033  * @par Function Description
01034  * This function is used to improve the performance of the device. It permit to
01035  * change a particular value used for a timeout or a threshold or a constant
01036  * in an algorithm. The function will change the value of the parameter
01037  * identified by an unique ID.
01038  *
01039  * @note This function doesn't Access to the device
01040  *
01041  * @param   Dev                          Device Handle
01042  * @param   TuningParameterId            Tuning Parameter ID
01043  * @param   TuningParameterValue         Tuning Parameter Value
01044  * @return  VL53L1_ERROR_NONE        Success
01045  * @return  "Other error code"       See ::VL53L1_Error
01046  */
01047 VL53L1_Error VL53L1_SetTuningParameter(VL53L1_DEV Dev,
01048         uint16_t TuningParameterId, int32_t TuningParameterValue);
01049 
01050 /**
01051  * @brief Get Tuning Parameter value for a given parameter ID
01052  *
01053  * @par Function Description
01054  * This function is used to get the value of the parameter
01055  * identified by an unique ID.
01056  *
01057  * @note This function doesn't Access to the device
01058  *
01059  * @param   Dev                          Device Handle
01060  * @param   TuningParameterId            Tuning Parameter ID
01061  * @param   pTuningParameterValue        Pointer to Tuning Parameter Value
01062  * for a given TuningParameterId.
01063  * @return  VL53L1_ERROR_NONE        Success
01064  * @return  "Other error code"       See ::VL53L1_Error
01065  */
01066 VL53L1_Error VL53L1_GetTuningParameter(VL53L1_DEV Dev,
01067         uint16_t TuningParameterId, int32_t *pTuningParameterValue);
01068 
01069 /**
01070  * @brief Performs Reference Spad Management
01071  *
01072  * @par Function Description
01073  * The reference SPAD initialization procedure determines the minimum amount
01074  * of reference spads to be enables to achieve a target reference signal rate
01075  * and should be performed once during initialization.
01076  *
01077  * @note This function Access to the device
01078  *
01079  * @param   Dev                          Device Handle
01080  * @return  VL53L1_ERROR_NONE        Success
01081  * @return  "Other error code"       See ::VL53L1_Error
01082  */
01083 VL53L1_Error VL53L1_PerformRefSpadManagement(VL53L1_DEV Dev);
01084 
01085 /**
01086  * @brief Enable/Disable dynamic Xtalk compensation feature
01087  *
01088  * Enable/Disable dynamic Xtalk compensation (aka smudge correction).
01089  *
01090  * @param   Dev    Device Handle
01091  * @param   Mode   Set the smudge correction mode
01092  * See ::VL53L1_SmudgeCorrectionModes
01093  * @return  VL53L1_ERROR_NONE        Success
01094  * @return  "Other error code"       See ::VL53L1_Error
01095  */
01096 VL53L1_Error VL53L1_SmudgeCorrectionEnable(VL53L1_DEV Dev,
01097         VL53L1_SmudgeCorrectionModes Mode);
01098 
01099 /**
01100  * @brief Enable/Disable Cross talk compensation feature
01101  *
01102  * Enable/Disable Cross Talk correction.
01103  *
01104  * @param   Dev                       Device Handle
01105  * @param   XTalkCompensationEnable   Cross talk compensation
01106  *  to be set 0 = disabled or 1 = enabled.
01107  * @return  VL53L1_ERROR_NONE        Success
01108  * @return  "Other error code"       See ::VL53L1_Error
01109  */
01110 VL53L1_Error VL53L1_SetXTalkCompensationEnable(VL53L1_DEV Dev,
01111 uint8_t XTalkCompensationEnable);
01112 
01113 /**
01114  * @brief Get Cross talk compensation rate enable
01115  *
01116  * Get if the Cross Talk is Enabled or Disabled.
01117  *
01118  * @note This function doesn't access to the device
01119  *
01120  * @param   Dev                        Device Handle
01121  * @param   pXTalkCompensationEnable   Pointer to the Cross talk compensation
01122  *  state 0=disabled or 1 = enabled
01123  * @return  VL53L1_ERROR_NONE        Success
01124  * @return  "Other error code"       See ::VL53L1_Error
01125  */
01126 VL53L1_Error VL53L1_GetXTalkCompensationEnable(VL53L1_DEV Dev,
01127     uint8_t *pXTalkCompensationEnable);
01128 
01129 
01130 /**
01131  * @brief Perform XTalk Calibration
01132  *
01133  * @details Perform a XTalk calibration of the Device.
01134  * This function will launch a ranging measurement, if interrupts
01135  * are enabled an interrupt will be done.
01136  * This function will clear the interrupt generated automatically.
01137  * This function will program a new value for the XTalk compensation
01138  * and it will enable the cross talk before exit.
01139  *
01140  * @warning This function is a blocking function
01141  *
01142  * @note This function Access to the device
01143  *
01144  * @param   Dev                  Device Handle
01145  * @param   CalibrationOption    Select the Calibration to be run :
01146  * @param                        CalibrationOption
01147  * @li VL53L1_XTALKCALIBRATIONMODE_SINGLE_TARGET the calibration uses current
01148  * preset and distance mode without altering them.<br>
01149  * User must call @a VL53L1_SetPresetMode() with VL53L1_PRESETMODE_AUTONOMOUS,
01150  * VL53L1_PRESETMODE_LITE_RANGING or VL53L1_PRESETMODE_LOWPOWER_AUTONOMOUS
01151  * parameter prior to launch calibration
01152  * @li VL53L1_XTALKCALIBRATIONMODE_NO_TARGET the calibration sets appropriate
01153  * preset and distance mode and thus override existing ones<br>
01154  * User must call @a VL53L1_SetPresetMode() again after calibration to set the
01155  * desired one. during this calibration mode no object must be put below a 80cm
01156  * distance from the target
01157  * @li VL53L1_XTALKCALIBRATIONMODE_FULL_ROI the calibration sets appropriate
01158  * preset and distance mode and thus override existing ones<br>
01159  * User must call @a VL53L1_SetPresetMode() again after calibration to set the
01160  * desired one.
01161  * The ROI settings must define a single 16x16 ROI before to launch this
01162  * function.
01163  * The calibration uses a target which should be located at least @60cm from the
01164  * device. The actual location of the target shall be passed
01165  * through the bare driver tuning parameters table
01166  *
01167  * @return  VL53L1_ERROR_NONE    Success
01168  * @return  "Other error code"   See ::VL53L1_Error
01169  */
01170 VL53L1_Error VL53L1_PerformXTalkCalibration(VL53L1_DEV Dev,
01171         uint8_t CalibrationOption);
01172 
01173 /**
01174  * @brief Define the mode to be used for the offset calibration
01175  *
01176  * Define the mode to be used for the offset calibration. This function should
01177  * be called before run the @a VL53L1_PerformOffsetCalibration()
01178  *
01179  * @param   Dev                       Device Handle
01180  * @param   OffsetCalibrationMode     Offset Calibration Mode valid values are:
01181  * @li                                VL53L1_OFFSETCALIBRATIONMODE_STANDARD
01182  * @li                                VL53L1_OFFSETCALIBRATIONMODE_PRERANGE_ONLY
01183  * @li                                VL53L1_OFFSETCALIBRATIONMODE_MULTI_ZONE
01184  *
01185  * @return  VL53L1_ERROR_NONE         Success
01186  * @return  "Other error code"        See ::VL53L1_Error
01187  */
01188 VL53L1_Error VL53L1_SetOffsetCalibrationMode(VL53L1_DEV Dev,
01189         VL53L1_OffsetCalibrationModes OffsetCalibrationMode);
01190 
01191 /**
01192  * @brief Define the mode to be used for the offset correction
01193  *
01194  * Define the mode to be used for the offset correction.
01195  *
01196  * @param   Dev                       Device Handle
01197  * @param   OffsetCorrectionMode      Offset Correction Mode valid values are:
01198  * @li                                VL53L1_OFFSETCORRECTIONMODE_STANDARD
01199  * @li                                VL53L1_OFFSETCORRECTIONMODE_PERZONE
01200  * @li                                VL53L1_OFFSETCORRECTIONMODE_PERVCSEL
01201  *
01202  * @return  VL53L1_ERROR_NONE         Success
01203  * @return  "Other error code"        See ::VL53L1_Error
01204  */
01205 VL53L1_Error VL53L1_SetOffsetCorrectionMode(VL53L1_DEV Dev,
01206         VL53L1_OffsetCorrectionModes OffsetCorrectionMode);
01207 
01208 
01209 /**
01210  * @brief Perform Offset Calibration
01211  *
01212  * @details Perform a Offset calibration of the Device.
01213  * This function will launch a ranging measurement, if interrupts are
01214  * enabled interrupts will be done.
01215  * This function will program a new value for the Offset calibration value
01216  *
01217  * @warning This function is a blocking function
01218  *
01219  * @note This function Access to the device
01220  *
01221  * @param   Dev                  Device Handle
01222  * @param   CalDistanceMilliMeter     Calibration distance value used for the
01223  * offset compensation.
01224  * @param   CalReflectancePercent     Calibration Target reflectance @ 940nm
01225  * in percentage.
01226  *
01227  * @return  VL53L1_ERROR_NONE
01228  * @return  "Other error code"   See ::VL53L1_Error
01229  */
01230 VL53L1_Error VL53L1_PerformOffsetCalibration(VL53L1_DEV Dev,
01231     int32_t CalDistanceMilliMeter,
01232     FixPoint1616_t CalReflectancePercent);
01233 
01234 /**
01235  * @brief Perform Offset simple Calibration
01236  *
01237  * @details Perform a very simple offset calibration of the Device.
01238  * This function will launch few ranging measurements and computes offset
01239  * calibration. The preset mode and the distance mode MUST be set by the
01240  * application before to call this function.
01241  *
01242  * @warning This function is a blocking function
01243  *
01244  * @note This function Access to the device
01245  *
01246  * @param   Dev                  Device Handle
01247  * @param   CalDistanceMilliMeter     Calibration distance value used for the
01248  * offset compensation.
01249  *
01250  * @return  VL53L1_ERROR_NONE
01251  * @return  VL53L1_ERROR_OFFSET_CAL_NO_SAMPLE_FAIL the calibration failed by
01252  * lack of valid measurements
01253  * @return  VL53L1_WARNING_OFFSET_CAL_SIGMA_TOO_HIGH means that the target
01254  * distance combined to the number of loops performed in the calibration lead to
01255  * an internal overflow. Try to reduce the distance of the target (140 mm)
01256  * @return  "Other error code"   See ::VL53L1_Error
01257  */
01258 VL53L1_Error VL53L1_PerformOffsetSimpleCalibration(VL53L1_DEV Dev,
01259         int32_t CalDistanceMilliMeter);
01260 
01261 /**
01262  * @brief Perform Offset simple Calibration with a "zero distance" target
01263  *
01264  * @details Perform a simple offset calibration of the Device.
01265  * This function will launch few ranging measurements and computes offset
01266  * calibration. The preset mode and the distance mode MUST be set by the
01267  * application before to call this function.
01268  * A target must be place very close to the device.
01269  * Ideally the target shall be touching the coverglass.
01270  *
01271  * @warning This function is a blocking function
01272  *
01273  * @note This function Access to the device
01274  *
01275  * @param   Dev                  Device Handle
01276  *
01277  * @return  VL53L1_ERROR_NONE
01278  * @return  VL53L1_ERROR_OFFSET_CAL_NO_SAMPLE_FAIL the calibration failed by
01279  * lack of valid measurements
01280  * @return  VL53L1_WARNING_OFFSET_CAL_SIGMA_TOO_HIGH means that the target
01281  * distance is too large, try to put the target closer to the device
01282  * @return  "Other error code"   See ::VL53L1_Error
01283  */
01284 VL53L1_Error VL53L1_PerformOffsetZeroDistanceCalibration(VL53L1_DEV Dev);
01285 
01286 /**
01287  * @brief Perform Offset per Vcsel Calibration. i.e. per distance mode
01288  *
01289  * @details Perform offset calibration of the Device depending on the
01290  * three distance mode settings: short, medium and long.
01291  * This function will launch few ranging measurements and computes offset
01292  * calibration in each of the three distance modes.
01293  * The preset mode MUST be set by the application before to call this function.
01294  *
01295  * @warning This function is a blocking function
01296  *
01297  * @note This function Access to the device
01298  *
01299  * @param   Dev                  Device Handle
01300  * @param   CalDistanceMilliMeter     Distance of the target used for the
01301  * offset compensation calibration.
01302  *
01303  * @return  VL53L1_ERROR_NONE
01304  * @return  VL53L1_ERROR_OFFSET_CAL_NO_SAMPLE_FAIL the calibration failed by
01305  * lack of valid measurements
01306  * @return  VL53L1_WARNING_OFFSET_CAL_SIGMA_TOO_HIGH means that the target
01307  * distance combined to the number of loops performed in the calibration lead to
01308  * an internal overflow. Try to reduce the distance of the target (140 mm)
01309  * @return  "Other error code"   See ::VL53L1_Error
01310  */
01311 VL53L1_Error VL53L1_PerformOffsetPerVcselCalibration(VL53L1_DEV Dev,
01312     int32_t CalDistanceMilliMeter);
01313 /**
01314  * @brief Sets the Calibration Data.
01315  *
01316  * @par Function Description
01317  * This function set all the Calibration Data issued from the functions
01318  * @a VL53L1_PerformRefSpadManagement(), @a VL53L1_PerformXTalkCalibration,
01319  * @a VL53L1_PerformOffsetCalibration()
01320  *
01321  * @note This function doesn't Accesses the device
01322  *
01323  * @param   Dev                          Device Handle
01324  * @param   *pCalibrationData            Pointer to Calibration data to be set.
01325  * @return  VL53L1_ERROR_NONE            Success
01326  * @return  VL53L1_ERROR_INVALID_PARAMS  pCalibrationData points to an older
01327  * version of the inner structure. Need for support to convert its content.
01328  * @return  "Other error code"           See ::VL53L1_Error
01329  */
01330 VL53L1_Error VL53L1_SetCalibrationData(VL53L1_DEV Dev,
01331         VL53L1_CalibrationData_t *pCalibrationData);
01332 
01333 /**
01334  * @brief Gets the Calibration Data.
01335  *
01336  * @par Function Description
01337  * This function get all the Calibration Data issued from the functions
01338  * @a VL53L1_PerformRefSpadManagement(), @a VL53L1_PerformXTalkCalibration,
01339  * @a VL53L1_PerformOffsetCalibration()
01340  *
01341  * @note This function doesn't Accesses the device
01342  *
01343  * @param   Dev                          Device Handle
01344  * @param   *pCalibrationData            pointer where to store Calibration
01345  *  data.
01346  * @return  VL53L1_ERROR_NONE            Success
01347  * @return  "Other error code"           See ::VL53L1_Error
01348  */
01349 VL53L1_Error VL53L1_GetCalibrationData(VL53L1_DEV Dev,
01350         VL53L1_CalibrationData_t  *pCalibrationData);
01351 
01352 /**
01353  * @brief Sets the Zone Calibration Data.
01354  *
01355  * @par Function Description
01356  * This function set all the Zone nCalibration Data issued from the functions
01357  * @a VL53L1_PerformOffsetCalibration() in multi zone
01358  *
01359  * @note This function doesn't Accesses the device
01360  *
01361  * @param   Dev                          Device Handle
01362  * @param   *pZoneCalibrationData        Pointer to Zone Calibration data to be
01363  *  set.
01364  * @return  VL53L1_ERROR_NONE            Success
01365  * @return  "Other error code"           See ::VL53L1_Error
01366  */
01367 VL53L1_Error VL53L1_SetZoneCalibrationData(VL53L1_DEV Dev,
01368         VL53L1_ZoneCalibrationData_t *pZoneCalibrationData);
01369 
01370 /**
01371  * @brief Gets the Zone Calibration Data.
01372  *
01373  * @par Function Description
01374  * This function get all the Zone Calibration Data issued from the functions
01375  * @a VL53L1_PerformOffsetCalibration()
01376  *
01377  * @note This function doesn't Accesses the device
01378  *
01379  * @param   Dev                          Device Handle
01380  * @param   *pZoneCalibrationData        pointer where to store Zone Calibration
01381  *  data.
01382  * @return  VL53L1_ERROR_NONE            Success
01383  * @return  "Other error code"           See ::VL53L1_Error
01384  */
01385 VL53L1_Error VL53L1_GetZoneCalibrationData(VL53L1_DEV Dev,
01386         VL53L1_ZoneCalibrationData_t *pZoneCalibrationData);
01387 /**
01388  * @brief Gets the optical center.
01389  *
01390  * @par Function Description
01391  * This function get the optical center issued from the nvm set at FTM stage
01392  * expressed in the same coordinate system as the ROI are
01393  *
01394  * @note This function doesn't Accesses the device
01395  *
01396  * @param   Dev                          Device Handle
01397  * @param   pOpticalCenterX              pointer to the X position of center
01398  * in 16.16 fix point
01399  * @param   pOpticalCenterY              pointer to the Y position of center
01400  * in 16.16 fix point
01401  * @return  VL53L1_ERROR_NONE            Success
01402  * @return  "Other error code"           See ::VL53L1_Error
01403  */
01404 VL53L1_Error VL53L1_GetOpticalCenter(VL53L1_DEV Dev,
01405         FixPoint1616_t *pOpticalCenterX,
01406         FixPoint1616_t *pOpticalCenterY);
01407 
01408 /** @} VL53L1_Calibration_group */
01409 
01410 /** @defgroup VL53L1_Thresholds_group VL53L1 IRQ Triggered events Functions
01411  *  @brief    Functions used to configure interrupt to be triggered only when
01412  *  a measurement satisfies some thresholds parameters
01413  *  @{
01414  */
01415 
01416 /**
01417  * @brief Configure the interrupt config, from the given structure
01418  *
01419  * @param[in]    Dev     : Device Handle
01420  * @param[in]    pConfig : pointer to configuration structure
01421  */
01422 
01423 VL53L1_Error VL53L1_SetThresholdConfig(VL53L1_DEV Dev,
01424         VL53L1_DetectionConfig_t *pConfig);
01425 
01426 /**
01427  * @brief Retrieves the interrupt config structure currently programmed
01428  *                             into the API
01429  *
01430  * @param[in]    Dev     : Device Handle
01431  * @param[out]   pConfig : pointer to configuration structure
01432  */
01433 
01434 VL53L1_Error VL53L1_GetThresholdConfig(VL53L1_DEV Dev,
01435         VL53L1_DetectionConfig_t *pConfig);
01436 
01437 
01438 /** @} VL53L1_Thresholds_group */
01439 
01440 
01441 /** @} VL53L1_cut11_group */
01442 
01443 #ifdef __cplusplus
01444 }
01445 #endif
01446 
01447 #endif /* _VL53L1_API_H_ */