rjrp44/vl53l8cx

readme

<h1 style="text-align: center;"> VL53L8CX library for ESP32  </h1>
<p style="text-align: center;">
<img src="https://seeklogo.com/images/E/espressif-systems-logo-1350B9E771-seeklogo.com.png" alt="Espressif logo" width="40">
&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp
<img src="https://upload.wikimedia.org/wikipedia/fr/e/e0/STMicroelectronics_%28logo-2020%29.svg" alt="ST logo" width="160">
</p>

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)
. This library is just an adaptation of the ST's library for esp-32.

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

## Contents 📌

* [Installation](#installation-)
  * [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-)

---

## Installation 📥
### 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

You can now 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 ! If you have not already done so, create a file named `idf_component.yml` in your `📁 ./main` folder. Now just add the library to it :
```yaml
dependencies:
  
  #V53L8CX-Library
  vl53l8cx:
    git: https://github.com/RJRP44/V53L8CX-Library.git

```

You can now reload your cmake project, and you should see it in the cmake log and in the `📁 ./managed_components` folder.

```log
Processing 2 dependencies:
[1/2] idf (5.0.0)
[2/2] vl53l8cx
```

## Examples 📄

You can find in `📁 ./examples` ST's examples adapted for ESP32 with I²C.

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

## 📝 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)

                                        
                                        | Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-S2 | ESP32-S3 |
| ----------------- | ----- | -------- | -------- | -------- | -------- |

# _Sample project_

(See the README.md file in the upper level 'examples' directory for more information about examples.)

This is the simplest buildable example. The example is used by command `idf.py create-project`
that copies the project to user specified path and set it's name. For more information follow the [docs page](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project)



## How to use example
We encourage the users to use the example as a template for the new projects.
A recommended way is to follow the instructions on a [docs page](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project).

## Example folder contents

The project **sample_project** contains one source file in C language [main.c](main/main.c). The file is located in folder [main](main).

ESP-IDF projects are built using CMake. The project build configuration is contained in `CMakeLists.txt`
files that provide set of directives and instructions describing the project's source files and targets
(executable, library, or both). 

Below is short explanation of remaining files in the project folder.

```
├── CMakeLists.txt
├── main
│   ├── CMakeLists.txt
│   └── main.c
└── README.md                  This is the file you are currently reading
```
Additionally, the sample project contains Makefile and component.mk files, used for the legacy Make based build system. 
They are not used or needed when building with CMake and idf.py.