Qwiic Distance Sensor (VL53L1X, VL53L4CD) Hookup Guide

≡ Pages

Contributors:

bboyho,

Elias The Sparkiest,

Englandsaurus

Favorited Favorite 3

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. This library was originally written for VL53L1X but it can also be used for the VL53L4CD. 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:

Download the SparkFun VL53L1X Arduino Library (ZIP)

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	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 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.

View as a single page Next Page →
Arduino Example Code

← Previous Page
Hardware Assembly

Qwiic Distance Sensor (VL53L1X, VL53L4CD) Hookup Guide

Arduino Library Overview

ABOUT SPARKFUN

PARTNER WITH US

SUPPORT

SITE INFORMATION

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

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

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