vl53lx_error_codes.h

00001 /******************************************************************************
00002  * Copyright (c) 2019, STMicroelectronics - All Rights Reserved
00003 
00004  This file is part of VL53LX Core and is dual licensed,
00005  either 'STMicroelectronics Proprietary license'
00006  or 'BSD 3-clause "New" or "Revised" License' , at your option.
00007 
00008  ******************************************************************************
00009 
00010  'STMicroelectronics Proprietary license'
00011 
00012  *******************************************************************************
00013 
00014  License terms: STMicroelectronics Proprietary in accordance with licensing
00015  terms at www.st.com/sla0081
00016 
00017  STMicroelectronics confidential
00018  Reproduction and Communication of this document is strictly prohibited unless
00019  specifically authorized in writing by STMicroelectronics.
00020 
00021 
00022  *******************************************************************************
00023 
00024  Alternatively, VL53LX Core may be distributed under the terms of
00025  'BSD 3-clause "New" or "Revised" License', in which case the following
00026  provisions apply instead of the ones mentioned above :
00027 
00028  *******************************************************************************
00029 
00030  License terms: BSD 3-clause "New" or "Revised" License.
00031 
00032  Redistribution and use in source and binary forms, with or without
00033  modification, are permitted provided that the following conditions are met:
00034 
00035  1. Redistributions of source code must retain the above copyright notice, this
00036  list of conditions and the following disclaimer.
00037 
00038  2. Redistributions in binary form must reproduce the above copyright notice,
00039  this list of conditions and the following disclaimer in the documentation
00040  and/or other materials provided with the distribution.
00041 
00042  3. Neither the name of the copyright holder nor the names of its contributors
00043  may be used to endorse or promote products derived from this software
00044  without specific prior written permission.
00045 
00046  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00047  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00048  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00049  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
00050  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00051  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00052  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00053  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00054  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00055  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00056 
00057 
00058  *******************************************************************************
00059  */
00060 
00061 /**
00062  * @file vl53lx_error_codes.h
00063  *
00064  * @brief Error Code definitions for VL53LX API.
00065  *
00066  */
00067 
00068 #ifndef _VL53LX_ERROR_CODES_H_
00069 #define _VL53LX_ERROR_CODES_H_
00070 
00071 #include "vl53lx_types.h"
00072 
00073 #ifdef __cplusplus
00074 extern "C" {
00075 #endif
00076 
00077 
00078 /*
00079  ****************************************
00080  * PRIVATE define do not edit
00081  ***************************************
00082  */
00083 
00084 /*
00085  * @defgroup VL53LX_define_Error_group Error and Warning code returned by API
00086  *  The following DEFINE are used to identify the PAL ERROR
00087  *  @{
00088  */
00089 
00090 typedef int8_t VL53LX_Error;
00091 
00092 #define VL53LX_ERROR_NONE                              ((VL53LX_Error)  0)
00093 #define VL53LX_ERROR_CALIBRATION_WARNING               ((VL53LX_Error) - 1)
00094     /*!< Warning invalid calibration data may be in used
00095      *  \a  VL53LX_InitData()
00096      *  \a VL53LX_GetOffsetCalibrationData
00097      *  \a VL53LX_SetOffsetCalibrationData
00098      */
00099 #define VL53LX_ERROR_MIN_CLIPPED                       ((VL53LX_Error) - 2)
00100     /*!< Warning parameter passed was clipped to min before to be applied */
00101 
00102 #define VL53LX_ERROR_UNDEFINED                         ((VL53LX_Error) - 3)
00103     /*!< Unqualified error */
00104 #define VL53LX_ERROR_INVALID_PARAMS                    ((VL53LX_Error) - 4)
00105     /*!< Parameter passed is invalid or out of range */
00106 #define VL53LX_ERROR_NOT_SUPPORTED                     ((VL53LX_Error) - 5)
00107     /*!< Function is not supported in current mode or configuration */
00108 #define VL53LX_ERROR_RANGE_ERROR                       ((VL53LX_Error) - 6)
00109     /*!< Device report a ranging error interrupt status */
00110 #define VL53LX_ERROR_TIME_OUT                          ((VL53LX_Error) - 7)
00111     /*!< Aborted due to time out */
00112 #define VL53LX_ERROR_MODE_NOT_SUPPORTED                ((VL53LX_Error) - 8)
00113     /*!< Asked mode is not supported by the device */
00114 #define VL53LX_ERROR_BUFFER_TOO_SMALL                  ((VL53LX_Error) - 9)
00115     /*!< ... */
00116 #define VL53LX_ERROR_COMMS_BUFFER_TOO_SMALL            ((VL53LX_Error) - 10)
00117     /*!< Supplied buffer is larger than I2C supports */
00118 #define VL53LX_ERROR_GPIO_NOT_EXISTING                 ((VL53LX_Error) - 11)
00119     /*!< User tried to setup a non-existing GPIO pin */
00120 #define VL53LX_ERROR_GPIO_FUNCTIONALITY_NOT_SUPPORTED  ((VL53LX_Error) - 12)
00121     /*!< unsupported GPIO functionality */
00122 #define VL53LX_ERROR_CONTROL_INTERFACE                 ((VL53LX_Error) - 13)
00123     /*!< error reported from IO functions */
00124 #define VL53LX_ERROR_INVALID_COMMAND                   ((VL53LX_Error) - 14)
00125     /*!< The command is not allowed in the current device state
00126      *  (power down)
00127      */
00128 #define VL53LX_ERROR_DIVISION_BY_ZERO                  ((VL53LX_Error) - 15)
00129     /*!< In the function a division by zero occurs */
00130 #define VL53LX_ERROR_REF_SPAD_INIT                     ((VL53LX_Error) - 16)
00131     /*!< Error during reference SPAD initialization */
00132 #define VL53LX_ERROR_GPH_SYNC_CHECK_FAIL               ((VL53LX_Error) - 17)
00133     /*!<  GPH sync interrupt check fail - API out of sync with device*/
00134 #define VL53LX_ERROR_STREAM_COUNT_CHECK_FAIL           ((VL53LX_Error) - 18)
00135     /*!<  Stream count check fail - API out of sync with device */
00136 #define VL53LX_ERROR_GPH_ID_CHECK_FAIL                 ((VL53LX_Error) - 19)
00137     /*!<  GPH ID check fail - API out of sync with device */
00138 #define VL53LX_ERROR_ZONE_STREAM_COUNT_CHECK_FAIL      ((VL53LX_Error) - 20)
00139     /*!<  Zone dynamic config stream count check failed - API out of sync */
00140 #define VL53LX_ERROR_ZONE_GPH_ID_CHECK_FAIL            ((VL53LX_Error) - 21)
00141     /*!<  Zone dynamic config GPH ID check failed - API out of sync */
00142 
00143 #define VL53LX_ERROR_XTALK_EXTRACTION_NO_SAMPLE_FAIL   ((VL53LX_Error) - 22)
00144     /*!<  Thrown when run_xtalk_extraction fn has 0 succesful samples
00145      * when using the full array to sample the xtalk. In this case there is
00146      * not enough information to generate new Xtalk parm info. The function
00147      * will exit and leave the current xtalk parameters unaltered
00148      */
00149 #define VL53LX_ERROR_XTALK_EXTRACTION_SIGMA_LIMIT_FAIL ((VL53LX_Error) - 23)
00150     /*!<  Thrown when run_xtalk_extraction fn has found that the
00151      * avg sigma estimate of the full array xtalk sample is > than the
00152      * maximal limit allowed. In this case the xtalk sample is too noisy for
00153      * measurement. The function will exit and leave the current xtalk
00154      * parameters unaltered.
00155      */
00156 
00157 
00158 #define VL53LX_ERROR_OFFSET_CAL_NO_SAMPLE_FAIL           ((VL53LX_Error) - 24)
00159     /*!<  Thrown if there one of stages has no valid offset calibration
00160      *    samples. A fatal error calibration not valid
00161      */
00162 #define VL53LX_ERROR_OFFSET_CAL_NO_SPADS_ENABLED_FAIL    ((VL53LX_Error) - 25)
00163     /*!<  Thrown if there one of stages has zero effective SPADS
00164      *    Traps the case when MM1 SPADs is zero.
00165      *    A fatal error calibration not valid
00166      */
00167 #define VL53LX_ERROR_ZONE_CAL_NO_SAMPLE_FAIL             ((VL53LX_Error) - 26)
00168     /*!<  Thrown if then some of the zones have no valid samples
00169      *    A fatal error calibration not valid
00170      */
00171 
00172 #define VL53LX_ERROR_TUNING_PARM_KEY_MISMATCH             ((VL53LX_Error) - 27)
00173     /*!<  Thrown if the tuning file key table version does not match with
00174      * expected value. The driver expects the key table version to match
00175      * the compiled default version number in the define
00176      * #VL53LX_TUNINGPARM_KEY_TABLE_VERSION_DEFAULT
00177      */
00178 
00179 #define VL53LX_WARNING_REF_SPAD_CHAR_NOT_ENOUGH_SPADS   ((VL53LX_Error) - 28)
00180     /*!<  Thrown if there are less than 5 good SPADs are available. */
00181 #define VL53LX_WARNING_REF_SPAD_CHAR_RATE_TOO_HIGH      ((VL53LX_Error) - 29)
00182     /*!<  Thrown if the final reference rate is greater than
00183      * the upper reference rate limit - default is 40 Mcps.
00184      * Implies a minimum Q3 (x10) SPAD (5) selected
00185      */
00186 #define VL53LX_WARNING_REF_SPAD_CHAR_RATE_TOO_LOW       ((VL53LX_Error) - 30)
00187     /*!<  Thrown if the final reference rate is less than
00188      * the lower reference rate limit - default is 10 Mcps.
00189      * Implies maximum Q1 (x1) SPADs selected
00190      */
00191 
00192 
00193 #define VL53LX_WARNING_OFFSET_CAL_MISSING_SAMPLES       ((VL53LX_Error) - 31)
00194     /*!<  Thrown if there is less than the requested number of
00195      *    valid samples.
00196      */
00197 #define VL53LX_WARNING_OFFSET_CAL_SIGMA_TOO_HIGH        ((VL53LX_Error) - 32)
00198     /*!<  Thrown if the offset calibration range sigma estimate is greater
00199      *    than 8.0 mm. This is the recommended min value to yield a stable
00200      *    offset measurement
00201      */
00202 #define VL53LX_WARNING_OFFSET_CAL_RATE_TOO_HIGH         ((VL53LX_Error) - 33)
00203     /*!< Thrown when VL53LX_run_offset_calibration()  peak rate is greater
00204      * than that 50.0Mcps. This is the recommended  max rate to avoid
00205      * pile-up influencing the offset measurement
00206      */
00207 #define VL53LX_WARNING_OFFSET_CAL_SPAD_COUNT_TOO_LOW    ((VL53LX_Error) - 34)
00208     /*!< Thrown when VL53LX_run_offset_calibration() when one of stages
00209      * range has less that 5.0 effective SPADS. This is the recommended
00210      * min value to yield a stable offset
00211      */
00212 
00213 
00214 #define VL53LX_WARNING_ZONE_CAL_MISSING_SAMPLES       ((VL53LX_Error) - 35)
00215     /*!<  Thrown if one of more of the zones have less than
00216      * the requested number of valid samples
00217      */
00218 #define VL53LX_WARNING_ZONE_CAL_SIGMA_TOO_HIGH        ((VL53LX_Error) - 36)
00219     /*!<  Thrown if one or more zones have sigma estimate value greater
00220      *    than 8.0 mm. This is the recommended min value to yield a stable
00221      *    offset measurement
00222      */
00223 #define VL53LX_WARNING_ZONE_CAL_RATE_TOO_HIGH         ((VL53LX_Error) - 37)
00224     /*!< Thrown if one of more zones have  peak rate higher than
00225      * that 50.0Mcps. This is the recommended  max rate to avoid
00226      * pile-up influencing the offset measurement
00227      */
00228 
00229 
00230 #define VL53LX_WARNING_XTALK_MISSING_SAMPLES             ((VL53LX_Error) - 38)
00231     /*!< Thrown to notify that some of the xtalk samples did not yield
00232      * valid ranging pulse data while attempting to measure
00233      * the xtalk signal in vl53lx_run_xtalk_extract(). This can signify any
00234      * of the zones are missing samples, for further debug information the
00235      * xtalk_results struct should be referred to. This warning is for
00236      * notification only, xtalk pulse and shape have still been generated
00237      */
00238 #define VL53LX_WARNING_XTALK_NO_SAMPLES_FOR_GRADIENT     ((VL53LX_Error) - 39)
00239     /*!< Thrown to notify that some of teh xtalk samples used for gradient
00240      * generation did not yield valid ranging pulse data while attempting to
00241      * measure the xtalk signal in vl53lx_run_xtalk_extract(). This can
00242      * signify that any one of the zones 0-3 yielded no successful samples.
00243      * xtalk_results struct should be referred to for further debug info.
00244      * This warning is for notification only, the xtalk pulse and shape
00245      * have still been generated.
00246      */
00247 #define VL53LX_WARNING_XTALK_SIGMA_LIMIT_FOR_GRADIENT    ((VL53LX_Error) - 40)
00248     /*!< Thrown to notify that some of the xtalk samples used for gradient
00249      * generation did not pass the sigma limit check  while attempting to
00250      * measure the xtalk signal in vl53lx_run_xtalk_extract(). This can
00251      * signify that any one of the zones 0-3 yielded an avg sigma_mm
00252      * value > the limit. The xtalk_results struct should be referred to for
00253      * further debug info.
00254      * This warning is for notification only, the xtalk pulse and shape
00255      * have still been generated.
00256      */
00257 
00258 #define VL53LX_ERROR_NOT_IMPLEMENTED                   ((VL53LX_Error) - 41)
00259     /*!< Tells requested functionality has not been implemented yet or
00260      * not compatible with the device
00261      */
00262 #define VL53LX_ERROR_PLATFORM_SPECIFIC_START           ((VL53LX_Error) - 60)
00263     /*!< Tells the starting code for platform */
00264 /** @} VL53LX_define_Error_group */
00265 
00266 
00267 #ifdef __cplusplus
00268 }
00269 #endif
00270 
00271 
00272 #endif /* _VL53LX_ERROR_CODES_H_ */
00273