circuitpython-vl53lxcx 0.0.5
CircuitPython driver for VL53L5CX and VL53L8CX ToF sensors
License: MIT
Keywords: adafruit, blinka, circuitpython, micropython, vl53lxcx, VL53L5CX, VL53L8CX

Introduction
============


.. image:: https://readthedocs.org/projects/circuitpython-vl53lxcx/badge/?version=latest
    :target: https://circuitpython-vl53lxcx.readthedocs.io/
    :alt: Documentation Status



.. image:: https://img.shields.io/discord/327254708534116352.svg
    :target: https://adafru.it/discord
    :alt: Discord


.. image:: https://github.com/sensebox/CircuitPython_VL53LxCX/workflows/Build%20CI/badge.svg
    :target: https://github.com/sensebox/CircuitPython_VL53LxCX/actions
    :alt: Build Status


.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Code Style: Ruff

CircuitPython driver for VL53L5CX and VL53L8CX ToF sensors


Dependencies
=============
This driver depends on:

* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
* `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
* `Register <https://github.com/adafruit/Adafruit_CircuitPython_Register>`_

Please ensure all dependencies are available on the CircuitPython filesystem.
This is easily achieved by downloading
`the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_
or individual libraries can be installed using
`circup <https://github.com/adafruit/circup>`_.

Installing from PyPI
=====================

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
PyPI <https://pypi.org/project/circuitpython-vl53lxcx/>`_.
To install for current user:

.. code-block:: shell

    pip3 install circuitpython-vl53lxcx

To install system-wide (this may be required in some cases):

.. code-block:: shell

    sudo pip3 install circuitpython-vl53lxcx

To install in a virtual environment in your current project:

.. code-block:: shell

    mkdir project-name && cd project-name
    python3 -m venv .venv
    source .env/bin/activate
    pip3 install circuitpython-vl53lxcx

Installing to a Connected CircuitPython Device with Circup
==========================================================

Make sure that you have ``circup`` installed in your Python environment.
Install it with the following command if necessary:

.. code-block:: shell

    pip3 install circup

With ``circup`` installed and your CircuitPython device connected use the
following command to install:

.. code-block:: shell

    circup install vl53lxcx

Or the following command to update an existing version:

.. code-block:: shell

    circup update

Important: Binary File Requirement
===================================

When using this library with CircuitPython, you must also copy the corresponding ``.bin`` file to the ``/lib`` folder on your CircuitPython device, alongside the ``.mpy`` file. This binary file contains the firmware required for the VL53L5CX/VL53L8CX sensors to function properly.

The binary file should be placed in the same ``/lib`` directory as the ``vl53lxcx.mpy`` file on your CircuitPython filesystem.

Usage Example
=============

.. code-block:: python

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

    import board
    import busio
    from digitalio import DigitalInOut, Direction

    from vl53lxcx import (
        DATA_DISTANCE_MM,
        DATA_TARGET_STATUS,
        RESOLUTION_8X8,
        STATUS_VALID,
        VL53L8CX,
    )

    lpn_pin = board.D3
    i2c = busio.I2C(board.SCL, board.SDA, frequency=1_000_000)

    lpn = DigitalInOut(lpn_pin)
    lpn.direction = Direction.OUTPUT
    lpn.value = True

    tof = VL53L8CX(i2c, lpn=lpn)


    def main():
        tof.reset()

        if not tof.is_alive():
            raise ValueError("VL53L8CX not detected")

        tof.init()

        tof.resolution = RESOLUTION_8X8
        grid = 7

        tof.ranging_freq = 2

        tof.start_ranging({DATA_DISTANCE_MM, DATA_TARGET_STATUS})

        while True:
            if tof.check_data_ready():
                results = tof.get_ranging_data()
                distance = results.distance_mm
                status = results.target_status

                for i, d in enumerate(distance):
                    if status[i] == STATUS_VALID:
                        print(f"{d:4}", end=" ")
                    else:
                        print("xxxx", end=" ")

                    if (i & grid) == grid:
                        print("")

                print("")

    main()



Documentation
=============
API documentation for this library can be found on `Read the Docs <https://circuitpython-vl53lxcx.readthedocs.io/>`_.

For information on building library documentation, please check out
`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.

Contributing
============

Contributions are welcome! Please read our `Code of Conduct
<https://github.com/sensebox/CircuitPython_VL53LxCX/blob/HEAD/CODE_OF_CONDUCT.md>`_
before contributing to help this project stay welcoming.