Restructure and add examples

Author: alex-mous

.gitignore

@@ -1,3 +1 @@
-build/*
-tmp/*
-external/*
+examples/build/*

CMakeLists.txt

@@ -13,22 +13,22 @@ Please see [CONTRIBUTING.md](CONTRIBUTING.md)
 ## Future Features
 - C++ object-oriented library
 - Easy way to configure defaults passed into initialization functions
-
-
-# Usage
-To use this library in your own project, include the `VL53L1X_pico_api` directory in your CMake script (e.g. `add_subdirectory(VL53L1X_pico_api)`). Then, include the needed headers as specified below, and add `VL53L1X_pico_api` to the `target_link_libraries` for your project. Running `cmake` for your project should then include and compile this API as needed.
+- Thread worker
 
 # Examples
-To build the project, first clone the code and then run the following:
+To build the examples for the project, first clone the code and then run the following:
 ```
+cd examples
 mkdir build
 cd build
 cmake ..
 make
 ```
 Note: if you have a Pico W, append `-DPICO_BOARD=pico_w` to the `cmake` command.
 
-This will build the example code. The resulting uf2 file in the `build/examples/continuous_measurement` can be uploaded to a Pico/Pico W. This example shows how to initialize and use the VL53L1X sensor to continously measure. The sensor must be attached to the following pins:
+This will build the example code. Either of th resulting `uf2` files in `build/examples/continuous_measurement` and  `build/examples/sampling` can be uploaded to a Pico/Pico W. The former will continously print the sensor reading to stdout (over USB), whereas the second only prints samples when input is recieved from stdin (also over USB). To use these, leave your Pico connected to your computer after uploading the `uf2` file, and open a USB serial connection to it (for example, using Putty on Windows or native tools on UNIX-based systems).
+
+For the examples to work correctly, the sensor must be attached to the following pins:
 
 | VL53L1X |  Pico |
 | ------ | ----- |
@@ -39,6 +39,34 @@ This will build the example code. The resulting uf2 file in the `build/examples/
 | SDA | GPIO5 |
 | XSHUT | Unconnected (Used to reset device)|
 
+# Installation
+To use/install this library in your own project, acquire a copy of this repo in your project (such as using `git submodule`), and then make the following modifications to your project's `CMakeLists.txt`:
+
+If your project structure is something like this:
+``` root/ (for your project)
+     yourapp.h
+     yourapp.c
+     CMakeLists.txt
+     build/
+         ...
+     VL53L1X-C-API-Pico/
+         library/
+             import.cmake
+             ...
+         ...
+```
+Then, add this line to your `CMakeLists.txt` file before defining/linking your executables (e.g. building `yourapp`):
+ ```
+ include(${PROJECT_SOURCE_DIR}/VL53L1X-C-API-Pico/library/import.cmake)
+ ```
+
+Then, to link `<your executable>` with libraries you already have (`<your libraries>`) and this VL53L1X library, change the `target_link_libraries` line for `<your executable>` as follows:
+```
+target_link_libraries(<your executable> PUBLIC pico_stdlib hardware_i2c VL53L1X_pico_api <your libraries> )
+```
+
+Running `cmake` for your project will now include and compile this API.
+
 # Documentation
 The header files all have extensive documentation on the purpose of each function, which can be supplemented by the *STMicroelectronics VL53L1X Ultra Lite Driver User Manual (UM2510)*.
 

README.md

@@ -1,3 +1,32 @@
+# Use this CMake file to compile the examples
+# This file can also serve as a template for how
+# to use the library in your own code. Note that
+# more details on how to use the library are
+# specified in library/import.cmake.
+
+cmake_minimum_required(VERSION 3.25)
+
+# Pull in SDK by downloading the pico_sdk_import
+set(PICO_SDK_IMPORT ${BINARY_DIR}/external/pico_sdk_import.cmake)
+if (NOT EXISTS ${PICO_SDK_IMPORT})
+        file(DOWNLOAD
+                https://raw.githubusercontent.com/raspberrypi/pico-sdk/2e6142b15b8a75c1227dd3edbe839193b2bf9041/external/pico_sdk_import.cmake
+                ${PICO_SDK_IMPORT}
+                )
+endif()
+include(${PICO_SDK_IMPORT})
+
+# Create project and set basic info
+project(VL53L1X_api
+        DESCRIPTION "VL53L1X Raspberry Pi Pico/Pico W examples")
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+add_compile_options(-Wall)
+pico_sdk_init()
+
+# Pull in the API
+include(${PROJECT_SOURCE_DIR}/../library/import.cmake)
+
 # Define flag for Pico W
 if(${PICO_BOARD} STREQUAL pico_w)
     add_compile_definitions(PICO_W_BOARD)
@@ -6,4 +35,5 @@ else()
     message("Compiling examples for Pico")
 endif()
 
-add_subdirectory(continuous_measurement)
+add_subdirectory(continuous_measurement)
+add_subdirectory(sampling)

VL53L1X_pico_api/CMakeLists.txt

@@ -1,7 +1,7 @@
 add_executable(continuous continuous.c)
 
 # Link to pico libraries as well as the VL53L1X_pico_api
-target_link_libraries(continuous PUBLIC VL53L1X_pico_api pico_stdlib)
+target_link_libraries(continuous PUBLIC pico_stdlib hardware_i2c VL53L1X_pico_api)
 
 # Add needed library if Pico W
 if(${PICO_BOARD} STREQUAL pico_w)

examples/CMakeLists.txt

@@ -1,14 +1,42 @@
+/*
+* Example usage of the VL53L1X Pico Library for Pico/Pico W
+*
+* This program will continously print out packets read from the VL53L1X sensor
+* to USB (to read them, leave the Pico/Pico W connected to your computer via USB
+* and then open a serial connection to the corresponding port with baudrate 115200).
+*/
+
+/*
+* Copyright 2022, Alex Mous
+*
+* Permission is hereby granted, free of charge, to any person obtaining a
+* copy of this software and associated documentation files (the "Software"),
+* to deal in the Software without restriction, including without limitation
+* the rights to use, copy, modify, merge, publish, distribute, sublicense,
+* and/or sell copies of the Software, and to permit persons to whom the
+* Software is furnished to do so, subject to the following conditions:
+*
+* The above copyright notice and this permission notice shall be included in
+* all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+* DEALINGS IN THE SOFTWARE.*/
+
+#include <stdio.h>
+#include <stdint.h>
+
 #include "pico/stdlib.h"
 #include "pico/binary_info.h"
-#include "hardware/i2c.h"
 
 #ifdef PICO_W_BOARD
 #include "pico/cyw43_arch.h"
 #endif
 
-#include <stdio.h>
-#include <stdint.h>
-
 #include "VL53L1X_api.h"
 #include "VL53L1X_types.h"
 
@@ -20,6 +48,7 @@ int main() {
 
     stdio_init_all();
 
+    // Blink the onboard LED to show booting
 #if PICO_W_BOARD
     if (cyw43_arch_init()) {
         printf("Failed to initialize Pico W.\n");

examples/continuous_measurement/CMakeLists.txt

@@ -0,0 +1,13 @@
+add_executable(sampling sampling.c)
+
+# Link to pico libraries as well as the VL53L1X_pico_api
+target_link_libraries(sampling PUBLIC pico_stdlib hardware_i2c VL53L1X_pico_api)
+
+# Add needed library if Pico W
+if(${PICO_BOARD} STREQUAL pico_w)
+    target_link_libraries(sampling PUBLIC pico_cyw43_arch_none)
+endif()
+
+# Generate executable, enabling STDIO over USB
+pico_add_extra_outputs(sampling)
+pico_enable_stdio_usb(sampling 1)

examples/continuous_measurement/continuous.c

@@ -0,0 +1,125 @@
+/*
+* Example usage of the VL53L1X Pico Library for Pico/Pico W
+*
+* This program will measure the VL53L1X sensor and print the result
+* every time a value is recieved from STDIN (e.g. over USB).
+*/
+
+/*
+* Copyright 2022, Alex Mous
+*
+* Permission is hereby granted, free of charge, to any person obtaining a
+* copy of this software and associated documentation files (the "Software"),
+* to deal in the Software without restriction, including without limitation
+* the rights to use, copy, modify, merge, publish, distribute, sublicense,
+* and/or sell copies of the Software, and to permit persons to whom the
+* Software is furnished to do so, subject to the following conditions:
+*
+* The above copyright notice and this permission notice shall be included in
+* all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+* DEALINGS IN THE SOFTWARE.*/
+
+#include <stdio.h>
+#include <stdint.h>
+
+#include "pico/stdlib.h"
+#include "pico/binary_info.h"
+
+#ifdef PICO_W_BOARD
+#include "pico/cyw43_arch.h"
+#endif
+
+#include "VL53L1X_api.h"
+#include "VL53L1X_types.h"
+
+
+int main() {
+	VL53L1X_Status_t status;
+	VL53L1X_Result_t results;
+    uint8_t I2CDevAddr = 0x29;
+
+    stdio_init_all();
+
+    // Blink the onboard LED to show booting
+#if PICO_W_BOARD
+    if (cyw43_arch_init()) {
+        printf("Failed to initialize Pico W.\n");
+        return 1;
+    }
+#else
+    gpio_init(PICO_DEFAULT_LED_PIN);
+    gpio_set_dir(PICO_DEFAULT_LED_PIN, GPIO_OUT);
+#endif
+
+    for (int i=0; i<10; i++) {
+#ifdef PICO_W_BOARD
+        cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, 1);
+#else
+        gpio_put(PICO_DEFAULT_LED_PIN, 1);
+#endif
+
+        sleep_ms(250);
+
+#ifdef PICO_W_BOARD
+        cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, 0);
+#else
+        gpio_put(PICO_DEFAULT_LED_PIN, 0);
+#endif
+
+        sleep_ms(250);
+    }
+
+    // Initialize Pico's I2C using PICO_DEFAULT_I2C_SDA_PIN 
+    // and PICO_DEFAULT_I2C_SCL_PIN (GPIO 4 and GPIO 5, respectively)
+    if (VL53L1X_I2C_Init(I2CDevAddr, i2c0) < 0) {
+        printf("Error initializing sensor.\n");
+        return 0;
+    }
+
+    // Ensure the sensor has booted
+    uint8_t sensorState;
+    do {
+		status += VL53L1X_BootState(I2CDevAddr, &sensorState);
+		VL53L1X_WaitMs(I2CDevAddr, 2);
+	} while (sensorState == 0);
+	printf("Sensor booted.\n");
+
+    // Initialize and configure sensor
+	status = VL53L1X_SensorInit(I2CDevAddr);
+	status += VL53L1X_SetDistanceMode(I2CDevAddr, 1);
+	status += VL53L1X_SetTimingBudgetInMs(I2CDevAddr, 100);
+	status += VL53L1X_SetInterMeasurementInMs(I2CDevAddr, 100);
+	status += VL53L1X_StartRanging(I2CDevAddr);
+
+    // Measure and print when value from stdin received
+	bool first_range = true;
+	while (1) {
+        // Read from stdin (blocking)
+        getc(stdin);
+        // Wait until we have new data
+		uint8_t dataReady;
+		do {
+			status = VL53L1X_CheckForDataReady(I2CDevAddr, &dataReady);
+			sleep_us(1);
+		} while (dataReady == 0);
+
+        // Read and display result
+		status += VL53L1X_GetResult(I2CDevAddr, &results);
+		printf("Status = %2d, dist = %5d, Ambient = %2d, Signal = %5d, #ofSpads = %5d\n",
+			results.status, results.distance, results.ambient, results.sigPerSPAD, results.numSPADs);
+
+        // Clear the sensor for a new measurement
+		status += VL53L1X_ClearInterrupt(I2CDevAddr);
+		if (first_range) {  // Clear twice on first measurement
+			status += VL53L1X_ClearInterrupt(I2CDevAddr);
+			first_range = false;
+		}
+	}
+}