Merge #10462

10462: drivers: add driver for ST VL6180X ranging and ambient light sensor r=benpicco a=gschorcht ### Contribution description This PR adds a driver for the ST VL6180X ranging and ambient light sensor. The driver can be used in two variants which differ in functionality and size: Module Name | Driver :-------------|:------------------------------------------- vl6180x | Driver with standard functionality and larger size vl6180x_basic | Driver with only basic functionality and smaller size Both driver variants provide - continuous ranging and ambient light sensing, - polling for new measurement results, and - SAUL capabilies. In addition to these basic functionalities, the standard driver `vl6180x` provides interrupt handling, single shot measurements, a number of configuration functions and power down / power up functionality. Features of the driver variants are summarized in the following comparison sheet. Feature | vl6180x_basic | vl6180x :---------------------------------------|:-------------:|:--------: Range measurements [mm] | X | X Ambient light measurements [Lux, raw] | X | X SAUL capability | X | X Continuous measurements | X | X Single shot measurements | | X Start and stop measurements | | X Polling for new measurement results | X | X Data-ready interrupts | | X Threshold interrupts | | X Measurement error status | | X Configuration during run-time | | X Power down and power up | | X Size on reference platform | 1.7 kByte | 3.0 kByte ### Testing procedure Using the make command ``` make flash -C tests/driver_vl6180x BOARD=... ``` the standard driver variant `vl6180x` is used with the following default configuration parameters: - periodic check of the availability of new data every 100 ms - a ranging inter-measurement period of 100 ms - a ranging maximum convergence time of 50 ms - an ambient light sensing (ALS) inter-measurement period of 500 ms - an ambient light sensing (ALS) integration time of 100 ms - an ambient light sensing (ALS) analogue light channel gain of 1.0 - an ambient light sensing period of 500 ms - a ranging period of 100 ms. To use the basic driver variant, the `vl6180x_basic` module has to be specified at make command line ``` USEMODULE=vl6180x_basic make flash -C tests/driver_vl6180x BOARD=... ``` The default configuration parameters used for the test application with the basic driver variant are the same as for the standard driver variant. To use interrupts to fetch new data instead of polling for new data periodically, the standard driver variant `vl6180x` has to be used and the pin connected with the interrupt signal GPIO1 of the sensor has to be defined by configuration paramater `VL6180X_PARAM_PIN_INT`, e.g., ``` CFLAGS="-DVL6180X_PARAM_PIN_INT=\(GPIO_PIN\(0,1\)\)" make flash -C tests/driver_vl6180x BOARD=... ``` To test the power down and power up functionality, the pin connected with the signal GPIO0/CE of the sensor has to be defined by configuration paramater `VL6180X_PARAM_PIN_SHUTDOWN `, e.g., ``` CFLAGS="-DVL6180X_PARAM_PIN_SHUTDOWN=\(GPIO_PIN\(0,2\)\)" make flash -C tests/driver_vl6180x BOARD=... ``` Co-authored-by: Gunar Schorcht <gunar@schorcht.net>
RIOT-OS · Feb 2, 2023 · b0fc3e5 · b0fc3e5
2 parents a9dbf8b + 0bee1dd
commit b0fc3e5
Show file tree

Hide file tree

Showing 18 changed files with 3,121 additions and 0 deletions.
diff --git a/drivers/Kconfig b/drivers/Kconfig
@@ -149,6 +149,7 @@ rsource "tsl2561/Kconfig"
 rsource "tsl4531x/Kconfig"
 rsource "vcnl40x0/Kconfig"
 rsource "veml6070/Kconfig"
+rsource "vl6180x/Kconfig"
 endmenu # Sensor Device Drivers
 
 menu "Storage Device Drivers"

diff --git a/drivers/Makefile.dep b/drivers/Makefile.dep
@@ -215,6 +215,10 @@ ifneq (,$(filter vcnl40%0,$(USEMODULE)))
   USEMODULE += vcnl40x0
 endif
 
+ifneq (,$(filter vl6180x_%,$(USEMODULE)))
+  USEMODULE += vl6180x
+endif
+
 ifneq (,$(filter ws281x_%,$(USEMODULE)))
   USEMODULE += ws281x
 endif

diff --git a/drivers/include/vl6180x.h b/drivers/include/vl6180x.h
diff --git a/drivers/saul/init_devs/auto_init_vl6180x.c b/drivers/saul/init_devs/auto_init_vl6180x.c
@@ -0,0 +1,78 @@
+/*
+ * Copyright (C) 2018 Gunar Schorcht
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ *
+ */
+
+/*
+ * @ingroup     drivers_vl6180x
+ * @ingroup     sys_auto_init_saul
+ * @brief       Auto initialization of ST VL6180X Ranging and Ambient Light Sensor
+ * @author      Gunar Schorcht <gunar@schorcht.net>
+ * @file
+ */
+
+#ifdef MODULE_VL6180X
+
+#include "assert.h"
+#include "log.h"
+#include "saul_reg.h"
+#include "vl6180x.h"
+#include "vl6180x_params.h"
+
+/**
+ * @brief   Define the number of configured sensors
+ */
+#define VL6180X_NUM    ARRAY_SIZE(vl6180x_params)
+
+/**
+ * @brief   Allocate memory for the device descriptors
+ */
+static vl6180x_t vl6180x_devs[VL6180X_NUM];
+
+/**
+ * @brief   Memory for the SAUL registry entries
+ */
+static saul_reg_t saul_entries[VL6180X_NUM * 2];
+
+/**
+ * @brief   Define the number of saul info
+ */
+#define VL6180X_INFO_NUM ARRAY_SIZE(vl6180x_saul_info)
+
+/**
+ * @brief   Reference the driver structs
+ */
+extern saul_driver_t vl6180x_saul_als_driver;
+extern saul_driver_t vl6180x_saul_rng_driver;
+
+void auto_init_vl6180x(void)
+{
+    assert(VL6180X_INFO_NUM == VL6180X_NUM);
+
+    for (unsigned i = 0; i < VL6180X_NUM; i++) {
+        LOG_DEBUG("[auto_init_saul] initializing vl6180x #%u\n", i);
+
+        if (vl6180x_init(&vl6180x_devs[i], &vl6180x_params[i]) != VL6180X_OK) {
+            LOG_ERROR("[auto_init_saul] error initializing vl6180x #%u\n", i);
+            continue;
+        }
+
+        saul_entries[(i * 2)].dev = &(vl6180x_devs[i]);
+        saul_entries[(i * 2)].name = vl6180x_saul_info[i].name;
+        saul_entries[(i * 2)].driver = &vl6180x_saul_als_driver;
+        saul_reg_add(&(saul_entries[(i * 2)]));
+
+        saul_entries[(i * 2) + 1].dev = &(vl6180x_devs[i]);
+        saul_entries[(i * 2) + 1].name = vl6180x_saul_info[i].name;
+        saul_entries[(i * 2) + 1].driver = &vl6180x_saul_rng_driver;
+        saul_reg_add(&(saul_entries[(i * 2) + 1]));
+    }
+}
+
+#else
+typedef int dont_be_pedantic;
+#endif /* MODULE_VL6180X */
diff --git a/drivers/saul/init_devs/init.c b/drivers/saul/init_devs/init.c
@@ -335,4 +335,8 @@ void saul_init_devs(void)
         extern void auto_init_veml6070(void);
         auto_init_veml6070();
     }
+    if (IS_USED(MODULE_VL6180X)) {
+        extern void auto_init_vl6180x(void);
+        auto_init_vl6180x();
+    }
 }
diff --git a/drivers/vl6180x/Kconfig b/drivers/vl6180x/Kconfig
@@ -0,0 +1,211 @@
+# Copyright (c) 2021 Gunar Schorcht
+#
+# This file is subject to the terms and conditions of the GNU Lesser
+# General Public License v2.1. See the file LICENSE in the top level
+# directory for more details.
+#
+
+menuconfig MODULE_VL6180X
+    bool "VL6180X Ranging and Ambient Light Sensing (ALS) module"
+    depends on TEST_KCONFIG
+    depends on HAS_PERIPH_I2C
+    select MODULE_PERIPH_I2C
+    select MODULE_ZTIMER_MSEC
+    help
+        Driver for the ST VL6180X Ranging and Ambient Light Sensing (ALS) module
+
+if MODULE_VL6180X
+
+config MODULE_VL6180X_RNG
+    bool "Ranging enabled"
+
+config VL6180X_RNG_MAX_TIME
+    int "Ranging maximum convergence time [ms]"
+    range 1 63
+    default 50
+    depends on MODULE_VL6180X_RNG
+
+config MODULE_VL6180X_ALS
+    bool "Ambient light sensing (ALS) enabled"
+
+if MODULE_VL6180X_ALS
+
+config VL6180X_ALS_INT_TIME
+    int "ALS integration time [ms]"
+    range 0 511
+    default 100
+
+choice VL6180X_ALS_GAIN
+    bool "ALS analogue light channel gain"
+    default VL6180X_ALS_GAIN_1
+
+config VL6180X_ALS_GAIN_1
+    bool "ALS gain setting 1 (actual analogue gain of 1.01)"
+config VL6180X_ALS_GAIN_1_25
+    bool "ALS gain setting 1.25 (actual analogue gain of 1.28)"
+config VL6180X_ALS_GAIN_1_67
+    bool "ALS gain setting 1.67 (actual analogue gain of 1.72)"
+config VL6180X_ALS_GAIN_2_5
+    bool "ALS gain setting 2.5 (actual analogue gain of 2.60)"
+config VL6180X_ALS_GAIN_5
+    bool "ALS gain setting 5 (actual analogue gain of 5.21)"
+config VL6180X_ALS_GAIN_10
+    bool "ALS gain setting 10 (actual analogue gain of 10.32)"
+config VL6180X_ALS_GAIN_20
+    bool "ALS gain setting 20 (actual analogue gain of 20)"
+config VL6180X_ALS_GAIN_40
+    bool "ALS gain setting 40 (actual analogue gain of 40)"
+
+endchoice
+
+config VL6180X_ALS_LUX_RES
+    int "ALS lux resolution [lux/count*1000]"
+    range 1 320
+    default 320
+    help
+        ALS lux resolution is used to convert count values from ambient
+        light sensing to lux values. It is specified as lux/count*1000.
+        The factory calibrated lux resolution is 0.32 lux/count.
+
+endif # MODULE_VL6180X_ALS
+
+config VL6180X_MEAS_PERIOD
+    int "Measurement period in continuous mode [10 ms]"
+    range 0 255
+    default 20
+    help
+        The measurement period is defined as multiple of 10 ms. It is used for
+        both range measurements and ambient light sensing (ALS) in
+        continuous mode.
+        The measurement period also controls the measurement mode used after
+        sensor initialization. If the measurement period is 0, the single-shot
+        mode is used for both the range and ALS measurements, and functions
+        vl6180x_rng_start_single and vl6180x_als_start_single have to be used
+        to start a single measurement. Otherwise the continuous mode is
+        used for both measurements which are started immediatly after sensor
+        initialization.
+
+config MODULE_VL6180X_IRQ
+    bool "Support for interrupts"
+    depends on HAS_PERIPH_GPIO_IRQ
+    select MODULE_PERIPH_GPIO_IRQ
+    help
+        Interrupts can be used either when new sensor data are ready to be
+        read or when sensor values exceed configured thresholds.
+        If interrupt handling is enabled, the interrupt signal
+        (sensor pin GPIO1) has to be connected to a MCU GPIO pin which
+        has to be defined in the board definition by VL6180X_PARAM_INT_PIN.
+
+if MODULE_VL6180X_IRQ
+
+choice
+    bool "Ranging interrupt mode"
+    depends on MODULE_VL6180X_RNG
+    default VL6180X_RNG_INT_DRDY
+    help
+        Interrupt defines the interrupt that is enabled for ranging.
+
+config VL6180X_RNG_INT_DRDY
+    bool "Data Ready"
+    help
+        Interrupt is triggered when new ranging data are ready to be read
+
+config VL6180X_RNG_INT_LOW
+    bool "Level Low"
+    help
+        Interrupt is triggered when ranging values are below lower threshold
+
+config VL6180X_RNG_INT_HIGH
+    bool "Level High"
+    help
+        Interrupt is triggered when ranging values are above upper threshold
+
+config VL6180X_RNG_INT_OUT
+    bool "Out of Window"
+    help
+        Interrupt is triggered when ranging values are below the lower
+        threshold or above the upper threshold (out of threshold window)
+
+endchoice
+
+config VL6180X_RNG_THRESH_LOW
+    int "Ranging lower threshold [mm]"
+    depends on VL6180X_RNG_INT_LOW || VL6180X_RNG_INT_OUT
+    range 0 255
+    default 20
+    help
+        Interrupt is triggered when ranging values are below this threshold
+
+config VL6180X_RNG_THRESH_HIGH
+    int "Ranging upper threshold [mm]"
+    depends on VL6180X_RNG_INT_HIGH || VL6180X_RNG_INT_OUT
+    range 0 255
+    default 90
+    help
+        Interrupt is triggered when ranging values are above this threshold
+
+choice
+    bool "ALS interrupt mode"
+    depends on MODULE_VL6180X_ALS
+    default VL6180X_ALS_INT_DRDY
+    help
+        Interrupt defines the interrupt that is enabled for ALS.
+
+config VL6180X_ALS_INT_DRDY
+    bool "Data Ready"
+    help
+        Interrupt is triggered when new ALS data are ready to be read
+
+config VL6180X_ALS_INT_LOW
+    bool "Level Low"
+    help
+        Interrupt is triggered when ALS values are below lower threshold
+
+config VL6180X_ALS_INT_HIGH
+    bool "Level High"
+    help
+        Interrupt is triggered when ALS values are above upper threshold
+
+config VL6180X_ALS_INT_OUT
+    bool "Out of Window"
+    help
+        Interrupt is triggered when ALS values are below the lower
+        threshold or above the upper threshold (out of threshold window)
+
+endchoice
+
+config VL6180X_ALS_THRESH_LOW
+    int "ALS lower threshold [counts]"
+    depends on VL6180X_ALS_INT_LOW || VL6180X_ALS_INT_OUT
+    range 0 65535
+    default 50
+    help
+        Interrupt is triggered when ALS values are below this threshold
+
+config VL6180X_ALS_THRESH_HIGH
+    int "ALS upper threshold [counts]"
+    depends on VL6180X_ALS_INT_HIGH || VL6180X_ALS_INT_OUT
+    range 0 65535
+    default 2000
+    help
+        Interrupt is triggered when ALS values are above this threshold
+
+endif # MODULE_VL6180X_IRQ
+
+config MODULE_VL6180X_SHUTDOWN
+    bool "Support for power-down and power-up"
+    depends on HAS_PERIPH_GPIO
+    select MODULE_PERIPH_GPIO
+    help
+        Enable the power-down and power-up functions. If power-down and
+        power-up functions are enabled by module, the shutdown signal
+        (sensor pin GPIO0/CE) has to be connected to a MCU GPIO pin which
+        has to be defined in the board definition by VL6180X_PARAM_SHUTDOWN_PIN.
+
+config MODULE_VL6180X_CONFIG
+    bool "Configuration of the sensor at runtime"
+    help
+        Enables the functions that can be used to reconfigure the sensor at
+        runtime.
+
+endif # MODULE_VL6180X
diff --git a/drivers/vl6180x/Makefile b/drivers/vl6180x/Makefile
@@ -0,0 +1 @@
+include $(RIOTBASE)/Makefile.base
diff --git a/drivers/vl6180x/Makefile.dep b/drivers/vl6180x/Makefile.dep
@@ -0,0 +1,17 @@
+ifneq (,$(filter vl6180x_irq_%,$(USEMODULE)))
+  USEMODULE += vl6180x_irq
+endif
+
+ifneq (,$(filter vl6180x,$(USEMODULE)))
+  FEATURES_REQUIRED += periph_i2c
+  USEMODULE += ztimer_msec
+endif
+
+ifneq (,$(filter vl6180x_shutdown,$(USEMODULE)))
+  FEATURES_REQUIRED += periph_gpio
+endif
+
+ifneq (,$(filter vl6180x_irq,$(USEMODULE)))
+  FEATURES_REQUIRED += periph_gpio
+  FEATURES_REQUIRED += periph_gpio_irq
+endif
diff --git a/drivers/vl6180x/Makefile.include b/drivers/vl6180x/Makefile.include
@@ -0,0 +1,9 @@
+# include variants of VL6180x drivers as pseudomodules
+PSEUDOMODULES += vl6180x_rng
+PSEUDOMODULES += vl6180x_als
+PSEUDOMODULES += vl6180x_irq
+PSEUDOMODULES += vl6180x_shutdown
+PSEUDOMODULES += vl6180x_config
+
+USEMODULE_INCLUDES_vl6180x:= $(LAST_MAKEFILEDIR)/include
+USEMODULE_INCLUDES += $(USEMODULE_INCLUDES_vl6180x)