Merge pull request RIOT-OS#21018 from miri64/saul_bat_voltage/feat/in…

…itial

saul: initial import of saul_bat_voltage module

boards/common/particle-mesh/Makefile.dep

@@ -1,5 +1,6 @@
 ifneq (,$(filter saul_default,$(USEMODULE)))
   USEMODULE += saul_gpio
+  USEMODULE += saul_bat_voltage
   USEMODULE += saul_pwm
 endif
 

boards/common/particle-mesh/Makefile.features

@@ -1,6 +1,7 @@
 CPU_MODEL = nrf52840xxaa
 
 # Put defined MCU peripherals here (in alphabetical order)
+FEATURES_PROVIDED += board_bat_voltage
 FEATURES_PROVIDED += periph_i2c
 FEATURES_PROVIDED += periph_pwm
 FEATURES_PROVIDED += periph_spi

boards/common/particle-mesh/bat_voltage.c

@@ -0,0 +1,31 @@
+/*
+ * Copyright (C)  2024 TU Dresden
+ *
+ * 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     boards_feather-nrf52840
+ * @ingroup     saul_bat_voltage
+ * @{
+ * @file
+ * @brief       Implementation of battery voltage convert function
+ *
+ * @author      Martine S. Lenders <[email protected]>
+ *
+ * @}
+ */
+
+#ifdef MODULE_SAUL_BAT_VOLTAGE
+#include "saul/bat_voltage.h"
+
+int16_t saul_bat_voltage_convert(int32_t adc_sample)
+{
+    /* See https://community.particle.io/t/can-argon-or-xenon-read-the-battery-state/45554/6
+     * and https://docs.particle.io/assets/images/xenon/schematic-main.png */
+    return (int16_t)((adc_sample * 33L * 1403L) / 10000L);
+}
+
+#endif /* MODULE_SAUL_BAT_VOLTAGE */

boards/common/particle-mesh/include/bat_voltage_params.h

@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2024 TU Dresden
+ *
+ * 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     boards_common_particle-mesh
+ * @{
+ *
+ * @file
+ * @brief       Configuration of SAUL mapped battery voltage information
+ *
+ * @author      Martine S. Lenders <[email protected]>
+ */
+
+#ifndef BAT_VOLTAGE_PARAMS_H
+#define BAT_VOLTAGE_PARAMS_H
+
+#include "saul/bat_voltage.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief  Conversion function to convert ADC sample to battery voltage
+ *
+ * @param[in] adc_sample    The raw ADC sample.
+ *
+ * @return Voltage value for phydat.
+ */
+int16_t saul_bat_voltage_convert(int32_t adc_sample);
+
+/**
+ * @brief   Battery voltage configuration
+ */
+static const saul_bat_voltage_params_t saul_bat_voltage_params[] =
+{
+    {
+        .name = "BAT",
+        .phydat_scale = -3,
+        .line = ADC_LINE(3),
+        .res = ADC_RES_10BIT,
+        .convert = saul_bat_voltage_convert,
+    },
+};
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BAT_VOLTAGE_PARAMS_H */
+/** @} */

boards/feather-nrf52840-sense/Makefile.dep

@@ -4,6 +4,7 @@ ifneq (,$(filter saul_default,$(USEMODULE)))
   USEMODULE += lis3mdl
   USEMODULE += lsm6dsxx
   USEMODULE += saul_gpio
+  USEMODULE += saul_bat_voltage
   USEMODULE += sht3x
   USEMODULE += ws281x
 endif

boards/feather-nrf52840-sense/Makefile.features

@@ -1,6 +1,7 @@
 CPU_MODEL = nrf52840xxaa
 
 # Put defined MCU peripherals here (in alphabetical order)
+FEATURES_PROVIDED += board_bat_voltage
 FEATURES_PROVIDED += periph_i2c
 FEATURES_PROVIDED += periph_spi
 FEATURES_PROVIDED += periph_uart

boards/feather-nrf52840-sense/bat_voltage.c

@@ -0,0 +1,35 @@
+/*
+ * Copyright (C)  2024 TU Dresden
+ *
+ * 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     boards_feather-nrf52840
+ * @ingroup     saul_bat_voltage
+ * @{
+ * @file
+ * @brief       Implementation of battery voltage convert function
+ *
+ * @author      Martine S. Lenders <[email protected]>
+ *
+ * @}
+ */
+
+#ifdef MODULE_SAUL_BAT_VOLTAGE
+#include "saul/bat_voltage.h"
+
+int16_t saul_bat_voltage_convert(int32_t adc_sample)
+{
+    /* See
+     * https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/power-management-2
+     *
+     * but the reference voltage is actually 3.3V (determined empirically)...
+     * we return in millivolt so we set the reference voltage to 3300
+     * instead of 3.3 */
+    return (int16_t)((adc_sample * 2L * 3300L) / 1024L);
+}
+
+#endif /* MODULE_SAUL_BAT_VOLTAGE */

boards/feather-nrf52840-sense/include/bat_voltage_params.h

@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2024 TU Dresden
+ *
+ * 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     boards_feather-nrf52840-sense
+ * @{
+ *
+ * @file
+ * @brief       Configuration of SAUL mapped battery voltage information
+ *
+ * @author      Martine S. Lenders <[email protected]>
+ */
+
+#ifndef BAT_VOLTAGE_PARAMS_H
+#define BAT_VOLTAGE_PARAMS_H
+
+#include "saul/bat_voltage.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief  Conversion function to convert ADC sample to battery voltage
+ *
+ * @param[in] adc_sample    The raw ADC sample.
+ *
+ * @return Voltage value for phydat.
+ */
+int16_t saul_bat_voltage_convert(int32_t adc_sample);
+
+/**
+ * @brief   Battery voltage configuration
+ */
+static const saul_bat_voltage_params_t saul_bat_voltage_params[] =
+{
+    {
+        .name = "BAT",
+        .phydat_scale = -3,
+        .line = ADC_LINE(5),
+        .res = ADC_RES_10BIT,
+        .convert = saul_bat_voltage_convert,
+    },
+};
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BAT_VOLTAGE_PARAMS_H */
+/** @} */

boards/feather-nrf52840/Makefile.dep

@@ -1,5 +1,6 @@
 ifneq (,$(filter saul_default,$(USEMODULE)))
   USEMODULE += saul_gpio
+  USEMODULE += saul_bat_voltage
   USEMODULE += ws281x
 endif
 

boards/feather-nrf52840/Makefile.features

@@ -1,6 +1,7 @@
 CPU_MODEL = nrf52840xxaa
 
 # Put defined MCU peripherals here (in alphabetical order)
+FEATURES_PROVIDED += board_bat_voltage
 FEATURES_PROVIDED += periph_i2c
 FEATURES_PROVIDED += periph_spi
 FEATURES_PROVIDED += periph_uart

boards/feather-nrf52840/bat_voltage.c

@@ -0,0 +1,35 @@
+/*
+ * Copyright (C)  2024 TU Dresden
+ *
+ * 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     boards_feather-nrf52840
+ * @ingroup     saul_bat_voltage
+ * @{
+ * @file
+ * @brief       Implementation of battery voltage convert function
+ *
+ * @author      Martine S. Lenders <[email protected]>
+ *
+ * @}
+ */
+
+#ifdef MODULE_SAUL_BAT_VOLTAGE
+#include "saul/bat_voltage.h"
+
+int16_t saul_bat_voltage_convert(int32_t adc_sample)
+{
+    /* See
+     * https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/power-management-2
+     *
+     * but the reference voltage is actually 3.3V (determined empirically)...
+     * we return in millivolt so we set the reference voltage to 3300
+     * instead of 3.3 */
+    return (int16_t)((adc_sample * 2L * 3300L) / 1024L);
+}
+
+#endif /* MODULE_SAUL_BAT_VOLTAGE */

boards/feather-nrf52840/include/bat_voltage_params.h

@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2024 TU Dresden
+ *
+ * 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     boards_feather-nrf52840
+ * @{
+ *
+ * @file
+ * @brief       Configuration of SAUL mapped battery voltage information
+ *
+ * @author      Martine S. Lenders <[email protected]>
+ */
+
+#ifndef BAT_VOLTAGE_PARAMS_H
+#define BAT_VOLTAGE_PARAMS_H
+
+#include "saul/bat_voltage.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief  Conversion function to convert ADC sample to battery voltage
+ *
+ * @param[in] adc_sample    The raw ADC sample.
+ *
+ * @return Voltage value for phydat.
+ */
+int16_t saul_bat_voltage_convert(int32_t adc_sample);
+
+/**
+ * @brief   Battery voltage configuration
+ */
+static const saul_bat_voltage_params_t saul_bat_voltage_params[] =
+{
+    {
+        .name = "BAT",
+        .phydat_scale = -3,
+        .line = ADC_LINE(5),
+        .res = ADC_RES_10BIT,
+        .convert = saul_bat_voltage_convert,
+    },
+};
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BAT_VOLTAGE_PARAMS_H */
+/** @} */

boards/particle-argon/doc.txt

@@ -18,6 +18,12 @@ that provides access to multiple communication protocols: BLE, 802.15.4 and WiFi
 
 The board datasheet is available [here](https://docs.particle.io/assets/pdfs/datasheets/argon-datasheet.pdf)
 
+@experimental Support to measure the voltage via ADC using the
+`board_bat_voltage` feature (see [Feature List](@ref feature-list)) is provided
+for this board. However, it was only ever tested for the very similar
+@ref boards_particle-xenon. If you encounter any errors when measuring the
+voltage for the Particle Argon, please report this!
+
 ### Flash the board
 
 See the `Flashing` section in @ref boards_common_particle-mesh.

boards/particle-boron/doc.txt

@@ -18,6 +18,12 @@ that provides access to multiple communication protocols: BLE, 802.15.4 and LTE.
 
 The board datasheet is available [here](https://docs.particle.io/assets/pdfs/datasheets/boron-datasheet.pdf)
 
+@experimental Support to measure the voltage via ADC using the
+`board_bat_voltage` feature (see [Feature List](@ref feature-list)) is provided
+for this board. However, it was only ever tested for the very similar
+@ref boards_particle-xenon. If you encounter any errors when measuring the
+voltage for the Particle Boron, please report this!
+
 ### Flash the board
 
 See the `Flashing` section in @ref boards_common_particle-mesh.

dist/tools/features_yaml2mx/features_yaml2mx.py

@@ -103,7 +103,7 @@ def write_mdfile(outfile, yaml_path, parsed):
     :type parsed:       dict
     """
     outfile.write(f"""\
-# List of Features (Features as Build System Enties)
+# List of Features (Features as Build System Enties)            {{#feature-list}}
 <!--
 WARNING: This has been auto-generated from {yaml_path}.
          Do not edit this by hand, but update {yaml_path} instead.

drivers/Makefile.dep

@@ -264,6 +264,11 @@ ifneq (,$(filter ws281x_%,$(USEMODULE)))
   USEMODULE += ws281x
 endif
 
+ifneq (,$(filter saul_bat_voltage,$(USEMODULE)))
+  FEATURES_REQUIRED += periph_adc
+  FEATURES_REQUIRED += board_bat_voltage
+endif
+
 ifneq (,$(filter saul_adc,$(USEMODULE)))
   FEATURES_REQUIRED += periph_adc
 endif