vl53l1_api.h

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