Sensor API

Sensor API (VL53L0X)

The VL53L0X class wraps the Adafruit VL53L0X driver for ST's time-of-flight laser ranging sensor. It returns distance in centimetres over I²C.

Supports single and multi-sensor setups (up to 16 on one bus via XSHUT pin sequencing).

Import: from megawrapper import VL53L0X or from megawrapper.sensor import VL53L0X. Both work.

---

VL53L0X()

VL53L0X(i2c: busio.I2C | None = None, address: int = 0x29) -> VL53L0X

Parameter	Type	Default	Description
i2c	busio.I2C	None	Existing I²C bus. Auto-created if omitted.
address	int	0x29	I²C address of the sensor (7-bit).

If no i2c is given one is created automatically from board.SCL / board.SDA (requires Blinka on the host).

from megawrapper import VL53L0X

sensor = VL53L0X()               # auto I2C, default address
print(sensor.distance, "cm")     # read distance in cm

---

distance property

VL53L0X.distance -> float

Returns the measured distance in centimetres. Internally converts the raw millimetre value from adafruit_vl53l0x by dividing by 10.

while True:
    print(f"{sensor.distance:.1f} cm")
    delay(100)

---

VL53L0X.auto_address()

@classmethod
VL53L0X.auto_address(
    xshut_pins: list[int],
    i2c: busio.I2C | None = None,
) -> list[VL53L0X]

Set up multiple VL53L0X sensors on the same I²C bus using their XSHUT (shutdown) pins.

Parameter	Type	Default	Description
xshut_pins	list[int]	—	GPIO pin numbers connected to each sensor's XSHUT. Order determines the returned list order.
i2c	busio.I2C	None	Existing I²C bus. Auto-created if omitted.

Returns: A list of VL53L0X instances, one per XSHUT pin, each with a unique I²C address (0x30, 0x31, … up to 0x3F).

How it works:

1. Each XSHUT pin number is converted to a board pin object (getattr(board, f'D{pin}', pin)) and driven LOW (all sensors in reset).
2. Sensors are woken one at a time.
3. Each sensor is temporarily addressed at 0x29, then reassigned to 0x30 + i.
4. The sensor is added to the result list and the next one is woken.

Pin conversion detail: The xshut_pins list accepts integer GPIO numbers (BCM numbering). Internally, each integer is converted via getattr(board, f'D{pin}', pin) to satisfy Blinka's DigitalInOut requirement for a pin object with an .id attribute. You never need to pass pin objects yourself.

from megawrapper import VL53L0X

sensors = VL53L0X.auto_address([5, 6, 7])
left, centre, right = sensors

print(left.distance)    # sensor on XSHUT=5
print(right.distance)   # sensor on XSHUT=7

Supports up to 16 sensors (addresses 0x30–0x3F).

---

Requirements

• Hardware: VL53L0X module(s), Raspberry Pi (or other Blinka-supported board), connected via I²C.
• Software: adafruit-circuitpython-vl53l0x — requires the sensor extra: pip install 'megawrapper[sensor]' (PyPI) or pip install -e '.[sensor]' (source). Requires Blinka on the host.

The adafruit_vl53l0x, board, busio, and digitalio modules are imported lazily (only when a VL53L0X is instantiated or auto_address is called). Importing megawrapper will not fail on non-Blinka platforms like Windows.

Note: The VL53L0X driver is an optional dependency — install the sensor extra explicitly. Without it, VL53L0X can be imported but will fail at construction time with ModuleNotFoundError.