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