Merge pull request #1 from davideq/main

VL53L4ED Driver and examples

.github/workflows/Continuous-integration.yml

@@ -0,0 +1,69 @@
+name: VL53L4ED Continuous Integration
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '*'
+      - '**.md'
+      - '**.txt'
+  pull_request:
+    paths-ignore:
+      - '*'
+      - '**.md'
+      - '**.txt'
+jobs:
+  astyle_check:
+    runs-on: ubuntu-latest
+    name: AStyle check
+    steps:
+    # First of all, clone the repo using the checkout action.
+    - name: Checkout
+      uses: actions/checkout@main
+
+    - name: Astyle check
+      id: Astyle
+      uses: stm32duino/actions/astyle-check@main
+
+    # Use the output from the `Astyle` step
+    - name: Astyle Errors
+      if: failure()
+      run: |
+        cat ${{ steps.Astyle.outputs.astyle-result }}
+        exit 1
+  codespell:
+    name: Check for spelling errors
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@main
+
+    # See: https://github.com/codespell-project/actions-codespell/blob/master/README.md
+    - name: Spell check
+      uses: codespell-project/actions-codespell@master
+      with:
+        check_filenames: true
+        check_hidden: true
+        # In the event of a false positive, add the word in all lower case to this file:
+        ignore_words_file: ./extras/codespell-ignore-words-list.txt
+  lib_build:
+    runs-on: ubuntu-latest
+    name: Library compilation
+    steps:
+
+    # First of all, clone the repo using the checkout action.
+    - name: Checkout
+      uses: actions/checkout@main
+
+    - name: Compilation
+      id: compile
+      uses: stm32duino/actions/compile-examples@main
+      with:
+        board-pattern: "NUCLEO_L476RG"
+
+    # Use the output from the `Compilation` step
+    - name: Compilation Errors
+      if: failure()
+      run: |
+        cat ${{ steps.compile.outputs.compile-result }}
+        exit 1

README.md

@@ -0,0 +1,33 @@
+# VL53L4ED
+Arduino library to support the VL53L4ED Time-of-Flight ranging sensor.
+
+## API
+
+This sensor uses I2C to communicate. And I2C instance is required to access to the sensor.
+The APIs provide simple distance measure in both polling and interrupt modes.
+
+## Examples
+
+There are 2 examples with the VL53L4ED library.
+
+In order to use these examples you need to connect the VL53L4ED satellite sensor directly to the Nucleo board with wires as explained below:
+- pin 1 (GND) of the VL53L4ED satellite connected to GND of the Nucleo board
+- pin 2 (VDD) of the VL53L4ED satellite connected to 3V3 pin of the Nucleo board
+- pin 3 (SCL) of the VL53L4ED satellite connected to pin D15 (SCL) of the Nucleo board
+- pin 4 (SDA) of the VL53L4ED satellite connected to pin D14 (SDA) of the Nucleo board
+- pin 5 (GPIO1) of the VL53L4ED satellite connected to pin A2 of the Nucleo board
+- pin 6 (XSHUT) of the VL53L4ED satellite connected to pin D3 of the Nucleo board
+
+* VL53L4ED_Sat_HelloWorld: This example code is to show how to get proximity values of the VL53L4ED satellite sensor in polling mode.
+
+* VL53L4ED_Sat_HelloWorld_Interrupt: This example code is to show how to get proximity values of the VL53L4ED satellite sensor in interrupt mode.
+
+* VL53L4ED_Sat_Threshold_Detection: This example code is to show how to configure the threshold and get proximity values when the ranging is below 100mm or above 200mm.
+
+## Documentation
+
+You can find the source files at  
+https://github.com/stm32duino/VL53L4ED
+
+The VL53L4ED datasheet is available at  
+https://www.st.com/content/st_com/en/products/imaging-and-photonics-solutions/proximity-sensors/vl53l4ed.html

examples/VL53L4ED_Sat_HelloWorld/VL53L4ED_Sat_HelloWorld.ino

@@ -0,0 +1,117 @@
+/**
+ ******************************************************************************
+ * @file    VL53L4ED_Sat_HelloWorld.ino
+ * @author  STMicroelectronics
+ * @version V1.0.0
+ * @date    01 April 2024
+ * @brief   Arduino test application for the STMicrolectronics VL53L4ED
+ *          proximity sensor satellite based on FlightSense.
+ *          This application makes use of C++ classes obtained from the C
+ *          components' drivers.
+ ******************************************************************************
+ * @attention
+ *
+ * <h2><center>&copy; COPYRIGHT(c) 2024 STMicroelectronics</center></h2>
+ *
+ * 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 STMicroelectronics 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.
+ *
+ ******************************************************************************
+ */
+
+/*
+ * To use this sketch you need to connect the VL53L4ED satellite sensor directly to the Nucleo board with wires in this way:
+ * pin 1 (GND) of the VL53L4ED satellite connected to GND of the Nucleo board
+ * pin 2 (VDD) of the VL53L4ED satellite connected to 3V3 pin of the Nucleo board
+ * pin 3 (SCL) of the VL53L4ED satellite connected to pin D15 (SCL) of the Nucleo board
+ * pin 4 (SDA) of the VL53L4ED satellite connected to pin D14 (SDA) of the Nucleo board
+ * pin 5 (GPIO1) of the VL53L4ED satellite connected to pin A2 of the Nucleo board
+ * pin 6 (XSHUT) of the VL53L4ED satellite connected to pin D3 of the Nucleo board
+ */
+/* Includes ------------------------------------------------------------------*/
+#include <vl53l4ed_class.h>
+
+#define DEV_I2C Wire
+#define SerialPort Serial
+
+#ifndef LED_BUILTIN
+  #define LED_BUILTIN 13
+#endif
+#define LedPin LED_BUILTIN
+
+// Components.
+VL53L4ED sensor_vl53l4ed_sat(&DEV_I2C, 3);
+
+/* Setup ---------------------------------------------------------------------*/
+
+void setup()
+{
+  // Led.
+  pinMode(LedPin, OUTPUT);
+
+  // Initialize serial for output.
+  SerialPort.begin(115200);
+  SerialPort.println("Starting...");
+
+  // Initialize I2C bus.
+  DEV_I2C.begin();
+
+  // Configure VL53L4ED satellite component.
+  sensor_vl53l4ed_sat.begin();
+
+  //Initialize VL53L4ED satellite component.
+  sensor_vl53l4ed_sat.InitSensor();
+
+  // Start Measurements
+  sensor_vl53l4ed_sat.VL53L4ED_StartRanging();
+}
+
+void loop()
+{
+  uint8_t NewDataReady = 0;
+  VL53L4ED_ResultsData_t results;
+  uint8_t status;
+  char report[64];
+
+  do {
+    status = sensor_vl53l4ed_sat.VL53L4ED_CheckForDataReady(&NewDataReady);
+  } while (!NewDataReady);
+
+  //Led on
+  digitalWrite(LedPin, HIGH);
+
+  if ((!status) && (NewDataReady != 0)) {
+    // (Mandatory) Clear HW interrupt to restart measurements
+    sensor_vl53l4ed_sat.VL53L4ED_ClearInterrupt();
+
+    // Read measured distance. RangeStatus = 0 means valid data
+    sensor_vl53l4ed_sat.VL53L4ED_GetResult(&results);
+    snprintf(report, sizeof(report), "Status = %3u, Distance = %5u mm, Signal = %6u kcps/spad\r\n",
+             results.range_status,
+             results.distance_mm,
+             results.signal_per_spad_kcps);
+    SerialPort.print(report);
+  }
+
+  //Led off
+  digitalWrite(LedPin, LOW);
+}

examples/VL53L4ED_Sat_HelloWorld_Interrupt/VL53L4ED_Sat_HelloWorld_Interrupt.ino

@@ -0,0 +1,136 @@
+/**
+ ******************************************************************************
+ * @file    VL53L4ED_Sat_HelloWorld_Interrupt.ino
+ * @author  STMicroelectronics
+ * @version V1.0.0
+ * @date    01 April 2024
+ * @brief   Arduino test application for the STMicrolectronics VL53L4ED
+ *          proximity sensor satellite based on FlightSense.
+ *          This application makes use of C++ classes obtained from the C
+ *          components' drivers.
+ ******************************************************************************
+ * @attention
+ *
+ * <h2><center>&copy; COPYRIGHT(c) 2024 STMicroelectronics</center></h2>
+ *
+ * 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 STMicroelectronics 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.
+ *
+ ******************************************************************************
+ */
+
+//On some boards like the Arduino Uno the pin used by the sensor to raise interrupts (A2)
+//can't be mapped as an interrupt pin. For this this reason this sketch will not work
+//unless some additional cabling is done and the interrupt pin is changed.
+/*
+ * To use this sketch you need to connect the VL53L4ED satellite sensor directly to the Nucleo board with wires in this way:
+ * pin 1 (GND) of the VL53L4ED satellite connected to GND of the Nucleo board
+ * pin 2 (VDD) of the VL53L4ED satellite connected to 3V3 pin of the Nucleo board
+ * pin 3 (SCL) of the VL53L4ED satellite connected to pin D15 (SCL) of the Nucleo board
+ * pin 4 (SDA) of the VL53L4ED satellite connected to pin D14 (SDA) of the Nucleo board
+ * pin 5 (GPIO1) of the VL53L4ED satellite connected to pin A2 of the Nucleo board
+ * pin 6 (XSHUT) of the VL53L4ED satellite connected to pin D3 of the Nucleo board
+ */
+/* Includes ------------------------------------------------------------------*/
+#include <vl53l4ed_class.h>
+
+
+#define DEV_I2C Wire
+#define SerialPort Serial
+
+#ifndef LED_BUILTIN
+  #define LED_BUILTIN 13
+#endif
+#define LedPin LED_BUILTIN
+
+#define interruptPin A2
+
+// Components.
+VL53L4ED sensor_vl53l4ed_sat(&DEV_I2C, 3);
+
+volatile int interruptCount = 0;
+
+void measure()
+{
+  interruptCount = 1;
+}
+
+/* Setup ---------------------------------------------------------------------*/
+
+void setup()
+{
+  // Led.
+  pinMode(LedPin, OUTPUT);
+
+  // Interrupt
+  pinMode(interruptPin, INPUT);
+  attachInterrupt(interruptPin, measure, FALLING);
+
+  // Initialize serial for output.
+  SerialPort.begin(115200);
+  SerialPort.println("Starting...");
+
+  // Initialize I2C bus.
+  DEV_I2C.begin();
+
+  // Configure VL53L4ED satellite component.
+  sensor_vl53l4ed_sat.begin();
+
+  //Initialize VL53L4ED satellite component.
+  sensor_vl53l4ed_sat.InitSensor();
+
+  // Start Measurements
+  sensor_vl53l4ed_sat.VL53L4ED_StartRanging();
+}
+
+void loop()
+{
+  uint8_t NewDataReady = 0;
+  VL53L4ED_ResultsData_t results;
+  uint8_t status;
+  char report[64];
+
+  if (interruptCount) {
+    interruptCount = 0;
+
+    status = sensor_vl53l4ed_sat.VL53L4ED_CheckForDataReady(&NewDataReady);
+
+    //Led on
+    digitalWrite(LedPin, HIGH);
+
+    if ((!status) && (NewDataReady != 0)) {
+      // (Mandatory) Clear HW interrupt to restart measurements
+      sensor_vl53l4ed_sat.VL53L4ED_ClearInterrupt();
+
+      // Read measured distance. RangeStatus = 0 means valid data
+      sensor_vl53l4ed_sat.VL53L4ED_GetResult(&results);
+      snprintf(report, sizeof(report), "Status = %3u, Distance = %5u mm, Signal = %6u kcps/spad\r\n",
+               results.range_status,
+               results.distance_mm,
+               results.signal_per_spad_kcps);
+      SerialPort.print(report);
+    }
+
+    //Led off
+    digitalWrite(LedPin, LOW);
+  }
+}