Adafruit VL53L1X: time-of-flight distance in millimeters
Yes. You can use the Adafruit VL53L1X library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (Laser distance, VL53L1X). The example below, "The Adafruit VL53L1X simpletest", runs on the Arduino Uno R3.
Built in on Mokxi: #include <Adafruit_VL53L1X.h> and it builds, with nothing to install. Free, and no account needed.
What Adafruit VL53L1X does
The VL53L1X is ST’s time-of-flight distance sensor. It sends laser pulses and times their return, giving a distance in millimeters that does not depend on the target’s color the way an infrared reflectance sensor does. It answers at 0x29 and, compared with the older VL53L0X, offers a long distance mode.
Adafruit’s library sits on ST’s Ultra Lite Driver. The flow is begin(), startRanging(), then in loop() wait for dataReady(), read distance() and call clearInterrupt() so the sensor starts the next measurement. Leaving out that last call is the usual reason a sketch prints one distance and then nothing. The timing budget, 15 to 500 ms, trades speed for steadier readings; begin() sets 50 ms and long mode.
The lower-level calls are there too under ST’s names, such as VL53L1X_SetDistanceMode() and VL53L1X_GetRangeStatus(), for settings the friendly calls skip. Pololu’s VL53L1X library drives the same chip with different calls, read() and ranging_data. In Mokxi the vl53l1x part’s slider sets the distance; the XSHUT and IRQ pins in the constructor are optional and matter when several sensors share a bus.
| Library Manager name | Adafruit VL53L1X |
|---|---|
| Author | Adafruit |
| Include | #include <Adafruit_VL53L1X.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | Laser distance, VL53L1X |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <Adafruit_VL53L1X.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "Adafruit VL53L1X" by Adafruit from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add Adafruit VL53L1X to lib_deps in PlatformIO. Mokxi follows the calls of release 3.1.2, so a sketch written here builds there too.
- ESP32-C3
- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- ESP32-C6
- WCH CH32V003
- Raspberry Pi Pico
- Raspberry Pi Pico W
- Seeed XIAO SAMD21
- STM32
- STM32 Nucleo-F411RE
- STM32 Blue Pill
- micro:bit V2
- Arduino Uno R4
- ESP32 DevKit
- ESP32-S3-DevKitC-1
- ESP8266 NodeMCU
- Arduino Pro Mini 3.3 V
- Seeed XIAO ESP32-C3
- ESP32-C3 SuperMini
- Seeed XIAO ESP32-C6
- ESP32-DevKitC V4
- LOLIN32 Lite
- Wemos D1 R32
- Cheap Yellow Display
- TTGO T-Display
- Seeed XIAO ESP32-S3
- ESP32-S3-CAM
- Arduino Nano ESP32
- Arduino Nano RP2040 Connect
- Seeed XIAO RP2040
- Waveshare RP2040-Zero
- Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
Adafruit_VL53L1X vl53 = Adafruit_VL53L1X()
Creates the driver. Adafruit_VL53L1X(XSHUT_PIN, IRQ_PIN) adds a shutdown pin, which begin() pulses, and an interrupt pin.
vl53.begin(0x29, &Wire)
Boots the sensor, checks its ID and sets long mode and 50 ms. Returns false, with the reason in vl53.vl_status.
vl53.sensorID()
The model ID, 0xEACC for a VL53L1X.
vl53.startRanging()
Starts back-to-back measurements; stopRanging() ends them.
vl53.setTimingBudget(50)
Milliseconds per measurement: 15 (short mode only), 20, 33, 50, 100, 200 or 500. Anything else returns false. getTimingBudget() reads it.
vl53.dataReady()
True when a measurement is waiting.
vl53.distance()
The distance in mm as an int16_t, or -1 when the read failed.
if (vl53.dataReady()) {
int16_t mm = vl53.distance();
Serial.println(mm);
vl53.clearInterrupt();
}vl53.clearInterrupt()
Releases the sensor for its next measurement. Call it after every reading.
vl53.VL53L1X_SetDistanceMode(1)
The ULD call for the mode: 1 is short, 2 is long. Other values return an invalid parameter error.
vl53.VL53L1X_GetRangeStatus(&rangeStatus)
How trustworthy the last result is; 0 means a valid range.
Example: The Adafruit VL53L1X simpletest
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include "Adafruit_VL53L1X.h"
Adafruit_VL53L1X vl53 = Adafruit_VL53L1X();
void setup() {
Serial.begin(115200);
Serial.println(F("Adafruit VL53L1X sensor demo"));
Wire.begin();
if (!vl53.begin(0x29, &Wire)) {
Serial.print(F("Error on init of VL sensor: "));
Serial.println(vl53.vl_status);
while (1) delay(10);
}
Serial.println(F("VL53L1X sensor OK!"));
Serial.print(F("Sensor ID: 0x"));
Serial.println(vl53.sensorID(), HEX);
if (!vl53.startRanging()) {
Serial.print(F("Couldn't start ranging: "));
Serial.println(vl53.vl_status);
while (1) delay(10);
}
vl53.setTimingBudget(50);
Serial.print(F("Timing budget (ms): "));
Serial.println(vl53.getTimingBudget());
}
void loop() {
if (vl53.dataReady()) {
int16_t distance = vl53.distance();
if (distance == -1) {
Serial.print(F("Couldn't get distance: "));
Serial.println(vl53.vl_status);
return;
}
Serial.print(F("Distance: "));
Serial.print(distance);
Serial.println(" mm");
vl53.clearInterrupt();
}
}Wiring
- Arduino Uno R3 A4 to Laser distance, VL53L1X SDA
- Arduino Uno R3 A5 to Laser distance, VL53L1X SCL
- Arduino Uno R3 5V to Laser distance, VL53L1X VIN
- Arduino Uno R3 GND to Laser distance, VL53L1X GND
Common errors and how to fix them
Error on init of VL sensor: followed by a number
begin() could not boot or identify the sensor, and the number is vl_status. Check the bus wires and power, and that no other device on the same pins uses 0x29, such as a TCS34725 or a second VL53L1X.
One distance prints, then nothing more
clearInterrupt() is missing after the read, so the sensor waits forever and dataReady() never turns true again. Call it after every distance().
setTimingBudget() returns false and the budget stays the same
Only the Ultra Lite Driver’s fixed values are accepted: 20, 33, 50, 100, 200 or 500 ms, and 15 ms in short mode. Pick one of those.
Questions and answers
What do the XSHUT and IRQ pins do?
XSHUT holds the sensor off, which lets a sketch bring several up one at a time and give each a new address with VL53L1X_SetI2CAddress(). IRQ signals a ready measurement; dataReady() polls the same thing.
Short mode or long mode on the VL53L1X?
Long mode is what begin() sets, and it reaches farther. Short mode is the only one that accepts the 15 ms budget, for the quickest readings at close range.
Keep going
Try Adafruit VL53L1X without installing anything
Open the example, change the sketch, and keep your version in a free account.