Qwiic Distance Sensor (VL53L1X) Hookup Guide
This Tutorial is Retired!
This tutorial covers concepts or technologies that are no longer current. It's still here for you to read and enjoy, but may not be as useful as our newest tutorials.
View the updated tutorial: Qwiic Distance Sensor (VL53L1X, VL53L4CD) Hookup Guide
Arduino Library Overview
Note: This example assumes you are using the latest version of the Arduino IDE on your desktop. If this is your first time using Arduino, please review our tutorial on installing the Arduino IDE. If you have not previously installed an Arduino library, please check out our installation guide.
First, you'll need the SparkFun VL53L1X Arduino library, which is an easy to use wrapper of ST's driver. You can obtain these libraries through the Arduino Library Manager. Search for Sparkfun VL53L1X Arduino Library to install the latest version. If you prefer downloading the libraries from the GitHub repository and manually installing it, you can grab them here:
Before we get started developing a sketch, let's look at the available functions of the library.
boolean init();
--- Initialize the sensorvoid startRanging();
--- Starts taking measurements.void stopRanging();
--- Stops taking measurements.bool checkForDataReady();
--- Checks if a measurement is ready.void setTimingBudgetInMs(uint16_t timingBudget)
--- Set the timing budget for a measurement in ms. The timing budget is the amount of time over which a measurement is taken. This can be set to any of the following.- 15
- 20
- 33
- 50
- 100 (default)
- 200
- 500
uint16_t getTimingBudgetInMs();
--- Get's the current timing budget in ms.void setDistanceModeLong();
--- Sets to 4M range.void setDistanceModeShort();
--- Sets to 1.3M rangeuint8_t getDistanceMode();
--- Returns 1 for short range, 2 for long range.void setIntermeasurementPeriod(uint16_t intermeasurement);
--- Set's the period in between measurements. Must be greater than or equal to the timing budget. Default is 100 ms.uint16_t getIntermeasurementPeriod();
--- Returns the intermeasurement period in ms.bool checkBootState();
--- Checks whether the device has been booted. Returns true if the device has been booted.uint16_t getSensorID();
--- Get the sensor ID, should be 0xEEAC.uint16_t getDistance();
--- Returns the results from the last measurement, distance in mmuint16_t getSignalPerSpad();
--- Returns the average signal rate per SPAD (The sensitive pads that detect light, the VL53L1X has a 16x16 array of these) in kcps/SPAD, or kilo counts per second per SPAD.uint16_t getAmbientPerSpad();
--- Returns the ambient noise when not measuring a signal in kcps/SPAD.uint16_t getSignalRate();
--- Returns the signal rate in kcps. All SPADs combined.uint16_t getSpadNb();
--- Returns the current number of enabled SPADsuint16_t getAmbientRate();
--- Returns the total ambinet rate in kcps. All SPADs combined.uint8_t getRangeStatus();
--- Returns the range status, which can be any of the following.- 0: No error
- 1: Signal fail
- 2: Sigma fail
- 7: Wrapped target fail
void setOffset(int16_t offset);
--- Manually set an offset for a measurement in mm.int16_t getOffset();
--- Get the current offset in mm.void setXTalk(uint16_t xTalk);
--- Manually set the value of crosstalk in counts per second (cps), which is interference from any sort of window in front of your sensor.uint16_t getXTalk();
--- Returns the current crosstalk value in cps.void setDistanceThreshold(uint16_t lowThresh, uint16_t hiThresh, uint8_t window);
--- Set bounds for the interrupt. lowThresh and hiThresh are the bounds of your interrupt while window decides when the interrupt should fire. The options forwindow
are shown below.- 0: Interrupt triggered on measured distance below lowThresh.
- 1: Interrupt triggered on measured distance above hiThresh.
- 2: Interrupt triggered on measured distance outside of bounds.
- 3: Interrupt triggered on measured distance inside of bounds.
uint16_t getDistanceThresholdWindow();
--- Returns distance threshold window option.uint16_t getDistanceThresholdLow();
--- Returns lower bound in mm.uint16_t getDistanceThresholdHigh();
--- Returns upper bound in mmvoid setROI(uint16_t x, uint16_t y, uint8_t opticalCenter);
--- Set the height and width of the ROI in SPADs, lowest possible option is 4. The center of the ROI you set is based on the table below. Set theopticalCenter
as the pad above and to the right of your exact center.
128 | 136 | 144 | 152 | 160 | 168 | 176 | 184 | 192 | 200 | 208 | 216 | 224 | 232 | 240 | 248 |
129 | 137 | 145 | 153 | 161 | 169 | 177 | 185 | 193 | 201 | 209 | 217 | 225 | 233 | 241 | 249 |
130 | 138 | 146 | 154 | 162 | 170 | 178 | 186 | 194 | 202 | 210 | 218 | 226 | 234 | 242 | 250 |
131 | 139 | 147 | 155 | 163 | 171 | 179 | 187 | 195 | 203 | 211 | 219 | 227 | 235 | 243 | 251 |
132 | 140 | 148 | 156 | 164 | 172 | 180 | 188 | 196 | 204 | 212 | 220 | 228 | 236 | 244 | 252 |
133 | 141 | 149 | 157 | 165 | 173 | 181 | 189 | 197 | 205 | 213 | 221 | 229 | 237 | 245 | 253 |
134 | 142 | 150 | 158 | 166 | 174 | 182 | 190 | 198 | 206 | 214 | 222 | 230 | 238 | 246 | 254 |
135 | 143 | 151 | 159 | 167 | 175 | 183 | 191 | 199 | 207 | 215 | 223 | 231 | 239 | 247 | 255 |
127 | 119 | 111 | 103 | 95 | 87 | 79 | 71 | 63 | 55 | 47 | 39 | 31 | 23 | 15 | 7 |
126 | 118 | 110 | 102 | 94 | 86 | 78 | 70 | 62 | 54 | 46 | 38 | 30 | 22 | 14 | 6 |
125 | 117 | 109 | 101 | 93 | 85 | 77 | 69 | 61 | 53 | 45 | 37 | 29 | 21 | 13 | 5 |
124 | 116 | 108 | 100 | 92 | 84 | 76 | 68 | 60 | 52 | 44 | 36 | 28 | 20 | 12 | 4 |
123 | 115 | 107 | 99 | 91 | 83 | 75 | 67 | 59 | 51 | 43 | 35 | 27 | 19 | 11 | 3 |
122 | 114 | 106 | 98 | 90 | 82 | 74 | 66 | 58 | 50 | 42 | 34 | 26 | 18 | 10 | 2 |
121 | 113 | 105 | 97 | 89 | 81 | 73 | 65 | 57 | 49 | 41 | 33 | 25 | 17 | 9 | 1 |
120 | 112 | 104 | 96 | 88 | 80 | 72 | 64 | 56 | 48 | 40 | 32 | 24 | 16 | 8 | 0 |
uint16_t getROIX();
--- Returns the width of the ROI in SPADsuint16_t getROIY();
--- Returns the height of the ROI in SPADsvoid setSignalThreshold(uint16_t signalThreshold);
--- Programs the necessary threshold to trigger a measurement. Default is 1024 kcps.uint16_t getSignalThreshold();
--- Returns the signal threshold in kcpsvoid setSigmaThreshold(uint16_t sigmaThreshold);
--- Programs a new sigma threshold in mm. (default=15 mm)uint16_t getSigmaThreshold();
--- Returns the current sigma threshold.void startTemperatureUpdate();
--- Recalibrates the sensor for temperature changes. Run this any time the temperature has changed by more than 8°Cvoid calibrateOffset(uint16_t targetDistanceInMm);
--- Autocalibrate the offset by placing a target a known distance away from the sensor and passing this known distance into the function.void calibrateXTalk(uint16_t targetDistanceInMm);
--- Autocalibrate the crosstalk by placing a target a known distance away from the sensor and passing this known distance into the function.