/* * vl53l0x_api_def.h - Linux kernel modules for STM VL53L0 FlightSense TOF * sensor * * Copyright (C) 2016 STMicroelectronics Imaging Division. * Copyright (c) 2018, The Linux Foundation. All rights reserved. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. */ /** * @file VL_def.h * * @brief Type definitions for VL53L0X API. * */ #ifndef _VL_DEF_H_ #define _VL_DEF_H_ #ifdef __cplusplus extern "C" { #endif /** @defgroup VL_globaldefine_group VL53L0X Defines * @brief VL53L0X Defines * @{ */ /** PAL SPECIFICATION major version */ #define VL53L0X10_SPECIFICATION_VER_MAJOR 1 /** PAL SPECIFICATION minor version */ #define VL53L0X10_SPECIFICATION_VER_MINOR 2 /** PAL SPECIFICATION sub version */ #define VL53L0X10_SPECIFICATION_VER_SUB 7 /** PAL SPECIFICATION sub version */ #define VL53L0X10_SPECIFICATION_VER_REVISION 1440 /** VL53L0X PAL IMPLEMENTATION major version */ #define VL53L0X10_IMPLEMENTATION_VER_MAJOR 1 /** VL53L0X PAL IMPLEMENTATION minor version */ #define VL53L0X10_IMPLEMENTATION_VER_MINOR 0 /** VL53L0X PAL IMPLEMENTATION sub version */ #define VL53L0X10_IMPLEMENTATION_VER_SUB 9 /** VL53L0X PAL IMPLEMENTATION sub version */ #define VL53L0X10_IMPLEMENTATION_VER_REVISION 3673 /** PAL SPECIFICATION major version */ #define VL_SPECIFICATION_VER_MAJOR 1 /** PAL SPECIFICATION minor version */ #define VL_SPECIFICATION_VER_MINOR 2 /** PAL SPECIFICATION sub version */ #define VL_SPECIFICATION_VER_SUB 7 /** PAL SPECIFICATION sub version */ #define VL_SPECIFICATION_VER_REVISION 1440 /** VL53L0X PAL IMPLEMENTATION major version */ #define VL_IMPLEMENTATION_VER_MAJOR 1 /** VL53L0X PAL IMPLEMENTATION minor version */ #define VL_IMPLEMENTATION_VER_MINOR 0 /** VL53L0X PAL IMPLEMENTATION sub version */ #define VL_IMPLEMENTATION_VER_SUB 2 /** VL53L0X PAL IMPLEMENTATION sub version */ #define VL_IMPLEMENTATION_VER_REVISION 4823 #define VL_DEFAULT_MAX_LOOP 2000 #define VL_MAX_STRING_LENGTH 32 #include "vl53l0x_device.h" #include "vl53l0x_types.h" /**************************************** * PRIVATE define do not edit ****************************************/ /** @brief Defines the parameters of the Get Version Functions */ struct VL_Version_t { uint32_t revision; /*!< revision number */ uint8_t major; /*!< major number */ uint8_t minor; /*!< minor number */ uint8_t build; /*!< build number */ }; /** @brief Defines the parameters of the Get Device Info Functions */ struct VL_DeviceInfo_t { char Name[VL_MAX_STRING_LENGTH]; /*!< Name of the Device e.g. Left_Distance */ char Type[VL_MAX_STRING_LENGTH]; /*!< Type of the Device e.g VL53L0X */ char ProductId[VL_MAX_STRING_LENGTH]; /*!< Product Identifier String */ uint8_t ProductType; /*!< Product Type, VL53L0X = 1, VL53L1 = 2 */ uint8_t ProductRevisionMajor; /*!< Product revision major */ uint8_t ProductRevisionMinor; /*!< Product revision minor */ }; /** @defgroup VL_define_Error_group Error and Warning code returned by API * The following DEFINE are used to identify the PAL ERROR * @{ */ #define VL_ERROR_NONE ((int8_t) 0) #define VL_ERROR_CALIBRATION_WARNING ((int8_t) -1) /*!< Warning invalid calibration data may be in used \a VL_InitData() \a VL_GetOffsetCalibrationData \a VL_SetOffsetCalibrationData */ #define VL_ERROR_MIN_CLIPPED ((int8_t) -2) /*!< Warning parameter passed was clipped to min before to be applied */ #define VL_ERROR_UNDEFINED ((int8_t) -3) /*!< Unqualified error */ #define VL_ERROR_INVALID_PARAMS ((int8_t) -4) /*!< Parameter passed is invalid or out of range */ #define VL_ERROR_NOT_SUPPORTED ((int8_t) -5) /*!< Function is not supported in current mode or configuration */ #define VL_ERROR_RANGE_ERROR ((int8_t) -6) /*!< Device report a ranging error interrupt status */ #define VL_ERROR_TIME_OUT ((int8_t) -7) /*!< Aborted due to time out */ #define VL_ERROR_MODE_NOT_SUPPORTED ((int8_t) -8) /*!< Asked mode is not supported by the device */ #define VL_ERROR_BUFFER_TOO_SMALL ((int8_t) -9) /*!< ... */ #define VL_ERROR_GPIO_NOT_EXISTING ((int8_t) -10) /*!< User tried to setup a non-existing GPIO pin */ #define VL_ERROR_GPIO_FUNCTIONALITY_NOT_SUPPORTED ((int8_t) -11) /*!< unsupported GPIO functionality */ #define VL_ERROR_INTERRUPT_NOT_CLEARED ((int8_t) -12) /*!< Error during interrupt clear */ #define VL_ERROR_CONTROL_INTERFACE ((int8_t) -20) /*!< error reported from IO functions */ #define VL_ERROR_INVALID_COMMAND ((int8_t) -30) /*!< The command is not allowed in the current device state * (power down) */ #define VL_ERROR_DIVISION_BY_ZERO ((int8_t) -40) /*!< In the function a division by zero occurs */ #define VL_ERROR_REF_SPAD_INIT ((int8_t) -50) /*!< Error during reference SPAD initialization */ #define VL_ERROR_NOT_IMPLEMENTED ((int8_t) -99) /*!< Tells requested functionality has not been implemented yet or * not compatible with the device */ /** @} VL_define_Error_group */ /** @defgroup VL_define_DeviceModes_group Defines Device modes * Defines all possible modes for the device * @{ */ #define VL_DEVICEMODE_SINGLE_RANGING ((uint8_t) 0) #define VL_DEVICEMODE_CONTINUOUS_RANGING ((uint8_t) 1) #define VL_DEVICEMODE_SINGLE_HISTOGRAM ((uint8_t) 2) #define VL_DEVICEMODE_CONTINUOUS_TIMED_RANGING ((uint8_t) 3) #define VL_DEVICEMODE_SINGLE_ALS ((uint8_t) 10) #define VL_DEVICEMODE_GPIO_DRIVE ((uint8_t) 20) #define VL_DEVICEMODE_GPIO_OSC ((uint8_t) 21) /* ... Modes to be added depending on device */ /** @} VL_define_DeviceModes_group */ /** @defgroup VL_define_HistogramModes_group Defines Histogram modes * Defines all possible Histogram modes for the device * @{ */ #define VL_HISTOGRAMMODE_DISABLED ((uint8_t) 0) /*!< Histogram Disabled */ #define VL_HISTOGRAMMODE_REFERENCE_ONLY ((uint8_t) 1) /*!< Histogram Reference array only */ #define VL_HISTOGRAMMODE_RETURN_ONLY ((uint8_t) 2) /*!< Histogram Return array only */ #define VL_HISTOGRAMMODE_BOTH ((uint8_t) 3) /*!< Histogram both Reference and Return Arrays */ /* ... Modes to be added depending on device */ /** @} VL_define_HistogramModes_group */ /** @defgroup VL_define_PowerModes_group List of available Power Modes * List of available Power Modes * @{ */ #define VL_POWERMODE_STANDBY_LEVEL1 ((uint8_t) 0) /*!< Standby level 1 */ #define VL_POWERMODE_STANDBY_LEVEL2 ((uint8_t) 1) /*!< Standby level 2 */ #define VL_POWERMODE_IDLE_LEVEL1 ((uint8_t) 2) /*!< Idle level 1 */ #define VL_POWERMODE_IDLE_LEVEL2 ((uint8_t) 3) /*!< Idle level 2 */ /** @} VL_define_PowerModes_group */ /** @brief Defines all parameters for the device */ struct VL_DeviceParameters_t { uint8_t DeviceMode; /*!< Defines type of measurement to be done for the next measure */ uint8_t HistogramMode; /*!< Defines type of histogram measurement to be done for the next * measure */ uint32_t MeasurementTimingBudgetMicroSeconds; /*!< Defines the allowed total time for a single measurement */ uint32_t InterMeasurementPeriodMilliSeconds; /*!< Defines time between two consecutive measurements (between two * measurement starts). If set to 0 means back-to-back mode */ uint8_t XTalkCompensationEnable; /*!< Tells if Crosstalk compensation shall be enable or not */ uint16_t XTalkCompensationRangeMilliMeter; /*!< CrossTalk compensation range in millimeter */ unsigned int XTalkCompensationRateMegaCps; /*!< CrossTalk compensation rate in Mega counts per seconds. * Expressed in 16.16 fixed point format. */ int32_t RangeOffsetMicroMeters; /*!< Range offset adjustment (mm). */ uint8_t LimitChecksEnable[VL_CHECKENABLE_NUMBER_OF_CHECKS]; /*!< This Array store all the Limit Check enable for this device. */ uint8_t LimitChecksStatus[VL_CHECKENABLE_NUMBER_OF_CHECKS]; /*!< This Array store all the Status of the check linked to last * measurement. */ unsigned int LimitChecksValue[VL_CHECKENABLE_NUMBER_OF_CHECKS]; /*!< This Array store all the Limit Check value for this device */ uint8_t WrapAroundCheckEnable; /*!< Tells if Wrap Around Check shall be enable or not */ }; /** @defgroup VL_define_State_group Defines the current status * of the device Defines the current status of the device * @{ */ #define VL_STATE_POWERDOWN ((uint8_t) 0) /*!< Device is in HW reset */ #define VL_STATE_WAIT_STATICINIT ((uint8_t) 1) /*!< Device is initialized and wait for static initialization */ #define VL_STATE_STANDBY ((uint8_t) 2) /*!< Device is in Low power Standby mode */ #define VL_STATE_IDLE ((uint8_t) 3) /*!< Device has been initialized and ready to do measurements */ #define VL_STATE_RUNNING ((uint8_t) 4) /*!< Device is performing measurement */ #define VL_STATE_UNKNOWN ((uint8_t) 98) /*!< Device is in unknown state and need to be rebooted */ #define VL_STATE_ERROR ((uint8_t) 99) /*!< Device is in error state and need to be rebooted */ /** @} VL_define_State_group */ /** @brief Structure containing the Dmax computation parameters and data */ struct VL_DMaxData_t { int32_t AmbTuningWindowFactor_K; /*!< internal algo tuning (*1000) */ int32_t RetSignalAt0mm; /*!< intermediate dmax computation value caching */ }; /** * @struct VL_RangeData_t * @brief Range measurement data. */ struct VL_RangingMeasurementData_t { uint32_t TimeStamp; /*!< 32-bit time stamp. */ uint32_t MeasurementTimeUsec; /*!< Give the Measurement time needed by the device to do the * measurement.*/ uint16_t RangeMilliMeter; /*!< range distance in millimeter. */ uint16_t RangeDMaxMilliMeter; /*!< Tells what is the maximum detection distance of the device * in current setup and environment conditions (Filled when * applicable) */ unsigned int SignalRateRtnMegaCps; /*!< Return signal rate (MCPS)\n these is a 16.16 fix point * value, which is effectively a measure of target * reflectance.*/ unsigned int AmbientRateRtnMegaCps; /*!< Return ambient rate (MCPS)\n these is a 16.16 fix point * value, which is effectively a measure of the ambien * t light.*/ uint16_t EffectiveSpadRtnCount; /*!< Return the effective SPAD count for the return signal. * To obtain Real value it should be divided by 256 */ uint8_t ZoneId; /*!< Denotes which zone and range scheduler stage the range * data relates to. */ uint8_t RangeFractionalPart; /*!< Fractional part of range distance. Final value is a * FixPoint168 value. */ uint8_t RangeStatus; /*!< Range Status for the current measurement. This is device * dependent. Value = 0 means value is valid. * See \ref RangeStatusPage */ }; #define VL_HISTOGRAM_BUFFER_SIZE 24 /** * @struct VL_HistogramData_t * @brief Histogram measurement data. */ struct VL_HistogramMeasurementData_t { /* Histogram Measurement data */ uint32_t HistogramData[VL_HISTOGRAM_BUFFER_SIZE]; /*!< Histogram data */ uint8_t HistogramType; /*!< Indicate the types of histogram data : Return only, Reference only, both Return and Reference */ uint8_t FirstBin; /*!< First Bin value */ uint8_t BufferSize; /*!< Buffer Size - Set by the user.*/ uint8_t NumberOfBins; /*!< Number of bins filled by the histogram measurement */ uint8_t ErrorStatus; /*!< Error status of the current measurement. \n see @a ::uint8_t @a VL_GetStatusErrorString() */ }; #define VL_REF_SPAD_BUFFER_SIZE 6 /** * @struct VL_SpadData_t * @brief Spad Configuration Data. */ struct VL_SpadData_t { uint8_t RefSpadEnables[VL_REF_SPAD_BUFFER_SIZE]; /*!< Reference Spad Enables */ uint8_t RefGoodSpadMap[VL_REF_SPAD_BUFFER_SIZE]; /*!< Reference Spad Good Spad Map */ }; struct VL_DeviceSpecificParameters_t { unsigned int OscFrequencyMHz; /* Frequency used */ uint16_t LastEncodedTimeout; /* last encoded Time out used for timing budget*/ uint8_t Pin0GpioFunctionality; /* store the functionality of the GPIO: pin0 */ uint32_t FinalRangeTimeoutMicroSecs; /*!< Execution time of the final range*/ uint8_t FinalRangeVcselPulsePeriod; /*!< Vcsel pulse period (pll clocks) for the final range measurement*/ uint32_t PreRangeTimeoutMicroSecs; /*!< Execution time of the final range*/ uint8_t PreRangeVcselPulsePeriod; /*!< Vcsel pulse period (pll clocks) for the pre-range measurement*/ uint16_t SigmaEstRefArray; /*!< Reference array sigma value in 1/100th of [mm] e.g. 100 = 1mm */ uint16_t SigmaEstEffPulseWidth; /*!< Effective Pulse width for sigma estimate in 1/100th * of ns e.g. 900 = 9.0ns */ uint16_t SigmaEstEffAmbWidth; /*!< Effective Ambient width for sigma estimate in 1/100th of ns * e.g. 500 = 5.0ns */ uint8_t ReadDataFromDeviceDone; /* Indicate if read from device has been done (==1) or not (==0) */ uint8_t ModuleId; /* Module ID */ uint8_t Revision; /* test Revision */ char ProductId[VL_MAX_STRING_LENGTH]; /* Product Identifier String */ uint8_t ReferenceSpadCount; /* used for ref spad management */ uint8_t ReferenceSpadType; /* used for ref spad management */ uint8_t RefSpadsInitialised; /* reports if ref spads are initialised. */ uint32_t PartUIDUpper; /*!< Unique Part ID Upper */ uint32_t PartUIDLower; /*!< Unique Part ID Lower */ unsigned int SignalRateMeasFixed400mm; /*!< Peek Signal rate at 400 mm*/ }; /** * @struct VL_DevData_t * * @brief VL53L0X PAL device ST private data structure \n * End user should never access any of these field directly * * These must never access directly but only via macro */ struct VL_DevData_t { struct VL_DMaxData_t DMaxData; /*!< Dmax Data */ int32_t Part2PartOffsetNVMMicroMeter; /*!< backed up NVM value */ int32_t Part2PartOffsetAdjustmentNVMMicroMeter; /*!< backed up NVM value representing additional offset adjustment */ struct VL_DeviceParameters_t CurrentParameters; /*!< Current Device Parameter */ struct VL_RangingMeasurementData_t LastRangeMeasure; /*!< Ranging Data */ struct VL_HistogramMeasurementData_t LastHistogramMeasure; /*!< Histogram Data */ struct VL_DeviceSpecificParameters_t DeviceSpecificParameters; /*!< Parameters specific to the device */ struct VL_SpadData_t SpadData; /*!< Spad Data */ uint8_t SequenceConfig; /*!< Internal value for the sequence config */ uint8_t RangeFractionalEnable; /*!< Enable/Disable fractional part of ranging data */ uint8_t PalState; /*!< Current state of the PAL for this device */ uint8_t PowerMode; /*!< Current Power Mode */ uint16_t SigmaEstRefArray; /*!< Reference array sigma value in 1/100th of [mm] e.g. 100 = 1mm */ uint16_t SigmaEstEffPulseWidth; /*!< Effective Pulse width for sigma estimate in 1/100th * of ns e.g. 900 = 9.0ns */ uint16_t SigmaEstEffAmbWidth; /*!< Effective Ambient width for sigma estimate in 1/100th of ns * e.g. 500 = 5.0ns */ uint8_t StopVariable; /*!< StopVariable used during the stop sequence */ uint16_t targetRefRate; /*!< Target Ambient Rate for Ref spad management */ unsigned int SigmaEstimate; /*!< Sigma Estimate - based on ambient & VCSEL rates and * signal_total_events */ unsigned int SignalEstimate; /*!< Signal Estimate - based on ambient & VCSEL rates and cross talk */ unsigned int LastSignalRefMcps; /*!< Latest Signal ref in Mcps */ uint8_t *pTuningSettingsPointer; /*!< Pointer for Tuning Settings table */ uint8_t UseInternalTuningSettings; /*!< Indicate if we use Tuning Settings table */ uint16_t LinearityCorrectiveGain; /*!< Linearity Corrective Gain value in x1000 */ uint16_t DmaxCalRangeMilliMeter; /*!< Dmax Calibration Range millimeter */ unsigned int DmaxCalSignalRateRtnMegaCps; /*!< Dmax Calibration Signal Rate Return MegaCps */ }; /** @defgroup VL_define_InterruptPolarity_group Defines the Polarity * of the Interrupt * Defines the Polarity of the Interrupt * @{ */ #define VL_INTERRUPTPOLARITY_LOW ((uint8_t) 0) /*!< Set active low polarity best setup for falling edge. */ #define VL_INTERRUPTPOLARITY_HIGH ((uint8_t) 1) /*!< Set active high polarity best setup for rising edge. */ /** @} VL_define_InterruptPolarity_group */ /** @defgroup VL_define_VcselPeriod_group Vcsel Period Defines * Defines the range measurement for which to access the vcsel period. * @{ */ #define VL_VCSEL_PERIOD_PRE_RANGE ((uint8_t) 0) /*!>9)&0xFFFF) #define VL_FIXPOINT97TOFIXPOINT1616(Value) \ (unsigned int)(Value<<9) #define VL_FIXPOINT1616TOFIXPOINT88(Value) \ (uint16_t)((Value>>8)&0xFFFF) #define VL_FIXPOINT88TOFIXPOINT1616(Value) \ (unsigned int)(Value<<8) #define VL_FIXPOINT1616TOFIXPOINT412(Value) \ (uint16_t)((Value>>4)&0xFFFF) #define VL_FIXPOINT412TOFIXPOINT1616(Value) \ (unsigned int)(Value<<4) #define VL_FIXPOINT1616TOFIXPOINT313(Value) \ (uint16_t)((Value>>3)&0xFFFF) #define VL_FIXPOINT313TOFIXPOINT1616(Value) \ (unsigned int)(Value<<3) #define VL_FIXPOINT1616TOFIXPOINT08(Value) \ (uint8_t)((Value>>8)&0x00FF) #define VL_FIXPOINT08TOFIXPOINT1616(Value) \ (unsigned int)(Value<<8) #define VL_FIXPOINT1616TOFIXPOINT53(Value) \ (uint8_t)((Value>>13)&0x00FF) #define VL_FIXPOINT53TOFIXPOINT1616(Value) \ (unsigned int)(Value<<13) #define VL_FIXPOINT1616TOFIXPOINT102(Value) \ (uint16_t)((Value>>14)&0x0FFF) #define VL_FIXPOINT102TOFIXPOINT1616(Value) \ (unsigned int)(Value<<12) #define VL_MAKEUINT16(lsb, msb) (uint16_t)((((uint16_t)msb)<<8) + \ (uint16_t)lsb) /** @} VL_define_GeneralMacro_group */ /** @} VL_globaldefine_group */ #ifdef __cplusplus } #endif #endif /* _VL_DEF_H_ */