rjrp44/vl53l5cx

readme

# VL53L5CX 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 VL53L5CX](https://www.st.com/content/st_com/en/products/embedded-software/imaging-software/stsw-img023.html) v1.3.11
. 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 VL53L5CX-SATEL](#wiring-for-the-vl53l5cx-satel- )
    * [Library Installation](#library-installation-)
* [Examples](#examples-)
* [Usual Errors](#usual-errors-)
    * [Stack overflow error](#stack-overflow-error-)

---

## Getting started
### Wiring for the VL53L5CX-SATEL 🔌

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

| VL53L5CX-SATEL Pins | ESP32S3 Pins                                  |           
|---------------------|-----------------------------------------------|
| INT                 | NC                                            |
| I2C_RST             | NC                                            |
| SDA                 | GPIO1, 2.2 kΩ pullup resistor required to 3v3 |
| SCL                 | GPIO2, 2.2 kΩ pullup resistor required to 3v3 |
| LPn                 | 3V3                                           |
| PWREN               | NC                                            |
| AVDD                | 3V3                                           |
| IOVDD               | 3V3                                           |
| GND                 | GND                                           |


### Library Installation 📥

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

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/vl53l5cx^2.0.4" 
```


## Examples 📄

You can find in `📁 ./examples` ST's examples adapted for ESP32 with I²C. For more information about the available features read [UM2884](https://www.st.com/resource/en/user_manual/um2884-a-guide-to-using-the-vl53l5cx-multizone-timeofflight-ranging-sensor-with-wide-field-of-view-ultra-lite-driver-uld-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)

                                        
                                        # Calibrate xtalk
This example shows the possibility of VL53L5CX to get/set params. It initializes the VL53L5CX 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 VL53L5CX 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`.


                                    

                                        
                                        # Detection thresholds
This example shows the possibility of VL53L5CX to program detection thresholds. It initializes the VL53L5CX 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`.

                                    

                                        
                                        # Get set params
This example shows the possibility of VL53L5CX to get/set params. It initializes the VL53L5CX 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
vl53l5cx_set_i2c_address(VL53L5CX_Configuration	*p_dev, uint16_t i2c_address);
```
### Power mode 🔋
This function is used to get the current sensor power mode.
```c
vl53l5cx_get_power_mode(VL53L5CX_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 ```VL53L5CX_POWER_MODE_SLEEP``` can be used to enable the low power mode. When user want to restart the sensor, he can use macro ```VL53L5CX_POWER_MODE_WAKEUP```. Please ensure that the device is not streaming before calling the function.
```c
vl53l5cx_set_power_mode(VL53L5CX_Configuration	*p_dev, uint8_t	p_power_mode);
```
### Resolution 📸
This function gets the current resolution (4x4 or 8x8).
```c
vl53l5cx_set_resolution(VL53L5CX_Configuration *p_dev, uint8_t p_resolution);
```
This function sets a new resolution (4x4 or 8x8).
```c
vl53l5cx_get_resolution(VL53L5CX_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
vl53l5cx_get_ranging_frequency_hz(VL53L5CX_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
vl53l5cx_set_ranging_frequency_hz(VL53L5CX_Configuration *p_dev,uint8_t frequency_hz);
```
### Integration time ⌚
This function gets the current integration time in ms.
```c
vl53l5cx_get_integration_time_ms(VL53L5CX_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
vl53l5cx_set_integration_time_ms(VL53L5CX_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
vl53l5cx_get_sharpener_percent(VL53L5CX_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
vl53l5cx_set_sharpener_percent(VL53L5CX_Configuration *p_dev, uint8_t p_sharpener_percent);
```
### Target order 🧮
This function gets the current target order (closest or strongest).
```c
vl53l5cx_get_target_order(VL53L5CX_Configuration *p_dev, uint8_t *p_target_order);
```
This function sets a new target order. Please use macros ```VL53L5CX_TARGET_ORDER_STRONGEST``` and ```VL53L5CX_TARGET_ORDER_CLOSEST``` to define the new output order. By default, the sensor is configured with the strongest
```c
vl53l5cx_set_target_order(VL53L5CX_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
vl53l5cx_get_ranging_mode(VL53L5CX_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
vl53l5cx_set_ranging_mode(VL53L5CX_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
vl53l5cx_get_external_sync_pin_enable(VL53L5CX_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
vl53l5cx_set_external_sync_pin_enable(VL53L5CX_Configuration *p_dev, uint8_t enable_sync_pin);
```

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

                                        
                                        # I²C and RAM optimization
This example shows the possibility of VL53L5CX to reduce I2C transactions and RAM footprint. It initializes the VL53L5CX 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`.


                                    

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

> **Warning**
> Make sure that macro ```VL53L5CX_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`.


                                    

                                        
                                        # 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 ```VL53L5CX_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`.
                                    

                                        
                                        # Multiple targets par zone
This example shows the possibility of VL53L5CX to get/set params. It initializes the VL53L5CX 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`.


                                    

                                        
                                        # Power modes
This example shows the possibility of VL53L5CX to change power mode. It initializes the VL53L5CX 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`.


                                    

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

By default, the vl53l5cx 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`.
                                    

                                        
                                        # Ranging modes
This example shows the differences between ranging modes of VL53L5CX (mode continuous and autonomous). For both modes, it initializes the VL53L5CX 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`.


                                    

                                        
                                        # Vizualize xtalk data
This example shows the possibility of VL53L5CX to visualize Xtalk data. It initializes the VL53L5CX 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 VL53L5CX 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`.