VL53L0X API Specification: vl53l0x_def.h Source File

VL53L0X API

VL53L0X API Specification

1.0.2.4823
 /*******************************************************************************
 Copyright � 2016, 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.
 *******************************************************************************/
 
 #ifndef _VL53L0X_DEF_H_
 #define _VL53L0X_DEF_H_
 
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #define VL53L0X10_SPECIFICATION_VER_MAJOR 1
 
 #define VL53L0X10_SPECIFICATION_VER_MINOR 2
 
 #define VL53L0X10_SPECIFICATION_VER_SUB 7
 
 #define VL53L0X10_SPECIFICATION_VER_REVISION 1440
 
 #define VL53L0X10_IMPLEMENTATION_VER_MAJOR 1
 
 #define VL53L0X10_IMPLEMENTATION_VER_MINOR 0
 
 #define VL53L0X10_IMPLEMENTATION_VER_SUB 9
 
 #define VL53L0X10_IMPLEMENTATION_VER_REVISION 3673
 
 #define VL53L0X_SPECIFICATION_VER_MAJOR 1
 
 #define VL53L0X_SPECIFICATION_VER_MINOR 2
 
 #define VL53L0X_SPECIFICATION_VER_SUB 7
 
 #define VL53L0X_SPECIFICATION_VER_REVISION 1440
 
 #define VL53L0X_IMPLEMENTATION_VER_MAJOR 1
 
 #define VL53L0X_IMPLEMENTATION_VER_MINOR 0
 
 #define VL53L0X_IMPLEMENTATION_VER_SUB 2
 
 #define VL53L0X_IMPLEMENTATION_VER_REVISION 4823
 #define VL53L0X_DEFAULT_MAX_LOOP 2000
 #define VL53L0X_MAX_STRING_LENGTH 32
 
 
 #include "vl53l0x_device.h"
 #include "vl53l0x_types.h"
 
 
 /****************************************
  * PRIVATE define do not edit
  ****************************************/
 
 typedef struct {
  uint32_t revision; 
  uint8_t major; 
  uint8_t minor; 
  uint8_t build; 
 } VL53L0X_Version_t;
 
 
 typedef struct {
  char Name[VL53L0X_MAX_STRING_LENGTH];
  char Type[VL53L0X_MAX_STRING_LENGTH];
  char ProductId[VL53L0X_MAX_STRING_LENGTH];
  uint8_t ProductType;
  uint8_t ProductRevisionMajor;
  uint8_t ProductRevisionMinor;
 } VL53L0X_DeviceInfo_t;
 
 
 typedef int8_t VL53L0X_Error;
 
 #define VL53L0X_ERROR_NONE ((VL53L0X_Error) 0)
 #define VL53L0X_ERROR_CALIBRATION_WARNING ((VL53L0X_Error) -1)
 
 #define VL53L0X_ERROR_MIN_CLIPPED ((VL53L0X_Error) -2)
 
 #define VL53L0X_ERROR_UNDEFINED ((VL53L0X_Error) -3)
 
 #define VL53L0X_ERROR_INVALID_PARAMS ((VL53L0X_Error) -4)
 
 #define VL53L0X_ERROR_NOT_SUPPORTED ((VL53L0X_Error) -5)
 
 #define VL53L0X_ERROR_RANGE_ERROR ((VL53L0X_Error) -6)
 
 #define VL53L0X_ERROR_TIME_OUT ((VL53L0X_Error) -7)
 
 #define VL53L0X_ERROR_MODE_NOT_SUPPORTED ((VL53L0X_Error) -8)
 
 #define VL53L0X_ERROR_BUFFER_TOO_SMALL ((VL53L0X_Error) -9)
 
 #define VL53L0X_ERROR_GPIO_NOT_EXISTING ((VL53L0X_Error) -10)
 
 #define VL53L0X_ERROR_GPIO_FUNCTIONALITY_NOT_SUPPORTED ((VL53L0X_Error) -11)
 
 #define VL53L0X_ERROR_INTERRUPT_NOT_CLEARED ((VL53L0X_Error) -12)
 
 #define VL53L0X_ERROR_CONTROL_INTERFACE ((VL53L0X_Error) -20)
 
 #define VL53L0X_ERROR_INVALID_COMMAND ((VL53L0X_Error) -30)
 
 #define VL53L0X_ERROR_DIVISION_BY_ZERO ((VL53L0X_Error) -40)
 
 #define VL53L0X_ERROR_REF_SPAD_INIT ((VL53L0X_Error) -50)
 
 #define VL53L0X_ERROR_NOT_IMPLEMENTED ((VL53L0X_Error) -99)
 
 typedef uint8_t VL53L0X_DeviceModes;
 
 #define VL53L0X_DEVICEMODE_SINGLE_RANGING ((VL53L0X_DeviceModes) 0)
 #define VL53L0X_DEVICEMODE_CONTINUOUS_RANGING ((VL53L0X_DeviceModes) 1)
 #define VL53L0X_DEVICEMODE_SINGLE_HISTOGRAM ((VL53L0X_DeviceModes) 2)
 #define VL53L0X_DEVICEMODE_CONTINUOUS_TIMED_RANGING ((VL53L0X_DeviceModes) 3)
 #define VL53L0X_DEVICEMODE_SINGLE_ALS ((VL53L0X_DeviceModes) 10)
 #define VL53L0X_DEVICEMODE_GPIO_DRIVE ((VL53L0X_DeviceModes) 20)
 #define VL53L0X_DEVICEMODE_GPIO_OSC ((VL53L0X_DeviceModes) 21)
  /* ... Modes to be added depending on device */
 typedef uint8_t VL53L0X_HistogramModes;
 
 #define VL53L0X_HISTOGRAMMODE_DISABLED ((VL53L0X_HistogramModes) 0)
 
 #define VL53L0X_HISTOGRAMMODE_REFERENCE_ONLY ((VL53L0X_HistogramModes) 1)
 
 #define VL53L0X_HISTOGRAMMODE_RETURN_ONLY ((VL53L0X_HistogramModes) 2)
 
 #define VL53L0X_HISTOGRAMMODE_BOTH ((VL53L0X_HistogramModes) 3)
 
  /* ... Modes to be added depending on device */
 typedef uint8_t VL53L0X_PowerModes;
 
 #define VL53L0X_POWERMODE_STANDBY_LEVEL1 ((VL53L0X_PowerModes) 0)
 
 #define VL53L0X_POWERMODE_STANDBY_LEVEL2 ((VL53L0X_PowerModes) 1)
 
 #define VL53L0X_POWERMODE_IDLE_LEVEL1 ((VL53L0X_PowerModes) 2)
 
 #define VL53L0X_POWERMODE_IDLE_LEVEL2 ((VL53L0X_PowerModes) 3)
 
 typedef struct {
  VL53L0X_DeviceModes DeviceMode;
  VL53L0X_HistogramModes HistogramMode;
  uint32_t MeasurementTimingBudgetMicroSeconds;
  uint32_t InterMeasurementPeriodMilliSeconds;
  uint8_t XTalkCompensationEnable;
  uint16_t XTalkCompensationRangeMilliMeter;
  FixPoint1616_t XTalkCompensationRateMegaCps;
  int32_t RangeOffsetMicroMeters;
  uint8_t LimitChecksEnable[VL53L0X_CHECKENABLE_NUMBER_OF_CHECKS];
  uint8_t LimitChecksStatus[VL53L0X_CHECKENABLE_NUMBER_OF_CHECKS];
  FixPoint1616_t LimitChecksValue[VL53L0X_CHECKENABLE_NUMBER_OF_CHECKS];
  uint8_t WrapAroundCheckEnable;
 } VL53L0X_DeviceParameters_t;
 
 
 typedef uint8_t VL53L0X_State;
 
 #define VL53L0X_STATE_POWERDOWN ((VL53L0X_State) 0)
 
 #define VL53L0X_STATE_WAIT_STATICINIT ((VL53L0X_State) 1)
 
 #define VL53L0X_STATE_STANDBY ((VL53L0X_State) 2)
 
 #define VL53L0X_STATE_IDLE ((VL53L0X_State) 3)
 
 #define VL53L0X_STATE_RUNNING ((VL53L0X_State) 4)
 
 #define VL53L0X_STATE_UNKNOWN ((VL53L0X_State) 98)
 
 #define VL53L0X_STATE_ERROR ((VL53L0X_State) 99)
 
 typedef struct {
  int32_t AmbTuningWindowFactor_K;
  int32_t RetSignalAt0mm;
 } VL53L0X_DMaxData_t;
 
 typedef struct {
  uint32_t TimeStamp; 
  uint32_t MeasurementTimeUsec;
  uint16_t RangeMilliMeter; 
  uint16_t RangeDMaxMilliMeter;
  FixPoint1616_t SignalRateRtnMegaCps;
  FixPoint1616_t AmbientRateRtnMegaCps;
  uint16_t EffectiveSpadRtnCount;
  uint8_t ZoneId;
  uint8_t RangeFractionalPart;
  uint8_t RangeStatus;
 } VL53L0X_RangingMeasurementData_t;
 
 
 #define VL53L0X_HISTOGRAM_BUFFER_SIZE 24
 
 typedef struct {
  /* Histogram Measurement data */
  uint32_t HistogramData[VL53L0X_HISTOGRAM_BUFFER_SIZE];
  uint8_t HistogramType; 
  uint8_t FirstBin; 
  uint8_t BufferSize; 
  uint8_t NumberOfBins;
  VL53L0X_DeviceError ErrorStatus;
 } VL53L0X_HistogramMeasurementData_t;
 
 #define VL53L0X_REF_SPAD_BUFFER_SIZE 6
 
 typedef struct {
  uint8_t RefSpadEnables[VL53L0X_REF_SPAD_BUFFER_SIZE];
  uint8_t RefGoodSpadMap[VL53L0X_REF_SPAD_BUFFER_SIZE];
 } VL53L0X_SpadData_t;
 
 typedef struct {
  FixPoint1616_t OscFrequencyMHz; /* Frequency used */
 
  uint16_t LastEncodedTimeout;
  /* last encoded Time out used for timing budget*/
 
  VL53L0X_GpioFunctionality Pin0GpioFunctionality;
  /* store the functionality of the GPIO: pin0 */
 
  uint32_t FinalRangeTimeoutMicroSecs;
  uint8_t FinalRangeVcselPulsePeriod;
  uint32_t PreRangeTimeoutMicroSecs;
  uint8_t PreRangeVcselPulsePeriod;
  uint16_t SigmaEstRefArray;
  uint16_t SigmaEstEffPulseWidth;
  uint16_t SigmaEstEffAmbWidth;
  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[VL53L0X_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; 
  uint32_t PartUIDLower; 
  FixPoint1616_t SignalRateMeasFixed400mm; 
 } VL53L0X_DeviceSpecificParameters_t;
 
 typedef struct {
  VL53L0X_DMaxData_t DMaxData;
  int32_t Part2PartOffsetNVMMicroMeter;
  int32_t Part2PartOffsetAdjustmentNVMMicroMeter;
  VL53L0X_DeviceParameters_t CurrentParameters;
  VL53L0X_RangingMeasurementData_t LastRangeMeasure;
  VL53L0X_HistogramMeasurementData_t LastHistogramMeasure;
  VL53L0X_DeviceSpecificParameters_t DeviceSpecificParameters;
  VL53L0X_SpadData_t SpadData;
  uint8_t SequenceConfig;
  uint8_t RangeFractionalEnable;
  VL53L0X_State PalState;
  VL53L0X_PowerModes PowerMode;
  uint16_t SigmaEstRefArray;
  uint16_t SigmaEstEffPulseWidth;
  uint16_t SigmaEstEffAmbWidth;
  uint8_t StopVariable;
  uint16_t targetRefRate;
  FixPoint1616_t SigmaEstimate;
  FixPoint1616_t SignalEstimate;
  FixPoint1616_t LastSignalRefMcps;
  uint8_t *pTuningSettingsPointer;
  uint8_t UseInternalTuningSettings;
  uint16_t LinearityCorrectiveGain;
  uint16_t DmaxCalRangeMilliMeter;
  FixPoint1616_t DmaxCalSignalRateRtnMegaCps;
 } VL53L0X_DevData_t;
 
 
 typedef uint8_t VL53L0X_InterruptPolarity;
 
 #define VL53L0X_INTERRUPTPOLARITY_LOW ((VL53L0X_InterruptPolarity) 0)
 
 #define VL53L0X_INTERRUPTPOLARITY_HIGH ((VL53L0X_InterruptPolarity) 1)
 
 typedef uint8_t VL53L0X_VcselPeriod;
 
 #define VL53L0X_VCSEL_PERIOD_PRE_RANGE ((VL53L0X_VcselPeriod) 0)
 
 #define VL53L0X_VCSEL_PERIOD_FINAL_RANGE ((VL53L0X_VcselPeriod) 1)
 
 typedef struct {
  uint8_t TccOn; 
  uint8_t MsrcOn; 
  uint8_t DssOn; 
  uint8_t PreRangeOn; 
  uint8_t FinalRangeOn; 
 } VL53L0X_SchedulerSequenceSteps_t;
 
 typedef uint8_t VL53L0X_SequenceStepId;
 
 #define VL53L0X_SEQUENCESTEP_TCC ((VL53L0X_VcselPeriod) 0)
 
 #define VL53L0X_SEQUENCESTEP_DSS ((VL53L0X_VcselPeriod) 1)
 
 #define VL53L0X_SEQUENCESTEP_MSRC ((VL53L0X_VcselPeriod) 2)
 
 #define VL53L0X_SEQUENCESTEP_PRE_RANGE ((VL53L0X_VcselPeriod) 3)
 
 #define VL53L0X_SEQUENCESTEP_FINAL_RANGE ((VL53L0X_VcselPeriod) 4)
 
 #define VL53L0X_SEQUENCESTEP_NUMBER_OF_CHECKS 5
 
 /* MACRO Definitions */
 /* Defines */
 #define VL53L0X_SETPARAMETERFIELD(Dev, field, value) \
  PALDevDataSet(Dev, CurrentParameters.field, value)
 
 #define VL53L0X_GETPARAMETERFIELD(Dev, field, variable) \
  variable = PALDevDataGet(Dev, CurrentParameters).field
 
 
 #define VL53L0X_SETARRAYPARAMETERFIELD(Dev, field, index, value) \
  PALDevDataSet(Dev, CurrentParameters.field[index], value)
 
 #define VL53L0X_GETARRAYPARAMETERFIELD(Dev, field, index, variable) \
  variable = PALDevDataGet(Dev, CurrentParameters).field[index]
 
 
 #define VL53L0X_SETDEVICESPECIFICPARAMETER(Dev, field, value) \
  PALDevDataSet(Dev, DeviceSpecificParameters.field, value)
 
 #define VL53L0X_GETDEVICESPECIFICPARAMETER(Dev, field) \
  PALDevDataGet(Dev, DeviceSpecificParameters).field
 
 
 #define VL53L0X_FIXPOINT1616TOFIXPOINT97(Value) \
  (uint16_t)((Value>>9)&0xFFFF)
 #define VL53L0X_FIXPOINT97TOFIXPOINT1616(Value) \
  (FixPoint1616_t)(Value<<9)
 
 #define VL53L0X_FIXPOINT1616TOFIXPOINT88(Value) \
  (uint16_t)((Value>>8)&0xFFFF)
 #define VL53L0X_FIXPOINT88TOFIXPOINT1616(Value) \
  (FixPoint1616_t)(Value<<8)
 
 #define VL53L0X_FIXPOINT1616TOFIXPOINT412(Value) \
  (uint16_t)((Value>>4)&0xFFFF)
 #define VL53L0X_FIXPOINT412TOFIXPOINT1616(Value) \
  (FixPoint1616_t)(Value<<4)
 
 #define VL53L0X_FIXPOINT1616TOFIXPOINT313(Value) \
  (uint16_t)((Value>>3)&0xFFFF)
 #define VL53L0X_FIXPOINT313TOFIXPOINT1616(Value) \
  (FixPoint1616_t)(Value<<3)
 
 #define VL53L0X_FIXPOINT1616TOFIXPOINT08(Value) \
  (uint8_t)((Value>>8)&0x00FF)
 #define VL53L0X_FIXPOINT08TOFIXPOINT1616(Value) \
  (FixPoint1616_t)(Value<<8)
 
 #define VL53L0X_FIXPOINT1616TOFIXPOINT53(Value) \
  (uint8_t)((Value>>13)&0x00FF)
 #define VL53L0X_FIXPOINT53TOFIXPOINT1616(Value) \
  (FixPoint1616_t)(Value<<13)
 
 #define VL53L0X_FIXPOINT1616TOFIXPOINT102(Value) \
  (uint16_t)((Value>>14)&0x0FFF)
 #define VL53L0X_FIXPOINT102TOFIXPOINT1616(Value) \
  (FixPoint1616_t)(Value<<12)
 
 #define VL53L0X_MAKEUINT16(lsb, msb) (uint16_t)((((uint16_t)msb)<<8) + \
  (uint16_t)lsb)
 
 #ifdef __cplusplus
 }
 #endif
 
 
 #endif /* _VL53L0X_DEF_H_ */
previous page start next page