vl53lx_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 VL53LX 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 _VL53LX_API_H_
00013 #define _VL53LX_API_H_
00014 
00015 #include "vl53lx_api_core.h"
00016 #include "vl53lx_preset_setup.h"
00017 
00018 #ifdef __cplusplus
00019 extern "C"
00020 {
00021 #endif
00022 
00023 /** @defgroup VL53LX_group VL53LX Function Definition
00024  *  @brief    VL53LX Function Definition
00025  *  @{
00026  */
00027 
00028 /** @defgroup VL53LX_general_group VL53LX General Functions
00029  *  @brief    General functions and definitions
00030  *  @{
00031  */
00032 
00033 /**
00034  * @brief Return the VL53LX driver Version
00035  *
00036  * @note This function doesn't access to the device
00037  *
00038  * @param   pVersion              Rer to current driver Version
00039  * @return  VL53LX_ERROR_NONE     Success
00040  * @return  "Other error code"    See ::VL53LX_Error
00041  */
00042 VL53LX_Error VL53LX_GetVersion(VL53LX_Version_t *pVersion);
00043 
00044 /**
00045  * @brief Reads the Product Revision for a for given Device
00046  * This function can be used to distinguish cut1.0 from cut1.1.
00047  *
00048  * @param   Dev                 Device Handle
00049  * @param   pProductRevisionMajor  Pointer to Product Revision Major
00050  * for a given Device
00051  * @param   pProductRevisionMinor  Pointer to Product Revision Minor
00052  * for a given Device
00053  * @return  VL53LX_ERROR_NONE        Success
00054  * @return  "Other error code"    See ::VL53LX_Error
00055  */
00056 VL53LX_Error VL53LX_GetProductRevision(VL53LX_DEV Dev,
00057     uint8_t *pProductRevisionMajor, uint8_t *pProductRevisionMinor);
00058 
00059 /**
00060  * @brief Reads the Device information for given Device
00061  *
00062  * @note This function Access to the device
00063  *
00064  * @param   Dev                 Device Handle
00065  * @param   pVL53LX_DeviceInfo  Pointer to current device info for a given
00066  *  Device
00067  * @return  VL53LX_ERROR_NONE   Success
00068  * @return  "Other error code"  See ::VL53LX_Error
00069  */
00070 VL53LX_Error VL53LX_GetDeviceInfo(VL53LX_DEV Dev,
00071     VL53LX_DeviceInfo_t *pVL53LX_DeviceInfo);
00072 
00073 /**
00074  * @brief Reads the Device unique identifier
00075  *
00076  * @note This function Access to the device
00077  *
00078  * @param   Dev                 Device Handle
00079  * @param   pUid                Pointer to current device unique ID
00080  * @return  VL53LX_ERROR_NONE   Success
00081  * @return  "Other error code"  See ::VL53LX_Error
00082  */
00083 VL53LX_Error VL53LX_GetUID(VL53LX_DEV Dev, uint64_t *pUid);
00084 
00085 
00086 /** @} VL53LX_general_group */
00087 
00088 /** @defgroup VL53LX_init_group VL53LX Init Functions
00089  *  @brief    VL53LX Init Functions
00090  *  @{
00091  */
00092 
00093 /**
00094  * @brief Set new device address
00095  *
00096  * After completion the device will answer to the new address programmed.
00097  * This function should be called when several devices are used in parallel
00098  * before start programming the sensor.
00099  * When a single device us used, there is no need to call this function.
00100  *
00101  * When it is requested for multi devices system this function MUST be called
00102  * prior to VL53LX_DataInit()
00103  *
00104  * @note This function Access to the device
00105  *
00106  * @param   Dev                   Device Handle
00107  * @param   DeviceAddress         The new Device address
00108  * @return  VL53LX_ERROR_NONE     Success
00109  * @return  "Other error code"    See ::VL53LX_Error
00110  */
00111 VL53LX_Error VL53LX_SetDeviceAddress(VL53LX_DEV Dev,
00112     uint8_t DeviceAddress);
00113 
00114 /**
00115  *
00116  * @brief One time device initialization
00117  *
00118  * To be called after device has been powered on and booted
00119  * see @a VL53LX_WaitDeviceBooted()
00120  *
00121  * @par Function Description
00122  * When not used after a fresh device "power up", it may return
00123  * @a #VL53LX_ERROR_CALIBRATION_WARNING meaning wrong calibration data
00124  * may have been fetched from device that can result in ranging offset error\n
00125  * If VL53LX_DataInit is called several times then the application must restore
00126  * calibration calling @a VL53LX_SetOffsetCalibrationData()
00127  * It implies application has gathered calibration data thanks to
00128  * @a VL53LX_GetOffsetCalibrationData() after an initial calibration stage.
00129  *
00130  * @note This function Access to the device
00131  *
00132  * @param   Dev                   Device Handle
00133  * @return  VL53LX_ERROR_NONE     Success
00134  * @return  "Other error code"    See ::VL53LX_Error
00135  */
00136 VL53LX_Error VL53LX_DataInit(VL53LX_DEV Dev);
00137 
00138 /**
00139  * @brief Wait for device booted after chip enable (hardware standby)
00140  *
00141  * @param   Dev                   Device Handle
00142  * @return  VL53LX_ERROR_NONE     Success
00143  * @return  "Other error code"    See ::VL53LX_Error
00144  *
00145  */
00146 VL53LX_Error VL53LX_WaitDeviceBooted(VL53LX_DEV Dev);
00147 
00148 
00149 /** @} VL53LX_init_group */
00150 
00151 /** @defgroup VL53LX_parameters_group VL53LX Parameters Functions
00152  *  @brief    Functions used to prepare and setup the device
00153  *  @{
00154  */
00155 
00156 /**
00157  * @brief  Set the distance mode
00158  * @par Function Description
00159  * Set the distance mode to be used for the next ranging.<br>
00160  * The modes Short, Medium and Long are used to optimize the ranging accuracy
00161  * in a specific range of distance.<br> The user select one of these modes to
00162  * select the distance range.
00163  * @note This function doesn't Access to the device
00164  *
00165  * @warning This function should be called after @a VL53LX_DataInit().
00166 
00167  * @param   Dev                   Device Handle
00168  * @param   DistanceMode          Distance mode to apply, valid values are:
00169  * @li VL53LX_DISTANCEMODE_SHORT
00170  * @li VL53LX_DISTANCEMODE_MEDIUM
00171  * @li VL53LX_DISTANCEMODE_LONG
00172  * @return  VL53LX_ERROR_NONE               Success
00173  * @return  VL53LX_ERROR_MODE_NOT_SUPPORTED This error occurs when DistanceMode
00174  *                                          is not in the supported list
00175  * @return  "Other error code"              See ::VL53LX_Error
00176  */
00177 VL53LX_Error VL53LX_SetDistanceMode(VL53LX_DEV Dev,
00178         VL53LX_DistanceModes DistanceMode);
00179 
00180 /**
00181  * @brief  Get the distance mode
00182  * @par Function Description
00183  * Get the distance mode used for the next ranging.
00184  *
00185  * @param   Dev                   Device Handle
00186  * @param   *pDistanceMode        Pointer to Distance mode
00187  * @return  VL53LX_ERROR_NONE            Success
00188  * @return  "Other error code"           See ::VL53LX_Error
00189  */
00190 VL53LX_Error VL53LX_GetDistanceMode(VL53LX_DEV Dev,
00191         VL53LX_DistanceModes *pDistanceMode);
00192 
00193 
00194 /**
00195  * @brief Set Ranging Timing Budget in microseconds
00196  *
00197  * @par Function Description
00198  * Defines the maximum time allowed by the user to the device to run a
00199  * full ranging sequence for the current mode (ranging, histogram, ASL ...)
00200  *
00201  * @param   Dev                                Device Handle
00202  * @param MeasurementTimingBudgetMicroSeconds  Max measurement time in
00203  * microseconds.
00204  * @return  VL53LX_ERROR_NONE            Success
00205  * @return  VL53LX_ERROR_INVALID_PARAMS  Error timing parameter not
00206  *                                       supported.
00207  *                                       The maximum accepted value for the
00208  *                                       computed timing budget is 10 seconds
00209  *                                       the minimum value depends on the preset
00210  *                                       mode selected.
00211  * @return  "Other error code"           See ::VL53LX_Error
00212  */
00213 VL53LX_Error VL53LX_SetMeasurementTimingBudgetMicroSeconds(
00214     VL53LX_DEV Dev, uint32_t MeasurementTimingBudgetMicroSeconds);
00215 
00216 /**
00217  * @brief Get Ranging Timing Budget in microseconds
00218  *
00219  * @par Function Description
00220  * Returns the programmed the maximum time allowed by the user to the
00221  * device to run a full ranging sequence for the current mode
00222  * (ranging, histogram, ...)
00223  *
00224  * @param   Dev                                    Device Handle
00225  * @param   pMeasurementTimingBudgetMicroSeconds   Max measurement time in
00226  * microseconds.
00227  * @return  VL53LX_ERROR_NONE            Success
00228  * @return  "Other error code"           See ::VL53LX_Error
00229  */
00230 VL53LX_Error VL53LX_GetMeasurementTimingBudgetMicroSeconds(
00231     VL53LX_DEV Dev, uint32_t *pMeasurementTimingBudgetMicroSeconds);
00232 /** @} VL53LX_parameters_group */
00233 
00234 
00235 /** @defgroup VL53LX_ROI_group VL53LX ROI Functions
00236  *  @brief    Functions used to select ROIs
00237  *  @{
00238  */
00239 
00240 /**
00241  * @brief Set the ROI  to be used for ranging
00242  *
00243  * @par Function Description
00244  * The user defined ROI is a rectangle described as per the following system
00245  * from the Top Left corner to the Bottom Right corner.
00246  * <br>Minimal ROI size is 4x4 spads
00247  * @image html roi_coord.png
00248  *
00249  * @param   Dev                      Device Handle
00250  * @param   pUserROi                 Pointer to the Structure definining the ROI
00251  * @return  VL53LX_ERROR_NONE            Success
00252  * @return  "Other error code"           See ::VL53LX_Error
00253  */
00254 VL53LX_Error VL53LX_SetUserROI(VL53LX_DEV Dev,
00255         VL53LX_UserRoi_t *pUserROi);
00256 
00257 /**
00258  * @brief Get the ROI managed by the Device
00259  *
00260  * @par Function Description
00261  * Get the ROI managed by the Device
00262  *
00263  * @param   Dev                   Device Handle
00264  * @param   pUserROi                 Pointer to the Structure definining the ROI
00265  * @return  VL53LX_ERROR_NONE            Success
00266  * @return  "Other error code"           See ::VL53LX_Error
00267  */
00268 VL53LX_Error VL53LX_GetUserROI(VL53LX_DEV Dev,
00269         VL53LX_UserRoi_t *pUserROi);
00270 
00271 /** @} VL53LX_ROI_group */
00272 
00273 
00274 /** @defgroup VL53LX_measurement_group VL53LX Measurement Functions
00275  *  @brief    Functions used for the measurements
00276  *  @{
00277  */
00278 
00279 /**
00280  * @brief Start device measurement
00281  *
00282  * @details Started measurement will depend on distance parameter set through
00283  * @a VL53LX_SetDistanceMode()
00284  *
00285  * @note This function Access to the device
00286  *
00287  * @param   Dev                  Device Handle
00288  * @return  VL53LX_ERROR_NONE                  Success
00289  * @return  VL53LX_ERROR_TIME_OUT    Time out on start measurement
00290  * @return  VL53LX_ERROR_INVALID_PARAMS This error might occur in timed mode
00291  * when inter measurement period is smaller or too close to the timing budget.
00292  * In such case measurements are not started and user must correct the timings
00293  * passed to @a VL53LX_SetMeasurementTimingBudgetMicroSeconds() and
00294  * @a VL53LX_SetInterMeasurementPeriodMilliSeconds() functions.
00295  * @return  "Other error code"   See ::VL53LX_Error
00296  */
00297 VL53LX_Error VL53LX_StartMeasurement(VL53LX_DEV Dev);
00298 
00299 /**
00300  * @brief Stop device measurement
00301  *
00302  * @details Will set the device in standby mode at end of current measurement\n
00303  *          Not necessary in single mode as device shall return automatically
00304  *          in standby mode at end of measurement.
00305  *
00306  * @note This function Access to the device
00307  *
00308  * @param   Dev                  Device Handle
00309  * @return  VL53LX_ERROR_NONE    Success
00310  * @return  "Other error code"   See ::VL53LX_Error
00311  */
00312 VL53LX_Error VL53LX_StopMeasurement(VL53LX_DEV Dev);
00313 
00314 /**
00315  * @brief Clear the Interrupt flag and start new measurement
00316  * *
00317  * @note This function Access to the device
00318  *
00319  * @param   Dev                  Device Handle
00320  * @return  VL53LX_ERROR_NONE    Success
00321  * @return  "Other error code"   See ::VL53LX_Error
00322  */
00323 VL53LX_Error VL53LX_ClearInterruptAndStartMeasurement(VL53LX_DEV Dev);
00324 
00325 /**
00326  * @brief Return Measurement Data Ready
00327  *
00328  * @par Function Description
00329  * This function indicate that a measurement data is ready.
00330  * This function is used for non-blocking capture.
00331  *
00332  * @note This function Access to the device
00333  *
00334  * @param   Dev                    Device Handle
00335  * @param   pMeasurementDataReady  Pointer to Measurement Data Ready.
00336  * 0 = data not ready, 1 = data ready
00337  * @return  VL53LX_ERROR_NONE      Success
00338  * @return  "Other error code"     See ::VL53LX_Error
00339  */
00340 VL53LX_Error VL53LX_GetMeasurementDataReady(VL53LX_DEV Dev,
00341     uint8_t *pMeasurementDataReady);
00342 
00343 /**
00344  * @brief Wait for measurement data ready.
00345  * Blocking function.
00346  * Note that the timeout is given by:
00347  * VL53LX_RANGE_COMPLETION_POLLING_TIMEOUT_MS defined in def.h
00348  *
00349  *
00350  * @note This function Access to the device
00351  *
00352  * @param   Dev      Device Handle
00353  * @return  VL53LX_ERROR_NONE        Success
00354  * @return  VL53LX_ERROR_TIME_OUT In case of timeout
00355  */
00356 VL53LX_Error VL53LX_WaitMeasurementDataReady(VL53LX_DEV Dev);
00357 
00358 
00359 /**
00360  * @brief Retrieve all measurements from device with the current setup
00361  *
00362  * @par Function Description
00363  * Get data from last successful Ranging measurement
00364  *
00365  * @warning USER must call @a VL53LX_ClearInterruptAndStartMeasurement() prior
00366  * to call again this function
00367  *
00368  * @note This function Access to the device
00369  *
00370  * @note The first valid value returned by this function will have a range
00371  * status equal to VL53LX_RANGESTATUS_RANGE_VALID_NO_WRAP_CHECK which means that
00372  * the data is valid but no wrap around check have been done. User should take
00373  * care about that.
00374  *
00375  * @param   Dev                      Device Handle
00376  * @param   pMultiRangingData        Pointer to the data structure to fill up.
00377  * @return  VL53LX_ERROR_NONE        Success
00378  * @return  "Other error code"       See ::VL53LX_Error
00379  */
00380 VL53LX_Error VL53LX_GetMultiRangingData(VL53LX_DEV Dev,
00381         VL53LX_MultiRangingData_t *pMultiRangingData);
00382 
00383 /**
00384  * @brief Get Additional Data
00385  *
00386  * @par Function Description
00387  * This function is used to get lld debugging data on the last histogram
00388  * measurement. shall be called when a new measurement is ready (interrupt or
00389  * positive VL53LX_GetMeasurementDataReady() polling) and before a call to
00390  * VL53LX_ClearInterruptAndStartMeasurement().
00391  *
00392  * @param   Dev                      Device Handle
00393  * @param   pAdditionalData          Pointer to Additional data
00394  * @return  VL53LX_ERROR_NONE        Success
00395  * @return  "Other error code"       See ::VL53LX_Error
00396  */
00397 VL53LX_Error VL53LX_GetAdditionalData(VL53LX_DEV Dev,
00398         VL53LX_AdditionalData_t *pAdditionalData);
00399 
00400 
00401 /** @} VL53LX_measurement_group */
00402 
00403 /** @defgroup VL53LX_Calibration_group VL53LX Calibration Functions
00404  *  @brief    Functions used for Calibration
00405  *  @{
00406  */
00407 
00408 
00409 /**
00410  * @brief Set Tuning Parameter value for a given parameter ID
00411  *
00412  * @par Function Description
00413  * This function is used to improve the performance of the device. It permit to
00414  * change a particular value used for a timeout or a threshold or a constant
00415  * in an algorithm. The function will change the value of the parameter
00416  * identified by an unique ID.
00417  *
00418  * @note This function doesn't Access to the device
00419  *
00420  * @param   Dev                          Device Handle
00421  * @param   TuningParameterId            Tuning Parameter ID
00422  * @param   TuningParameterValue         Tuning Parameter Value
00423  * @return  VL53LX_ERROR_NONE        Success
00424  * @return  "Other error code"       See ::VL53LX_Error
00425  */
00426 VL53LX_Error VL53LX_SetTuningParameter(VL53LX_DEV Dev,
00427         uint16_t TuningParameterId, int32_t TuningParameterValue);
00428 
00429 /**
00430  * @brief Get Tuning Parameter value for a given parameter ID
00431  *
00432  * @par Function Description
00433  * This function is used to get the value of the parameter
00434  * identified by an unique ID.
00435  *
00436  * @note This function doesn't Access to the device
00437  *
00438  * @param   Dev                          Device Handle
00439  * @param   TuningParameterId            Tuning Parameter ID
00440  * @param   pTuningParameterValue        Pointer to Tuning Parameter Value
00441  * for a given TuningParameterId.
00442  * @return  VL53LX_ERROR_NONE        Success
00443  * @return  "Other error code"       See ::VL53LX_Error
00444  */
00445 VL53LX_Error VL53LX_GetTuningParameter(VL53LX_DEV Dev,
00446         uint16_t TuningParameterId, int32_t *pTuningParameterValue);
00447 
00448 /**
00449  * @brief Performs Reference Spad Management
00450  *
00451  * @par Function Description
00452  * The reference SPAD initialization procedure determines the minimum amount
00453  * of reference spads to be enables to achieve a target reference signal rate
00454  * and should be performed once during initialization.
00455  *
00456  * @note This function Access to the device
00457  *
00458  * @param   Dev                          Device Handle
00459  * @return  VL53LX_ERROR_NONE        Success
00460  * @return  "Other error code"       See ::VL53LX_Error
00461  */
00462 VL53LX_Error VL53LX_PerformRefSpadManagement(VL53LX_DEV Dev);
00463 
00464 /**
00465  * @brief Enable/Disable dynamic Xtalk compensation feature
00466  *
00467  * Enable/Disable dynamic Xtalk compensation (aka smudge correction).
00468  *
00469  * @param   Dev    Device Handle
00470  * @param   Mode   Set the smudge correction mode
00471  * See ::VL53LX_SmudgeCorrectionModes
00472  * @return  VL53LX_ERROR_NONE        Success
00473  * @return  "Other error code"       See ::VL53LX_Error
00474  */
00475 VL53LX_Error VL53LX_SmudgeCorrectionEnable(VL53LX_DEV Dev,
00476         VL53LX_SmudgeCorrectionModes Mode);
00477 
00478 
00479 /**
00480  * @brief Enable/Disable Cross talk compensation feature
00481  *
00482  * Enable/Disable Cross Talk correction.
00483  *
00484  * @param   Dev                       Device Handle
00485  * @param   XTalkCompensationEnable   Cross talk compensation
00486  *  to be set 0 = disabled or 1 = enabled.
00487  * @return  VL53LX_ERROR_NONE        Success
00488  * @return  "Other error code"       See ::VL53LX_Error
00489  */
00490 VL53LX_Error VL53LX_SetXTalkCompensationEnable(VL53LX_DEV Dev,
00491 uint8_t XTalkCompensationEnable);
00492 
00493 /**
00494  * @brief Get Cross talk compensation rate enable
00495  *
00496  * Get if the Cross Talk is Enabled or Disabled.
00497  *
00498  * @note This function doesn't access to the device
00499  *
00500  * @param   Dev                        Device Handle
00501  * @param   pXTalkCompensationEnable   Pointer to the Cross talk compensation
00502  *  state 0=disabled or 1 = enabled
00503  * @return  VL53LX_ERROR_NONE        Success
00504  * @return  "Other error code"       See ::VL53LX_Error
00505  */
00506 VL53LX_Error VL53LX_GetXTalkCompensationEnable(VL53LX_DEV Dev,
00507     uint8_t *pXTalkCompensationEnable);
00508 
00509 /**
00510  * @brief Perform XTalk Calibration
00511  *
00512  * @details Perform a XTalk calibration of the Device.
00513  * This function will launch a  measurement, if interrupts
00514  * are enabled an interrupt will be done.
00515  * This function will clear the interrupt generated automatically.
00516  * This function will program a new value for the XTalk compensation
00517  * and it will enable the cross talk before exit.
00518  *
00519  * @warning This function is a blocking function
00520  *
00521  * @note This function Access to the device
00522  *
00523  * @param   Dev                  Device Handle
00524  * the calibration sets appropriate
00525  * distance mode and thus override existing one<br>
00526  * The calibration uses a target which should be located at least @60cm from the
00527  * device. The actual location of the target shall be passed
00528  * through the bare driver tuning parameters table
00529  *
00530  * @return  VL53LX_ERROR_NONE    Success
00531  * @return  "Other error code"   See ::VL53LX_Error
00532  */
00533 VL53LX_Error VL53LX_PerformXTalkCalibration(VL53LX_DEV Dev);
00534 
00535 
00536 /**
00537  * @brief Define the mode to be used for the offset correction
00538  *
00539  * Define the mode to be used for the offset correction.
00540  *
00541  * @param   Dev                       Device Handle
00542  * @param   OffsetCorrectionMode      Offset Correction Mode valid values are:
00543  * @li                                VL53LX_OFFSETCORRECTIONMODE_STANDARD
00544  * @li                                VL53LX_OFFSETCORRECTIONMODE_PERVCSEL
00545  *
00546  * @return  VL53LX_ERROR_NONE         Success
00547  * @return  "Other error code"        See ::VL53LX_Error
00548  */
00549 VL53LX_Error VL53LX_SetOffsetCorrectionMode(VL53LX_DEV Dev,
00550         VL53LX_OffsetCorrectionModes OffsetCorrectionMode);
00551 
00552 
00553 /**
00554  * @brief Perform Offset simple Calibration
00555  *
00556  * @details Perform a very simple offset calibration of the Device.
00557  * This function will launch few ranging measurements and computes offset
00558  * calibration. The preset mode and the distance mode MUST be set by the
00559  * application before to call this function.
00560  *
00561  * @warning This function is a blocking function
00562  *
00563  * @note This function Access to the device
00564  *
00565  * @param   Dev                  Device Handle
00566  * @param   CalDistanceMilliMeter     Calibration distance value used for the
00567  * offset compensation.
00568  *
00569  * @return  VL53LX_ERROR_NONE
00570  * @return  VL53LX_ERROR_OFFSET_CAL_NO_SAMPLE_FAIL the calibration failed by
00571  * lack of valid measurements
00572  * @return  VL53LX_WARNING_OFFSET_CAL_SIGMA_TOO_HIGH means that the target
00573  * distance combined to the number of loops performed in the calibration lead to
00574  * an internal overflow. Try to reduce the distance of the target (140 mm)
00575  * @return  "Other error code"   See ::VL53LX_Error
00576  */
00577 VL53LX_Error VL53LX_PerformOffsetSimpleCalibration(VL53LX_DEV Dev,
00578         int32_t CalDistanceMilliMeter);
00579 
00580 /**
00581  * @brief Perform Offset simple Calibration with a "zero distance" target
00582  *
00583  * @details Perform a simple offset calibration of the Device.
00584  * This function will launch few ranging measurements and computes offset
00585  * calibration. The preset mode and the distance mode MUST be set by the
00586  * application before to call this function.
00587  * A target must be place very close to the device.
00588  * Ideally the target shall be touching the coverglass.
00589  *
00590  * @warning This function is a blocking function
00591  *
00592  * @note This function Access to the device
00593  *
00594  * @param   Dev                  Device Handle
00595  *
00596  * @return  VL53LX_ERROR_NONE
00597  * @return  VL53LX_ERROR_OFFSET_CAL_NO_SAMPLE_FAIL the calibration failed by
00598  * lack of valid measurements
00599  * @return  VL53LX_WARNING_OFFSET_CAL_SIGMA_TOO_HIGH means that the target
00600  * distance is too large, try to put the target closer to the device
00601  * @return  "Other error code"   See ::VL53LX_Error
00602  */
00603 VL53LX_Error VL53LX_PerformOffsetZeroDistanceCalibration(VL53LX_DEV Dev);
00604 
00605 
00606 /**
00607  * @brief Perform Offset per Vcsel Calibration. i.e. per distance mode
00608  *
00609  * @details Perform offset calibration of the Device depending on the
00610  * three distance mode settings: short, medium and long.
00611  * This function will launch few ranging measurements and computes offset
00612  * calibration in each of the three distance modes.
00613  * The preset mode MUST be set by the application before to call this function.
00614  *
00615  * @warning This function is a blocking function
00616  *
00617  * @note This function Access to the device
00618  *
00619  * @param   Dev                  Device Handle
00620  * @param   CalDistanceMilliMeter     Distance of the target used for the
00621  * offset compensation calibration.
00622  *
00623  * @return  VL53LX_ERROR_NONE
00624  * @return  VL53LX_ERROR_OFFSET_CAL_NO_SAMPLE_FAIL the calibration failed by
00625  * lack of valid measurements
00626  * @return  VL53LX_WARNING_OFFSET_CAL_SIGMA_TOO_HIGH means that the target
00627  * distance combined to the number of loops performed in the calibration lead to
00628  * an internal overflow. Try to reduce the distance of the target (140 mm)
00629  * @return  "Other error code"   See ::VL53LX_Error
00630  */
00631 VL53LX_Error VL53LX_PerformOffsetPerVcselCalibration(VL53LX_DEV Dev,
00632     int32_t CalDistanceMilliMeter);
00633 
00634 
00635 /**
00636  * @brief Sets the Calibration Data.
00637  *
00638  * @par Function Description
00639  * This function set all the Calibration Data issued from the functions
00640  * @a VL53LX_PerformRefSpadManagement(), @a VL53LX_PerformXTalkCalibration,
00641  * @a VL53LX_PerformOffsetCalibration()
00642  *
00643  * @note This function doesn't Accesses the device
00644  *
00645  * @param   Dev                          Device Handle
00646  * @param   *pCalibrationData            Pointer to Calibration data to be set.
00647  * @return  VL53LX_ERROR_NONE            Success
00648  * @return  VL53LX_ERROR_INVALID_PARAMS  pCalibrationData points to an older
00649  * version of the inner structure. Need for support to convert its content.
00650  * @return  "Other error code"           See ::VL53LX_Error
00651  */
00652 VL53LX_Error VL53LX_SetCalibrationData(VL53LX_DEV Dev,
00653         VL53LX_CalibrationData_t *pCalibrationData);
00654 
00655 /**
00656  * @brief Gets the Calibration Data.
00657  *
00658  * @par Function Description
00659  * This function get all the Calibration Data issued from the functions
00660  * @a VL53LX_PerformRefSpadManagement(), @a VL53LX_PerformXTalkCalibration,
00661  * @a VL53LX_PerformOffsetCalibration()
00662  *
00663  * @note This function doesn't Accesses the device
00664  *
00665  * @param   Dev                          Device Handle
00666  * @param   *pCalibrationData            pointer where to store Calibration
00667  *  data.
00668  * @return  VL53LX_ERROR_NONE            Success
00669  * @return  "Other error code"           See ::VL53LX_Error
00670  */
00671 VL53LX_Error VL53LX_GetCalibrationData(VL53LX_DEV Dev,
00672         VL53LX_CalibrationData_t  *pCalibrationData);
00673 
00674 
00675 /**
00676  * @brief Gets the optical center.
00677  *
00678  * @par Function Description
00679  * This function get the optical center issued from the nvm set at FTM stage
00680  * expressed in the same coordinate system as the ROI are
00681  *
00682  * @note This function doesn't Accesses the device
00683  *
00684  * @param   Dev                          Device Handle
00685  * @param   pOpticalCenterX              pointer to the X position of center
00686  * in 16.16 fix point
00687  * @param   pOpticalCenterY              pointer to the Y position of center
00688  * in 16.16 fix point
00689  * @return  VL53L1_ERROR_NONE            Success
00690  * @return  "Other error code"           See ::VL53LX_Error
00691  */
00692 VL53LX_Error VL53LX_GetOpticalCenter(VL53LX_DEV Dev,
00693         FixPoint1616_t *pOpticalCenterX,
00694         FixPoint1616_t *pOpticalCenterY);
00695 
00696 
00697 /** @} VL53LX_Calibration_group */
00698 
00699 /** @} VL53LX_group */
00700 
00701 #ifdef __cplusplus
00702 }
00703 #endif
00704 
00705 #endif /* _VL53LX_API_H_ */