vl53l1_error_codes.h

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