VL6180X.h

00001 // VL6180X Time of Flight sensor interface
00002 
00003 #ifndef _VL6180X_H_
00004 #define _VL6180X_H_
00005 
00006 #include "mbed.h"
00007 #include "BitBangI2C.h"
00008 
00009 
00010 #define VL6180X_IDENTIFICATION_MODEL_ID              0x0000
00011 #define VL6180X_IDENTIFICATION_MODEL_REV_MAJOR       0x0001
00012 #define VL6180X_IDENTIFICATION_MODEL_REV_MINOR       0x0002
00013 #define VL6180X_IDENTIFICATION_MODULE_REV_MAJOR      0x0003
00014 #define VL6180X_IDENTIFICATION_MODULE_REV_MINOR      0x0004
00015 #define VL6180X_IDENTIFICATION_DATE                  0x0006  // NB - 16-bit value
00016 #define VL6180X_IDENTIFICATION_TIME                  0x0008  // NB - 16-bit value
00017  
00018 #define VL6180X_SYSTEM_MODE_GPIO0                    0x0010
00019 #define VL6180X_SYSTEM_MODE_GPIO1                    0x0011
00020 #define VL6180X_SYSTEM_HISTORY_CTRL                  0x0012
00021 #define VL6180X_SYSTEM_INTERRUPT_CONFIG_GPIO         0x0014
00022 #define VL6180X_SYSTEM_INTERRUPT_CLEAR               0x0015
00023 #define VL6180X_SYSTEM_FRESH_OUT_OF_RESET            0x0016
00024 #define VL6180X_SYSTEM_GROUPED_PARAMETER_HOLD        0x0017
00025  
00026 #define VL6180X_SYSRANGE_START                       0x0018
00027 #define VL6180X_SYSRANGE_THRESH_HIGH                 0x0019
00028 #define VL6180X_SYSRANGE_THRESH_LOW                  0x001A
00029 #define VL6180X_SYSRANGE_INTERMEASUREMENT_PERIOD     0x001B
00030 #define VL6180X_SYSRANGE_MAX_CONVERGENCE_TIME        0x001C
00031 #define VL6180X_SYSRANGE_CROSSTALK_COMPENSATION_RATE 0x001E
00032 #define VL6180X_SYSRANGE_CROSSTALK_VALID_HEIGHT      0x0021
00033 #define VL6180X_SYSRANGE_EARLY_CONVERGENCE_ESTIMATE  0x0022
00034 #define VL6180X_SYSRANGE_PART_TO_PART_RANGE_OFFSET   0x0024
00035 #define VL6180X_SYSRANGE_RANGE_IGNORE_VALID_HEIGHT   0x0025
00036 #define VL6180X_SYSRANGE_RANGE_IGNORE_THRESHOLD      0x0026
00037 #define VL6180X_SYSRANGE_MAX_AMBIENT_LEVEL_MULT      0x002C
00038 #define VL6180X_SYSRANGE_RANGE_CHECK_ENABLES         0x002D
00039 #define VL6180X_SYSRANGE_VHV_RECALIBRATE             0x002E
00040 #define VL6180X_SYSRANGE_VHV_REPEAT_RATE             0x0031
00041  
00042 #define VL6180X_SYSALS_START                         0x0038
00043 #define VL6180X_SYSALS_THRESH_HIGH                   0x003A
00044 #define VL6180X_SYSALS_THRESH_LOW                    0x003C
00045 #define VL6180X_SYSALS_INTERMEASUREMENT_PERIOD       0x003E
00046 #define VL6180X_SYSALS_ANALOGUE_GAIN                 0x003F
00047 #define VL6180X_SYSALS_INTEGRATION_PERIOD            0x0040
00048  
00049 #define VL6180X_RESULT_RANGE_STATUS                  0x004D
00050 #define VL6180X_RESULT_ALS_STATUS                    0x004E
00051 #define VL6180X_RESULT_INTERRUPT_STATUS_GPIO         0x004F
00052 #define VL6180X_RESULT_ALS_VAL                       0x0050
00053 #define VL6180X_RESULT_HISTORY_BUFFER                0x0052 
00054 #define VL6180X_RESULT_RANGE_VAL                     0x0062
00055 #define VL6180X_RESULT_RANGE_RAW                     0x0064
00056 #define VL6180X_RESULT_RANGE_RETURN_RATE             0x0066
00057 #define VL6180X_RESULT_RANGE_REFERENCE_RATE          0x0068
00058 #define VL6180X_RESULT_RANGE_RETURN_SIGNAL_COUNT     0x006C
00059 #define VL6180X_RESULT_RANGE_REFERENCE_SIGNAL_COUNT  0x0070
00060 #define VL6180X_RESULT_RANGE_RETURN_AMB_COUNT        0x0074
00061 #define VL6180X_RESULT_RANGE_REFERENCE_AMB_COUNT     0x0078
00062 #define VL6180X_RESULT_RANGE_RETURN_CONV_TIME        0x007C
00063 #define VL6180X_RESULT_RANGE_REFERENCE_CONV_TIME     0x0080
00064  
00065 #define VL6180X_READOUT_AVERAGING_SAMPLE_PERIOD      0x010A
00066 #define VL6180X_FIRMWARE_BOOTUP                      0x0119
00067 #define VL6180X_FIRMWARE_RESULT_SCALER               0x0120
00068 #define VL6180X_I2C_SLAVE_DEVICE_ADDRESS             0x0212
00069 #define VL6180X_INTERLEAVED_MODE_ENABLE              0x02A3
00070  
00071 // gain settings
00072 enum VL6180X_ALS_Gain 
00073 {
00074     GAIN_20 = 0,    // 20
00075     GAIN_10,        // 10.32
00076     GAIN_5,         // 5.21
00077     GAIN_2_5,       // 2.60
00078     GAIN_1_67,      // 1.72
00079     GAIN_1_25,      // 1.28
00080     GAIN_1,         // 1.01
00081     GAIN_40,        // 40 
00082 };
00083 
00084 // identification
00085 struct VL6180X_ID 
00086 {
00087     uint8_t model;              // model number
00088     uint8_t modelRevMajor;      // model revision number major...
00089     uint8_t modelRevMinor;      // ...and minor
00090     uint8_t moduleRevMajor;     // module revision number major...
00091     uint8_t moduleRevMinor;     // ... and minior
00092     struct
00093     {
00094         uint8_t month;          // month 1..12
00095         uint8_t day;            // day of month 1..31
00096         uint16_t year;          // calendar year, 4-digit (e.g., 2016)
00097         uint8_t phase;          // manufacturing phase, 0..7
00098         uint8_t hh;             // hour, 0..23
00099         uint8_t mm;             // minute, 0..59
00100         uint8_t ss;             // second, 0..59
00101     } manufDate;                // manufacturing date and time
00102 };
00103 
00104 // range statistics
00105 struct VL6180X_RangeStats
00106 {
00107     uint16_t returnRate;        // return signal rate
00108     uint16_t refReturnRate;     // reference return rate
00109     uint32_t returnCnt;         // return signal count
00110     uint32_t refReturnCnt;      // reference return count
00111     uint32_t ambCnt;            // ambient count
00112     uint32_t refAmbCnt;         // reference ambient count
00113     uint32_t convTime;          // convergence time
00114     uint32_t refConvTime;       // reference convergence time
00115 };
00116 
00117 class VL6180X
00118 {
00119 public:
00120     // Set up the interface with the given I2C pins, I2C address, and
00121     // the GPIO0 pin (for resetting the sensor at startup).  
00122     //
00123     // If 'internalPullups' is true, we'll set the I2C SDA/SCL pins to 
00124     // enable the internal pullup resistors.  Set this to false if you're
00125     // using your own external pullup resistors on the lines.  External
00126     // pullups are better if you're attaching more than one device to the
00127     // same physical I2C bus; the internal pullups are fine if there's only
00128     // one I2C device (in this case the VL6180X) connected to these pins.
00129     //
00130     // Note that VL6180X's I2C address is always 0x29 at power-on.  The
00131     // address can be changed during a session, but there's no way to save
00132     // the value persistently on the VL6180X, so it always resets to 0x29 
00133     // on the next power cycle.  As a result, I see little reason to ever
00134     // change it during a session.
00135     VL6180X(PinName sda, PinName scl, uint8_t addr, PinName gpio0,
00136         bool internalPullups);
00137     
00138     // destruction
00139     ~VL6180X();
00140 
00141     // Send the required initialization sequence.  Returns true on
00142     // success, false on failure.
00143     bool init();
00144 
00145     // set up default settings
00146     void setDefaults();
00147     
00148     // Start a distance reading, returning immediately without waiting
00149     // for the reading to finish.  The caller can poll for the finished
00150     // reading via distanceReady().
00151     void startRangeReading();
00152 
00153     // Get TOF range distance in mm.  Returns 0 on success, a device
00154     // "range error code" (>0) on failure, or -1 on timeout.
00155     //
00156     // 'tMid' is the timestamp in microseconds of the midpoint of the
00157     // sample, relative to an arbitrary zero point.  This can be used
00158     // to construct a timeline of successive readings, such as for
00159     // velocity calculations.  'dt' is the time the sensor took to
00160     // collect the sample.
00161     int getRange(
00162         uint8_t &distance, uint32_t &tMid, uint32_t &dt, 
00163         uint32_t timeout_us);
00164     
00165     // get range statistics
00166     void getRangeStats(VL6180X_RangeStats &stats);
00167 
00168     // set continuous distance mode
00169     void continuousDistanceMode(bool on);
00170     
00171     // is a sample ready?
00172     bool rangeReady();
00173 
00174     // get identification data
00175     void getID(VL6180X_ID &id);
00176 
00177 protected:
00178     // READOUT_AVERAGING_SAMPLE_PERIOD setting.  Each unit represents
00179     // 64.5us of added time beyond the 1.3ms fixed base period.  The
00180     // default is 48 units.
00181     static const int averagingSamplePeriod = 48;
00182 
00183     // I2C interface to device
00184     BitBangI2C i2c;
00185     
00186     // GPIO0 pin for hard reset
00187     DigitalInOut gpio0Pin;
00188     
00189     // device address
00190     uint8_t addr;
00191     
00192     // current distance mode: 0=single shot, 1=continuous
00193     bool distMode;
00194     
00195     // range reading is in progress
00196     bool rangeStarted;
00197     
00198     // sample timer
00199     Timer sampleTimer;
00200 
00201     // time (from Timer t) of start of last range sample
00202     uint32_t tSampleStart;
00203 
00204     // read registers
00205     uint8_t readReg8(uint16_t regAddr);
00206     uint16_t readReg16(uint16_t regAddr);
00207     uint32_t readReg32(uint16_t regAddr);
00208 
00209     // write registers
00210     void writeReg8(uint16_t regAddr, uint8_t data);
00211     void writeReg16(uint16_t regAddr, uint16_t data);
00212 };
00213  
00214 #endif