VL6180x.h

00001 /**
00002 * @file VL6180x.h
00003  * @brief Library for VL6180x time of flight range finder.
00004  * Casey Kuhns @ SparkFun Electronics
00005  * 10/29/2014
00006  * https://github.com/sparkfun/
00007  * 
00008  * The VL6180x by ST micro is a time of flight range finder that
00009  * uses pulsed IR light to determine distances from object at close
00010  * range.  The average range of a sensor is between 0-200mm
00011  * 
00012  * In this file are the function prototypes in the VL6180x class
00013  * 
00014  * Resources:
00015  * This library uses the Arduino Wire.h to complete I2C transactions.
00016  * 
00017  * Development environment specifics:
00018  *  IDE: Arduino 1.0.5
00019  *  Hardware Platform: Arduino Pro 3.3V/8MHz
00020  *  VL6180x Breakout Version: 1.0
00021  * 
00022  * Some settings and initial values come from code written by Kris Winer
00023  * VL6180X_t3 Basic Example Code
00024  * by: Kris Winer
00025  * date: September 1, 2014
00026  * license: Beerware - Use this code however you'd like. If you 
00027  * find it useful you can buy me a beer some time.
00028  * 
00029  * This code is beerware. If you see me (or any other SparkFun employee) at the
00030  * local pub, and you've found our code helpful, please buy us a round!
00031  * 
00032  * Distributed as-is; no warranty is given.
00033 */
00034 /**
00035 * VL6180x tof/als sensor example
00036 *
00037 * @code
00038 #include "mbed.h"
00039 #include <VL6180x.h>
00040 
00041 const float GAIN_1    = 1.01;  // Actual ALS Gain of 1.01
00042 const float GAIN_1_25 = 1.28;  // Actual ALS Gain of 1.28
00043 const float GAIN_1_67 = 1.72;  // Actual ALS Gain of 1.72
00044 const float GAIN_2_5  = 2.6;   // Actual ALS Gain of 2.60
00045 const float GAIN_5    = 5.21;  // Actual ALS Gain of 5.21
00046 const float GAIN_10   = 10.32; // Actual ALS Gain of 10.32
00047 const float GAIN_20   = 20;    // Actual ALS Gain of 20
00048 const float GAIN_40   = 40;    // Actual ALS Gain of 40
00049 
00050 
00051 #define VL6180X_ADDRESS 0x29
00052 
00053 VL6180xIdentification identification;
00054 // mbed uses 8bit addresses shift address by 1 bit left
00055 VL6180x sensor(D14, D15, VL6180X_ADDRESS<<1);
00056 
00057 void printIdentification(struct VL6180xIdentification *temp){
00058   printf("Model ID = ");
00059   printf("%d\n",temp->idModel);
00060 
00061   printf("Model Rev = ");
00062   printf("%d",temp->idModelRevMajor);
00063   printf(".");
00064   printf("%d\n",temp->idModelRevMinor);
00065 
00066   printf("Module Rev = ");
00067   printf("%d",temp->idModuleRevMajor);
00068   printf(".");
00069   printf("%d\n",temp->idModuleRevMinor);  
00070 
00071   printf("Manufacture Date = ");
00072   printf("%d",((temp->idDate >> 3) & 0x001F));
00073   printf("/");
00074   printf("%d",((temp->idDate >> 8) & 0x000F));
00075   printf("/1");
00076   printf("%d\n",((temp->idDate >> 12) & 0x000F));
00077   printf(" Phase: ");
00078   printf("%d\n",(temp->idDate & 0x0007));
00079 
00080   printf("Manufacture Time (s)= ");
00081   printf("%d\n",(temp->idTime * 2));
00082   printf("\n\n");
00083 }
00084 int main() {
00085 
00086   wait_ms(100); // delay .1s
00087 
00088   sensor.getIdentification(&identification); // Retrieve manufacture info from device memory
00089   printIdentification(&identification); // Helper function to print all the Module information
00090 
00091   if(sensor.VL6180xInit() != 0){
00092         printf("FAILED TO INITALIZE\n"); //Initialize device and check for errors
00093   }; 
00094 
00095   sensor.VL6180xDefautSettings(); //Load default settings to get started.
00096   
00097     wait_ms(1000); // delay 1s
00098 
00099     
00100     
00101     while(1) {
00102   //Get Ambient Light level and report in LUX
00103       printf("Ambient Light Level (Lux) = ");
00104   
00105   //Input GAIN for light levels, 
00106   // GAIN_20     // Actual ALS Gain of 20
00107   // GAIN_10     // Actual ALS Gain of 10.32
00108   // GAIN_5      // Actual ALS Gain of 5.21
00109   // GAIN_2_5    // Actual ALS Gain of 2.60
00110   // GAIN_1_67   // Actual ALS Gain of 1.72
00111   // GAIN_1_25   // Actual ALS Gain of 1.28
00112   // GAIN_1      // Actual ALS Gain of 1.01
00113   // GAIN_40     // Actual ALS Gain of 40
00114   
00115       printf("%f\n",sensor.getAmbientLight(GAIN_1) );
00116 
00117   //Get Distance and report in mm
00118       printf("Distance measured (mm) = ");
00119       printf("%d\n", sensor.getDistance() ); 
00120 
00121       wait_ms(500);  
00122     }
00123 }
00124 * @endcode
00125 */
00126 #include "mbed.h"
00127 #ifndef VL6180x_h
00128 #define VL6180x_h
00129 
00130 #define VL6180x_FAILURE_RESET  -1
00131 
00132 #define VL6180X_IDENTIFICATION_MODEL_ID              0x0000
00133 #define VL6180X_IDENTIFICATION_MODEL_REV_MAJOR       0x0001
00134 #define VL6180X_IDENTIFICATION_MODEL_REV_MINOR       0x0002
00135 #define VL6180X_IDENTIFICATION_MODULE_REV_MAJOR      0x0003
00136 #define VL6180X_IDENTIFICATION_MODULE_REV_MINOR      0x0004
00137 #define VL6180X_IDENTIFICATION_DATE                  0x0006 //16bit value
00138 #define VL6180X_IDENTIFICATION_TIME                  0x0008 //16bit value
00139 
00140 #define VL6180X_SYSTEM_MODE_GPIO0                    0x0010
00141 #define VL6180X_SYSTEM_MODE_GPIO1                    0x0011
00142 #define VL6180X_SYSTEM_HISTORY_CTRL                  0x0012
00143 #define VL6180X_SYSTEM_INTERRUPT_CONFIG_GPIO         0x0014
00144 #define VL6180X_SYSTEM_INTERRUPT_CLEAR               0x0015
00145 #define VL6180X_SYSTEM_FRESH_OUT_OF_RESET            0x0016
00146 #define VL6180X_SYSTEM_GROUPED_PARAMETER_HOLD        0x0017
00147 
00148 #define VL6180X_SYSRANGE_START                       0x0018
00149 #define VL6180X_SYSRANGE_THRESH_HIGH                 0x0019
00150 #define VL6180X_SYSRANGE_THRESH_LOW                  0x001A
00151 #define VL6180X_SYSRANGE_INTERMEASUREMENT_PERIOD     0x001B
00152 #define VL6180X_SYSRANGE_MAX_CONVERGENCE_TIME        0x001C
00153 #define VL6180X_SYSRANGE_CROSSTALK_COMPENSATION_RATE 0x001E
00154 #define VL6180X_SYSRANGE_CROSSTALK_VALID_HEIGHT      0x0021
00155 #define VL6180X_SYSRANGE_EARLY_CONVERGENCE_ESTIMATE  0x0022
00156 #define VL6180X_SYSRANGE_PART_TO_PART_RANGE_OFFSET   0x0024
00157 #define VL6180X_SYSRANGE_RANGE_IGNORE_VALID_HEIGHT   0x0025
00158 #define VL6180X_SYSRANGE_RANGE_IGNORE_THRESHOLD      0x0026
00159 #define VL6180X_SYSRANGE_MAX_AMBIENT_LEVEL_MULT      0x002C
00160 #define VL6180X_SYSRANGE_RANGE_CHECK_ENABLES         0x002D
00161 #define VL6180X_SYSRANGE_VHV_RECALIBRATE             0x002E
00162 #define VL6180X_SYSRANGE_VHV_REPEAT_RATE             0x0031
00163 
00164 #define VL6180X_SYSALS_START                         0x0038
00165 #define VL6180X_SYSALS_THRESH_HIGH                   0x003A
00166 #define VL6180X_SYSALS_THRESH_LOW                    0x003C
00167 #define VL6180X_SYSALS_INTERMEASUREMENT_PERIOD       0x003E
00168 #define VL6180X_SYSALS_ANALOGUE_GAIN                 0x003F
00169 #define VL6180X_SYSALS_INTEGRATION_PERIOD            0x0040
00170 
00171 #define VL6180X_RESULT_RANGE_STATUS                  0x004D
00172 #define VL6180X_RESULT_ALS_STATUS                    0x004E
00173 #define VL6180X_RESULT_INTERRUPT_STATUS_GPIO         0x004F
00174 #define VL6180X_RESULT_ALS_VAL                       0x0050
00175 #define VL6180X_RESULT_HISTORY_BUFFER                0x0052 
00176 #define VL6180X_RESULT_RANGE_VAL                     0x0062
00177 #define VL6180X_RESULT_RANGE_RAW                     0x0064
00178 #define VL6180X_RESULT_RANGE_RETURN_RATE             0x0066
00179 #define VL6180X_RESULT_RANGE_REFERENCE_RATE          0x0068
00180 #define VL6180X_RESULT_RANGE_RETURN_SIGNAL_COUNT     0x006C
00181 #define VL6180X_RESULT_RANGE_REFERENCE_SIGNAL_COUNT  0x0070
00182 #define VL6180X_RESULT_RANGE_RETURN_AMB_COUNT        0x0074
00183 #define VL6180X_RESULT_RANGE_REFERENCE_AMB_COUNT     0x0078
00184 #define VL6180X_RESULT_RANGE_RETURN_CONV_TIME        0x007C
00185 #define VL6180X_RESULT_RANGE_REFERENCE_CONV_TIME     0x0080
00186 
00187 #define VL6180X_READOUT_AVERAGING_SAMPLE_PERIOD      0x010A
00188 #define VL6180X_FIRMWARE_BOOTUP                      0x0119
00189 #define VL6180X_FIRMWARE_RESULT_SCALER               0x0120
00190 #define VL6180X_I2C_SLAVE_DEVICE_ADDRESS             0x0212
00191 #define VL6180X_INTERLEAVED_MODE_ENABLE              0x02A3
00192 
00193 /**
00194 * gain settings for ALS
00195 *Data sheet shows gain values as binary list
00196 */
00197 enum vl6180x_als_gain { 
00198 
00199 GAIN_20 = 0, // Actual ALS Gain of 20
00200 GAIN_10,     // Actual ALS Gain of 10.32
00201 GAIN_5,      // Actual ALS Gain of 5.21
00202 GAIN_2_5,    // Actual ALS Gain of 2.60
00203 GAIN_1_67,   // Actual ALS Gain of 1.72
00204 GAIN_1_25,   // Actual ALS Gain of 1.28
00205 GAIN_1 ,     // Actual ALS Gain of 1.01
00206 GAIN_40,     // Actual ALS Gain of 40
00207 
00208 };
00209 /**
00210 * VL6180xIdentification
00211 * @brief structure to hold module identification
00212 *
00213 * @param idModel Model number
00214 * @param idModelRevMajor Major revision
00215 * @param idModelRevMinor Minor revision
00216 * @param idModuleRevMajor Module Major revision
00217 * @param idModuleRevMinor Module Minor revision
00218 * @param idDate Date of manufacture
00219 * @param idTime Seconds after midnight manufacture
00220 */
00221 struct VL6180xIdentification {
00222   uint8_t idModel;
00223   uint8_t idModelRevMajor;
00224   uint8_t idModelRevMinor;
00225   uint8_t idModuleRevMajor;
00226   uint8_t idModuleRevMinor;
00227   uint16_t idDate;
00228   uint16_t idTime;
00229 };
00230 
00231 class VL6180x
00232 {
00233 public: 
00234 /**
00235 * VL6180x constructor
00236 *
00237 * @param sda SDA pin
00238 * @param sdl SCL pin
00239 * @param addr addr of the I2C peripheral
00240 */
00241   VL6180x(PinName sda, PinName scl, uint8_t addr);
00242 /**
00243 * VL6180x destructor
00244 */
00245   ~VL6180x();
00246 /**
00247 * Send mandatory settings as stated in ST datasheet.
00248 * http://www.st.com/st-web-ui/static/active/en/resource/technical/document/application_note/DM00122600.pdf (Section 1.3)
00249 * @returns 0 if ok 
00250 * @returns -1 on error*/
00251   int VL6180xInit(void);
00252 /**
00253 * Use default settings from ST data sheet section 9.
00254 *
00255 * http://www.st.com/st-web-ui/static/active/en/resource/technical/document/application_note/DM00122600.pdf
00256 */
00257   void VL6180xDefautSettings(void);
00258 /**
00259 * Get Range distance in (mm)
00260 * @returns TOF distance in mm  
00261 */
00262   uint8_t getDistance();
00263 /**
00264 * Get ALS level in Lux
00265 * @param vl6180x_als_gain gain setting for sensor
00266 * @param sdl SCL pin
00267 * @param addr addr of the I2C peripheral
00268 * @returns light level in Lux 
00269 */
00270   float getAmbientLight(vl6180x_als_gain VL6180X_ALS_GAIN);
00271 /**
00272 * Load structure provided by the user with identification info
00273 * Structure example:
00274 * struct VL6180xIdentification
00275 */
00276   void getIdentification(struct VL6180xIdentification *temp);
00277 
00278 /**
00279 * Change the default address of the device to allow multiple
00280 * sensors on the bus.  Can use up to 127 sensors. New address
00281 * is saved in non-volatile device memory.
00282 * @param old_address current address
00283 * @param new_address desired new address
00284 * @returns new address
00285 */
00286   uint8_t changeAddress(uint8_t old_address, uint8_t new_address);
00287 
00288 
00289 private:
00290   //Store address given when the class is initialized.
00291   //This value can be changed by the changeAddress() function
00292   I2C m_i2c;
00293   int m_addr;
00294 /**
00295 * read 8 bit register
00296 * @param registerAddr address for register
00297 * @returns contents of register
00298 */
00299   uint8_t VL6180x_getRegister(uint16_t registerAddr);
00300 /**
00301 * read 16 bit register
00302 * @param registerAddr address for register
00303 * @param returns contents of register
00304 */
00305 uint16_t VL6180x_getRegister16bit(uint16_t registerAddr);
00306 /**
00307 * write 8 bit register
00308 * @param registerAddr address for register
00309 * @returns ERROR
00310 */
00311   void VL6180x_setRegister(uint16_t registerAddr, uint8_t data);
00312 /**
00313 * write 16 bit register
00314 * @param registerAddr address for register
00315 * @returns ERROR
00316 */
00317   void VL6180x_setRegister16bit(uint16_t registerAddr, uint16_t data);
00318 };
00319 
00320 #endif