From a3adaed33b43783821db5f186d8fd1d3b251ad25 Mon Sep 17 00:00:00 2001 From: Charly-sketch Date: Mon, 23 Mar 2026 14:59:02 +0100 Subject: [PATCH 1/2] docs: Expand README for vl53l1x driver. --- lib/vl53l1x/README.md | 111 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 106 insertions(+), 5 deletions(-) diff --git a/lib/vl53l1x/README.md b/lib/vl53l1x/README.md index 14f56142..bd987e68 100644 --- a/lib/vl53l1x/README.md +++ b/lib/vl53l1x/README.md @@ -1,9 +1,110 @@ -# MicroPython Driver for the vl53l1x ToF sensor +# VL53L1X MicroPython Driver -This library is a port of the [MicroPython driver for the vl53l1x ToF sensor](https://github.com/drakxtwo/vl53l1x_pico). +MicroPython driver for the **VL53L1X Time-of-Flight (ToF) distance sensor**. -The examples could be easily tested with [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) with the following command : +This library is a port of the original MicroPython VL53L1X driver. -```sh - mpremote mount . run examples/distance.py +## Features + +* Time-of-Flight **distance measurement** +* Distance reading in **millimeters** +* **Model ID verification** on initialization +* Start / stop ranging control +* Data-ready polling +* Power management: + + * power on / off + * software reset +* Continuous measurement support + +## Sensor Specifications + +| Feature | Value | +| ------------- | -------------------- | +| Technology | Time-of-Flight (ToF) | +| Range | Up to ~4 meters | +| Accuracy | ± few mm (typical) | +| Field of View | ~27° | +| Interface | I²C | + +## I2C Address + +Default I²C address: + +``` +0x29 +``` + +## Basic Usage + +```python +from machine import I2C +from vl53l1x import VL53L1X + +# Init I2C +i2c = I2C(1) + +# Init sensor +tof = VL53L1X(i2c) + +# Read distance (mm) +distance = tof.read() + +print("Distance:", distance, "mm") +``` + +## API Reference + +### Initialization + +```python +VL53L1X(i2c, address=0x29) ``` + +### Measurement + +* `read()` — read distance in millimeters +* `distance_mm()` — same as `read()` + +### Ranging Control + +* `start_ranging()` — start continuous ranging +* `stop_ranging()` — stop ranging +* `data_ready()` — check if new data is available + +### Device Control + +* `device_id()` — read sensor model ID +* `reset()` — software reset + +### Power Management + +* `power_on()` — power up sensor +* `power_off()` — power down sensor + +## Examples + +Examples are available in the `examples/` folder: + +| File | Description | +| ----------- | -------------------------- | +| distance.py | Basic distance measurement | + +Run an example with: + +```bash +mpremote mount lib/vl53l1x run lib/vl53l1x/examples/distance.py +``` + +## Notes + +* The sensor requires **initialization time after power-on** (~200 ms). +* The driver automatically checks the **device ID (0xEACC)** during initialization and raises an error if the sensor is not detected. +* Distance measurements are returned in **millimeters**. +* The driver waits for data readiness internally before returning a measurement. + +## Source + +This library is a port of: + +[https://github.com/drakxtwo/vl53l1x_pico](https://github.com/drakxtwo/vl53l1x_pico) From 29162fe6bf96b6c553729d9b5a2a15e0a57ebd8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= Date: Mon, 23 Mar 2026 16:52:21 +0100 Subject: [PATCH 2/2] docs: Rewrite vl53l1x README addressing all review comments. --- lib/vl53l1x/README.md | 82 +++++++++++++++---------------------------- 1 file changed, 29 insertions(+), 53 deletions(-) diff --git a/lib/vl53l1x/README.md b/lib/vl53l1x/README.md index bd987e68..dfa674fd 100644 --- a/lib/vl53l1x/README.md +++ b/lib/vl53l1x/README.md @@ -2,54 +2,39 @@ MicroPython driver for the **VL53L1X Time-of-Flight (ToF) distance sensor**. -This library is a port of the original MicroPython VL53L1X driver. +This library is a port of [vl53l1x_pico](https://github.com/drakxtwo/vl53l1x_pico). + +## Supported Sensor + +| Feature | Value | +| -------------------- | -------------------- | +| Technology | Time-of-Flight (ToF) | +| Range | Up to ~4 meters | +| Accuracy | ± 3% (typical) | +| Field of View | 27° | +| Interface | I²C | +| Default I²C address | `0x29` | +| Device ID | `0xEACC` | ## Features -* Time-of-Flight **distance measurement** -* Distance reading in **millimeters** -* **Model ID verification** on initialization +* Time-of-Flight distance measurement in millimeters +* Model ID verification on initialization * Start / stop ranging control * Data-ready polling -* Power management: - - * power on / off - * software reset +* Power management (on/off, reset) * Continuous measurement support -## Sensor Specifications - -| Feature | Value | -| ------------- | -------------------- | -| Technology | Time-of-Flight (ToF) | -| Range | Up to ~4 meters | -| Accuracy | ± few mm (typical) | -| Field of View | ~27° | -| Interface | I²C | - -## I2C Address - -Default I²C address: - -``` -0x29 -``` - ## Basic Usage ```python from machine import I2C from vl53l1x import VL53L1X -# Init I2C i2c = I2C(1) - -# Init sensor tof = VL53L1X(i2c) -# Read distance (mm) distance = tof.read() - print("Distance:", distance, "mm") ``` @@ -58,13 +43,15 @@ print("Distance:", distance, "mm") ### Initialization ```python -VL53L1X(i2c, address=0x29) +tof = VL53L1X(i2c, address=0x29) ``` +The constructor checks the device ID (`0xEACC`) and raises `OSError` if the sensor is not detected. + ### Measurement -* `read()` — read distance in millimeters -* `distance_mm()` — same as `read()` +* `distance_mm()` — read distance in millimeters (triggers ranging if needed) +* `read()` — alias for `distance_mm()` ### Ranging Control @@ -74,8 +61,8 @@ VL53L1X(i2c, address=0x29) ### Device Control -* `device_id()` — read sensor model ID -* `reset()` — software reset +* `device_id()` — read sensor model ID (returns `0xEACC`) +* `reset()` — hardware reset via SOFT_RESET register (takes ~100 ms) ### Power Management @@ -84,13 +71,9 @@ VL53L1X(i2c, address=0x29) ## Examples -Examples are available in the `examples/` folder: - -| File | Description | -| ----------- | -------------------------- | -| distance.py | Basic distance measurement | - -Run an example with: +| File | Description | +| ------------- | ----------------------------------- | +| `distance.py` | Continuous distance measurement loop | ```bash mpremote mount lib/vl53l1x run lib/vl53l1x/examples/distance.py @@ -98,13 +81,6 @@ mpremote mount lib/vl53l1x run lib/vl53l1x/examples/distance.py ## Notes -* The sensor requires **initialization time after power-on** (~200 ms). -* The driver automatically checks the **device ID (0xEACC)** during initialization and raises an error if the sensor is not detected. -* Distance measurements are returned in **millimeters**. -* The driver waits for data readiness internally before returning a measurement. - -## Source - -This library is a port of: - -[https://github.com/drakxtwo/vl53l1x_pico](https://github.com/drakxtwo/vl53l1x_pico) +* The sensor requires initialization time after power-on (~200 ms). +* The driver automatically waits for data readiness before returning a measurement. +* Distance measurements are returned in millimeters.