MojoScale Studio Docs
API Reference

vl53l0x

VL53L0X time-of-flight distance sensor module.

All modules Open Studio
Studio Docs Sensors & I/O

import vl53l0x

The vl53l0x module reads ST VL53L0X laser time-of-flight ranging sensors over I2C. It performs the sensor initialization, tuning, timing-budget setup, and reference calibration needed before measurements are useful.

Quick example

import vl53l0x

front = vl53l0x.VL53L0X(sda=21, scl=22)

reading = front.read()
if reading["ok"]:
    print(reading["distance_mm"])

front.configure(profile="long_range")
print(front.distance())

front.start_continuous(period_ms=100)
data = front.read_continuous()
print(data["mm"])
front.stop_continuous()

importvl53l0x

VL53L0X time-of-flight distance sensor module.

The vl53l0x module reads ST VL53L0X laser time-of-flight ranging sensors over I2C. It performs the sensor initialization, tuning, timing-budget setup, and reference calibration needed before measurements are useful.

API 44 available

vl53l0x.VL53L0X(sda: int, scl: int, address: int = None, frequency: int = None, port: int = None, io_2v8: bool = None) -> vl53l0x_sensor

Create and initialize an independent VL53L0X distance sensor.

Use one VL53L0X object for each physical ranging sensor. Multiple sensors can share one I2C bus after each sensor is assigned a unique address.

Parameters
Name Type Pass as Required Description
sda int positional or keyword Yes GPIO pin used for I2C SDA.
scl int positional or keyword Yes GPIO pin used for I2C SCL.
address int positional or keyword No Optional I2C address. Defaults to 0x29.
frequency int positional or keyword No Optional I2C bus speed in hertz. Defaults to 400000.
port int positional or keyword No Optional ESP-IDF I2C port number. Defaults to 0.
io_2v8 bool positional or keyword No Optional bool. True enables 2.8 V I/O mode. Defaults to True.
Returns

vl53l0x_sensor vl53l0x_sensor object.

vl53l0x.VL53L0X().configure(profile=None, timing_budget_us=None, signal_rate_limit=None, pre_vcsel=None, final_vcsel=None) -> bool

Configure ranging profile and advanced measurement settings.

Parameters
Name Type Pass as Required Description
profile str positional or keyword No Optional value. Defaults to None.
timing_budget_us int positional or keyword No Optional value. Defaults to None.
signal_rate_limit float positional or keyword No Optional value. Defaults to None.
pre_vcsel int positional or keyword No Optional value. Defaults to None.
final_vcsel int positional or keyword No Optional value. Defaults to None.

vl53l0x.VL53L0X().profile(name) -> bool

Apply a named ranging profile.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Required value.

vl53l0x.VL53L0X().read(timeout_ms=None) -> dict

Perform one single-shot range measurement.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword No Optional value. Defaults to None.

vl53l0x.VL53L0X().distance(timeout_ms=None) -> int

Perform one single-shot measurement and return millimeters.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword No Optional value. Defaults to None.

vl53l0x.VL53L0X().start_continuous(period_ms=None) -> bool

Start continuous ranging.

Parameters
Name Type Pass as Required Description
period_ms int positional or keyword No Optional value. Defaults to None.

vl53l0x.VL53L0X().read_continuous(timeout_ms=None) -> dict

Read the next continuous ranging result.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword No Optional value. Defaults to None.

vl53l0x.VL53L0X().stop_continuous() -> bool

Stop continuous ranging.

vl53l0x.VL53L0X().ready() -> bool

Check whether a range result is ready.

vl53l0x.VL53L0X().set_timeout(timeout_ms) -> bool

Set the default read timeout.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword Yes Required value.

vl53l0x.VL53L0X().set_signal_rate_limit(limit_mcps) -> bool

Set return signal-rate limit.

Parameters
Name Type Pass as Required Description
limit_mcps float positional or keyword Yes Required value.

vl53l0x.VL53L0X().get_signal_rate_limit() -> float

Return the current signal-rate limit.

vl53l0x.VL53L0X().set_timing_budget(timing_budget_us) -> bool

Set measurement timing budget.

Parameters
Name Type Pass as Required Description
timing_budget_us int positional or keyword Yes Required value.

vl53l0x.VL53L0X().get_timing_budget() -> int

Return the current measurement timing budget.

vl53l0x.VL53L0X().set_vcsel_period(type, period_pclks) -> bool

Set a VCSEL pulse period.

Parameters
Name Type Pass as Required Description
type str positional or keyword Yes Required value.
period_pclks int positional or keyword Yes Required value.

vl53l0x.VL53L0X().get_vcsel_period(type) -> int

Return a VCSEL pulse period.

Parameters
Name Type Pass as Required Description
type str positional or keyword Yes Required value.

vl53l0x.VL53L0X().set_address(address) -> bool

Change this sensor's I2C address.

Parameters
Name Type Pass as Required Description
address int positional or keyword Yes Required value.

vl53l0x.VL53L0X().id() -> dict

Read identification registers.

vl53l0x.VL53L0X().timeout_occurred() -> bool

Return and clear the timeout flag.

vl53l0x.VL53L0X().reset() -> bool

Soft-reset and reinitialize this sensor.

vl53l0x.VL53L0X().info() -> dict

Return I2C, timeout, profile, and timing settings.

vl53l0x.VL53L0X().close() -> bool

Release this VL53L0X handle.

vl53l0x.VL53L0X().Example

sensor = vl53l0x.VL53L0X(sda=21, scl=22) print(sensor.distance())

vl53l0x.begin(sda: int, scl: int, address: int = None, frequency: int = None, port: int = None, io_2v8: bool = None) -> bool

Legacy: initialize the module-level default VL53L0X sensor.

Prefer ``sensor = vl53l0x.VL53L0X(...)`` for new projects. The legacy wrapper keeps older singleton-style scripts working.

Parameters
Name Type Pass as Required Description
sda int positional or keyword Yes GPIO pin used for I2C SDA.
scl int positional or keyword Yes GPIO pin used for I2C SCL.
address int positional or keyword No Optional I2C address. Defaults to 0x29.
frequency int positional or keyword No Optional I2C bus speed in hertz. Defaults to 400000.
port int positional or keyword No Optional ESP-IDF I2C port number. Defaults to 0.
io_2v8 bool positional or keyword No Optional bool. True enables 2.8 V I/O mode, which is suitable for most breakout boards. Defaults to True.
Returns

bool True when the sensor is detected, initialized, tuned, and calibrated.

vl53l0x.configure(profile: str = None, timing_budget_us: int = None, signal_rate_limit: float = None, pre_vcsel: int = None, final_vcsel: int = None) -> bool

Configure ranging profile and advanced measurement settings.

Profiles are convenience presets. Use ``"default"`` for normal reads, ``"high_speed"`` for faster lower-accuracy reads, ``"high_accuracy"`` for slower precise reads, and ``"long_range"`` for better dark-condition range.

Parameters
Name Type Pass as Required Description
profile str positional or keyword No Optional preset name. Use "default", "high_speed", "high_accuracy", or "long_range".
timing_budget_us int positional or keyword No Optional measurement timing budget in microseconds. Must be at least 20000.
signal_rate_limit float positional or keyword No Optional return signal-rate limit in MCPS. Lower values can extend range but may reduce reliability.
pre_vcsel int positional or keyword No Optional pre-range VCSEL pulse period. Use 12, 14, 16, or 18.
final_vcsel int positional or keyword No Optional final-range VCSEL pulse period. Use 8, 10, 12, or 14.
Returns

bool True when all requested settings are accepted.

vl53l0x.profile(name: str) -> bool

Apply a named ranging profile.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Preset name. Use "default", "high_speed", "high_accuracy", or "long_range".
Returns

bool True when the profile is applied.

vl53l0x.read(timeout_ms: int = None) -> dict

Perform one single-shot range measurement.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword No Optional timeout in milliseconds. Defaults to the module timeout, initially 500.
Returns

dict Dict with ``ok``, ``timeout``, ``distance_mm``, ``mm``, ``range_status``, ``continuous``, ``timeout_ms``, ``address``, ``profile``, and ``timing_budget_us`` fields.

vl53l0x.distance(timeout_ms: int = None) -> int

Perform one single-shot range measurement and return millimeters.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword No Optional timeout in milliseconds. Defaults to the module timeout, initially 500.
Returns

int Integer distance in millimeters, or -1 when the read times out.

vl53l0x.start_continuous(period_ms: int = None) -> bool

Start continuous ranging.

Parameters
Name Type Pass as Required Description
period_ms int positional or keyword No Optional inter-measurement period in milliseconds. Use 0 for back-to-back measurements. Defaults to 0.
Returns

bool True when continuous ranging is started.

vl53l0x.read_continuous(timeout_ms: int = None) -> dict

Read the next continuous ranging result.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword No Optional timeout in milliseconds. Defaults to the module timeout, initially 500.
Returns

dict Dict with the same fields as ``read()``, with ``continuous`` set to True when continuous mode is active.

vl53l0x.stop_continuous() -> bool

Stop continuous ranging.

Returns

bool True when continuous ranging is stopped.

vl53l0x.ready() -> bool

Check whether a range result is ready.

Returns

bool True when the VL53L0X interrupt status says a measurement is ready.

vl53l0x.set_timeout(timeout_ms: int) -> bool

Set the default read timeout.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword Yes Timeout in milliseconds. Use 0 to disable timeout checks.
Returns

bool True when the timeout is stored.

vl53l0x.set_signal_rate_limit(limit_mcps: float) -> bool

Set return signal-rate limit.

Parameters
Name Type Pass as Required Description
limit_mcps float positional or keyword Yes Signal-rate limit in MCPS. Lower values can improve possible range but can also admit weaker, less reliable returns.
Returns

bool True when the value is accepted.

vl53l0x.get_signal_rate_limit() -> float

Return the current return signal-rate limit.

Returns

float Float signal-rate limit in MCPS.

vl53l0x.set_timing_budget(timing_budget_us: int) -> bool

Set measurement timing budget.

Parameters
Name Type Pass as Required Description
timing_budget_us int positional or keyword Yes Measurement timing budget in microseconds. Must be at least 20000.
Returns

bool True when the timing budget is accepted.

vl53l0x.get_timing_budget() -> int

Return the current measurement timing budget.

Returns

int Integer timing budget in microseconds.

vl53l0x.set_vcsel_period(type: str, period_pclks: int) -> bool

Set a VCSEL pulse period.

Parameters
Name Type Pass as Required Description
type str positional or keyword Yes VCSEL period type. Use "pre" or "final".
period_pclks int positional or keyword Yes Pulse period in PCLKs. Pre-range accepts 12, 14, 16, or 18. Final-range accepts 8, 10, 12, or 14.
Returns

bool True when the period is valid and calibration succeeds.

vl53l0x.get_vcsel_period(type: str) -> int

Return a VCSEL pulse period.

Parameters
Name Type Pass as Required Description
type str positional or keyword Yes VCSEL period type. Use "pre" or "final".
Returns

int Integer pulse period in PCLKs.

vl53l0x.set_address(address: int) -> bool

Change the VL53L0X I2C address.

This is useful when multiple VL53L0X sensors are on the same bus and each sensor is brought out of shutdown one at a time.

Parameters
Name Type Pass as Required Description
address int positional or keyword Yes New 7-bit I2C address.
Returns

bool True when the device address is changed and the native handle is moved to the new address.

vl53l0x.id() -> dict

Read VL53L0X identification registers.

Returns

dict Dict with ``model_id``, ``revision_id``, and ``address`` fields.

vl53l0x.timeout_occurred() -> bool

Return and clear the timeout flag.

Returns

bool True when a previous read timed out since the last check.

vl53l0x.reset() -> bool

Soft-reset and reinitialize the VL53L0X.

Returns

bool True when the sensor is reset, initialized, and calibrated again.

vl53l0x.info() -> dict

Return VL53L0X module state.

Returns

dict Dict with initialization state, I2C settings, timeout, profile, timing budget, signal-rate limit, VCSEL periods, and last I2C status.