Merge pull request #1 from davideq/main

Add VL53L7CH driver and relative examples

.github/workflows/Continuous-integration.yml

@@ -0,0 +1,67 @@
+name: VL53L7CH 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
+  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

@@ -1,2 +1,39 @@
 # VL53L7CH
-Arduino library to support the VL53L7CH artificial intelligence enabler, Time-of-Flight (ToF) 8x8 multizone sensor with 90 degrees FoV
+Arduino library to support the VL53L7CH Time-of-Flight 8x8 multizone ranging sensor with wide field view.
+
+## API
+
+This sensor uses I2C to communicate. And I2C instance is required to access to the sensor.
+The APIs provide simple distance measure and multizone detection in both polling and interrupt modes.
+The APIs derive from VL53LMZ ULD SDK v1.7.0.
+
+## Examples
+
+The examples contained in this library are based on VL53L7CH-SATEL sensor board.
+
+You need to connect the VL53L7CH-SATEL sensor board directly to the Nucleo board with wires as explained below in the case of I2C communication:
+ * pin 1 (GND) of the VL53L7CX satellite connected to GND of the Nucleo board
+ * pin 2 (IOVDD) of the VL53L7CX satellite connected to 3V3 pin of the Nucleo board
+ * pin 3 (AVDD) of the VL53L7CX satellite connected to 5V pin of the Nucleo board
+ * pin 4 (PWREN) of the VL53L7CX satellite connected to pin A5 of the Nucleo board
+ * pin 5 (LPn) of the VL53L7CX satellite connected to pin A3 of the Nucleo board
+ * pin 6 (SCL) of the VL53L7CX satellite connected to pin D15 (SCL) of the Nucleo board
+ * pin 7 (SDA) of the VL53L7CX satellite connected to pin D14 (SDA) of the Nucleo board
+ * pin 8 (I2C_RST) of the VL53L7CX satellite connected to pin A1 of the Nucleo board
+ * pin 9 (INT) of the VL53L7CX satellite connected to pin A2 of the Nucleo board
+
+There are 2 examples with the VL53L7CH library:
+
+* VL53L7CH_Sat_HelloWorld_I2C: This example code is to show how to get multizone detection and proximity
+  values of the VL53L7CH satellite sensor in polling mode using I2C communication.
+
+* VL53L7CH_ThresholdsDetection: This example code is to show how to configure the thresholds detection of the VL53L7CH satellite sensor.
+
+
+## Documentation
+
+You can find the source files at
+https://github.com/stm32duino/VL53L7CH
+
+The VL53L7CH datasheet is available at
+https://www.st.com/en/imaging-and-photonics-solutions/VL53L7CH.html

examples/VL53L7CH_HelloWorld_I2C/VL53L7CH_HelloWorld_I2C.ino

@@ -0,0 +1,281 @@
+/**
+******************************************************************************
+* @file    VL53LMZ_HelloWorld_I2C.ino
+* @author  STMicroelectronics
+* @version V1.0.0
+* @date    17 July 2024
+* @brief   Arduino test application for STMicroelectronics VL53L7CH
+*          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 these examples you need to connect the VL53L7CH satellite sensor directly to the Nucleo board with wires as explained below:
+ * pin 1 (SPI_I2C_N) of the VL53L7CH satellite connected to pin GND of the Nucleo board
+ * pin 2 (LPn) of the VL53L7CH satellite connected to pin A3 of the Nucleo board
+ * pin 3 (NCS) not connected
+ * pin 4 (MISO) not connected
+ * pin 5 (MOSI_SDA) of the VL53L7CH satellite connected to pin D14 (SDA) of the Nucleo board
+ * pin 6 (MCLK_SCL) of the VL53L7CH satellite connected to pin D15 (SCL) of the Nucleo board
+ * pin 7 (PWREN) of the VL53L7CH satellite connected to pin D11 of the Nucleo board
+ * pin 8 (I0VDD) of the VL53L7CH satellite not connected
+ * pin 9 (3V3) of the VL53L7CH satellite connected to 3V3 of the Nucleo board
+ * pin 10 (1V8) of the VL53L7CH satellite not connected
+ * pin 11 (5V) of the VL53L7CH satellite not connected
+ * GPIO1 of VL53L7CH satellite connected to A2 pin of the Nucleo board (not used)
+ * GND of the VL53L7CH satellite connected to GND of the Nucleo board
+ */
+
+/* Includes ------------------------------------------------------------------*/
+
+#include <vl53l7ch.h>
+
+
+#ifdef ARDUINO_SAM_DUE
+  #define DEV_I2C Wire1
+#else
+  #define DEV_I2C Wire
+#endif
+#define SerialPort Serial
+
+#define LPN_PIN A3
+#define PWREN_PIN 11
+
+void print_result(VL53LMZ_ResultsData *Result);
+void clear_screen(void);
+void handle_cmd(uint8_t cmd);
+void display_commands_banner(void);
+
+// Components.
+VL53L7CH sensor_vl53l7ch_top(&DEV_I2C, LPN_PIN);
+
+bool EnableAmbient = false;
+bool EnableSignal = false;
+uint8_t res = VL53LMZ_RESOLUTION_4X4;
+char report[256];
+uint8_t status;
+
+/* Setup ---------------------------------------------------------------------*/
+void setup()
+{
+
+  // Enable PWREN pin if present
+  if (PWREN_PIN >= 0) {
+    pinMode(PWREN_PIN, OUTPUT);
+    digitalWrite(PWREN_PIN, HIGH);
+    delay(10);
+  }
+
+  // Initialize serial for output.
+  SerialPort.begin(460800);
+
+  // Initialize I2C bus.
+  DEV_I2C.begin();
+
+  // Configure VL53L7CH component.
+  sensor_vl53l7ch_top.begin();
+  status = sensor_vl53l7ch_top.init();
+
+  // Start Measurements
+  status = sensor_vl53l7ch_top.start_ranging();
+}
+
+void loop()
+{
+  VL53LMZ_ResultsData Results;
+  uint8_t NewDataReady = 0;
+
+  do {
+    status = sensor_vl53l7ch_top.check_data_ready(&NewDataReady);
+  } while (!NewDataReady);
+
+  if ((!status) && (NewDataReady != 0)) {
+    status = sensor_vl53l7ch_top.get_ranging_data(&Results);
+    print_result(&Results);
+  }
+
+  if (Serial.available() > 0) {
+    handle_cmd(Serial.read());
+  }
+  delay(100);
+}
+
+void print_result(VL53LMZ_ResultsData *Result)
+{
+  int8_t i, j, k, l;
+  uint8_t zones_per_line;
+  uint8_t number_of_zones = res;
+
+  zones_per_line = (number_of_zones == 16) ? 4 : 8;
+
+  display_commands_banner();
+
+  SerialPort.print("Cell Format :\n\n");
+
+  for (l = 0; l < VL53LMZ_NB_TARGET_PER_ZONE; l++) {
+    snprintf(report, sizeof(report), " \033[38;5;10m%20s\033[0m : %20s\n", "Distance [mm]", "Status");
+    SerialPort.print(report);
+
+    if (EnableAmbient || EnableSignal) {
+      snprintf(report, sizeof(report), " %20s : %20s\n", "Signal [kcps/spad]", "Ambient [kcps/spad]");
+      SerialPort.print(report);
+    }
+  }
+
+  SerialPort.print("\n\n");
+
+  for (j = 0; j < number_of_zones; j += zones_per_line) {
+    for (i = 0; i < zones_per_line; i++) {
+      SerialPort.print(" -----------------");
+    }
+    SerialPort.print("\n");
+
+    for (i = 0; i < zones_per_line; i++) {
+      SerialPort.print("|                 ");
+    }
+    SerialPort.print("|\n");
+
+    for (l = 0; l < VL53LMZ_NB_TARGET_PER_ZONE; l++) {
+      // Print distance and status
+      for (k = (zones_per_line - 1); k >= 0; k--) {
+        if (Result->nb_target_detected[j + k] > 0) {
+          snprintf(report, sizeof(report), "| \033[38;5;10m%5ld\033[0m  :  %5ld ",
+                   (long)Result->distance_mm[(VL53LMZ_NB_TARGET_PER_ZONE * (j + k)) + l],
+                   (long)Result->target_status[(VL53LMZ_NB_TARGET_PER_ZONE * (j + k)) + l]);
+          SerialPort.print(report);
+        } else {
+          snprintf(report, sizeof(report), "| %5s  :  %5s ", "X", "X");
+          SerialPort.print(report);
+        }
+      }
+      SerialPort.print("|\n");
+
+      if (EnableAmbient || EnableSignal) {
+        // Print Signal and Ambient
+        for (k = (zones_per_line - 1); k >= 0; k--) {
+          if (Result->nb_target_detected[j + k] > 0) {
+            if (EnableSignal) {
+              snprintf(report, sizeof(report), "| %5ld  :  ", (long)Result->signal_per_spad[(VL53LMZ_NB_TARGET_PER_ZONE * (j + k)) + l]);
+              SerialPort.print(report);
+            } else {
+              snprintf(report, sizeof(report), "| %5s  :  ", "X");
+              SerialPort.print(report);
+            }
+            if (EnableAmbient) {
+              snprintf(report, sizeof(report), "%5ld ", (long)Result->ambient_per_spad[j + k]);
+              SerialPort.print(report);
+            } else {
+              snprintf(report, sizeof(report), "%5s ", "X");
+              SerialPort.print(report);
+            }
+          } else {
+            snprintf(report, sizeof(report), "| %5s  :  %5s ", "X", "X");
+            SerialPort.print(report);
+          }
+        }
+        SerialPort.print("|\n");
+      }
+    }
+  }
+  for (i = 0; i < zones_per_line; i++) {
+    SerialPort.print(" -----------------");
+  }
+  SerialPort.print("\n");
+}
+
+void toggle_resolution(void)
+{
+  status = sensor_vl53l7ch_top.stop_ranging();
+
+  switch (res) {
+    case VL53LMZ_RESOLUTION_4X4:
+      res = VL53LMZ_RESOLUTION_8X8;
+      break;
+
+    case VL53LMZ_RESOLUTION_8X8:
+      res = VL53LMZ_RESOLUTION_4X4;
+      break;
+
+    default:
+      break;
+  }
+  status = sensor_vl53l7ch_top.set_resolution(res);
+  status = sensor_vl53l7ch_top.start_ranging();
+}
+
+void toggle_signal_and_ambient(void)
+{
+  EnableAmbient = (EnableAmbient) ? false : true;
+  EnableSignal = (EnableSignal) ? false : true;
+}
+
+void clear_screen(void)
+{
+  snprintf(report, sizeof(report), "%c[2J", 27); /* 27 is ESC command */
+  SerialPort.print(report);
+}
+
+void display_commands_banner(void)
+{
+  snprintf(report, sizeof(report), "%c[2H", 27); /* 27 is ESC command */
+  SerialPort.print(report);
+
+  Serial.print("53L7CH Simple Ranging demo application\n");
+  Serial.print("--------------------------------------\n\n");
+
+  Serial.print("Use the following keys to control application\n");
+  Serial.print(" 'r' : change resolution\n");
+  Serial.print(" 's' : enable signal and ambient\n");
+  Serial.print(" 'c' : clear screen\n");
+  Serial.print("\n");
+}
+
+void handle_cmd(uint8_t cmd)
+{
+  switch (cmd) {
+    case 'r':
+      toggle_resolution();
+      clear_screen();
+      break;
+
+    case 's':
+      toggle_signal_and_ambient();
+      clear_screen();
+      break;
+
+    case 'c':
+      clear_screen();
+      break;
+
+    default:
+      break;
+  }
+}