Add examples

README.md

@@ -54,7 +54,7 @@ idf.py add-dependency "rjrp44/vl53l8cx^0.1.0"
 
 ## Examples 📄
 
-You can find in `📁 ./examples` ST's examples adapted for ESP32 with I²C.
+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 💽
@@ -65,7 +65,7 @@ If by running an example you get a stack overflow error, this means that your ma
 ```
 **Increase the main stack size :**
 
-Run `idf.py menuconfig`. Go to Component Config -> ESP System settings and increase the Main task 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
 

examples/I2C_and_RAM_optimization/CMakeLists.txt

@@ -0,0 +1,8 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(main)

examples/I2C_and_RAM_optimization/README.md

@@ -0,0 +1,7 @@
+# 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`.
+

examples/I2C_and_RAM_optimization/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "main.c"
+                    INCLUDE_DIRS ".")

examples/I2C_and_RAM_optimization/main/idf_component.yml

@@ -0,0 +1,5 @@
+version: "1.0.0"
+description: "VL53L8CX I2C and RAM optimization example"
+dependencies:
+  rjrp44/vl53l8cx:
+    version : "~1.0.0"

examples/I2C_and_RAM_optimization/main/main.c

@@ -0,0 +1,209 @@
+/*******************************************************************************
+* Copyright (c) 2020, STMicroelectronics - All Rights Reserved
+*
+* This file is part of the VL53L8CX Ultra Lite Driver and is dual licensed,
+* either 'STMicroelectronics Proprietary license'
+* or 'BSD 3-clause "New" or "Revised" License' , at your option.
+*
+********************************************************************************
+*
+* 'STMicroelectronics Proprietary license'
+*
+********************************************************************************
+*
+* License terms: STMicroelectronics Proprietary in accordance with licensing
+* terms at www.st.com/sla0081
+*
+* STMicroelectronics confidential
+* Reproduction and Communication of this document is strictly prohibited unless
+* specifically authorized in writing by STMicroelectronics.
+*
+*
+********************************************************************************
+*
+* Alternatively, the VL53L8CX Ultra Lite Driver may be distributed under the
+* terms of 'BSD 3-clause "New" or "Revised" License', in which case the
+* following provisions apply instead of the ones mentioned above :
+*
+********************************************************************************
+*
+* License terms: BSD 3-clause "New" or "Revised" License.
+*
+* Redistribution and use in source and binary forms, with or without
+* modification, are permitted provided that the following conditions are met:
+*
+* Redistribution and use in source and binary forms, with or without
+* modification, are permitted provided that the following conditions are met:
+*
+* 1. Redistributions of source code must retain the above copyright notice, this
+* list of conditions and the following disclaimer.
+*
+* 2. Redistributions in binary form must reproduce the above copyright notice,
+* this list of conditions and the following disclaimer in the documentation
+* and/or other materials provided with the distribution.
+*
+* 3. Neither the name of the copyright holder nor the names of its contributors
+* may be used to endorse or promote products derived from this software
+* without specific prior written permission.
+*
+* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*
+*
+*******************************************************************************/
+
+/**************************************/
+/*  VL53L8CX ULD I2C/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.
+*
+* In this example, we also suppose that the number of target per zone is
+* set to 1 , and all output are enabled (see file platform.h).
+*/
+
+#include <stdlib.h>
+#include <string.h>
+#include <stdio.h>
+#include "vl53l8cx_api.h"
+
+void app_main(void)
+{
+
+    //Define the i2c bus configuration
+    i2c_port_t i2c_port = I2C_NUM_1;
+    i2c_config_t i2c_config = {
+            .mode = I2C_MODE_MASTER,
+            .sda_io_num = 1,
+            .scl_io_num = 2,
+            .sda_pullup_en = GPIO_PULLUP_ENABLE,
+            .scl_pullup_en = GPIO_PULLUP_ENABLE,
+            .master.clk_speed = VL53L8CX_MAX_CLK_SPEED,
+    };
+
+    i2c_param_config(i2c_port, &i2c_config);
+    i2c_driver_install(i2c_port, i2c_config.mode, 0, 0, 0);
+
+    /*********************************/
+    /*   VL53L8CX ranging variables  */
+    /*********************************/
+
+    uint8_t 				status, loop, isAlive, isReady, i;
+    VL53L8CX_Configuration 	Dev;			/* Sensor configuration */
+    VL53L8CX_ResultsData 	Results;		/* Results data from VL53L8CX */
+
+
+    /*********************************/
+    /*      Customer platform        */
+    /*********************************/
+
+    /* Fill the platform structure with customer's implementation. For this
+    * example, only the I2C address is used.
+    */
+    Dev.platform.address = VL53L8CX_DEFAULT_I2C_ADDRESS;
+    Dev.platform.port = i2c_port;
+
+    /* (Optional) Reset sensor toggling PINs (see platform, not in API) */
+    //Reset_Sensor(&(Dev.platform));
+
+    /* (Optional) Set a new I2C address if the wanted address is different
+    * from the default one (filled with 0x20 for this example).
+    */
+    //status = vl53l8cx_set_i2c_address(&Dev, 0x20);
+
+
+    /*********************************/
+    /*   Power on sensor and init    */
+    /*********************************/
+
+    /* (Optional) Check if there is a VL53L8CX sensor connected */
+    status = vl53l8cx_is_alive(&Dev, &isAlive);
+    if(!isAlive || status)
+    {
+        printf("VL53L8CX not detected at requested address\n");
+        return;
+    }
+
+    /* (Mandatory) Init VL53L8CX sensor */
+    status = vl53l8cx_init(&Dev);
+    if(status)
+    {
+        printf("VL53L8CX ULD Loading failed\n");
+        return;
+    }
+
+    printf("VL53L8CX ULD ready ! (Version : %s)\n",
+           VL53L8CX_API_REVISION);
+
+
+    /*********************************/
+    /*   Reduce RAM & I2C access	 */
+    /*********************************/
+
+    /* Results can be tuned in order to reduce I2C access and RAM footprints.
+     * The 'platform.h' file contains macros used to disable output. If user declare
+     * one of these macros, the results will not be sent through I2C, and the array will not
+     * be created into the VL53L8CX_ResultsData structure.
+     * For the minimum size, ST recommends 1 targets per zone, and only keep distance_mm,
+     * target_status, and nb_target_detected. The following macros can be defined into file 'platform.h':
+     *
+     * #define VL53L8CX_DISABLE_AMBIENT_PER_SPAD
+     * #define VL53L8CX_DISABLE_NB_SPADS_ENABLED
+     * #define VL53L8CX_DISABLE_SIGNAL_PER_SPAD
+     * #define VL53L8CX_DISABLE_RANGE_SIGMA_MM
+     * #define VL53L8CX_DISABLE_REFLECTANCE_PERCENT
+     * #define VL53L8CX_DISABLE_MOTION_INDICATOR
+     */
+
+    /*********************************/
+    /*         Ranging loop          */
+    /*********************************/
+
+    status = vl53l8cx_start_ranging(&Dev);
+
+    loop = 0;
+    while(loop < 10)
+    {
+        /* Use polling function to know when a new measurement is ready.
+         * Another way can be to wait for HW interrupt raised on PIN A1
+         * (INT) when a new measurement is ready */
+
+        status = vl53l8cx_check_data_ready(&Dev, &isReady);
+
+        if(isReady)
+        {
+            vl53l8cx_get_ranging_data(&Dev, &Results);
+
+            /* As the sensor is set in 4x4 mode by default, we have a total
+             * of 16 zones to print. For this example, only the data of first zone are
+             * print */
+            printf("Print data no : %3u\n", Dev.streamcount);
+            for(i = 0; i < 16; i++)
+            {
+                printf("Zone : %3d, Status : %3u, Distance : %4d mm\n",
+                       i,
+                       Results.target_status[VL53L8CX_NB_TARGET_PER_ZONE*i],
+                       Results.distance_mm[VL53L8CX_NB_TARGET_PER_ZONE*i]);
+            }
+            printf("\n");
+            loop++;
+        }
+
+        /* Wait a few ms to avoid too high polling (function in platform
+         * file, not in API) */
+        WaitMs(&(Dev.platform), 5);
+    }
+
+    status = vl53l8cx_stop_ranging(&Dev);
+    printf("End of ULD demo\n");
+}

examples/calibrate_xtalk/CMakeLists.txt

@@ -0,0 +1,8 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(main)

examples/calibrate_xtalk/README.md

@@ -0,0 +1,13 @@
+# 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`.
+

examples/calibrate_xtalk/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "main.c"
+                    INCLUDE_DIRS ".")

examples/calibrate_xtalk/main/idf_component.yml

@@ -0,0 +1,5 @@
+version: "1.0.0"
+description: "VL53L8CX calibrate xtalk example"
+dependencies:
+  rjrp44/vl53l8cx:
+    version : "~1.0.0"