vl6180x_def.h

00001 /*******************************************************************************
00002 Copyright © 2014, STMicroelectronics International N.V.
00003 All rights reserved.
00004 
00005 Redistribution and use in source and binary forms, with or without
00006 modification, are permitted provided that the following conditions are met:
00007     * Redistributions of source code must retain the above copyright
00008       notice, this list of conditions and the following disclaimer.
00009     * Redistributions in binary form must reproduce the above copyright
00010       notice, this list of conditions and the following disclaimer in the
00011       documentation and/or other materials provided with the distribution.
00012     * Neither the name of STMicroelectronics nor the
00013       names of its contributors may be used to endorse or promote products
00014       derived from this software without specific prior written permission.
00015 
00016 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00017 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00018 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
00019 NON-INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS ARE DISCLAIMED. 
00020 IN NO EVENT SHALL STMICROELECTRONICS INTERNATIONAL N.V. BE LIABLE FOR ANY
00021 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00022 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00023 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00024 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00025 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00026 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027 ********************************************************************************/
00028 
00029 /*
00030  * $Date: 2015-05-13 14:12:05 +0200 (Wed, 13 May 2015) $
00031  * $Revision: 2290 $
00032  */
00033 
00034 /**
00035  * @file VL6180x_def.h
00036  *
00037  * @brief Type definitions for vl6180x api.
00038  *
00039  */
00040 
00041 
00042 #ifndef _VL6180x_DEF
00043 #define _VL6180x_DEF
00044 
00045 /** API major version */
00046 #define VL6180x_API_REV_MAJOR   3
00047 /** API minor version */
00048 #define VL6180x_API_REV_MINOR   2
00049 /** API sub version */
00050 #define VL6180x_API_REV_SUB     0
00051 
00052 #define VL6180X_STR_HELPER(x) #x
00053 #define VL6180X_STR(x) VL6180X_STR_HELPER(x)
00054 
00055 #include "vl6180x_cfg.h"
00056 #include "vl6180x_types.h"
00057 
00058 /*
00059  * check configuration macro raise error or warning and suggest a default value
00060  */
00061 
00062 #ifndef VL6180x_UPSCALE_SUPPORT
00063 #error "VL6180x_UPSCALE_SUPPORT not defined"
00064 /* TODO you must define value for  upscale support in your vl6180x_cfg.h  */
00065 #endif
00066 
00067 #ifndef VL6180x_ALS_SUPPORT
00068 #error "VL6180x_ALS_SUPPORT not defined"
00069 /* TODO you must define VL6180x_ALS_SUPPORT  with a value in your vl6180x_cfg.h  set to 0 do disable*/
00070 #endif
00071 
00072 #ifndef VL6180x_HAVE_DMAX_RANGING
00073 #error "VL6180x_HAVE_DMAX_RANGING not defined"
00074 /* TODO you may remove or comment these #error and keep the default below  or update your vl6180x_cfg.h .h file */
00075 /**
00076  * force VL6180x_HAVE_DMAX_RANGING to not supported when not part of cfg file
00077  */
00078 #define VL6180x_HAVE_DMAX_RANGING   0
00079 #endif
00080 
00081 #ifndef VL6180x_EXTENDED_RANGE
00082 #define VL6180x_EXTENDED_RANGE   0
00083 #endif
00084 
00085 #ifndef  VL6180x_WRAP_AROUND_FILTER_SUPPORT
00086 #error "VL6180x_WRAP_AROUND_FILTER_SUPPORT not defined ?"
00087 /* TODO you may remove or comment these #error and keep the default below  or update vl6180x_cfg.h file */
00088 /**
00089  * force VL6180x_WRAP_AROUND_FILTER_SUPPORT to not supported when not part of cfg file
00090  */
00091 #define VL6180x_WRAP_AROUND_FILTER_SUPPORT 0
00092 #endif
00093 
00094 
00095 
00096 #ifndef VL6180x_HAVE_MULTI_READ
00097 #   define VL6180x_HAVE_MULTI_READ  0
00098 #endif
00099 
00100 /**
00101  * Force VL6180x_CACHED_REG to default 0 when not defined
00102  */
00103 #ifndef VL6180x_CACHED_REG
00104 #   define VL6180x_CACHED_REG  0
00105 #else
00106 #   define VL6180x_FIRST_CACHED_INDEX      0x04D
00107 #   define VL6180x_LAST_CACHED_INDEX       (VL6180x_FIRST_CACHED_INDEX+55)
00108 #   define VL6180x_CACHED_REG_CNT           (VL6180x_LAST_CACHED_INDEX-VL6180x_FIRST_CACHED_INDEX+1)
00109 #endif
00110 
00111 /****************************************
00112  * PRIVATE define do not edit
00113  ****************************************/
00114 
00115 /** Maximal buffer size ever use in i2c */
00116 #define VL6180x_MAX_I2C_XFER_SIZE   8 /* At present time it 6 byte max but that can change */
00117 
00118 #if VL6180x_UPSCALE_SUPPORT < 0
00119 /**
00120  * @def VL6180x_HAVE_UPSCALE_DATA
00121  * @brief  is defined if device data structure has data so when user configurable up-scale is active
00122  */
00123 #define VL6180x_HAVE_UPSCALE_DATA /* have data only for user configurable up-scale config */
00124 #endif
00125 
00126 #if VL6180x_WRAP_AROUND_FILTER_SUPPORT
00127 /**
00128  * @def VL6180x_HAVE_WRAP_AROUND_DATA
00129  * @brief  is defined if device data structure has filter data so when active in cfg file
00130  */
00131 #define  VL6180x_HAVE_WRAP_AROUND_DATA
00132 #endif
00133 
00134 #if VL6180x_ALS_SUPPORT != 0
00135 /**
00136  * @def  VL6180x_HAVE_ALS_DATA
00137  * @brief is defined when als data are include in device data structure so when als suport if configured
00138  */
00139 #define VL6180x_HAVE_ALS_DATA
00140 #endif
00141 
00142 
00143 #if VL6180x_WRAP_AROUND_FILTER_SUPPORT || VL6180x_HAVE_DMAX_RANGING
00144     #define VL6180x_HAVE_RATE_DATA
00145 #endif
00146 
00147 /** Error and warning code returned by API
00148  *
00149  * negative value are true error mostly fatal\n
00150  * positive value  are warning most of time it's ok to continue\n
00151  */
00152 enum VL6180x_ErrCode_t{
00153     API_NO_ERROR        = 0,
00154     CALIBRATION_WARNING = 1,  /*!< warning invalid calibration data may be in used \a  VL6180x_InitData() \a VL6180x_GetOffsetCalibrationData \a VL6180x_SetOffsetCalibrationData*/
00155     MIN_CLIPED          = 2,  /*!< warning parameter passed was clipped to min before to be applied */
00156     NOT_GUARANTEED      = 3,  /*!< Correct operation is not guaranteed typically using extended ranging on vl6180x */
00157 
00158     API_ERROR      = -1,    /*!< Unqualified error */
00159     INVALID_PARAMS = -2,    /*!< parameter passed is invalid or out of range */
00160     NOT_SUPPORTED  = -3,    /*!< function is not supported in current mode or configuration */
00161     RANGE_ERROR    = -4,    /*!< device report a ranging error interrupt status */
00162     TIME_OUT       = -5,    /*!< aborted due to time out */
00163 };
00164 
00165 /**
00166  * Filtered result data structure  range data is to be used
00167  */
00168 typedef struct RangeFilterResult_tag {
00169     uint16_t range_mm ;      /*!< Filtered ranging value */
00170     uint16_t rawRange_mm ;   /*!< raw range value (scaled) */
00171     uint32_t filterError ;   /*!< current filter error code */
00172 } RangeFilterResult_t;
00173 
00174 /**
00175  * "small" unsigned data type used in filter
00176  *
00177  * if data space saving is not a concern it can be change to platform native unsigned int
00178  */
00179 typedef uint32_t  FilterType1_t;
00180 
00181 /**
00182  * @def FILTER_NBOF_SAMPLES
00183  * @brief sample history len used for wrap around filtering
00184  */
00185 #define FILTER_NBOF_SAMPLES             10
00186 /**
00187  * Wrap around filter internal data
00188  */
00189 struct FilterData_t {
00190     uint32_t MeasurementIndex ;                      /*!< current measurement index */
00191     uint32_t MeasurementsSinceLastFlush ;            /*!< Number of measurements done since last time buffer has been flushed */
00192     uint16_t LastTrueRange [FILTER_NBOF_SAMPLES];    /*!< filtered/corrected  distance history */
00193     uint32_t LastReturnRates [FILTER_NBOF_SAMPLES];  /*!< Return rate history */
00194     uint16_t StdFilteredReads ;                      /*!< internal use */
00195     FilterType1_t Default_ZeroVal ;                  /*!< internal use */
00196     FilterType1_t Default_VAVGVal ;                  /*!< internal use */
00197     FilterType1_t NoDelay_ZeroVal ;                  /*!< internal use */
00198     FilterType1_t NoDelay_VAVGVal ;                  /*!< internal use */
00199     FilterType1_t Previous_VAVGDiff ;                /*!< internal use */
00200     uint32_t FilteringOnGoingConsecutiveStates ;    /*!< internal use */
00201     uint32_t filterError ;                           /*!< current filter error code */
00202 };
00203 
00204 #if  VL6180x_HAVE_DMAX_RANGING
00205 typedef int32_t DMaxFix_t;
00206 struct DMaxData_t {
00207     uint32_t ambTuningWindowFactor_K; /*!<  internal algo tuning (*1000) */
00208 
00209     DMaxFix_t retSignalAt400mm;  /*!< intermediate dmax computation value caching @a #SYSRANGE_CROSSTALK_COMPENSATION_RATE and private reg 0x02A */
00210     /* int32_t RegB8; */             /*!< register 0xB8 cached to speed reduce i2c traffic for dmax computation */
00211     /* place all word data below to optimize struct packing */
00212     /* int32_t minSignalNeeded; */    /*!< optimized computation intermediate base on register cached value */
00213     int32_t snrLimit_K;         /*!< cached and optimized computation intermediate from  @a #SYSRANGE_MAX_AMBIENT_LEVEL_MULT */
00214     uint16_t ClipSnrLimit;      /*!< Max value for snr limit */
00215     /* place all byte data below to optimize packing */
00216     /* uint8_t MaxConvTime; */        /*!< cached max convergence time @a #SYSRANGE_MAX_CONVERGENCE_TIME*/
00217 };
00218 #endif
00219 
00220 struct RangeIgnoreData_t {
00221     uint16_t ValidHeight;
00222     uint16_t IgnoreThreshold;
00223     uint8_t Enabled;
00224 };
00225 /**
00226  * @struct VL6180xDevData_t
00227  *
00228  * @brief Per VL6180x device St private data structure \n
00229  * End user should never access any of these field directly
00230  *
00231  * These must never access directly but only via VL6180xDev/SetData(dev, field) macro
00232  */
00233 struct VL6180xDevData_t {
00234 
00235     uint32_t Part2PartAmbNVM ;  /*!< backed up NVM value */
00236     uint32_t XTalkCompRate_KCps; /*! Cached XTlak Compensation Rate */
00237 
00238     uint16_t EceFactorM ;        /*!< Ece Factor M numerator  */
00239     uint16_t EceFactorD ;        /*!< Ece Factor D denominator*/
00240 
00241     struct RangeIgnoreData_t RangeIgnore;
00242 #ifdef VL6180x_HAVE_ALS_DATA
00243     uint16_t IntegrationPeriod ; /*!< cached als Integration period avoid slow read from device at each measure */
00244     uint16_t AlsGainCode ;       /*!< cached Als gain avoid slow read from device at each measure */
00245     uint16_t AlsScaler ;         /*!< cached Als scaler avoid slow read from device at each measure */
00246 #endif
00247 
00248 #ifdef VL6180x_HAVE_UPSCALE_DATA
00249     uint8_t UpscaleFactor ;      /*!<  up-scaling factor*/
00250 #endif
00251 
00252 #ifdef  VL6180x_HAVE_WRAP_AROUND_DATA
00253     uint8_t WrapAroundFilterActive ; /*!< Filter on/off */
00254     struct FilterData_t FilterData ; /*!< Filter internal data state history ... */
00255 #endif
00256 
00257 #if VL6180x_CACHED_REG
00258     uint8_t CacheFilled ;             /*!< Set if valid data got fetched use to control when to fill up register cache */
00259     uint8_t CachedRegs [VL6180x_CACHED_REG_CNT];          /*!< Cache register storage */
00260 #endif
00261 #if  VL6180x_HAVE_DMAX_RANGING
00262     struct DMaxData_t DMaxData;
00263     uint8_t DMaxEnable;
00264 #endif
00265     int8_t  Part2PartOffsetNVM ;     /*!< backed up NVM value */
00266 };
00267 
00268 
00269 /**
00270  * @struct VL6180x_RangeData_t
00271  * @brief Range and any optional measurement data.
00272  */
00273 typedef struct {
00274     uint32_t range_mm ;          /*!< range distance in mm. */
00275     int32_t signalRate_mcps ;   /*!< signal rate (MCPS)\n these is a 9.7 fix point value, which is effectively a measure of target reflectance.*/
00276     uint32_t errorStatus ;      /*!< Error status of the current measurement. \n see @a ::RangeError_u @a VL6180x_GetRangeStatusErrString() */
00277 
00278 
00279 #ifdef VL6180x_HAVE_RATE_DATA
00280     uint32_t rtnAmbRate ;    /*!< Return Ambient rate in KCount per sec related to \a RESULT_RANGE_RETURN_AMB_COUNT */
00281     uint32_t rtnRate ;       /*!< Return rate in KCount per sec  related to \a RESULT_RANGE_RETURN_SIGNAL_COUNT  */
00282     uint32_t rtnConvTime ;   /*!< Return Convergence time \a RESULT_RANGE_RETURN_CONV_TIME */
00283     uint32_t refConvTime ;   /*!< Reference convergence time \a RESULT_RANGE_REFERENCE_CONV_TIME */
00284 #endif
00285 
00286 
00287 #if  VL6180x_HAVE_DMAX_RANGING
00288     uint32_t DMax ;              /*!< DMax  when applicable */
00289 #endif
00290 
00291 #ifdef  VL6180x_HAVE_WRAP_AROUND_DATA
00292     RangeFilterResult_t FilteredData ; /*!< Filter result main range_mm is updated */
00293 #endif
00294 }VL6180x_RangeData_t;
00295 
00296 
00297 /** use where fix point 9.7 bit values are expected
00298  *
00299  * given a floating point value f it's .7 bit point is (int)(f*(1<<7))*/
00300 typedef uint16_t FixPoint97_t;
00301 
00302 /** lux data type */
00303 typedef uint32_t lux_t;
00304 
00305 /**
00306  * @brief This data type defines als  measurement data.
00307  */
00308 typedef struct VL6180x_AlsData_st{
00309     lux_t lux;                 /**< Light measurement (Lux) */
00310     uint32_t errorStatus;      /**< Error status of the current measurement. \n
00311      * No Error := 0. \n
00312      * Refer to product sheets for other error codes. */
00313 }VL6180x_AlsData_t;
00314 
00315 /**
00316  * @brief Range status Error code
00317  *
00318  * @a VL6180x_GetRangeStatusErrString() if configured ( @a #VL6180x_RANGE_STATUS_ERRSTRING )
00319  * related to register @a #RESULT_RANGE_STATUS and additional post processing
00320  */
00321 typedef enum {
00322     NoError = 0,               /*!< 0  0b0000 NoError  */
00323     VCSEL_Continuity_Test,     /*!< 1  0b0001 VCSEL_Continuity_Test */
00324     VCSEL_Watchdog_Test,       /*!< 2  0b0010 VCSEL_Watchdog_Test */
00325     VCSEL_Watchdog,            /*!< 3  0b0011 VCSEL_Watchdog */
00326     PLL1_Lock,                 /*!< 4  0b0100 PLL1_Lock */
00327     PLL2_Lock,                 /*!< 5  0b0101 PLL2_Lock */
00328     Early_Convergence_Estimate,/*!< 6  0b0110 Early_Convergence_Estimate */
00329     Max_Convergence,           /*!< 7  0b0111 Max_Convergence */
00330     No_Target_Ignore,          /*!< 8  0b1000 No_Target_Ignore */
00331     Not_used_9,                /*!< 9  0b1001 Not_used */
00332     Not_used_10,               /*!< 10 0b1010 Not_used_ */
00333     Max_Signal_To_Noise_Ratio, /*!< 11 0b1011 Max_Signal_To_Noise_Ratio*/
00334     Raw_Ranging_Algo_Underflow,/*!< 12 0b1100 Raw_Ranging_Algo_Underflow*/
00335     Raw_Ranging_Algo_Overflow, /*!< 13 0b1101 Raw_Ranging_Algo_Overflow */
00336     Ranging_Algo_Underflow,    /*!< 14 0b1110 Ranging_Algo_Underflow */
00337     Ranging_Algo_Overflow,     /*!< 15 0b1111 Ranging_Algo_Overflow */
00338 
00339     /* code below are addition for API/software side they are not hardware*/
00340     RangingFiltered =0x10,     /*!< 16 0b10000 filtered by post processing*/
00341     DataNotReady = 0x12,             /*!< 18 0b10011 New data sample not ready */
00342 
00343 } RangeError_u;
00344 
00345 
00346 /** @defgroup device_regdef Device registers & masks definitions
00347  *  @brief    Device registers and masks definitions
00348  */
00349 
00350  
00351 /** @ingroup device_regdef
00352  * @{*/
00353 
00354 /**
00355  * The device model ID
00356  */
00357 #define IDENTIFICATION_MODEL_ID                 0x000
00358 /**
00359  * Revision identifier of the Device for major change.
00360  */
00361 #define IDENTIFICATION_MODULE_REV_MAJOR         0x003
00362 /**
00363  * Revision identifier of the Device for minor change.
00364  */
00365 #define IDENTIFICATION_MODULE_REV_MINOR         0x004
00366 
00367 
00368 /**
00369  * @def SYSTEM_MODE_GPIO0
00370  * @brief Configures polarity and select which function gpio 0 serves.
00371  *  Gpio0 is chip enable at power up ! Be aware of all h/w implication of turning it to output.
00372  *  Same definition as #SYSTEM_MODE_GPIO1
00373  * @ingroup device_regdef
00374  */
00375 #define SYSTEM_MODE_GPIO0                       0x010
00376 /**
00377  * @def SYSTEM_MODE_GPIO1
00378  * @brief Configures polarity and select what als or ranging functionality gpio pin serves.
00379  *
00380  * Function can be #GPIOx_SELECT_OFF  #GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT.\n
00381  * Same definition apply to register GPIO0 that is used as chip enable at power up.
00382  * @ingroup device_regdef
00383  */
00384 #define SYSTEM_MODE_GPIO1                       0x011
00385     /** gpio pad POLARITY mask in #SYSTEM_MODE_GPIO1 (and/or 0) write  1  to set active high polarity (positive edge) */
00386     #define GPIOx_POLARITY_SELECT_MASK              0x20
00387     /** gpio pad Function select shift in #SYSTEM_MODE_GPIO1 or 0 */
00388     #define GPIOx_FUNCTIONALITY_SELECT_SHIFT          1
00389     /** gpio pad Function select mask in #SYSTEM_MODE_GPIO1 or 0 */
00390     #define GPIOx_FUNCTIONALITY_SELECT_MASK          (0xF<<GPIOx_FUNCTIONALITY_SELECT_SHIFT)
00391     /** select no interrupt in #SYSTEM_MODE_GPIO1 pad is put in  Hi-Z*/
00392     #define GPIOx_SELECT_OFF                        0x00
00393     /** select gpiox as interrupt output in  #SYSTEM_MODE_GPIO1 */
00394     #define GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT      0x08
00395     /** select range as source for interrupt on in #SYSTEM_MODE_GPIO1 */
00396     #define GPIOx_MODE_SELECT_RANGING               0x00
00397     /** select als as source for interrupt on in #SYSTEM_MODE_GPIO1 */
00398     #define GPIOx_MODE_SELECT_ALS                   0x01
00399 
00400 
00401 /**
00402  * @def SYSTEM_INTERRUPT_CONFIG_GPIO
00403  *
00404  * @brief   Configure Als and Ranging interrupt reporting
00405  *
00406  * Possible values for Range and ALS are\n
00407  *
00408  * #CONFIG_GPIO_INTERRUPT_DISABLED\n
00409  * #CONFIG_GPIO_INTERRUPT_LEVEL_LOW\n
00410  * #CONFIG_GPIO_INTERRUPT_LEVEL_HIGH\n
00411  * #CONFIG_GPIO_INTERRUPT_OUT_OF_WINDOW\n
00412  * #CONFIG_GPIO_INTERRUPT_NEW_SAMPLE_READY\n
00413  * Apply respective rang/als shift and mask \n
00414  *  #CONFIG_GPIO_RANGE_SHIFT and full reg mask #CONFIG_GPIO_RANGE_MASK\n
00415  *  #CONFIG_GPIO_ALS_SHIFT and full reg mask #CONFIG_GPIO_ALS_MASK\n
00416  *
00417  * \sa GPIO use for interrupt #SYSTEM_MODE_GPIO0 or #SYSTEM_MODE_GPIO1\n
00418  * @ingroup device_regdef
00419  */
00420 #define SYSTEM_INTERRUPT_CONFIG_GPIO           0x014
00421     /** RANGE bits shift in #SYSTEM_INTERRUPT_CONFIG_GPIO */
00422     #define CONFIG_GPIO_RANGE_SHIFT            0
00423     /** RANGE bits mask in #SYSTEM_INTERRUPT_CONFIG_GPIO  (unshifted)*/
00424     #define CONFIG_GPIO_RANGE_MASK             (0x7<<CONFIG_GPIO_RANGE_SHIFT)
00425     /** ALS bits shift in #SYSTEM_INTERRUPT_CONFIG_GPIO */
00426     #define CONFIG_GPIO_ALS_SHIFT              3
00427     /** ALS bits mask in #SYSTEM_INTERRUPT_CONFIG_GPIO  (unshifted)*/
00428     #define CONFIG_GPIO_ALS_MASK               (0x7<<CONFIG_GPIO_ALS_SHIFT)
00429     /** interrupt is disabled */
00430     #define CONFIG_GPIO_INTERRUPT_DISABLED         0x00
00431     /** trigger when value < low threshold */
00432     #define CONFIG_GPIO_INTERRUPT_LEVEL_LOW        0x01
00433     /** trigger when value < low threshold */
00434     #define CONFIG_GPIO_INTERRUPT_LEVEL_HIGH       0x02
00435     /** trigger when outside range defined by high low threshold */
00436     #define CONFIG_GPIO_INTERRUPT_OUT_OF_WINDOW    0x03
00437     /** trigger when new sample are ready */
00438     #define CONFIG_GPIO_INTERRUPT_NEW_SAMPLE_READY 0x04
00439 
00440 /**
00441  *  @def SYSTEM_INTERRUPT_CLEAR
00442  *  @brief Writing to this register will clear interrupt source
00443  *
00444  *  Use or combination of any #INTERRUPT_CLEAR_RANGING , #INTERRUPT_CLEAR_ALS , #INTERRUPT_CLEAR_ERROR
00445  *  @ingroup device_regdef
00446  */
00447 #define SYSTEM_INTERRUPT_CLEAR                0x015
00448     /** clear ranging interrupt in write to #SYSTEM_INTERRUPT_CLEAR */
00449     #define INTERRUPT_CLEAR_RANGING                0x01
00450     /** clear als interrupt  in write to #SYSTEM_INTERRUPT_CLEAR */
00451     #define INTERRUPT_CLEAR_ALS                    0x02
00452     /** clear error interrupt in write to #SYSTEM_INTERRUPT_CLEAR */
00453     #define INTERRUPT_CLEAR_ERROR                  0x04
00454 
00455 /** After power up or reset this register will start reading 1 when device is ready */
00456 #define SYSTEM_FRESH_OUT_OF_RESET             0x016
00457 
00458 /**
00459  * @def SYSTEM_GROUPED_PARAMETER_HOLD
00460  * @brief Writing 1/0 activate/deactivate safe host update of multiple register in critical group \n
00461  *        rather use \a VL6180x_SetGroupParamHold()
00462  *
00463  * The critical register group is made of: \n
00464  * #SYSTEM_INTERRUPT_CONFIG_GPIO \n
00465  * #SYSRANGE_THRESH_HIGH \n
00466  * #SYSRANGE_THRESH_LOW \n
00467  * #SYSALS_INTEGRATION_PERIOD \n
00468  * #SYSALS_ANALOGUE_GAIN \n
00469  * #SYSALS_THRESH_HIGH \n
00470  * #SYSALS_THRESH_LOW
00471  * @ingroup device_regdef
00472  */
00473 #define SYSTEM_GROUPED_PARAMETER_HOLD         0x017
00474 
00475 
00476 /**
00477  * @def SYSRANGE_START
00478  * @brief Start/stop and set operating range mode
00479  *
00480  * Write Combination of #MODE_START_STOP  and #MODE_CONTINUOUS to select and start desired operation.
00481  *
00482  * @ingroup device_regdef
00483  */
00484 #define SYSRANGE_START                        0x018
00485     /** mask existing bit in #SYSRANGE_START*/
00486     #define SYSRANGE_START_MODE_MASK          0x03
00487     /** bit 0 in #SYSRANGE_START write 1 toggle state in continuous mode and arm next shot in single shot mode */
00488     #define MODE_START_STOP    0x01
00489     /** bit 1 write 1 in #SYSRANGE_START set continuous operation mode */
00490     #define MODE_CONTINUOUS    0x02
00491     /** bit 1 write 0 in #SYSRANGE_START set single shot mode */
00492     #define MODE_SINGLESHOT    0x00
00493 
00494 /**
00495  * @def SYSRANGE_THRESH_HIGH
00496  * High level range  threshold (must be scaled)
00497  * @ingroup device_regdef
00498  */
00499 #define SYSRANGE_THRESH_HIGH                  0x019
00500 
00501 /**
00502  * @def SYSRANGE_THRESH_LOW
00503  * Low level range  threshold (must be scaled)
00504  * @ingroup device_regdef
00505  */
00506 #define SYSRANGE_THRESH_LOW                   0x01A
00507 
00508 /**
00509  * @def SYSRANGE_INTERMEASUREMENT_PERIOD
00510  * @brief Continuous mode intermeasurement delay \a VL6180x_RangeSetInterMeasPeriod()
00511  *
00512  * Time delay between measurements in Ranging continuous mode.\n
00513  * Range 0-254 (0 = 10ms).\n Step size = 10ms.
00514  *
00515  * @ingroup device_regdef
00516  */
00517 #define SYSRANGE_INTERMEASUREMENT_PERIOD      0x01B
00518 
00519 /**
00520  * @brief Maximum time to run measurement in Ranging modes.
00521  * Range 1 - 63 ms (1 code = 1 ms);
00522  *
00523  * Measurement aborted when limit reached to aid power  reduction.\
00524  * For example, 0x01 = 1ms, 0x0a = 10ms.\
00525  * Note: Effective max_convergence_time depends on readout_averaging_sample_period setting.
00526  *
00527  * @ingroup device_regdef
00528  */
00529 #define SYSRANGE_MAX_CONVERGENCE_TIME         0x01C
00530 /**@brief Cross talk compensation rate
00531  * @warning  never write register directly use @a VL6180x_SetXTalkCompensationRate()
00532  * refer to manual for calibration procedure and computation
00533  * @ingroup device_regdef
00534  */
00535 #define SYSRANGE_CROSSTALK_COMPENSATION_RATE  0x01E
00536 /**
00537  * @brief Minimum range value in mm to qualify for crosstalk compensation
00538  */
00539 #define SYSRANGE_CROSSTALK_VALID_HEIGHT       0x021
00540 #define SYSRANGE_EARLY_CONVERGENCE_ESTIMATE   0x022
00541 #define SYSRANGE_PART_TO_PART_RANGE_OFFSET    0x024
00542 /**
00543  * @brief range ignore valid height
00544  * @warning  do not program directly use @a VL6180x_RangeIgnoreConfigure() and @a VL6180x_RangeIgnoreSetEnable()
00545  */
00546 #define SYSRANGE_RANGE_IGNORE_VALID_HEIGHT    0x025
00547 /**
00548  * @brief range ignore threshold
00549  * @warning  do not program directly use @a VL6180x_RangeIgnoreConfigure() and @a VL6180x_RangeIgnoreSetEnable()
00550  */
00551 #define SYSRANGE_RANGE_IGNORE_THRESHOLD       0x026
00552 #define SYSRANGE_EMITTER_BLOCK_THRESHOLD      0x028
00553 #define SYSRANGE_MAX_AMBIENT_LEVEL_THRESH     0x02A
00554 #define SYSRANGE_MAX_AMBIENT_LEVEL_MULT       0x02C
00555 /** @brief  various Enable check enable register
00556  *  @a VL6180x_RangeSetEceState()
00557  *  @a VL6180x_RangeIgnoreConfigure() and @a VL6180x_RangeIgnoreSetEnable()
00558  */
00559 #define SYSRANGE_RANGE_CHECK_ENABLES          0x02D
00560     #define RANGE_CHECK_ECE_ENABLE_MASK      0x01
00561     #define RANGE_CHECK_RANGE_ENABLE_MASK    0x02
00562     #define RANGE_CHECK_SNR_ENABLE           0x10
00563 
00564 #define SYSRANGE_VHV_RECALIBRATE              0x02E
00565 #define SYSRANGE_VHV_REPEAT_RATE              0x031
00566 
00567 /**
00568  * @def SYSALS_START
00569  * @brief Start/stop and set operating als mode
00570  *
00571  * same bit definition as range \a #SYSRANGE_START \n
00572  */
00573 #define SYSALS_START                          0x038
00574 
00575 /** ALS low Threshold high */
00576 #define SYSALS_THRESH_HIGH                    0x03A
00577 /** ALS low Threshold low */
00578 #define SYSALS_THRESH_LOW                     0x03C
00579 /** ALS intermeasurement period */
00580 #define SYSALS_INTERMEASUREMENT_PERIOD        0x03E
00581 /** 
00582  * @warning or value with 0x40 when writing to these register*/
00583 #define SYSALS_ANALOGUE_GAIN                  0x03F
00584 /** ALS integration period */
00585 #define SYSALS_INTEGRATION_PERIOD             0x040
00586 
00587 /**
00588  * @brief Result range status
00589  *
00590  *  Hold the various range interrupt flags and error Specific error codes
00591  */
00592 #define RESULT_RANGE_STATUS                   0x04D
00593     /** Device ready for new command bit 0*/
00594     #define RANGE_DEVICE_READY_MASK       0x01
00595     /** mask for error status covers bits [7:4]  in #RESULT_RANGE_STATUS @a ::RangeError_u */
00596     #define RANGE_ERROR_CODE_MASK         0xF0 /* */
00597     /** range error bit position in #RESULT_RANGE_STATUS */
00598     #define RANGE_ERROR_CODE_SHIFT        4
00599 
00600 /**
00601  * @def RESULT_ALS_STATUS
00602  * @brief Result  als status \n
00603  *  Hold the various als interrupt flags and Specific error codes
00604  */
00605 #define RESULT_ALS_STATUS                     0x4E
00606     /** Device ready for new command bit 0*/
00607    #define ALS_DEVICE_READY_MASK       0x01
00608 
00609 /**
00610  * @def RESULT_ALS_VAL
00611  * @brief 16 Bit ALS count output value.
00612  *
00613  * Lux value depends on Gain and integration settings and calibrated lux/count setting
00614  * \a VL6180x_AlsGetLux() \a VL6180x_AlsGetMeasurement()
00615  */
00616 #define RESULT_ALS_VAL                        0x50
00617 
00618 /**
00619  * @def FW_ALS_RESULT_SCALER
00620  * @brief Als scaler register  Bits [3:0] analogue gain 1 to 16x
00621  * these register content is cached by API in \a VL6180xDevData_t::AlsScaler
00622  * for lux computation acceleration
00623  */
00624 #define FW_ALS_RESULT_SCALER                  0x120
00625 
00626 
00627 /**
00628  * these union can be use as a generic bit field type for map #RESULT_INTERRUPT_STATUS_GPIO register
00629  * @ingroup device_regdef
00630  */
00631 typedef union IntrStatus_u{
00632     uint8_t val ;           /*!< raw 8 bit register value*/
00633     struct  {
00634         unsigned Range      :3; /*!< Range status one of :\n  \a #RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD  \n \a #RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD  \n \a #RES_INT_STAT_GPIO_OUT_OF_WINDOW \n \a #RES_INT_STAT_GPIO_NEW_SAMPLE_READY */
00635         unsigned Als        :3; /*!< Als status one of: \n \a #RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD  \n \a #RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD  \n \a #RES_INT_STAT_GPIO_OUT_OF_WINDOW \n \a #RES_INT_STAT_GPIO_NEW_SAMPLE_READY  */
00636         unsigned Error      :2; /*!<  Error status of: \n \a #RES_INT_ERROR_LASER_SAFETY  \n \a #RES_INT_ERROR_PLL */
00637      } status ;                 /*!< interrupt status as bit field */
00638 } IntrStatus_t;
00639 
00640 /**
00641  * @def RESULT_INTERRUPT_STATUS_GPIO
00642  * @brief System interrupt status report selected interrupt for als and ranging
00643  *
00644  * These register can be polled even if no gpio pins is active\n
00645  * What reported is selected by \a  #SYSTEM_INTERRUPT_CONFIG_GPIO \n
00646  * Range mask with \a #RES_INT_RANGE_MASK and shit by \a #RES_INT_RANGE_SHIFT
00647  * Als   mask with \a #RES_INT_ALS_MASK and shit by \a #RES_INT_ALS_SHIFT
00648  * Result value express condition (or combination?)
00649  * \a #RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD \n
00650  * \a #RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD \n
00651  * \a #RES_INT_STAT_GPIO_OUT_OF_WINDOW \n
00652  * \a #RES_INT_STAT_GPIO_NEW_SAMPLE_READY
00653  *
00654  * @ingroup device_regdef
00655  */
00656 #define RESULT_INTERRUPT_STATUS_GPIO          0x4F
00657     /** ranging interrupt 1st bit position in #RESULT_INTERRUPT_STATUS_GPIO */
00658     #define RES_INT_RANGE_SHIFT  0
00659     /** ALS interrupt 1st bit position in #RESULT_INTERRUPT_STATUS_GPIO */
00660     #define RES_INT_ALS_SHIFT    3
00661     /** interrupt bit position in #RESULT_INTERRUPT_STATUS_GPIO */
00662     #define RES_INT_ERROR_SHIFT  6
00663     /** Ranging interrupt mask in #RESULT_INTERRUPT_STATUS_GPIO (prior to shift)  \sa IntrStatus_t */
00664     #define RES_INT_RANGE_MASK (0x7<<RES_INT_RANGE_SHIFT)
00665     /** als interrupt mask in #RESULT_INTERRUPT_STATUS_GPIO (prior to shift)  \sa IntrStatus_t */
00666     #define RES_INT_ALS_MASK   (0x7<<RES_INT_ALS_SHIFT)
00667 
00668     /** low threshold condition in #RESULT_INTERRUPT_STATUS_GPIO for */
00669     #define RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD  0x01
00670     /** high threshold condition in #RESULT_INTERRUPT_STATUS_GPIO for ALs or Rage*/
00671     #define RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD 0x02
00672     /** out of window condition in #RESULT_INTERRUPT_STATUS_GPIO */
00673     #define RES_INT_STAT_GPIO_OUT_OF_WINDOW        0x03
00674     /** new sample ready in #RESULT_INTERRUPT_STATUS_GPIO */
00675     #define RES_INT_STAT_GPIO_NEW_SAMPLE_READY     0x04
00676     /** error  in #RESULT_INTERRUPT_STATUS_GPIO */
00677     #define RES_INT_ERROR_MASK (0x3<<RES_INT_ERROR_SHIFT)
00678         /** laser safety error on #RES_INT_ERROR_MASK of #RESULT_INTERRUPT_STATUS_GPIO */
00679         #define RES_INT_ERROR_LASER_SAFETY  1
00680         /** pll 1 or 2 error on #RES_INT_ERROR_MASK of #RESULT_INTERRUPT_STATUS_GPIO*/
00681         #define RES_INT_ERROR_PLL           2
00682 
00683 /**
00684  * Final range result value presented to the user for use. Unit is in mm.
00685  */
00686 #define RESULT_RANGE_VAL                        0x062
00687 
00688 /**
00689  * Raw Range result value with offset applied (no cross talk compensation applied). Unit is in mm.
00690  */
00691 #define RESULT_RANGE_RAW                        0x064
00692 
00693 /**
00694  * @brief Sensor count rate of signal returns correlated to IR emitter.
00695  *
00696  * Computed from RETURN_SIGNAL_COUNT / RETURN_CONV_TIME. Mcps 9.7 format
00697  */
00698 #define RESULT_RANGE_SIGNAL_RATE                0x066
00699 
00700 /**
00701  * @brief Return signal count
00702  *
00703  *  Sensor count output value attributed to signal correlated to IR emitter on the Return array.
00704  */
00705 #define RESULT_RANGE_RETURN_SIGNAL_COUNT        0x06C
00706 
00707 /**
00708  * @brief Reference signal count
00709  *
00710  * sensor count output value attributed to signal correlated to IR emitter on the Reference array.
00711  */
00712 #define RESULT_RANGE_REFERENCE_SIGNAL_COUNT     0x070
00713 
00714 /**
00715  * @brief Return ambient count
00716  *
00717  * sensor count output value attributed to uncorrelated ambient signal on the Return array.
00718  * Must be multiplied by 6 if used to calculate the ambient to signal threshold
00719  */
00720 #define RESULT_RANGE_RETURN_AMB_COUNT           0x074
00721 
00722 /**
00723  * @brief   Reference ambient count
00724  *
00725  * Sensor count output value attributed to uncorrelated ambient signal on the Reference array.
00726  */
00727 #define RESULT_RANGE_REFERENCE_AMB_COUNT        0x078
00728 
00729 /**
00730  * sensor count output value attributed to signal on the Return array.
00731  */
00732 #define RESULT_RANGE_RETURN_CONV_TIME           0x07C
00733 
00734 /**
00735  * sensor count output value attributed to signal on the Reference array.
00736  */
00737 #define RESULT_RANGE_REFERENCE_CONV_TIME        0x080
00738 
00739 
00740 /**
00741  * @def RANGE_SCALER
00742  * @brief RANGE scaling register
00743  *
00744  * Never should  user write directly onto that register directly \a VL6180x_UpscaleSetScaling()
00745  */
00746 #define RANGE_SCALER                            0x096
00747 
00748 /**
00749  * @def READOUT_AVERAGING_SAMPLE_PERIOD
00750  * @brief Readout averaging sample period register
00751  *
00752  *
00753  * The internal readout averaging sample period can be adjusted from 0 to 255.
00754  * Increasing the sampling period decreases noise but also reduces the effective
00755  * max convergence time and increases power consumption
00756  * Each unit sample period corresponds to around 64.5 μs additional processing time.
00757  * The recommended setting is 48 which equates to around 4.3 ms.
00758  *
00759  * see datasheet for more detail
00760  */
00761 #define READOUT_AVERAGING_SAMPLE_PERIOD     0x10A
00762 
00763 /**
00764  * @def I2C_SLAVE_DEVICE_ADDRESS
00765  * User programmable I2C address (7-bit). Device address can be re-designated after power-up.
00766  * @warning What programmed in the register 7-0 are bit 8-1 of i2c address on bus (bit 0 is rd/wr)
00767  * so what prohamd is commonly whar ergfer as adrerss /2
00768  * @sa VL6180x_SetI2CAddress()
00769  */
00770 #define I2C_SLAVE_DEVICE_ADDRESS               0x212
00771 
00772 #endif /* _VL6180x_DEF */
00773