A vl53l8cx library for esp32 using the esp-idf framework.

readme

# VL53L8CX library for ESP32

A vl53l5cx library for esp32 using the **esp-idf framework**. This library is based
on [ST's  Ultra Lite Driver (ULD) for VL53L8CX](https://www.st.com/content/st_com/en/products/embedded-software/imaging-software/stsw-img040.html)
v.1.2.1. This library is just an adaptation of the ST's library for esp-32.

> **Warning**
> This Library is **not** compatible with Arduino framework

## Contents šŸ“Œ

* [Getting started](#Getting-started)
  * [Wiring for the SATEL-VL53L8](#wiring-for-the-satel-VL53L8)
  * [Library Installation](#library-installation-)
* [Examples](#examples-)
* [Usual Errors](#usual-errors-)
  * [Stack overflow error](#stack-overflow-error-)

---

## Getting started
### Wiring for the SATEL-VL53L8

For the examples this is the used wiring, but feel free to modify it and adapt it for your needs.

| SATEL-VL53L8 Pins | ESP32S3 Pins                                  |           
|-------------------|-----------------------------------------------|
| 5v                | 5v                                            |
| 1v8               | NC                                            |
| 3v3               | NC                                            |
| IOVDD             | NC                                            |
| PWREN             | 5V                                            |
| MCLK_SCL          | GPIO2, 2.2 kĪ© pullup resistor required to 3v3 |
| MOSI_SDA          | GPIO1, 2.2 kĪ© pullup resistor required to 3v3 |
| MISO              | NC                                            |
| NCS               | 3v3                                           |       
| SPI_I2C_N         | GND                                           |
| GPIO1             | NC                                            |
| GPIO2             | NC                                            |
| GND               | GND                                           |


### Library Installation šŸ“„

The library is available at https://components.espressif.com/components/rjrp44/vl53l8cx.

So, you can use the [IDF Component Manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html) to easily import this library into your project.
To add this component to your project, run:

```log
idf.py add-dependency "rjrp44/vl53l8cx^1.1.0" 
```


## Examples šŸ“„

You can find in `šŸ“ ./examples` ST's examples adapted for ESP32 with IĀ²C. For more information about the available features read [UM3109](https://www.st.com/resource/en/user_manual/um3109-a-guide-for-using-the-vl53l8cx-lowpower-highperformance-timeofflight-multizone-ranging-sensor-stmicroelectronics.pdf).

## Usual errors šŸ›
### Stack overflow error šŸ’½

If by running an example you get a stack overflow error, this means that your main stack size is too small.
```log
***ERROR*** A stack overflow in task main has been detected.
```
**Increase the main stack size :**

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.

## šŸ“ License

Copyright Ā© 2023 [RJRP](https://www.github.com/RJRP44).

This project is [BSD 3-Clause](https://opensource.org/licenses/BSD-3-Clause/)  licensed.

## āœØ Show your support

Give a ā­ļø if this project helped you!

## šŸ‘¤ Authors

- [@RJRP](https://www.github.com/RJRP44)

readme of calibrate_xtalk example

                                        
                                        # Calibrate xtalk
This example shows the possibility of VL53L8CX to get/set params. It initializes the VL53L8CX ULD, set a configuration, and starts a ranging to capture 10 frames.

> **Warning**
> This example requires a protective window (cover glass) on the sensor.

## Xtalk
Crosstalk (Xtalk) is defined as the amount of signal received on the SPAD array, which is due to VCSEL light reflection inside the protective window (cover glass) added on top of the module. The VL53L8CX module is self-calibrated, and can be used without any additional calibration.
## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.


                                    

readme of detection_thresholds example

                                        
                                        # Detection thresholds
This example shows the possibility of VL53L8CX to program detection thresholds. It initializes the VL53L8CX ULD, create 2 thresholds per zone for a 4x4 resolution, and starts a ranging to capture 10 frames.

> **Warning**
> This example requires to connect the INT (GPO) pin of the sensor to the GPIO3 of the esp32

For this example, the thresholds is :
- a signal equaling 150 kcps/spads 
- a distance between 200mm and 400mm

## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.

                                    

readme of get_set_params example

                                        
                                        # Get set params
This example shows the possibility of VL53L8CX to get/set params. It initializes the VL53L8CX ULD, set a configuration, and starts a ranging to capture 10 frames.

## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.

## Parameters āš™
- [IĀ²C address](#ic-address-)
- [Power mode](#power-mode-)
- [Resolution](#resolution-)
- [Frequency](#frequency-)
- [Integration time](#integration-time-)
- [Sharpener percent](#sharpener-percent-)
- [Target order ](#target-order-)
- [Ranging mode](#ranging-mode-)
- [Synchronization pin](#synchronization-pin-)

This is a list of all the parameters that you can modify :
### IĀ²C address šŸ“«
This function is used to change the I2C address of the sensor. If multiple VL53L5 sensors are connected to the same I2C line, all other LPn pins needs to be set to Low. The default sensor address is 0x52.
```c
vl53l8cx_set_i2c_address(VL53L8CX_Configuration	*p_dev, uint16_t i2c_address);
```
### Power mode šŸ”‹
This function is used to get the current sensor power mode.
```c
vl53l8cx_get_power_mode(VL53L8CX_Configuration	*p_dev, uint8_t	*p_power_mode);
```
This function is used to set the sensor in Low Power mode, for example if the sensor is not used during a long time. The macro ```VL53L8CX_POWER_MODE_SLEEP``` can be used to enable the low power mode. When user want to restart the sensor, he can use macro ```VL53L8CX_POWER_MODE_WAKEUP```. Please ensure that the device is not streaming before calling the function.
```c
vl53l8cx_set_power_mode(VL53L8CX_Configuration	*p_dev, uint8_t	p_power_mode);
```
### Resolution šŸ“ø
This function gets the current resolution (4x4 or 8x8).
```c
vl53l8cx_set_resolution(VL53L8CX_Configuration *p_dev, uint8_t p_resolution);
```
This function sets a new resolution (4x4 or 8x8).
```c
vl53l8cx_get_resolution(VL53L8CX_Configuration *p_dev, uint8_t *p_resolution);
```
### Frequency šŸ“”
This function gets the current ranging frequency in Hz. Ranging frequency corresponds to the time between each measurement.
```c
vl53l8cx_get_ranging_frequency_hz(VL53L8CX_Configuration *p_dev,uint8_t *frequency_hz);
```
This function sets a new ranging frequency in Hz. Ranging frequency corresponds to the measurements' frequency. This setting depends of the resolution, so please select your resolution before using this function.
```c
vl53l8cx_set_ranging_frequency_hz(VL53L8CX_Configuration *p_dev,uint8_t frequency_hz);
```
### Integration time āŒš
This function gets the current integration time in ms.
```c
vl53l8cx_get_integration_time_ms(VL53L8CX_Configuration *p_dev, uint32_t *p_time_ms);
```
This function sets a new integration time in ms. Integration time must be computed to be lower than the ranging period, for a selected resolution. Please note that this function has no impact on ranging mode continous.
```c
vl53l8cx_set_integration_time_ms(VL53L8CX_Configuration *p_dev, uint32_t p_time_ms);
```
### Sharpener percent šŸ”Ŗ
This function gets the current sharpener in percent. Sharpener can be changed to blur more or less zones depending of the application.
```c
vl53l8cx_get_sharpener_percent(VL53L8CX_Configuration *p_dev, uint8_t *p_sharpener_percent);
```
This function sets a new sharpener value in percent. Sharpener can be changed to blur more or less zones depending of the application. Min value is 0 (disabled), and max is 99.
```c
vl53l8cx_set_sharpener_percent(VL53L8CX_Configuration *p_dev, uint8_t p_sharpener_percent);
```
### Target order šŸ§®
This function gets the current target order (closest or strongest).
```c
vl53l8cx_get_target_order(VL53L8CX_Configuration *p_dev, uint8_t *p_target_order);
```
This function sets a new target order. Please use macros ```VL53L8CX_TARGET_ORDER_STRONGEST``` and ```VL53L8CX_TARGET_ORDER_CLOSEST``` to define the new output order. By default, the sensor is configured with the strongest
```c
vl53l8cx_set_target_order(VL53L8CX_Configuration *p_dev, uint8_t p_target_order);
```
### Ranging mode šŸ”§
This function is used to get the ranging mode. Two modes are available using ULD : Continuous and autonomous. The default mode is Autonomous.
```c
vl53l8cx_get_ranging_mode(VL53L8CX_Configuration *p_dev, uint8_t *p_ranging_mode);
```
This function is used to set the ranging mode. Two modes are available using ULD : Continuous and autonomous. The default mode is Autonomous.
```c
vl53l8cx_set_ranging_mode(VL53L8CX_Configuration *p_dev, uint8_t p_ranging_mode);
```
### Synchronization pin šŸ”—
This function is used to check if the synchronization pin is enabled or disabled. When it is enabled, the sensor waits an interrupt on B1 pin to start the next measurement. It is useful for multi-devices
```c
vl53l8cx_get_external_sync_pin_enable(VL53L8CX_Configuration *p_dev, uint8_t *enable_sync_pin);
```
This function is used to enable or disable the synchronization pin. When it is enabled, the sensor waits an interrupt on B1 pin to start the next measurement. It is useful for multi-devices synchronization. By default the sync pin is disabled.
```c
vl53l8cx_set_external_sync_pin_enable(VL53L8CX_Configuration *p_dev, uint8_t enable_sync_pin);
```

> All function descriptions come from the vl53l8cx_api.h file.
                                    

readme of I2C_and_RAM_optimization example

                                        
                                        # IĀ²C and RAM optimization
This example shows the possibility of VL53L8CX to reduce I2C transactions and RAM footprint. It initializes the VL53L8CX ULD, and starts a ranging to capture 10 frames.
## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.


                                    

readme of motion_indicator example

                                        
                                        # Motion indicator
This example shows the VL53L8CX motion indicator capabilities.

> **Warning**
> Make sure that macro ```VL53L8CX_DISABLE_MOTION_INDICATOR``` is NOT enabled (see file platform.h).

## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.


                                    

readme of motion_indicator_with_detection_thresholds example

                                        
                                        # Motion indicator with detection thresholds
This example shows how to use the motion indicator with detection threshold. This kind of configuration might be used for user detection applications.

> **Warning**
> This example requires to connect the INT (GPO) pin of the sensor to the GPIO3 of the esp32
> Make sure that macro ```VL53L8CX_DISABLE_MOTION_INDICATOR``` is NOT enabled (see file platform.h).

For this example, motion above 44 will be considered as a movement.

## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.
                                    

readme of multiple_targets_per_zone example

                                        
                                        # Multiple targets par zone
This example shows the possibility of VL53L8CX to get/set params. It initializes the VL53L8CX ULD, set a configuration, and starts a ranging to capture 10 frames.
## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.


                                    

readme of power_modes example

                                        
                                        # Power modes
This example shows the possibility of VL53L8CX to change power mode. It initializes the VL53L8CX ULD, set a configuration, change the power mode, and starts a ranging to capture 10 frames.

## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.


                                    

readme of ranging_basic example

                                        
                                        # Ranging Basic
This example is the most basic. It initializes the VL53L8CX ULD, and starts a ranging to capture 10 frames.

By default, the vl53l8cx is configured to have the following settings :
- Resolution 4x4
- Ranging period 1Hz

## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.
                                    

readme of ranging_modes example

                                        
                                        # Ranging modes
This example shows the differences between ranging modes of VL53L8CX (mode continuous and autonomous). For both modes, it initializes the VL53L8CX ULD, set the mode, and starts a ranging to capture 10 frames.
## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.


                                    

readme of vizualize_xtalk_data example

                                        
                                        # Vizualize xtalk data
This example shows the possibility of VL53L8CX to visualize Xtalk data. It initializes the VL53L8CX ULD, perform a Xtalk calibration, and starts a ranging to capture 10 frames.

> **Warning**
> This example requires a protective window (cover glass) on the sensor.

## Xtalk
Crosstalk (Xtalk) is defined as the amount of signal received on the SPAD array, which is due to VCSEL light reflection inside the protective window (cover glass) added on top of the module. The VL53L8CX module is self-calibrated, and can be used without any additional calibration.
## Get started
In order to run this example you need to increase the main stack size else you will get a stack overflow error.

Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task stack size to at least `7168`.


                                    

Supports all targets

License: BSD-3-Clause

To add this component to your project, run:

idf.py add-dependency "rjrp44/vl53l8cx^1.1.1"

or download archive

Dependencies

  • ESP-IDF >=5.0
  • Examples:

    calibrate_xtalk

    more details

    detection_thresholds

    more details

    get_set_params

    more details

    I2C_and_RAM_optimization

    more details

    motion_indicator

    more details

    motion_indicator_with_detection_thresholds

    more details

    multiple_targets_per_zone

    more details

    power_modes

    more details

    ranging_basic

    more details

    ranging_modes

    more details

    vizualize_xtalk_data

    more details

    Stats

    • Archive size
      Archive size: 139.96 KB
    • Downloaded in total
      Downloaded in total 7 times
    • Downloaded this version
      This version: 1 time

    Badge

    rjrp44/vl53l8cx version: 1.1.1 |