vl53l1x_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 /**
00064  * @file vl53l1_error_codes.h
00065  *
00066  * @brief Error Code definitions for VL53L1 API.
00067  *
00068  */
00069 
00070 #ifndef _VL53L1X_ERROR_CODES_H_
00071 #define _VL53L1X_ERROR_CODES_H_
00072 
00073 #ifdef __cplusplus
00074 extern "C" {
00075 #endif
00076 
00077 
00078 /****************************************
00079  * PRIVATE define do not edit
00080  ****************************************/
00081 
00082 /** @defgroup VL53L1_define_Error_group Error and Warning code returned by API
00083  *  The following DEFINE are used to identify the PAL ERROR
00084  *  @{
00085  */
00086 
00087 typedef int8_t VL53L1_Error;
00088 
00089 #define VL53L1_ERROR_NONE                              ((VL53L1_Error)  0)
00090 #define VL53L1_ERROR_CALIBRATION_WARNING               ((VL53L1_Error) - 1)
00091     /*!< Warning invalid calibration data may be in used
00092         \a  VL53L1_InitData()
00093         \a VL53L1_GetOffsetCalibrationData
00094         \a VL53L1_SetOffsetCalibrationData */
00095 #define VL53L1_ERROR_MIN_CLIPPED                       ((VL53L1_Error) - 2)
00096     /*!< Warning parameter passed was clipped to min before to be applied */
00097 
00098 #define VL53L1_ERROR_UNDEFINED                         ((VL53L1_Error) - 3)
00099     /*!< Unqualified error */
00100 #define VL53L1_ERROR_INVALID_PARAMS                    ((VL53L1_Error) - 4)
00101     /*!< Parameter passed is invalid or out of range */
00102 #define VL53L1_ERROR_NOT_SUPPORTED                     ((VL53L1_Error) - 5)
00103     /*!< Function is not supported in current mode or configuration */
00104 #define VL53L1_ERROR_RANGE_ERROR                       ((VL53L1_Error) - 6)
00105     /*!< Device report a ranging error interrupt status */
00106 #define VL53L1_ERROR_TIME_OUT                          ((VL53L1_Error) - 7)
00107     /*!< Aborted due to time out */
00108 #define VL53L1_ERROR_MODE_NOT_SUPPORTED                ((VL53L1_Error) - 8)
00109     /*!< Asked mode is not supported by the device */
00110 #define VL53L1_ERROR_BUFFER_TOO_SMALL                  ((VL53L1_Error) - 9)
00111     /*!< ... */
00112 #define VL53L1_ERROR_COMMS_BUFFER_TOO_SMALL            ((VL53L1_Error) - 10)
00113     /*!< Supplied buffer is larger than I2C supports */
00114 #define VL53L1_ERROR_GPIO_NOT_EXISTING                 ((VL53L1_Error) - 11)
00115     /*!< User tried to setup a non-existing GPIO pin */
00116 #define VL53L1_ERROR_GPIO_FUNCTIONALITY_NOT_SUPPORTED  ((VL53L1_Error) - 12)
00117     /*!< unsupported GPIO functionality */
00118 #define VL53L1_ERROR_CONTROL_INTERFACE                 ((VL53L1_Error) - 13)
00119     /*!< error reported from IO functions */
00120 #define VL53L1_ERROR_INVALID_COMMAND                   ((VL53L1_Error) - 14)
00121     /*!< The command is not allowed in the current device state
00122      *  (power down) */
00123 #define VL53L1_ERROR_DIVISION_BY_ZERO                  ((VL53L1_Error) - 15)
00124     /*!< In the function a division by zero occurs */
00125 #define VL53L1_ERROR_REF_SPAD_INIT                     ((VL53L1_Error) - 16)
00126     /*!< Error during reference SPAD initialization */
00127 #define VL53L1_ERROR_GPH_SYNC_CHECK_FAIL               ((VL53L1_Error) - 17)
00128     /*!<  GPH sync interrupt check fail - API out of sync with device*/
00129 #define VL53L1_ERROR_STREAM_COUNT_CHECK_FAIL           ((VL53L1_Error) - 18)
00130     /*!<  Stream count check fail - API out of sync with device */
00131 #define VL53L1_ERROR_GPH_ID_CHECK_FAIL                 ((VL53L1_Error) - 19)
00132     /*!<  GPH ID check fail - API out of sync with device */
00133 #define VL53L1_ERROR_ZONE_STREAM_COUNT_CHECK_FAIL      ((VL53L1_Error) - 20)
00134     /*!<  Zone dynamic config stream count check failed - API out of sync */
00135 #define VL53L1_ERROR_ZONE_GPH_ID_CHECK_FAIL            ((VL53L1_Error) - 21)
00136     /*!<  Zone dynamic config GPH ID check failed - API out of sync */
00137 
00138 #define VL53L1_ERROR_XTALK_EXTRACTION_NO_SAMPLE_FAIL   ((VL53L1_Error) - 22)
00139     /*!<  Thrown when run_xtalk_extraction fn has 0 succesful samples
00140      * when using the full array to sample the xtalk. In this case there is
00141      * not enough information to generate new Xtalk parm info. The function
00142      * will exit and leave the current xtalk parameters unaltered */
00143 #define VL53L1_ERROR_XTALK_EXTRACTION_SIGMA_LIMIT_FAIL ((VL53L1_Error) - 23)
00144     /*!<  Thrown when run_xtalk_extraction fn has found that the
00145      * avg sigma estimate of the full array xtalk sample is > than the
00146      * maximal limit allowed. In this case the xtalk sample is too noisy for
00147      * measurement. The function will exit and leave the current xtalk parameters
00148      * unaltered. */
00149 
00150 
00151 #define VL53L1_ERROR_OFFSET_CAL_NO_SAMPLE_FAIL           ((VL53L1_Error) - 24)
00152     /*!<  Thrown if there one of stages has no valid offset calibration
00153      *    samples. A fatal error calibration not valid */
00154 #define VL53L1_ERROR_OFFSET_CAL_NO_SPADS_ENABLED_FAIL    ((VL53L1_Error) - 25)
00155     /*!<  Thrown if there one of stages has zero effective SPADS
00156      *    Traps the case when MM1 SPADs is zero.
00157      *    A fatal error calibration not valid */
00158 #define VL53L1_ERROR_ZONE_CAL_NO_SAMPLE_FAIL             ((VL53L1_Error) - 26)
00159     /*!<  Thrown if then some of the zones have no valid samples
00160      *    A fatal error calibration not valid */
00161 
00162 #define VL53L1_ERROR_TUNING_PARM_KEY_MISMATCH             ((VL53L1_Error) - 27)
00163     /*!<  Thrown if the tuning file key table version does not match with
00164      * expected value. The driver expects the key table version to match
00165      * the compiled default version number in the define
00166      * #VL53L1_TUNINGPARM_KEY_TABLE_VERSION_DEFAULT
00167      * */
00168 
00169 #define VL53L1_WARNING_REF_SPAD_CHAR_NOT_ENOUGH_SPADS   ((VL53L1_Error) - 28)
00170     /*!<  Thrown if there are less than 5 good SPADs are available. */
00171 #define VL53L1_WARNING_REF_SPAD_CHAR_RATE_TOO_HIGH      ((VL53L1_Error) - 29)
00172     /*!<  Thrown if the final reference rate is greater than
00173           the upper reference rate limit - default is 40 Mcps.
00174           Implies a minimum Q3 (x10) SPAD (5) selected */
00175 #define VL53L1_WARNING_REF_SPAD_CHAR_RATE_TOO_LOW       ((VL53L1_Error) - 30)
00176     /*!<  Thrown if the final reference rate is less than
00177           the lower reference rate limit - default is 10 Mcps.
00178           Implies maximum Q1 (x1) SPADs selected */
00179 
00180 
00181 #define VL53L1_WARNING_OFFSET_CAL_MISSING_SAMPLES       ((VL53L1_Error) - 31)
00182     /*!<  Thrown if there is less than the requested number of
00183      *    valid samples. */
00184 #define VL53L1_WARNING_OFFSET_CAL_SIGMA_TOO_HIGH        ((VL53L1_Error) - 32)
00185     /*!<  Thrown if the offset calibration range sigma estimate is greater
00186      *    than 8.0 mm. This is the recommended min value to yield a stable
00187      *    offset measurement */
00188 #define VL53L1_WARNING_OFFSET_CAL_RATE_TOO_HIGH         ((VL53L1_Error) - 33)
00189     /*!< Thrown when VL53L1_run_offset_calibration()  peak rate is greater
00190          than that 50.0Mcps. This is the recommended  max rate to avoid
00191          pile-up influencing the offset measurement */
00192 #define VL53L1_WARNING_OFFSET_CAL_SPAD_COUNT_TOO_LOW    ((VL53L1_Error) - 34)
00193     /*!< Thrown when VL53L1_run_offset_calibration() when one of stages
00194          range has less that 5.0 effective SPADS. This is the recommended
00195          min value to yield a stable offset */
00196 
00197 
00198 #define VL53L1_WARNING_ZONE_CAL_MISSING_SAMPLES       ((VL53L1_Error) - 35)
00199     /*!<  Thrown if one of more of the zones have less than
00200           the requested number of valid samples */
00201 #define VL53L1_WARNING_ZONE_CAL_SIGMA_TOO_HIGH        ((VL53L1_Error) - 36)
00202     /*!<  Thrown if one or more zones have sigma estimate value greater
00203      *    than 8.0 mm. This is the recommended min value to yield a stable
00204      *    offset measurement */
00205 #define VL53L1_WARNING_ZONE_CAL_RATE_TOO_HIGH         ((VL53L1_Error) - 37)
00206     /*!< Thrown if one of more zones have  peak rate higher than
00207           that 50.0Mcps. This is the recommended  max rate to avoid
00208          pile-up influencing the offset measurement */
00209 
00210 
00211 #define VL53L1_WARNING_XTALK_MISSING_SAMPLES             ((VL53L1_Error) - 38)
00212     /*!< Thrown to notify that some of the xtalk samples did not yield
00213      * valid ranging pulse data while attempting to measure
00214      * the xtalk signal in vl53l1_run_xtalk_extract(). This can signify any of
00215      * the zones are missing samples, for further debug information the
00216      * xtalk_results struct should be referred to. This warning is for
00217      * notification only, the xtalk pulse and shape have still been generated
00218      */
00219 #define VL53L1_WARNING_XTALK_NO_SAMPLES_FOR_GRADIENT     ((VL53L1_Error) - 39)
00220     /*!< Thrown to notify that some of teh xtalk samples used for gradient
00221      * generation did not yield valid ranging pulse data while attempting to
00222      * measure the xtalk signal in vl53l1_run_xtalk_extract(). This can signify
00223      * that any one of the zones 0-3 yielded no successful samples. The
00224      * xtalk_results struct should be referred to for further debug info.
00225      * This warning is for notification only, the xtalk pulse and shape
00226      * have still been generated.
00227      */
00228 #define VL53L1_WARNING_XTALK_SIGMA_LIMIT_FOR_GRADIENT    ((VL53L1_Error) - 40)
00229 /*!< Thrown to notify that some of the xtalk samples used for gradient
00230      * generation did not pass the sigma limit check  while attempting to
00231      * measure the xtalk signal in vl53l1_run_xtalk_extract(). This can signify
00232      * that any one of the zones 0-3 yielded an avg sigma_mm value > the limit.
00233      * The xtalk_results struct should be referred to for further debug info.
00234      * This warning is for notification only, the xtalk pulse and shape
00235      * have still been generated.
00236      */
00237 
00238 #define VL53L1_ERROR_NOT_IMPLEMENTED                   ((VL53L1_Error) - 41)
00239     /*!< Tells requested functionality has not been implemented yet or
00240      * not compatible with the device */
00241 #define VL53L1_ERROR_PLATFORM_SPECIFIC_START           ((VL53L1_Error) - 60)
00242     /*!< Tells the starting code for platform */
00243 /** @} VL53L1_define_Error_group */
00244 
00245 
00246 #ifdef __cplusplus
00247 }
00248 #endif
00249 
00250 
00251 #endif /* _VL53L1X_ERROR_CODES_H_ */