VL6180x.h

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