Adafruit_VL53L0X: time-of-flight ranging the Adafruit way
Adafruit_VL53L0X wraps ST鈥檚 own VL53L0X API, so it carries ST鈥檚 structures and names into your sketch. A measurement arrives in a VL53L0X_RangingMeasurementData_t: you call rangingTest(), then read RangeMilliMeter for the distance and RangeStatus to know whether to believe it. A status of 4 means the target was out of range.
Built in on Mokxi: #include <Adafruit_VL53L0X.h> and it builds, with nothing to install. Free, and no account needed.
What Adafruit_VL53L0X does
Since version 1.1 the library has simpler calls beside that one. readRange() returns millimeters directly, and startRangeContinuous() with isRangeComplete() lets a loop pick up results without waiting. configSensor() switches between the sensing profiles ST defines: default, long range, high speed and high accuracy.
The sensor鈥檚 GPIO1 pin can signal that a new measurement is ready, so a sketch can wait on an interrupt instead of polling. On the I2C side it behaves like every VL53L0X: address 0x29 at power up, and begin(0x30) to move a second sensor out of the way while the first one is held in reset.
| Library Manager name | Adafruit_VL53L0X |
|---|---|
| Author | Adafruit |
| Include | #include <Adafruit_VL53L0X.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 | VL53L0X time-of-flight sensor |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <Adafruit_VL53L0X.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "Adafruit_VL53L0X" by Adafruit from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add Adafruit_VL53L0X to lib_deps in PlatformIO. Mokxi follows the calls of release 1.2.4, so a sketch written here builds there too.
What to know in the simulator: The part raises GPIO1 for a new measurement; the threshold modes of setGpioConfig() are accepted and leave the pin idle.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 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 路 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_VL53L0X lox = Adafruit_VL53L0X()
Creates the sensor object, as the library鈥檚 examples write it.
lox.begin()
Starts I2C and sets the sensor up at 0x29. Returns false when it is not found. begin(0x30) gives it another address.
VL53L0X_RangingMeasurementData_t measure
The structure ST鈥檚 API fills in: RangeMilliMeter, RangeStatus and the signal figures.
lox.rangingTest(&measure, false)
Takes one measurement into the structure. Pass true instead of false to print ST鈥檚 debug output.
lox.rangingTest(&measure, false);
if (measure.RangeStatus != 4) {
Serial.println(measure.RangeMilliMeter);
} else {
Serial.println("out of range");
}lox.readRange()
One measurement, returned as millimeters, for sketches that do not need the status.
lox.startRangeContinuous()
Starts back-to-back ranging. Check isRangeComplete() and then call readRange() to collect each result.
lox.configSensor(Adafruit_VL53L0X::VL53L0X_SENSE_LONG_RANGE)
Switches to ST鈥檚 long range profile, which reaches farther at the cost of speed. The other profiles are DEFAULT, HIGH_SPEED and HIGH_ACCURACY.
Example: Adafruit VL53L0X: what happens with no chip
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <Adafruit_VL53L0X.h>
Adafruit_VL53L0X lox = Adafruit_VL53L0X();
void setup() {
Serial.begin(115200);
if (!lox.begin()) {
Serial.println(F("Failed to boot VL53L0X"));
return;
}
}
void loop() {
VL53L0X_RangingMeasurementData_t measure;
lox.rangingTest(&measure, false);
if (measure.RangeStatus != 4) {
Serial.println(measure.RangeMilliMeter);
}
delay(100);
}Common errors and how to fix them
Failed to boot VL53L0X
This is the example鈥檚 message when begin() returns false. Check SDA, SCL and power, and that no other device is already at 0x29. If you have two sensors, hold one in reset with XSHUT before calling begin() on the other.
RangeMilliMeter reads a big constant number
Look at RangeStatus first: a status of 4 means out of range and the distance field is meaningless. Only print RangeMilliMeter when the status is not 4.
'class Adafruit_VL53L0X' has no member named 'readRange'
Your copy of the library on a real board predates version 1.1. Update it in the Library Manager, or use rangingTest() and the measurement structure, which every version has.
Try Adafruit_VL53L0X without installing anything
Open the example, change the sketch, and keep your version in a free account.