Simple test

Ensure your device works with this simple test.

examples/vl53l1x_simpletest.py

# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
# SPDX-FileCopyrightText: Copyright (c) 2021 Carter Nelson for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

# Simple demo of the VL53L1X distance sensor.
# Will print the sensed range/distance every second.

import time

import board

import adafruit_vl53l1x

i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller

vl53 = adafruit_vl53l1x.VL53L1X(i2c)

# OPTIONAL: can set non-default values
vl53.distance_mode = 1
vl53.timing_budget = 100

print("VL53L1X Simple Test.")
print("--------------------")
model_id, module_type, mask_rev = vl53.model_info
print(f"Model ID: 0x{model_id:0X}")
print(f"Module Type: 0x{module_type:0X}")
print(f"Mask Revision: 0x{mask_rev:0X}")
print("Distance Mode: ", end="")
if vl53.distance_mode == 1:
    print("SHORT")
elif vl53.distance_mode == 2:
    print("LONG")
else:
    print("UNKNOWN")
print(f"Timing Budget: {vl53.timing_budget}")
print("--------------------")

vl53.start_ranging()

while True:
    if vl53.data_ready:
        print(f"Distance: {vl53.distance} cm")
        vl53.clear_interrupt()
        time.sleep(1.0)

Multiple Sensors

Use set_address to update the I2C address of additional connected sensors.

examples/vl53l1x_set_address_multiple_sensors.py

# SPDX-FileCopyrightText: 2022 wrdaigle for Adafruit Industries
# SPDX-FileCopyrightText: 2022 Kattni Rembor for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
VL53L1X multiple sensor I2C set_address demo.

This example is written for two sensors, but it can easily be modified to include more.

NOTE: A multitude of sensors may require more current than the on-board 3V regulator can output.
The typical current consumption during active range readings is about 19 mA per sensor.
"""

import time

import board
import digitalio

import adafruit_vl53l1x

# Define the I2C pins.
i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller

xshut = [
    # Update the D6 and D5 pins to match the pins to which you wired your sensor XSHUT pins.
    digitalio.DigitalInOut(board.D6),
    digitalio.DigitalInOut(board.D5),
    # Add more VL53L1X sensors by defining their XSHUT pins here.
]

for shutdown_pin in xshut:
    # Set the shutdown pins to output, and pull them low.
    shutdown_pin.switch_to_output(value=False)
    # These pins are active when Low, meaning:
    #   If the output signal is LOW, then the VL53L1X sensor is off.
    #   If the output signal is HIGH, then the VL53L1X sensor is on.
# All VL53L1X sensors are now off.

# Create a list to be used for the array of VL53L1X sensors.
vl53l1x = []

# Change the address of the additional VL53L1X sensors.
for pin_number, shutdown_pin in enumerate(xshut):
    # Turn on the VL53L1X sensors to allow hardware check.
    shutdown_pin.value = True
    # Instantiate the VL53L1X I2C object and insert it into the vl53l1x list.
    # This also performs VL53L1X hardware check.
    sensor_i2c = adafruit_vl53l1x.VL53L1X(i2c)
    vl53l1x.append(sensor_i2c)
    # This ensures no address change on one sensor board, specifically the last one in the series.
    if pin_number < len(xshut) - 1:
        # The default address is 0x29. Update it to an address that is not already in use.
        sensor_i2c.set_address(pin_number + 0x30)

# Print the various sensor I2C addresses to the serial console.
if i2c.try_lock():
    print("Sensor I2C addresses:", [hex(x) for x in i2c.scan()])
    i2c.unlock()

# Start ranging for sensor data collection.
for sensor in vl53l1x:
    sensor.start_ranging()
while True:
    # Extract the appropriate data from the current list, and print
    # the sensor distance readings for all available sensors.
    for sensor_number, sensor in enumerate(vl53l1x):
        if sensor.data_ready:
            print(f"Sensor {sensor_number + 1}: {sensor.distance}")
            sensor.clear_interrupt()
    time.sleep(0.5)

DisplayIO Simpletest

This is a simple test for boards with built-in display.

examples/vl53l1x_displayio_simpletest.py

# SPDX-FileCopyrightText: 2024 Tim Cocks for Adafruit Industries
# contributions by J Fletcher, adapting code by Prof Gallaugher:
#           https://www.youtube.com/watch?v=cdx1A1xoEWc&t=5s
# tested on ESP32-S3 Reverse TFT Feather:
#           https://www.adafruit.com/product/5691
# SPDX-License-Identifier: MIT

import time

import board
from adafruit_display_text.bitmap_label import Label
from displayio import Group
from terminalio import FONT

import adafruit_vl53l1x

# create a main_group to hold anything we want to show on the display.
main_group = Group()

# Create sensor object, communicating over the board's default I2C bus
# i2c = board.I2C()  # uses board.SCL and board.SDA
i2c = board.STEMMA_I2C()
# For using the built-in STEMMA QT connector on a microcontroller
vl53 = adafruit_vl53l1x.VL53L1X(i2c)

# Create a Label to show the readings. If you have a very small
# display you may need to change to scale=1.
display_output_label = Label(FONT, text="", scale=1)

# place the label near the top left corner with anchored positioning
display_output_label.anchor_point = (0, 0)
display_output_label.anchored_position = (4, 4)

# add the label to the main_group
main_group.append(display_output_label)

# set the main_group as the root_group of the built-in DISPLAY
board.DISPLAY.root_group = main_group
# create a display object placeholder to be updated by the loop
screen = f"Distance: {''}cm, {''}in, {''}ft"
# initiate repeated sensor readings
vl53.start_ranging()


# begin main loop
while True:
    # There will be no values to populate at first, just the bare 'Distance: cm, in, ft' text
    # Assuming the first 'try' succeeds, this will be updated once the loop starts over
    display_output_label.text = screen

    # This 'try' sequence will either update the displayed items with fresh data or repeat the
    # last available data. VL53L1X sensors output `None` when no object reflects the laser,
    # e.g., there is nothing within 4 meters, or when objects pass too quickly in and out of
    # view (usually perpendicular to the field of vision).
    try:
        if vl53.distance:
            # simple test to see there is a value to read; no value = exception
            distance = vl53.distance
            # sets the variable (used by the display) to the sensor data
            inches = distance * 0.394
            # VL53L1X outputs distance in metric, so we convert to imperial
            screen = f"Distance: {distance: .1f}cm, {inches: .1f}in, {inches/12: .1f}ft"
            # if we made it this far, we have new data to display!
    except TypeError:
        repeat_screen = screen
        screen = repeat_screen
        # if things went sideways, we repeat the previous loop's data so we can try again

    time.sleep(0.25)