Qwiic Distance Sensor (VL53L1X) Hookup Guide

Contributors: Englandsaurus
Favorited Favorite 2


The VL53L1X is the latest Time Of Flight (ToF) sensor to be released. It uses a VCSEL (vertical cavity surface emitting laser) to emit a class 1 IR laser (940 nm) and time the reflection to the target. (You can’t see the laser but cell phones can) What does all this mean? You can measure the distance to an object up to 4 meters away with millimeter resolution! That’s pretty incredible.

SparkFun Distance Sensor Breakout - 4 Meter, VL53L1X (Qwiic)

SparkFun Distance Sensor Breakout - 4 Meter, VL53L1X (Qwiic)


We’ve found the precision of the sensor to be 1mm but the accuracy is around +/-5mm. The minimum read distance of this sensor is 4cm. In this hookup guide we'll go over how to read distance, change ranging modes, and check the status of our range measurement along with the sample rate. We'll also check out how to display distance and speed over an LCD display.

Required Materials

The Qwiic Distance Sensor does need a few additional items for you to get started. The RedBoard Qwiic is for the Arduino examples and the Qwiic pHAT is for the Raspberry Pi example (see note below). You may already have a few of these items, so feel free to modify your cart based on your needs. Additionally, there are also options that are available as well (click button below to toggle options).

SparkFun RedBoard Qwiic

SparkFun RedBoard Qwiic

SparkFun Qwiic Cable Kit

SparkFun Qwiic Cable Kit

SparkFun Qwiic pHAT for Raspberry Pi

SparkFun Qwiic pHAT for Raspberry Pi

Qwiic compatible microcontrollers:

SparkFun Thing Plus - ESP32 WROOM

SparkFun RedBoard Qwiic

SparkFun RedBoard Qwiic

SparkFun RedBoard Turbo - SAMD21 Development Board

SparkFun RedBoard Turbo - SAMD21 Development Board

SparkFun Thing Plus - SAMD51

SparkFun Thing Plus - SAMD51

In addition we also offer, Qwiic compatible stackable shields for microcontrollers and pHATs for single board computers (like the Raspberry Pi boards) that don't include a Qwiic connector.
SparkFun Qwiic Shield for Arduino

SparkFun Qwiic Shield for Arduino

SparkFun Qwiic Adapter

SparkFun Qwiic Adapter

SparkFun Qwiic Shield for Photon

SparkFun Qwiic Shield for Photon

SparkFun Qwiic SHIM for Raspberry Pi

SparkFun Qwiic SHIM for Raspberry Pi

SparkFun Qwiic HAT for Raspberry Pi

SparkFun Qwiic HAT for Raspberry Pi

SparkFun Qwiic pHAT for Raspberry Pi

SparkFun Qwiic pHAT for Raspberry Pi

SparkFun Servo pHAT for Raspberry Pi

SparkFun Servo pHAT for Raspberry Pi

You will also need a Qwiic cable to connect to your Qwiic Distance Sensor, choose a length that suits your needs.
Qwiic Cable - 100mm

Qwiic Cable - 100mm

Qwiic Cable - 200mm

Qwiic Cable - 200mm

Qwiic Cable - 50mm

Qwiic Cable - 50mm

Qwiic Cable - 500mm

Qwiic Cable - 500mm


Raspberry Pi Example: If you don't already have them, you will need a Raspberry Pi and standard peripherals. An example setup is listed below. (The Qwiic Distance Sensor and Python library have not been tested on the newly released Raspberry Pi 4 because we don't carry it in out catalog yet.)

Suggested Reading

If you're unfamiliar with jumper pads, I2C, Qwiic, or Python be sure to checkout some of these foundational tutorials.

Serial Communication

Asynchronous serial communication concepts: packets, signal levels, baud rates, UARTs and more!

Logic Levels

Learn the difference between 3.3V and 5V devices and logic levels.


An introduction to I2C, one of the main embedded communications protocols in use today.

Serial Terminal Basics

This tutorial will show you how to communicate with your serial devices using a variety of terminal emulator applications.

Raspberry Pi SPI and I2C Tutorial

Learn how to use serial I2C and SPI buses on your Raspberry Pi using the wiringPi I/O library for C/C++ and spidev/smbus for Python.

Raspberry Pi 3 Starter Kit Hookup Guide

Guide for getting going with the Raspberry Pi 3 Model B and Raspberry Pi 3 Model B+ starter kit.

Python Programming Tutorial: Getting Started with the Raspberry Pi

This guide will show you how to write programs on your Raspberry Pi using Python to control hardware.

Qwiic pHAT for Raspberry Pi Hookup Guide

Get started interfacing your Qwiic enabled boards with your Raspberry Pi. The Qwiic pHAT connects the I2C bus (GND, 3.3V, SDA, and SCL) on your Raspberry Pi to an array of Qwiic connectors.

Qwiic Shield for Arduino & Photon Hookup Guide

Get started with our Qwiic ecosystem with the Qwiic shield for Arduino or Photon.

RedBoard Qwiic Hookup Guide

This tutorial covers the basic functionality of the RedBoard Qwiic. This tutorial also covers how to get started blinking an LED and using the Qwiic system.

Qwiic Connect System

The Qwiic Distance Sensor is intended for the Qwiic connect system. We recommend familiarizing yourself with the Logic Levels and I2C tutorials before using it. Click on the banner above to learn more about our Qwiic products.

Hardware Overview

First let's check out some of the characteristics of the VL53L1X sensor we're dealing with, so we know what to expect out of the board.

Operating Voltage2.6V-3.5V
Power Consumption20 mW @10Hz
Measurement Range~40mm to 4,000mm
Light SourceClass 1 940nm VCSEL
I2C Address0x29
Field of View15° - 27°
Max Read Rate50Hz


The following table lists all of the VL53L1X's pins and their functionality.

INTInterrupt, goes low when data is ready.Out
SHUTShutdown, can be pulled low to put the IC in shutdown mode.In

Optional Features

The VL53L1X breakout has pull up resistors attached to the I2C bus as well as the interrupt pin; if multiple sensors are connected to the bus with the pull-up resistors enabled, the parallel equivalent resistance will create too strong of a pull-up for the bus to operate correctly. As a general rule of thumb, disable all but one pair of pull-up resistors if multiple devices are connected to the bus. If you need to disconnect the pull up resistors they can be removed by cutting the traces on the corresponding jumpers highlighted below.

Pullup Jumpers

The onboard LED (highlighted below) will light up when the board is powered, and the sensor (also highlighted below) should be left uncovered in your application.

Sensor and LED

Hardware Assembly

If you haven't yet assembled your Qwiic Shield, now would be the time to head on over to that tutorial. Depending on the microcontroller and shield you've chosen, your assembly may be different, but here's a handy link to the Qwiic Shield for Arduino and Photon Hookup Guide to get you started!

With the shield assembled, SparkFun's new Qwiic environment means that connecting the sensor could not be easier. Just plug one end of the Qwiic cable into the VL53L1X breakout, the other into the Qwiic Shield and you'll be ready to upload a sketch and figure out how far away you are from that thing over there. It seems like it's too easy too use, but that's why we made it that way!

Connected to Qwiic Shield

SparkFun RedBoard and Qwiic Shield with the Qwiic Distance Sensor Attached

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 sensor
  • void 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 range
  • uint8_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 mm
  • uint16_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 SPADs
  • uint16_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 for window 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 mm
  • void 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 the opticalCenter 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 146 155 163 171 179 187 195 203 211 219 227 235 243 251
132 140 147 156 164 172 180 188 196 204 212 220 228 236 244 252
133 141 148 157 165 173 181 189 197 205 213 221 229 237 245 253
134 142 149 158 166 174 182 190 198 206 214 222 230 238 246 254
135 143 150 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 SPADs
  • uint16_t getROIY(); --- Returns the height of the ROI in SPADs
  • void setSignalThreshold(uint16_t signalThreshold); --- Programs the necessary threshold to trigger a measurement. Default is 1024 kcps.
  • uint16_t getSignalThreshold(); --- Returns the signal threshold in kcps
  • void 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°C
  • void 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.

Arduino Example Code

Now that we have our library installed and we understand the basic functions, let's run some examples for our distance sensor to see how it behaves.

Example 1 - Read Distance

To get started with the first example, open up File > Examples > SparkFun VL53L1x 4M Laser Distance Sensor > Example1_ReadDistance. In this example, we begin by creating a SFEVL53L1X object called distanceSensor with our wire port, Wire, and then our shutdown and interrupt pins. Then we initialize our sensor object in the setup() loop. The code to do this is shown below and is repeated in some form in all of the examples.

#include <Wire.h>
#include "SparkFun_VL53L1X.h"

//Optional interrupt and shutdown pins.
#define SHUTDOWN_PIN 2


void setup(void)

  Serial.println("VL53L1X Qwiic Test");

  if (distanceSensor.init() == false)
    Serial.println("Sensor online!");


Once we've initialized our sensor, we can start grabbing measurements from it. To do this, we send some configuration bytes to our sensor using distanceSensor.startRanging() to initiate the measurement. We then wait for data to become available and when it does, we read it in, convert it from millimeters to feet, and print it out over serial. The void loop() function that does this is shown below.

void loop(void)
  distanceSensor.startRanging(); //Write configuration bytes to initiate measurement
  int distance = distanceSensor.getDistance(); //Get the result of the measurement from the sensor

  Serial.print("Distance(mm): ");

  float distanceInches = distance * 0.0393701;
  float distanceFeet = distanceInches / 12.0;

  Serial.print("\tDistance(ft): ");
  Serial.print(distanceFeet, 2);


Opening your serial monitor to a baud rate of 9600 should show the distance between the sensor and the object it's pointed at in both millimeters and feet. The output should look something like the below image.

Read Distance

Distance readings in mm and ft

Example 2 - Set Distance Mode

In this example, we'll change the distance mode of the VL53L1X. The default long range mode is the most robust as far as sample rate and range are concerned, but for a slightly higher sample rate, you can bring the range down to short (~1.3M). To get started with the second example, open up File > Examples > SparkFun VL53L1x 4M Laser Distance Sensor > Example2_SetDistanceMode. The main difference between this example and the previous example is that we call distanceSensor.setDistanceModeShort to change the range of our sensor to short range. Although this feature is available, we'd recommend sticking with long range as it is the most robust.

Example 3 - Status and Rate

In the third example, we'll read and average our distance as well as read the sample rate and status of each measurement. To get started with the third example, open up File > Examples > SparkFun VL53L1x 4M Laser Distance Sensor > ExampleStatusandRate. The status of a measurement can be any of 8 values. Our void loop() interprets the value returned by distanceSensor.getRangeStatus() and prints that value over serial. The below table shows the possible values of rangeStatus and their corresponding errors.

Range StatusError
0Valid measurement
1Raised if sigma estimator (uncertainty in measurement) check is above the internal defined threshold
2 Raised if signal value is below the internal defined threshold
4Raised when phase is out of bounds
5Raised in case of HW or VCSEL failure
7Wrapped target, not matching phases
8Internal algorithm underflow or overflow
14The reported range is invalid

In the example code, notice how the sketch stores our previous values in the array history so that the average distance can also be calculated. Uploading this sketch to your microcontroller and opening the serial monitor to a baud rate of 9600 should give you an output similar to the image shown below.

Status and Rate

Click the image for a closer look.

Example 4 - Set Intermeasurement Period

The fourth example allows you to change the time alotted for a measurement. The VL53L1X will send out a laser pulse and then listen for the alotted time. We'd recommend 20, 33, and 100 ms for short, medium and long distance modes respectively. To open up the example, head to File > Examples > SparkFun VL53L1x 4M Laser Distance Sensor > Example4_SetIntermeasurementPeriod. There's not much that needs to be done to change the intermeasurement period other than a call to distanceSensor.setIntermeasurementPeriod(33) to change the time alotted time for a measurement to 33 ms. This will give us a data rate of roughly 30 Hz, lengthening the intermeasurement period will give us a lower sample rate, but will yield higher accuracy at longer ranges. Opening the serial monitor should yield an output similar to example 1.

Example 5 - LCD Demo

The fifth example requires a serial enabled LCD screen for us to write our distance values to. If you haven't played around with a Serial enabled LCD before, checkout our hookup guide on the matter. To get started with the fourth example, open up File > Examples > SparkFun VL53L1x 4M Laser Distance Sensor > Example5_LCDDemo. We'll first need to connect the RX pin of our Serial LCD to pin A3 on our Arduino. Connect 5V and ground on the LCD and the backlight should light up. Notice how we also include the SoftwareSerial library. Uploading the sketch to our Arduino then takes in our sample rate and distances. By using these values, it calculates a velocity. Like the sketch before, distances are stored in an array. The sketch uses these values in the array to calculate velocity and the velocity is then displayed along with the current distance on the LCD. The output on the LCD should look something like the below GIF.

LCD Distance Display

Python Package Overview

Note: Update in progress...

Python Examples

Note: Update in progress...

Resources and Going Further

Now that you've successfully got your Qwiic Distance Sensor up and running, it's time to incorporate it into your own project!

For more information, check out the resources below:

Want a great use case for your ToF sensor? How about integrating one into your AVC submission? Have a look here:

Need even more inspiration for your next project? Check out some of these related tutorials:

Qwiic Single Relay Hookup Guide

Get started switching those higher power loads around with the Qwiic Single Relay.

SparkFun GPS Breakout (ZOE-M8Q and SAM-M8Q) Hookup Guide

The SparkFun ZOE-M8Q and SAM-M8Q are two similarly powerful GPS units but with different project applications. We'll compare both chips before getting each up and running.

GPS Geo-Mapping at the Push of a Button

Let's ramp up our GPS tracking skills with KML files and Google Earth. We'll make a tracker that logs location and allows us to visualize our steps with Google Earth.

Qwiic TMP117 High Precision Digital Temperature Sensor Hookup Guide

Add a high precision, digital temperature sensor to your projects using the TMP117 over the I2C!