/******************************************************************************* Copyright © 2015, STMicroelectronics International N.V. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of STMicroelectronics nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS ARE DISCLAIMED. IN NO EVENT SHALL STMICROELECTRONICS INTERNATIONAL N.V. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ********************************************************************************/ /* * $Date: 2018-07-04 16:49:57 +0200 (Wed, 04 Jul 2018) $ * $Revision: 2768 $ */ /** * @file VL6180x_def.h * * @brief Type definitions for vl6180x api. * */ #ifndef _VL6180x_DEF #define _VL6180x_DEF /** API major version */ #define VL6180x_API_REV_MAJOR 3 /** API minor version */ #define VL6180x_API_REV_MINOR 2 /** API sub version */ #define VL6180x_API_REV_SUB 2 #define VL6180X_STR_HELPER(x) #x #define VL6180X_STR(x) VL6180X_STR_HELPER(x) #include "vl6180x_cfg.h" #include "vl6180x_types.h" /* * check configuration macro raise error or warning and suggest a default value */ #ifndef VL6180x_UPSCALE_SUPPORT #error "VL6180x_UPSCALE_SUPPORT not defined" /* TODO you must define value for upscale support in your vl6180x_cfg.h */ #endif #ifndef VL6180x_ALS_SUPPORT #error "VL6180x_ALS_SUPPORT not defined" /* TODO you must define VL6180x_ALS_SUPPORT with a value in your vl6180x_cfg.h set to 0 do disable*/ #endif #ifndef VL6180x_HAVE_DMAX_RANGING #error "VL6180x_HAVE_DMAX_RANGING not defined" /* TODO you may remove or comment these #error and keep the default below or update your vl6180x_cfg.h .h file */ /** * force VL6180x_HAVE_DMAX_RANGING to not supported when not part of cfg file */ #define VL6180x_HAVE_DMAX_RANGING 0 #endif #ifndef VL6180x_EXTENDED_RANGE #define VL6180x_EXTENDED_RANGE 0 #endif #ifndef VL6180x_WRAP_AROUND_FILTER_SUPPORT #error "VL6180x_WRAP_AROUND_FILTER_SUPPORT not defined ?" /* TODO you may remove or comment these #error and keep the default below or update vl6180x_cfg.h file */ /** * force VL6180x_WRAP_AROUND_FILTER_SUPPORT to not supported when not part of cfg file */ #define VL6180x_WRAP_AROUND_FILTER_SUPPORT 0 #endif #ifndef VL6180x_HAVE_MULTI_READ # define VL6180x_HAVE_MULTI_READ 0 #endif /** * Force VL6180x_CACHED_REG to default 0 when not defined */ #ifndef VL6180x_CACHED_REG # define VL6180x_CACHED_REG 0 #else # define VL6180x_FIRST_CACHED_INDEX 0x04D # define VL6180x_LAST_CACHED_INDEX (VL6180x_FIRST_CACHED_INDEX+55) # define VL6180x_CACHED_REG_CNT (VL6180x_LAST_CACHED_INDEX-VL6180x_FIRST_CACHED_INDEX+1) #endif /**************************************** * PRIVATE define do not edit ****************************************/ /** Maximal buffer size ever use in i2c */ #define VL6180x_MAX_I2C_XFER_SIZE 8 /* At present time it 6 byte max but that can change */ #if VL6180x_UPSCALE_SUPPORT < 0 /** * @def VL6180x_HAVE_UPSCALE_DATA * @brief is defined if device data structure has data so when user configurable up-scale is active */ #define VL6180x_HAVE_UPSCALE_DATA /* have data only for user configurable up-scale config */ #endif #if VL6180x_WRAP_AROUND_FILTER_SUPPORT /** * @def VL6180x_HAVE_WRAP_AROUND_DATA * @brief is defined if device data structure has filter data so when active in cfg file */ #define VL6180x_HAVE_WRAP_AROUND_DATA #endif #if VL6180x_ALS_SUPPORT != 0 /** * @def VL6180x_HAVE_ALS_DATA * @brief is defined when als data are include in device data structure so when als suport if configured */ #define VL6180x_HAVE_ALS_DATA #endif #if VL6180x_WRAP_AROUND_FILTER_SUPPORT || VL6180x_HAVE_DMAX_RANGING #define VL6180x_HAVE_RATE_DATA #endif /** Error and warning code returned by API * * negative value are true error mostly fatal\n * positive value are warning most of time it's ok to continue\n */ enum VL6180x_ErrCode_t { API_NO_ERROR = 0, CALIBRATION_WARNING = 1, /*!< warning invalid calibration data may be in used \a VL6180x_InitData() \a VL6180x_GetOffsetCalibrationData \a VL6180x_SetOffsetCalibrationData*/ MIN_CLIPED = 2, /*!< warning parameter passed was clipped to min before to be applied */ NOT_GUARANTEED = 3, /*!< Correct operation is not guaranteed typically using extended ranging on vl6180x */ API_ERROR = -1, /*!< Unqualified error */ INVALID_PARAMS = -2, /*!< parameter passed is invalid or out of range */ NOT_SUPPORTED = -3, /*!< function is not supported in current mode or configuration */ RANGE_ERROR = -4, /*!< device report a ranging error interrupt status */ TIME_OUT = -5, /*!< aborted due to time out */ }; /** * Filtered result data structure range data is to be used */ typedef struct RangeFilterResult_tag { uint16_t range_mm; /*!< Filtered ranging value */ uint16_t rawRange_mm; /*!< raw range value (scaled) */ uint32_t filterError; /*!< current filter error code */ } RangeFilterResult_t; /** * "small" unsigned data type used in filter * * if data space saving is not a concern it can be change to platform native unsigned int */ typedef uint32_t FilterType1_t; /** * @def FILTER_NBOF_SAMPLES * @brief sample history len used for wrap around filtering */ #define FILTER_NBOF_SAMPLES 10 /** * Wrap around filter internal data */ struct FilterData_t { uint32_t MeasurementIndex; /*!< current measurement index */ uint32_t MeasurementsSinceLastFlush; /*!< Number of measurements done since last time buffer has been flushed */ uint16_t LastTrueRange[FILTER_NBOF_SAMPLES]; /*!< filtered/corrected distance history */ uint32_t LastReturnRates[FILTER_NBOF_SAMPLES]; /*!< Return rate history */ uint16_t StdFilteredReads; /*!< internal use */ FilterType1_t Default_ZeroVal; /*!< internal use */ FilterType1_t Default_VAVGVal; /*!< internal use */ FilterType1_t NoDelay_ZeroVal; /*!< internal use */ FilterType1_t NoDelay_VAVGVal; /*!< internal use */ FilterType1_t Previous_VAVGDiff; /*!< internal use */ uint32_t FilteringOnGoingConsecutiveStates; /*!< internal use */ uint32_t filterError; /*!< current filter error code */ }; #if VL6180x_HAVE_DMAX_RANGING typedef int32_t DMaxFix_t; struct DMaxData_t { uint32_t ambTuningWindowFactor_K; /*!< internal algo tuning (*1000) */ DMaxFix_t retSignalAt400mm; /*!< intermediate dmax computation value caching @a #SYSRANGE_CROSSTALK_COMPENSATION_RATE and private reg 0x02A */ /* int32_t RegB8; */ /*!< register 0xB8 cached to speed reduce i2c traffic for dmax computation */ /* place all word data below to optimize struct packing */ /* int32_t minSignalNeeded; */ /*!< optimized computation intermediate base on register cached value */ int32_t snrLimit_K; /*!< cached and optimized computation intermediate from @a #SYSRANGE_MAX_AMBIENT_LEVEL_MULT */ uint16_t ClipSnrLimit; /*!< Max value for snr limit */ /* place all byte data below to optimize packing */ /* uint8_t MaxConvTime; */ /*!< cached max convergence time @a #SYSRANGE_MAX_CONVERGENCE_TIME*/ }; #endif struct RangeIgnoreData_t { uint16_t ValidHeight; uint16_t IgnoreThreshold; uint8_t Enabled; }; /** * @struct VL6180xDevData_t * * @brief Per VL6180x device St private data structure \n * End user should never access any of these field directly * * These must never access directly but only via VL6180xDev/SetData(dev, field) macro */ struct VL6180xDevData_t { uint32_t Part2PartAmbNVM; /*!< backed up NVM value */ uint32_t XTalkCompRate_KCps; /*! Cached XTlak Compensation Rate */ uint16_t EceFactorM; /*!< Ece Factor M numerator */ uint16_t EceFactorD; /*!< Ece Factor D denominator*/ struct RangeIgnoreData_t RangeIgnore; #ifdef VL6180x_HAVE_ALS_DATA uint16_t IntegrationPeriod; /*!< cached als Integration period avoid slow read from device at each measure */ uint16_t AlsGainCode; /*!< cached Als gain avoid slow read from device at each measure */ uint16_t AlsScaler; /*!< cached Als scaler avoid slow read from device at each measure */ #endif #ifdef VL6180x_HAVE_UPSCALE_DATA uint8_t UpscaleFactor; /*!< up-scaling factor*/ #endif #ifdef VL6180x_HAVE_WRAP_AROUND_DATA uint8_t WrapAroundFilterActive; /*!< Filter on/off */ struct FilterData_t FilterData; /*!< Filter internal data state history ... */ #endif #if VL6180x_CACHED_REG uint8_t CacheFilled; /*!< Set if valid data got fetched use to control when to fill up register cache */ uint8_t CachedRegs[VL6180x_CACHED_REG_CNT]; /*!< Cache register storage */ #endif #if VL6180x_HAVE_DMAX_RANGING struct DMaxData_t DMaxData; uint8_t DMaxEnable; #endif int8_t Part2PartOffsetNVM; /*!< backed up NVM value */ }; /** * @struct VL6180x_RangeData_t * @brief Range and any optional measurement data. */ typedef struct { int32_t range_mm; /*!< range distance in mm. */ int32_t signalRate_mcps; /*!< signal rate (MCPS)\n these is a 9.7 fix point value, which is effectively a measure of target reflectance.*/ uint32_t errorStatus; /*!< Error status of the current measurement. \n see @a ::RangeError_u @a VL6180x_GetRangeStatusErrString() */ #ifdef VL6180x_HAVE_RATE_DATA uint32_t rtnAmbRate; /*!< Return Ambient rate in KCount per sec related to \a RESULT_RANGE_RETURN_AMB_COUNT */ uint32_t rtnRate; /*!< Return rate in KCount per sec related to \a RESULT_RANGE_RETURN_SIGNAL_COUNT */ uint32_t rtnConvTime; /*!< Return Convergence time \a RESULT_RANGE_RETURN_CONV_TIME */ uint32_t refConvTime; /*!< Reference convergence time \a RESULT_RANGE_REFERENCE_CONV_TIME */ #endif #if VL6180x_HAVE_DMAX_RANGING uint32_t DMax; /*!< DMax when applicable */ #endif #ifdef VL6180x_HAVE_WRAP_AROUND_DATA RangeFilterResult_t FilteredData; /*!< Filter result main range_mm is updated */ #endif } VL6180x_RangeData_t; /** use where fix point 9.7 bit values are expected * * given a floating point value f it's .7 bit point is (int)(f*(1<<7))*/ typedef uint16_t FixPoint97_t; /** lux data type */ typedef uint32_t lux_t; /** * @brief This data type defines als measurement data. */ typedef struct VL6180x_AlsData_st { lux_t lux; /**< Light measurement (Lux) */ uint32_t errorStatus; /**< Error status of the current measurement. \n * No Error := 0. \n * Refer to product sheets for other error codes. */ } VL6180x_AlsData_t; /** * @brief Range status Error code * * @a VL6180x_GetRangeStatusErrString() if configured ( @a #VL6180x_RANGE_STATUS_ERRSTRING ) * related to register @a #RESULT_RANGE_STATUS and additional post processing */ typedef enum { NoError = 0, /*!< 0 0b0000 NoError */ VCSEL_Continuity_Test, /*!< 1 0b0001 VCSEL_Continuity_Test */ VCSEL_Watchdog_Test, /*!< 2 0b0010 VCSEL_Watchdog_Test */ VCSEL_Watchdog, /*!< 3 0b0011 VCSEL_Watchdog */ PLL1_Lock, /*!< 4 0b0100 PLL1_Lock */ PLL2_Lock, /*!< 5 0b0101 PLL2_Lock */ Early_Convergence_Estimate,/*!< 6 0b0110 Early_Convergence_Estimate */ Max_Convergence, /*!< 7 0b0111 Max_Convergence */ No_Target_Ignore, /*!< 8 0b1000 No_Target_Ignore */ Not_used_9, /*!< 9 0b1001 Not_used */ Not_used_10, /*!< 10 0b1010 Not_used_ */ Max_Signal_To_Noise_Ratio, /*!< 11 0b1011 Max_Signal_To_Noise_Ratio*/ Raw_Ranging_Algo_Underflow,/*!< 12 0b1100 Raw_Ranging_Algo_Underflow*/ Raw_Ranging_Algo_Overflow, /*!< 13 0b1101 Raw_Ranging_Algo_Overflow */ Ranging_Algo_Underflow, /*!< 14 0b1110 Ranging_Algo_Underflow */ Ranging_Algo_Overflow, /*!< 15 0b1111 Ranging_Algo_Overflow */ /* code below are addition for API/software side they are not hardware*/ RangingFiltered = 0x10, /*!< 16 0b10000 filtered by post processing*/ DataNotReady = 0x12, /*!< 18 0b10011 New data sample not ready */ } RangeError_u; /** @defgroup device_regdef Device registers & masks definitions * @brief Device registers and masks definitions */ /** @ingroup device_regdef * @{*/ /** * The device model ID */ #define IDENTIFICATION_MODEL_ID 0x000 /** * Revision identifier of the Device for major change. */ #define IDENTIFICATION_MODULE_REV_MAJOR 0x003 /** * Revision identifier of the Device for minor change. */ #define IDENTIFICATION_MODULE_REV_MINOR 0x004 /** * @def SYSTEM_MODE_GPIO0 * @brief Configures polarity and select which function gpio 0 serves. * Gpio0 is chip enable at power up ! Be aware of all h/w implication of turning it to output. * Same definition as #SYSTEM_MODE_GPIO1 * @ingroup device_regdef */ #define SYSTEM_MODE_GPIO0 0x010 /** * @def SYSTEM_MODE_GPIO1 * @brief Configures polarity and select what als or ranging functionality gpio pin serves. * * Function can be #GPIOx_SELECT_OFF #GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT.\n * Same definition apply to register GPIO0 that is used as chip enable at power up. * @ingroup device_regdef */ #define SYSTEM_MODE_GPIO1 0x011 /** gpio pad POLARITY mask in #SYSTEM_MODE_GPIO1 (and/or 0) write 1 to set active high polarity (positive edge) */ #define GPIOx_POLARITY_SELECT_MASK 0x20 /** gpio pad Function select shift in #SYSTEM_MODE_GPIO1 or 0 */ #define GPIOx_FUNCTIONALITY_SELECT_SHIFT 1 /** gpio pad Function select mask in #SYSTEM_MODE_GPIO1 or 0 */ #define GPIOx_FUNCTIONALITY_SELECT_MASK (0xF<