VL53L0X.cpp

00001 // Most of the functionality of this library is based on the VL53L0X API
00002 // provided by ST (STSW-IMG005), and some of the explanatory comments are quoted
00003 // or paraphrased from the API source code, API user manual (UM2039), and the
00004 // VL53L0X datasheet.
00005 
00006 #include <memory>
00007 #include <VL53L0X.h>
00008 
00009 // Defines /////////////////////////////////////////////////////////////////////
00010 
00011 // The Arduino two-wire interface uses a 7-bit number for the address,
00012 // and sets the last bit correctly based on reads and writes
00013 #define ADDRESS_DEFAULT (0b0101001 << 1)
00014 
00015 // Record the current time to check an upcoming timeout against
00016 #define startTimeout() (timeout_start_ms = millis())
00017 
00018 // Check if timeout is enabled (set to nonzero value) and has expired
00019 #define checkTimeoutExpired() (io_timeout > 0 && ((uint16_t)millis() - timeout_start_ms) > io_timeout)
00020 
00021 // Decode VCSEL (vertical cavity surface emitting laser) pulse period in PCLKs
00022 // from register value
00023 // based on VL53L0X_decode_vcsel_period()
00024 #define decodeVcselPeriod(reg_val)      (((reg_val) + 1) << 1)
00025 
00026 // Encode VCSEL pulse period register value from period in PCLKs
00027 // based on VL53L0X_encode_vcsel_period()
00028 #define encodeVcselPeriod(period_pclks) (((period_pclks) >> 1) - 1)
00029 
00030 // Calculate macro period in *nanoseconds* from VCSEL period in PCLKs
00031 // based on VL53L0X_calc_macro_period_ps()
00032 // PLL_period_ps = 1655; macro_period_vclks = 2304
00033 #define calcMacroPeriod(vcsel_period_pclks) ((((uint32_t)2304 * (vcsel_period_pclks) * 1655) + 500) / 1000)
00034 
00035 // Transmission status (https://www.arduino.cc/en/Reference/WireEndTransmission)
00036 #define ERR_OK 0
00037 #define ERR_NACK_ADDR 2 // received NACK on transmit of address
00038 #define ERR_NACK_DATA 3 // received NACK on transmit of data
00039 #define ERR_OTHER 4
00040 
00041 #define millis() timer->read_ms()
00042 
00043 // Constructors ////////////////////////////////////////////////////////////////
00044 
00045 VL53L0X::VL53L0X(I2C* i2c, Timer* timer)
00046   : address(ADDRESS_DEFAULT)
00047   , io_timeout(0) // no timeout
00048   , did_timeout(false)
00049   , i2c(i2c)
00050   , timer(timer)
00051 {
00052 }
00053 
00054 // Public Methods //////////////////////////////////////////////////////////////
00055 
00056 void VL53L0X::setAddress(uint8_t new_addr)
00057 {
00058   writeReg(I2C_SLAVE_DEVICE_ADDRESS, new_addr & 0x7F);
00059   address = new_addr << 1;
00060 }
00061 
00062 // Initialize sensor using sequence based on VL53L0X_DataInit(),
00063 // VL53L0X_StaticInit(), and VL53L0X_PerformRefCalibration().
00064 // This function does not perform reference SPAD calibration
00065 // (VL53L0X_PerformRefSpadManagement()), since the API user manual says that it
00066 // is performed by ST on the bare modules; it seems like that should work well
00067 // enough unless a cover glass is added.
00068 // If io_2v8 (optional) is true or not given, the sensor is configured for 2V8
00069 // mode.
00070 bool VL53L0X::init(bool io_2v8)
00071 {
00072   // VL53L0X_DataInit() begin
00073 
00074   // sensor uses 1V8 mode for I/O by default; switch to 2V8 mode if necessary
00075   if (io_2v8)
00076   {
00077     writeReg(VHV_CONFIG_PAD_SCL_SDA__EXTSUP_HV,
00078       readReg(VHV_CONFIG_PAD_SCL_SDA__EXTSUP_HV) | 0x01); // set bit 0
00079   }
00080 
00081   // "Set I2C standard mode"
00082   writeReg(0x88, 0x00);
00083 
00084   writeReg(0x80, 0x01);
00085   writeReg(0xFF, 0x01);
00086   writeReg(0x00, 0x00);
00087   stop_variable = readReg(0x91);
00088   writeReg(0x00, 0x01);
00089   writeReg(0xFF, 0x00);
00090   writeReg(0x80, 0x00);
00091 
00092   // disable SIGNAL_RATE_MSRC (bit 1) and SIGNAL_RATE_PRE_RANGE (bit 4) limit checks
00093   writeReg(MSRC_CONFIG_CONTROL, readReg(MSRC_CONFIG_CONTROL) | 0x12);
00094 
00095   // set final range signal rate limit to 0.25 MCPS (million counts per second)
00096   setSignalRateLimit(0.25);
00097 
00098   writeReg(SYSTEM_SEQUENCE_CONFIG, 0xFF);
00099 
00100   // VL53L0X_DataInit() end
00101 
00102   // VL53L0X_StaticInit() begin
00103 
00104   uint8_t spad_count;
00105   bool spad_type_is_aperture;
00106   if (!getSpadInfo(&spad_count, &spad_type_is_aperture)) { return false; }
00107 
00108   // The SPAD map (RefGoodSpadMap) is read by VL53L0X_get_info_from_device() in
00109   // the API, but the same data seems to be more easily readable from
00110   // GLOBAL_CONFIG_SPAD_ENABLES_REF_0 through _6, so read it from there
00111   uint8_t ref_spad_map[6];
00112   readMulti(GLOBAL_CONFIG_SPAD_ENABLES_REF_0, ref_spad_map, 6);
00113 
00114   // -- VL53L0X_set_reference_spads() begin (assume NVM values are valid)
00115 
00116   writeReg(0xFF, 0x01);
00117   writeReg(DYNAMIC_SPAD_REF_EN_START_OFFSET, 0x00);
00118   writeReg(DYNAMIC_SPAD_NUM_REQUESTED_REF_SPAD, 0x2C);
00119   writeReg(0xFF, 0x00);
00120   writeReg(GLOBAL_CONFIG_REF_EN_START_SELECT, 0xB4);
00121 
00122   uint8_t first_spad_to_enable = spad_type_is_aperture ? 12 : 0; // 12 is the first aperture spad
00123   uint8_t spads_enabled = 0;
00124 
00125   for (uint8_t i = 0; i < 48; i++)
00126   {
00127     if (i < first_spad_to_enable || spads_enabled == spad_count)
00128     {
00129       // This bit is lower than the first one that should be enabled, or
00130       // (reference_spad_count) bits have already been enabled, so zero this bit
00131       ref_spad_map[i / 8] &= ~(1 << (i % 8));
00132     }
00133     else if ((ref_spad_map[i / 8] >> (i % 8)) & 0x1)
00134     {
00135       spads_enabled++;
00136     }
00137   }
00138 
00139   writeMulti(GLOBAL_CONFIG_SPAD_ENABLES_REF_0, ref_spad_map, 6);
00140 
00141   // -- VL53L0X_set_reference_spads() end
00142 
00143   // -- VL53L0X_load_tuning_settings() begin
00144   // DefaultTuningSettings from vl53l0x_tuning.h
00145 
00146   writeReg(0xFF, 0x01);
00147   writeReg(0x00, 0x00);
00148 
00149   writeReg(0xFF, 0x00);
00150   writeReg(0x09, 0x00);
00151   writeReg(0x10, 0x00);
00152   writeReg(0x11, 0x00);
00153 
00154   writeReg(0x24, 0x01);
00155   writeReg(0x25, 0xFF);
00156   writeReg(0x75, 0x00);
00157 
00158   writeReg(0xFF, 0x01);
00159   writeReg(0x4E, 0x2C);
00160   writeReg(0x48, 0x00);
00161   writeReg(0x30, 0x20);
00162 
00163   writeReg(0xFF, 0x00);
00164   writeReg(0x30, 0x09);
00165   writeReg(0x54, 0x00);
00166   writeReg(0x31, 0x04);
00167   writeReg(0x32, 0x03);
00168   writeReg(0x40, 0x83);
00169   writeReg(0x46, 0x25);
00170   writeReg(0x60, 0x00);
00171   writeReg(0x27, 0x00);
00172   writeReg(0x50, 0x06);
00173   writeReg(0x51, 0x00);
00174   writeReg(0x52, 0x96);
00175   writeReg(0x56, 0x08);
00176   writeReg(0x57, 0x30);
00177   writeReg(0x61, 0x00);
00178   writeReg(0x62, 0x00);
00179   writeReg(0x64, 0x00);
00180   writeReg(0x65, 0x00);
00181   writeReg(0x66, 0xA0);
00182 
00183   writeReg(0xFF, 0x01);
00184   writeReg(0x22, 0x32);
00185   writeReg(0x47, 0x14);
00186   writeReg(0x49, 0xFF);
00187   writeReg(0x4A, 0x00);
00188 
00189   writeReg(0xFF, 0x00);
00190   writeReg(0x7A, 0x0A);
00191   writeReg(0x7B, 0x00);
00192   writeReg(0x78, 0x21);
00193 
00194   writeReg(0xFF, 0x01);
00195   writeReg(0x23, 0x34);
00196   writeReg(0x42, 0x00);
00197   writeReg(0x44, 0xFF);
00198   writeReg(0x45, 0x26);
00199   writeReg(0x46, 0x05);
00200   writeReg(0x40, 0x40);
00201   writeReg(0x0E, 0x06);
00202   writeReg(0x20, 0x1A);
00203   writeReg(0x43, 0x40);
00204 
00205   writeReg(0xFF, 0x00);
00206   writeReg(0x34, 0x03);
00207   writeReg(0x35, 0x44);
00208 
00209   writeReg(0xFF, 0x01);
00210   writeReg(0x31, 0x04);
00211   writeReg(0x4B, 0x09);
00212   writeReg(0x4C, 0x05);
00213   writeReg(0x4D, 0x04);
00214 
00215   writeReg(0xFF, 0x00);
00216   writeReg(0x44, 0x00);
00217   writeReg(0x45, 0x20);
00218   writeReg(0x47, 0x08);
00219   writeReg(0x48, 0x28);
00220   writeReg(0x67, 0x00);
00221   writeReg(0x70, 0x04);
00222   writeReg(0x71, 0x01);
00223   writeReg(0x72, 0xFE);
00224   writeReg(0x76, 0x00);
00225   writeReg(0x77, 0x00);
00226 
00227   writeReg(0xFF, 0x01);
00228   writeReg(0x0D, 0x01);
00229 
00230   writeReg(0xFF, 0x00);
00231   writeReg(0x80, 0x01);
00232   writeReg(0x01, 0xF8);
00233 
00234   writeReg(0xFF, 0x01);
00235   writeReg(0x8E, 0x01);
00236   writeReg(0x00, 0x01);
00237   writeReg(0xFF, 0x00);
00238   writeReg(0x80, 0x00);
00239 
00240   // -- VL53L0X_load_tuning_settings() end
00241 
00242   // "Set interrupt config to new sample ready"
00243   // -- VL53L0X_SetGpioConfig() begin
00244 
00245   writeReg(SYSTEM_INTERRUPT_CONFIG_GPIO, 0x04);
00246   writeReg(GPIO_HV_MUX_ACTIVE_HIGH, readReg(GPIO_HV_MUX_ACTIVE_HIGH) & ~0x10); // active low
00247   writeReg(SYSTEM_INTERRUPT_CLEAR, 0x01);
00248 
00249   // -- VL53L0X_SetGpioConfig() end
00250 
00251   measurement_timing_budget_us = getMeasurementTimingBudget();
00252 
00253   // "Disable MSRC and TCC by default"
00254   // MSRC = Minimum Signal Rate Check
00255   // TCC = Target CentreCheck
00256   // -- VL53L0X_SetSequenceStepEnable() begin
00257 
00258   writeReg(SYSTEM_SEQUENCE_CONFIG, 0xE8);
00259 
00260   // -- VL53L0X_SetSequenceStepEnable() end
00261 
00262   // "Recalculate timing budget"
00263   setMeasurementTimingBudget(measurement_timing_budget_us);
00264 
00265   // VL53L0X_StaticInit() end
00266 
00267   // VL53L0X_PerformRefCalibration() begin (VL53L0X_perform_ref_calibration())
00268 
00269   // -- VL53L0X_perform_vhv_calibration() begin
00270 
00271   writeReg(SYSTEM_SEQUENCE_CONFIG, 0x01);
00272   if (!performSingleRefCalibration(0x40)) { return false; }
00273 
00274   // -- VL53L0X_perform_vhv_calibration() end
00275 
00276   // -- VL53L0X_perform_phase_calibration() begin
00277 
00278   writeReg(SYSTEM_SEQUENCE_CONFIG, 0x02);
00279   if (!performSingleRefCalibration(0x00)) { return false; }
00280 
00281   // -- VL53L0X_perform_phase_calibration() end
00282 
00283   // "restore the previous Sequence Config"
00284   writeReg(SYSTEM_SEQUENCE_CONFIG, 0xE8);
00285 
00286   // VL53L0X_PerformRefCalibration() end
00287 
00288   return true;
00289 }
00290 
00291 // Write an 8-bit register
00292 void VL53L0X::writeReg(uint8_t reg, uint8_t value)
00293 {
00294   char data[] = {
00295     reg,
00296     value
00297   };
00298   if (i2c->write(address, data, 2)) {
00299     last_status = ERR_OTHER;
00300   } else {
00301     last_status = ERR_OK;
00302   }
00303 }
00304 
00305 // Write a 16-bit register
00306 void VL53L0X::writeReg16Bit(uint8_t reg, uint16_t value)
00307 {
00308   char data[] = {
00309     reg,
00310     static_cast<char>((value >> 8) & 0xFF), // value high byte
00311     static_cast<char>(value        & 0xFF)  // value low byte
00312   };
00313   if (i2c->write(address, data, 3)) {
00314     last_status = ERR_OTHER;
00315   } else {
00316     last_status = ERR_OK;
00317   }
00318 }
00319 
00320 // Write a 32-bit register
00321 void VL53L0X::writeReg32Bit(uint8_t reg, uint32_t value)
00322 {
00323   char data[] = {
00324     reg,
00325     static_cast<char>((value >> 24) & 0xFF), // value highest byte
00326     static_cast<char>((value >> 16) & 0xFF),
00327     static_cast<char>((value >>  8) & 0xFF),
00328     static_cast<char>(value         & 0xFF)  // value lowest byte
00329   };
00330   if (i2c->write(address, data, 5)) {
00331     last_status = ERR_OTHER;
00332   } else {
00333     last_status = ERR_OK;
00334   }
00335 }
00336 
00337 // Read an 8-bit register
00338 uint8_t VL53L0X::readReg(uint8_t reg)
00339 {
00340   uint8_t value;
00341 
00342   if (i2c->write(address, reinterpret_cast<char *>(&reg), 1)) {
00343     last_status = ERR_NACK_ADDR;
00344     return 0;
00345   }
00346   if (i2c->read(address, reinterpret_cast<char *>(&value), 1)) {
00347     last_status = ERR_NACK_DATA;
00348     return 0;
00349   }
00350   last_status = ERR_OK;
00351 
00352   return value;
00353 }
00354 
00355 // Read a 16-bit register
00356 uint16_t VL53L0X::readReg16Bit(uint8_t reg)
00357 {
00358   uint16_t value;
00359   uint8_t data[2];
00360 
00361   if (i2c->write(address, reinterpret_cast<char *>(&reg), 1)) {
00362     last_status = ERR_NACK_ADDR;
00363     return 0;
00364   }
00365   if (i2c->read(address, reinterpret_cast<char *>(data), 2)) {
00366     last_status = ERR_NACK_DATA;
00367     return 0;
00368   }
00369   last_status = ERR_OK;
00370 
00371   value  = static_cast<uint16_t>(data[0] << 8); // value high byte
00372   value |=                       data[1];       // value low byte
00373 
00374   return value;
00375 }
00376 
00377 // Read a 32-bit register
00378 uint32_t VL53L0X::readReg32Bit(uint8_t reg)
00379 {
00380   uint32_t value;
00381   uint8_t data[4];
00382 
00383   if (i2c->write(address, reinterpret_cast<char *>(&reg), 1)) {
00384     last_status = ERR_NACK_ADDR;
00385     return 0;
00386   }
00387   if (i2c->read(address, reinterpret_cast<char *>(data), 4)) {
00388     last_status = ERR_NACK_DATA;
00389     return 0;
00390   }
00391   last_status = ERR_OK;
00392 
00393   value  = static_cast<uint32_t>(data[0] << 24); // value highest byte
00394   value |= static_cast<uint32_t>(data[1] << 16);
00395   value |= static_cast<uint32_t>(data[2] <<  8);
00396   value |=                       data[3];       // value lowest byte
00397 
00398   return value;
00399 }
00400 
00401 // Write an arbitrary number of bytes from the given array to the sensor,
00402 // starting at the given register
00403 void VL53L0X::writeMulti(uint8_t reg, uint8_t const * src, uint8_t count)
00404 {
00405   if (i2c->write(address, reinterpret_cast<char *>(&reg), 1, true)) {
00406     last_status = ERR_NACK_ADDR;
00407     return;
00408   }
00409 
00410   if (i2c->write(address, const_cast<char *>(
00411       reinterpret_cast<const char *>(src)), count)) {
00412     last_status = ERR_NACK_DATA;
00413     return;
00414   }
00415   last_status = ERR_OK;
00416 }
00417 
00418 // Read an arbitrary number of bytes from the sensor, starting at the given
00419 // register, into the given array
00420 void VL53L0X::readMulti(uint8_t reg, uint8_t * dst, uint8_t count)
00421 {
00422   if (i2c->write(address, reinterpret_cast<char *>(&reg), 1)) {
00423     last_status = ERR_NACK_ADDR;
00424     return;
00425   }
00426   if (i2c->read(address, reinterpret_cast<char *>(dst), count)) {
00427     last_status = ERR_NACK_DATA;
00428     return;
00429   }
00430   last_status = ERR_OK;
00431 }
00432 
00433 // Set the return signal rate limit check value in units of MCPS (mega counts
00434 // per second). "This represents the amplitude of the signal reflected from the
00435 // target and detected by the device"; setting this limit presumably determines
00436 // the minimum measurement necessary for the sensor to report a valid reading.
00437 // Setting a lower limit increases the potential range of the sensor but also
00438 // seems to increase the likelihood of getting an inaccurate reading because of
00439 // unwanted reflections from objects other than the intended target.
00440 // Defaults to 0.25 MCPS as initialized by the ST API and this library.
00441 bool VL53L0X::setSignalRateLimit(float limit_Mcps)
00442 {
00443   if (limit_Mcps < 0 || limit_Mcps > 511.99) { return false; }
00444 
00445   // Q9.7 fixed point format (9 integer bits, 7 fractional bits)
00446   writeReg16Bit(FINAL_RANGE_CONFIG_MIN_COUNT_RATE_RTN_LIMIT, limit_Mcps * (1 << 7));
00447   return true;
00448 }
00449 
00450 // Get the return signal rate limit check value in MCPS
00451 float VL53L0X::getSignalRateLimit(void)
00452 {
00453   return (float)readReg16Bit(FINAL_RANGE_CONFIG_MIN_COUNT_RATE_RTN_LIMIT) / (1 << 7);
00454 }
00455 
00456 // Set the measurement timing budget in microseconds, which is the time allowed
00457 // for one measurement; the ST API and this library take care of splitting the
00458 // timing budget among the sub-steps in the ranging sequence. A longer timing
00459 // budget allows for more accurate measurements. Increasing the budget by a
00460 // factor of N decreases the range measurement standard deviation by a factor of
00461 // sqrt(N). Defaults to about 33 milliseconds; the minimum is 20 ms.
00462 // based on VL53L0X_set_measurement_timing_budget_micro_seconds()
00463 bool VL53L0X::setMeasurementTimingBudget(uint32_t budget_us)
00464 {
00465   SequenceStepEnables enables;
00466   SequenceStepTimeouts timeouts;
00467 
00468   uint16_t const StartOverhead      = 1320; // note that this is different than the value in get_
00469   uint16_t const EndOverhead        = 960;
00470   uint16_t const MsrcOverhead       = 660;
00471   uint16_t const TccOverhead        = 590;
00472   uint16_t const DssOverhead        = 690;
00473   uint16_t const PreRangeOverhead   = 660;
00474   uint16_t const FinalRangeOverhead = 550;
00475 
00476   uint32_t const MinTimingBudget = 20000;
00477 
00478   if (budget_us < MinTimingBudget) { return false; }
00479 
00480   uint32_t used_budget_us = StartOverhead + EndOverhead;
00481 
00482   getSequenceStepEnables(&enables);
00483   getSequenceStepTimeouts(&enables, &timeouts);
00484 
00485   if (enables.tcc)
00486   {
00487     used_budget_us += (timeouts.msrc_dss_tcc_us + TccOverhead);
00488   }
00489 
00490   if (enables.dss)
00491   {
00492     used_budget_us += 2 * (timeouts.msrc_dss_tcc_us + DssOverhead);
00493   }
00494   else if (enables.msrc)
00495   {
00496     used_budget_us += (timeouts.msrc_dss_tcc_us + MsrcOverhead);
00497   }
00498 
00499   if (enables.pre_range)
00500   {
00501     used_budget_us += (timeouts.pre_range_us + PreRangeOverhead);
00502   }
00503 
00504   if (enables.final_range)
00505   {
00506     used_budget_us += FinalRangeOverhead;
00507 
00508     // "Note that the final range timeout is determined by the timing
00509     // budget and the sum of all other timeouts within the sequence.
00510     // If there is no room for the final range timeout, then an error
00511     // will be set. Otherwise the remaining time will be applied to
00512     // the final range."
00513 
00514     if (used_budget_us > budget_us)
00515     {
00516       // "Requested timeout too big."
00517       return false;
00518     }
00519 
00520     uint32_t final_range_timeout_us = budget_us - used_budget_us;
00521 
00522     // set_sequence_step_timeout() begin
00523     // (SequenceStepId == VL53L0X_SEQUENCESTEP_FINAL_RANGE)
00524 
00525     // "For the final range timeout, the pre-range timeout
00526     //  must be added. To do this both final and pre-range
00527     //  timeouts must be expressed in macro periods MClks
00528     //  because they have different vcsel periods."
00529 
00530     uint16_t final_range_timeout_mclks =
00531       timeoutMicrosecondsToMclks(final_range_timeout_us,
00532                                  timeouts.final_range_vcsel_period_pclks);
00533 
00534     if (enables.pre_range)
00535     {
00536       final_range_timeout_mclks += timeouts.pre_range_mclks;
00537     }
00538 
00539     writeReg16Bit(FINAL_RANGE_CONFIG_TIMEOUT_MACROP_HI,
00540       encodeTimeout(final_range_timeout_mclks));
00541 
00542     // set_sequence_step_timeout() end
00543 
00544     measurement_timing_budget_us = budget_us; // store for internal reuse
00545   }
00546   return true;
00547 }
00548 
00549 // Get the measurement timing budget in microseconds
00550 // based on VL53L0X_get_measurement_timing_budget_micro_seconds()
00551 // in us
00552 uint32_t VL53L0X::getMeasurementTimingBudget(void)
00553 {
00554   SequenceStepEnables enables;
00555   SequenceStepTimeouts timeouts;
00556 
00557   uint16_t const StartOverhead     = 1910; // note that this is different than the value in set_
00558   uint16_t const EndOverhead        = 960;
00559   uint16_t const MsrcOverhead       = 660;
00560   uint16_t const TccOverhead        = 590;
00561   uint16_t const DssOverhead        = 690;
00562   uint16_t const PreRangeOverhead   = 660;
00563   uint16_t const FinalRangeOverhead = 550;
00564 
00565   // "Start and end overhead times always present"
00566   uint32_t budget_us = StartOverhead + EndOverhead;
00567 
00568   getSequenceStepEnables(&enables);
00569   getSequenceStepTimeouts(&enables, &timeouts);
00570 
00571   if (enables.tcc)
00572   {
00573     budget_us += (timeouts.msrc_dss_tcc_us + TccOverhead);
00574   }
00575 
00576   if (enables.dss)
00577   {
00578     budget_us += 2 * (timeouts.msrc_dss_tcc_us + DssOverhead);
00579   }
00580   else if (enables.msrc)
00581   {
00582     budget_us += (timeouts.msrc_dss_tcc_us + MsrcOverhead);
00583   }
00584 
00585   if (enables.pre_range)
00586   {
00587     budget_us += (timeouts.pre_range_us + PreRangeOverhead);
00588   }
00589 
00590   if (enables.final_range)
00591   {
00592     budget_us += (timeouts.final_range_us + FinalRangeOverhead);
00593   }
00594 
00595   measurement_timing_budget_us = budget_us; // store for internal reuse
00596   return budget_us;
00597 }
00598 
00599 // Set the VCSEL (vertical cavity surface emitting laser) pulse period for the
00600 // given period type (pre-range or final range) to the given value in PCLKs.
00601 // Longer periods seem to increase the potential range of the sensor.
00602 // Valid values are (even numbers only):
00603 //  pre:  12 to 18 (initialized default: 14)
00604 //  final: 8 to 14 (initialized default: 10)
00605 // based on VL53L0X_set_vcsel_pulse_period()
00606 bool VL53L0X::setVcselPulsePeriod(vcselPeriodType type, uint8_t period_pclks)
00607 {
00608   uint8_t vcsel_period_reg = encodeVcselPeriod(period_pclks);
00609 
00610   SequenceStepEnables enables;
00611   SequenceStepTimeouts timeouts;
00612 
00613   getSequenceStepEnables(&enables);
00614   getSequenceStepTimeouts(&enables, &timeouts);
00615 
00616   // "Apply specific settings for the requested clock period"
00617   // "Re-calculate and apply timeouts, in macro periods"
00618 
00619   // "When the VCSEL period for the pre or final range is changed,
00620   // the corresponding timeout must be read from the device using
00621   // the current VCSEL period, then the new VCSEL period can be
00622   // applied. The timeout then must be written back to the device
00623   // using the new VCSEL period.
00624   //
00625   // For the MSRC timeout, the same applies - this timeout being
00626   // dependant on the pre-range vcsel period."
00627 
00628 
00629   if (type == VcselPeriodPreRange)
00630   {
00631     // "Set phase check limits"
00632     switch (period_pclks)
00633     {
00634       case 12:
00635         writeReg(PRE_RANGE_CONFIG_VALID_PHASE_HIGH, 0x18);
00636         break;
00637 
00638       case 14:
00639         writeReg(PRE_RANGE_CONFIG_VALID_PHASE_HIGH, 0x30);
00640         break;
00641 
00642       case 16:
00643         writeReg(PRE_RANGE_CONFIG_VALID_PHASE_HIGH, 0x40);
00644         break;
00645 
00646       case 18:
00647         writeReg(PRE_RANGE_CONFIG_VALID_PHASE_HIGH, 0x50);
00648         break;
00649 
00650       default:
00651         // invalid period
00652         return false;
00653     }
00654     writeReg(PRE_RANGE_CONFIG_VALID_PHASE_LOW, 0x08);
00655 
00656     // apply new VCSEL period
00657     writeReg(PRE_RANGE_CONFIG_VCSEL_PERIOD, vcsel_period_reg);
00658 
00659     // update timeouts
00660 
00661     // set_sequence_step_timeout() begin
00662     // (SequenceStepId == VL53L0X_SEQUENCESTEP_PRE_RANGE)
00663 
00664     uint16_t new_pre_range_timeout_mclks =
00665       timeoutMicrosecondsToMclks(timeouts.pre_range_us, period_pclks);
00666 
00667     writeReg16Bit(PRE_RANGE_CONFIG_TIMEOUT_MACROP_HI,
00668       encodeTimeout(new_pre_range_timeout_mclks));
00669 
00670     // set_sequence_step_timeout() end
00671 
00672     // set_sequence_step_timeout() begin
00673     // (SequenceStepId == VL53L0X_SEQUENCESTEP_MSRC)
00674 
00675     uint16_t new_msrc_timeout_mclks =
00676       timeoutMicrosecondsToMclks(timeouts.msrc_dss_tcc_us, period_pclks);
00677 
00678     writeReg(MSRC_CONFIG_TIMEOUT_MACROP,
00679       (new_msrc_timeout_mclks > 256) ? 255 : (new_msrc_timeout_mclks - 1));
00680 
00681     // set_sequence_step_timeout() end
00682   }
00683   else if (type == VcselPeriodFinalRange)
00684   {
00685     switch (period_pclks)
00686     {
00687       case 8:
00688         writeReg(FINAL_RANGE_CONFIG_VALID_PHASE_HIGH, 0x10);
00689         writeReg(FINAL_RANGE_CONFIG_VALID_PHASE_LOW,  0x08);
00690         writeReg(GLOBAL_CONFIG_VCSEL_WIDTH, 0x02);
00691         writeReg(ALGO_PHASECAL_CONFIG_TIMEOUT, 0x0C);
00692         writeReg(0xFF, 0x01);
00693         writeReg(ALGO_PHASECAL_LIM, 0x30);
00694         writeReg(0xFF, 0x00);
00695         break;
00696 
00697       case 10:
00698         writeReg(FINAL_RANGE_CONFIG_VALID_PHASE_HIGH, 0x28);
00699         writeReg(FINAL_RANGE_CONFIG_VALID_PHASE_LOW,  0x08);
00700         writeReg(GLOBAL_CONFIG_VCSEL_WIDTH, 0x03);
00701         writeReg(ALGO_PHASECAL_CONFIG_TIMEOUT, 0x09);
00702         writeReg(0xFF, 0x01);
00703         writeReg(ALGO_PHASECAL_LIM, 0x20);
00704         writeReg(0xFF, 0x00);
00705         break;
00706 
00707       case 12:
00708         writeReg(FINAL_RANGE_CONFIG_VALID_PHASE_HIGH, 0x38);
00709         writeReg(FINAL_RANGE_CONFIG_VALID_PHASE_LOW,  0x08);
00710         writeReg(GLOBAL_CONFIG_VCSEL_WIDTH, 0x03);
00711         writeReg(ALGO_PHASECAL_CONFIG_TIMEOUT, 0x08);
00712         writeReg(0xFF, 0x01);
00713         writeReg(ALGO_PHASECAL_LIM, 0x20);
00714         writeReg(0xFF, 0x00);
00715         break;
00716 
00717       case 14:
00718         writeReg(FINAL_RANGE_CONFIG_VALID_PHASE_HIGH, 0x48);
00719         writeReg(FINAL_RANGE_CONFIG_VALID_PHASE_LOW,  0x08);
00720         writeReg(GLOBAL_CONFIG_VCSEL_WIDTH, 0x03);
00721         writeReg(ALGO_PHASECAL_CONFIG_TIMEOUT, 0x07);
00722         writeReg(0xFF, 0x01);
00723         writeReg(ALGO_PHASECAL_LIM, 0x20);
00724         writeReg(0xFF, 0x00);
00725         break;
00726 
00727       default:
00728         // invalid period
00729         return false;
00730     }
00731 
00732     // apply new VCSEL period
00733     writeReg(FINAL_RANGE_CONFIG_VCSEL_PERIOD, vcsel_period_reg);
00734 
00735     // update timeouts
00736 
00737     // set_sequence_step_timeout() begin
00738     // (SequenceStepId == VL53L0X_SEQUENCESTEP_FINAL_RANGE)
00739 
00740     // "For the final range timeout, the pre-range timeout
00741     //  must be added. To do this both final and pre-range
00742     //  timeouts must be expressed in macro periods MClks
00743     //  because they have different vcsel periods."
00744 
00745     uint16_t new_final_range_timeout_mclks =
00746       timeoutMicrosecondsToMclks(timeouts.final_range_us, period_pclks);
00747 
00748     if (enables.pre_range)
00749     {
00750       new_final_range_timeout_mclks += timeouts.pre_range_mclks;
00751     }
00752 
00753     writeReg16Bit(FINAL_RANGE_CONFIG_TIMEOUT_MACROP_HI,
00754       encodeTimeout(new_final_range_timeout_mclks));
00755 
00756     // set_sequence_step_timeout end
00757   }
00758   else
00759   {
00760     // invalid type
00761     return false;
00762   }
00763 
00764   // "Finally, the timing budget must be re-applied"
00765 
00766   setMeasurementTimingBudget(measurement_timing_budget_us);
00767 
00768   // "Perform the phase calibration. This is needed after changing on vcsel period."
00769   // VL53L0X_perform_phase_calibration() begin
00770 
00771   uint8_t sequence_config = readReg(SYSTEM_SEQUENCE_CONFIG);
00772   writeReg(SYSTEM_SEQUENCE_CONFIG, 0x02);
00773   performSingleRefCalibration(0x0);
00774   writeReg(SYSTEM_SEQUENCE_CONFIG, sequence_config);
00775 
00776   // VL53L0X_perform_phase_calibration() end
00777 
00778   return true;
00779 }
00780 
00781 // Get the VCSEL pulse period in PCLKs for the given period type.
00782 // based on VL53L0X_get_vcsel_pulse_period()
00783 uint8_t VL53L0X::getVcselPulsePeriod(vcselPeriodType type)
00784 {
00785   if (type == VcselPeriodPreRange)
00786   {
00787     return decodeVcselPeriod(readReg(PRE_RANGE_CONFIG_VCSEL_PERIOD));
00788   }
00789   else if (type == VcselPeriodFinalRange)
00790   {
00791     return decodeVcselPeriod(readReg(FINAL_RANGE_CONFIG_VCSEL_PERIOD));
00792   }
00793   else { return 255; }
00794 }
00795 
00796 // Start continuous ranging measurements. If period_ms (optional) is 0 or not
00797 // given, continuous back-to-back mode is used (the sensor takes measurements as
00798 // often as possible); otherwise, continuous timed mode is used, with the given
00799 // inter-measurement period in milliseconds determining how often the sensor
00800 // takes a measurement.
00801 // based on VL53L0X_StartMeasurement()
00802 void VL53L0X::startContinuous(uint32_t period_ms)
00803 {
00804   writeReg(0x80, 0x01);
00805   writeReg(0xFF, 0x01);
00806   writeReg(0x00, 0x00);
00807   writeReg(0x91, stop_variable);
00808   writeReg(0x00, 0x01);
00809   writeReg(0xFF, 0x00);
00810   writeReg(0x80, 0x00);
00811 
00812   if (period_ms != 0)
00813   {
00814     // continuous timed mode
00815 
00816     // VL53L0X_SetInterMeasurementPeriodMilliSeconds() begin
00817 
00818     uint16_t osc_calibrate_val = readReg16Bit(OSC_CALIBRATE_VAL);
00819 
00820     if (osc_calibrate_val != 0)
00821     {
00822       period_ms *= osc_calibrate_val;
00823     }
00824 
00825     writeReg32Bit(SYSTEM_INTERMEASUREMENT_PERIOD, period_ms);
00826 
00827     // VL53L0X_SetInterMeasurementPeriodMilliSeconds() end
00828 
00829     writeReg(SYSRANGE_START, 0x04); // VL53L0X_REG_SYSRANGE_MODE_TIMED
00830   }
00831   else
00832   {
00833     // continuous back-to-back mode
00834     writeReg(SYSRANGE_START, 0x02); // VL53L0X_REG_SYSRANGE_MODE_BACKTOBACK
00835   }
00836 }
00837 
00838 // Stop continuous measurements
00839 // based on VL53L0X_StopMeasurement()
00840 void VL53L0X::stopContinuous(void)
00841 {
00842   writeReg(SYSRANGE_START, 0x01); // VL53L0X_REG_SYSRANGE_MODE_SINGLESHOT
00843 
00844   writeReg(0xFF, 0x01);
00845   writeReg(0x00, 0x00);
00846   writeReg(0x91, 0x00);
00847   writeReg(0x00, 0x01);
00848   writeReg(0xFF, 0x00);
00849 }
00850 
00851 // Returns a range reading in millimeters when continuous mode is active
00852 // (readRangeSingleMillimeters() also calls this function after starting a
00853 // single-shot range measurement)
00854 uint16_t VL53L0X::readRangeContinuousMillimeters(void)
00855 {
00856   startTimeout();
00857   while ((readReg(RESULT_INTERRUPT_STATUS) & 0x07) == 0)
00858   {
00859     if (checkTimeoutExpired())
00860     {
00861       did_timeout = true;
00862       return 65535;
00863     }
00864   }
00865 
00866   // assumptions: Linearity Corrective Gain is 1000 (default);
00867   // fractional ranging is not enabled
00868   uint16_t range = readReg16Bit(RESULT_RANGE_STATUS + 10);
00869 
00870   writeReg(SYSTEM_INTERRUPT_CLEAR, 0x01);
00871 
00872   return range;
00873 }
00874 
00875 // Performs a single-shot range measurement and returns the reading in
00876 // millimeters
00877 // based on VL53L0X_PerformSingleRangingMeasurement()
00878 uint16_t VL53L0X::readRangeSingleMillimeters(void)
00879 {
00880   writeReg(0x80, 0x01);
00881   writeReg(0xFF, 0x01);
00882   writeReg(0x00, 0x00);
00883   writeReg(0x91, stop_variable);
00884   writeReg(0x00, 0x01);
00885   writeReg(0xFF, 0x00);
00886   writeReg(0x80, 0x00);
00887 
00888   writeReg(SYSRANGE_START, 0x01);
00889 
00890   // "Wait until start bit has been cleared"
00891   startTimeout();
00892   while (readReg(SYSRANGE_START) & 0x01)
00893   {
00894     if (checkTimeoutExpired())
00895     {
00896       did_timeout = true;
00897       return 65535;
00898     }
00899   }
00900 
00901   return readRangeContinuousMillimeters();
00902 }
00903 
00904 // Did a timeout occur in one of the read functions since the last call to
00905 // timeoutOccurred()?
00906 bool VL53L0X::timeoutOccurred()
00907 {
00908   bool tmp = did_timeout;
00909   did_timeout = false;
00910   return tmp;
00911 }
00912 
00913 // Private Methods /////////////////////////////////////////////////////////////
00914 
00915 // Get reference SPAD (single photon avalanche diode) count and type
00916 // based on VL53L0X_get_info_from_device(),
00917 // but only gets reference SPAD count and type
00918 bool VL53L0X::getSpadInfo(uint8_t * count, bool * type_is_aperture)
00919 {
00920   uint8_t tmp;
00921 
00922   writeReg(0x80, 0x01);
00923   writeReg(0xFF, 0x01);
00924   writeReg(0x00, 0x00);
00925 
00926   writeReg(0xFF, 0x06);
00927   writeReg(0x83, readReg(0x83) | 0x04);
00928   writeReg(0xFF, 0x07);
00929   writeReg(0x81, 0x01);
00930 
00931   writeReg(0x80, 0x01);
00932 
00933   writeReg(0x94, 0x6b);
00934   writeReg(0x83, 0x00);
00935   startTimeout();
00936   while (readReg(0x83) == 0x00)
00937   {
00938     if (checkTimeoutExpired()) { return false; }
00939   }
00940   writeReg(0x83, 0x01);
00941   tmp = readReg(0x92);
00942 
00943   *count = tmp & 0x7f;
00944   *type_is_aperture = (tmp >> 7) & 0x01;
00945 
00946   writeReg(0x81, 0x00);
00947   writeReg(0xFF, 0x06);
00948   writeReg(0x83, readReg( 0x83  & ~0x04));
00949   writeReg(0xFF, 0x01);
00950   writeReg(0x00, 0x01);
00951 
00952   writeReg(0xFF, 0x00);
00953   writeReg(0x80, 0x00);
00954 
00955   return true;
00956 }
00957 
00958 // Get sequence step enables
00959 // based on VL53L0X_GetSequenceStepEnables()
00960 void VL53L0X::getSequenceStepEnables(SequenceStepEnables * enables)
00961 {
00962   uint8_t sequence_config = readReg(SYSTEM_SEQUENCE_CONFIG);
00963 
00964   enables->tcc          = (sequence_config >> 4) & 0x1;
00965   enables->dss          = (sequence_config >> 3) & 0x1;
00966   enables->msrc         = (sequence_config >> 2) & 0x1;
00967   enables->pre_range    = (sequence_config >> 6) & 0x1;
00968   enables->final_range  = (sequence_config >> 7) & 0x1;
00969 }
00970 
00971 // Get sequence step timeouts
00972 // based on get_sequence_step_timeout(),
00973 // but gets all timeouts instead of just the requested one, and also stores
00974 // intermediate values
00975 void VL53L0X::getSequenceStepTimeouts(SequenceStepEnables const * enables, SequenceStepTimeouts * timeouts)
00976 {
00977   timeouts->pre_range_vcsel_period_pclks = getVcselPulsePeriod(VcselPeriodPreRange);
00978 
00979   timeouts->msrc_dss_tcc_mclks = readReg(MSRC_CONFIG_TIMEOUT_MACROP) + 1;
00980   timeouts->msrc_dss_tcc_us =
00981     timeoutMclksToMicroseconds(timeouts->msrc_dss_tcc_mclks,
00982                                timeouts->pre_range_vcsel_period_pclks);
00983 
00984   timeouts->pre_range_mclks =
00985     decodeTimeout(readReg16Bit(PRE_RANGE_CONFIG_TIMEOUT_MACROP_HI));
00986   timeouts->pre_range_us =
00987     timeoutMclksToMicroseconds(timeouts->pre_range_mclks,
00988                                timeouts->pre_range_vcsel_period_pclks);
00989 
00990   timeouts->final_range_vcsel_period_pclks = getVcselPulsePeriod(VcselPeriodFinalRange);
00991 
00992   timeouts->final_range_mclks =
00993     decodeTimeout(readReg16Bit(FINAL_RANGE_CONFIG_TIMEOUT_MACROP_HI));
00994 
00995   if (enables->pre_range)
00996   {
00997     timeouts->final_range_mclks -= timeouts->pre_range_mclks;
00998   }
00999 
01000   timeouts->final_range_us =
01001     timeoutMclksToMicroseconds(timeouts->final_range_mclks,
01002                                timeouts->final_range_vcsel_period_pclks);
01003 }
01004 
01005 // Decode sequence step timeout in MCLKs from register value
01006 // based on VL53L0X_decode_timeout()
01007 // Note: the original function returned a uint32_t, but the return value is
01008 // always stored in a uint16_t.
01009 uint16_t VL53L0X::decodeTimeout(uint16_t reg_val)
01010 {
01011   // format: "(LSByte * 2^MSByte) + 1"
01012   return (uint16_t)((reg_val & 0x00FF) <<
01013          (uint16_t)((reg_val & 0xFF00) >> 8)) + 1;
01014 }
01015 
01016 // Encode sequence step timeout register value from timeout in MCLKs
01017 // based on VL53L0X_encode_timeout()
01018 // Note: the original function took a uint16_t, but the argument passed to it
01019 // is always a uint16_t.
01020 uint16_t VL53L0X::encodeTimeout(uint16_t timeout_mclks)
01021 {
01022   // format: "(LSByte * 2^MSByte) + 1"
01023 
01024   uint32_t ls_byte = 0;
01025   uint16_t ms_byte = 0;
01026 
01027   if (timeout_mclks > 0)
01028   {
01029     ls_byte = timeout_mclks - 1;
01030 
01031     while ((ls_byte & 0xFFFFFF00) > 0)
01032     {
01033       ls_byte >>= 1;
01034       ms_byte++;
01035     }
01036 
01037     return (ms_byte << 8) | (ls_byte & 0xFF);
01038   }
01039   else { return 0; }
01040 }
01041 
01042 // Convert sequence step timeout from MCLKs to microseconds with given VCSEL period in PCLKs
01043 // based on VL53L0X_calc_timeout_us()
01044 uint32_t VL53L0X::timeoutMclksToMicroseconds(uint16_t timeout_period_mclks, uint8_t vcsel_period_pclks)
01045 {
01046   uint32_t macro_period_ns = calcMacroPeriod(vcsel_period_pclks);
01047 
01048   return ((timeout_period_mclks * macro_period_ns) + (macro_period_ns / 2)) / 1000;
01049 }
01050 
01051 // Convert sequence step timeout from microseconds to MCLKs with given VCSEL period in PCLKs
01052 // based on VL53L0X_calc_timeout_mclks()
01053 uint32_t VL53L0X::timeoutMicrosecondsToMclks(uint32_t timeout_period_us, uint8_t vcsel_period_pclks)
01054 {
01055   uint32_t macro_period_ns = calcMacroPeriod(vcsel_period_pclks);
01056 
01057   return (((timeout_period_us * 1000) + (macro_period_ns / 2)) / macro_period_ns);
01058 }
01059 
01060 
01061 // based on VL53L0X_perform_single_ref_calibration()
01062 bool VL53L0X::performSingleRefCalibration(uint8_t vhv_init_byte)
01063 {
01064   writeReg(SYSRANGE_START, 0x01 | vhv_init_byte); // VL53L0X_REG_SYSRANGE_MODE_START_STOP
01065 
01066   startTimeout();
01067   while ((readReg(RESULT_INTERRUPT_STATUS) & 0x07) == 0)
01068   {
01069     if (checkTimeoutExpired()) { return false; }
01070   }
01071 
01072   writeReg(SYSTEM_INTERRUPT_CLEAR, 0x01);
01073 
01074   writeReg(SYSRANGE_START, 0x00);
01075 
01076   return true;
01077 }
01078