Pololu VL53L1X Arduino Library

This library is a streamlined wrapper around ST's official VL53L1X API (STSW-IMG007).

Key Differences:

• Pros: Provides a quicker, easier interface for Arduino with a smaller storage and memory footprint.
• Cons: Does not implement advanced features like sensor calibration for cover glass or selecting a smaller Region of Interest (ROI), and has less robust error checking.

If your application requires advanced functionality and you have sufficient storage/memory, consider using the official ST API directly or the Pololu implementation of ST's VL53L1X API for Arduino.

If the Library Manager is unavailable, follow these steps to install manually:

1. Download the latest release archive from the GitHub releases page and decompress it.
2. Rename the folder vl53l1x-arduino-master to VL53L1X.
3. Move the VL53L1X folder into the libraries directory inside your Arduino sketchbook directory.
   • Note: You can find your sketchbook location via File > Preferences in the Arduino IDE.
4. Restart the Arduino IDE.

For 3.3V Arduino boards (e.g., Arduino Due), use the following wiring scheme:

Once the library is installed correctly, you can find example sketches within the Arduino IDE:

1. Open the File menu.
2. Select Examples.
3. Select VL53L1X.

To take measurements repeatedly at a set interval, use continuous mode.

1. Call startContinuous(uint32_t period_ms) to begin. The period_ms defines the inter-measurement period. If this period is shorter than the timing budget, the sensor starts a new measurement immediately after the previous one finishes.
2. Use read() or readRangeContinuousMillimeters() to get the distance in millimeters.
3. By default, read() is blocking and waits for new data. To avoid blocking, check dataReady() first.
4. Call stopContinuous() to end the mode.

sensor.startContinuous(50); // 50ms period

while (true) {
  if (sensor.dataReady()) {
    uint16_t distance = sensor.read();
    Serial.print("Distance: ");
    Serial.println(distance);
  }
}

To take a single measurement and then stop, use readSingle() (or its alias readRangeSingleMillimeters()).

Blocking vs Non-blocking

• Blocking (default): readSingle(true) waits until the measurement is complete and updates the ranging_data struct.
• Non-blocking: readSingle(false) starts the measurement and returns 0 immediately. To use this pattern, you must manually wait for the data using dataReady() before calling read(false) to retrieve the result.

// Non-blocking single shot pattern
sensor.readSingle(false); 
while (!sensor.dataReady()) {
  // Wait or do other tasks
}
uint16_t distance = sensor.read(false);

The VL53L1X sensor communicates via I2C. Depending on your Arduino board's voltage, follow the appropriate wiring scheme below:

For 5V Arduino boards

(e.g., Arduino Uno, Leonardo, Mega, Pololu A-Star 32U4)

If you are using Arduino IDE version 1.6.2 or later, you can install the library through the built-in manager:

1. Open the Sketch menu in the Arduino IDE.
2. Select Include Library > Manage Libraries....
3. Search for VL53L1X.
4. Select the VL53L1X entry.
5. Click Install.

By default, the library uses the Wire object. If your sensor is connected to a different I2C bus (for example, Wire1 on some Arduino boards), use setBus() to configure it.

To retrieve the currently configured bus, use getBus().

// Example: Using the second I2C bus
sensor.setBus(&Wire1);

The VL53L1X supports different distance modes and timing budgets to balance range, accuracy, and speed.

Distance Modes

Use setDistanceMode(DistanceMode mode) to select one of the following:

• VL53L1X::Short: Lower maximum range, but less affected by ambient light.
• VL53L1X::Medium
• VL53L1X::Long

Timing Budget

Use setMeasurementTimingBudget(uint32_t budget_us) to set the time allowed for one measurement in microseconds.

• A longer budget increases accuracy.
• Minimums: 20,000 $\mu$s for Short mode; 33,000 $\mu$s for Medium and Long modes.

sensor.setDistanceMode(VL53L1X::Long);
sensor.setMeasurementTimingBudget(50000); // 50ms

Use the init() method to configure the sensor. You can optionally specify the I/O voltage mode via the io_2v8 parameter:

• true (default): Configures the sensor for 2.8V I/O.
• false: Configures the sensor for 1.8V I/O.

The method returns a bool indicating whether initialization was successful.

if (!sensor.init(true)) {
  // Initialization failed
}