drivers/sen5x: Add device driver for SEN5x

drivers/Kconfig

@@ -131,6 +131,7 @@ rsource "sdp3x/Kconfig"
 rsource "sgp30/Kconfig"
 rsource "sds011/Kconfig"
 rsource "seesaw_soil/Kconfig"
+rsource "sen5x/Kconfig"
 rsource "sht1x/Kconfig"
 rsource "sht2x/Kconfig"
 rsource "sht3x/Kconfig"

drivers/Makefile.dep

@@ -176,6 +176,10 @@ ifneq (,$(filter sdp3x_%,$(USEMODULE)))
   USEMODULE += sdp3x
 endif
 
+ifneq (,$(filter sen5%,$(USEMODULE)))
+  USEMODULE += sen5x
+endif
+
 ifneq (,$(filter servo_%,$(USEMODULE)))
   USEMODULE += servo
 endif

drivers/include/sen5x.h

@@ -0,0 +1,306 @@
+/*
+ * Copyright (C) 2023 TU Braunschweig Institut für Betriebssysteme und Rechnerverbund
+ *
+ * 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.
+ */
+
+/**
+ * @defgroup    drivers_sen5x Sensirion Embedded I2C SEN5x Driver
+ * @ingroup     drivers_sensors
+ * @ingroup     drivers_saul
+ * @brief       Driver for I2C communication to SEN5x devices.
+ *
+ * @{
+ *
+ * @file
+ *
+ * @author      Daniel Prigoshij <[email protected]>
+ */
+
+#ifndef SEN5X_H
+#define SEN5X_H
+
+/* Add header includes here */
+
+#include "periph/i2c.h"
+#include <stdint.h>
+#include "saul.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Declare the API of the driver */
+
+/**
+ * @brief   Wrapper for measured values
+ */
+typedef struct {
+    uint16_t mass_concentration_pm1p0;      /** raw value is scaled with factor 10: PM1.0 [µg/m³] = value / 10 */
+    uint16_t mass_concentration_pm2p5;      /** raw value is scaled with factor 10: PM2.5 [µg/m³] = value / 10 */
+    uint16_t mass_concentration_pm4p0;      /** raw value is scaled with factor 10: PM4.0 [µg/m³] = value / 10 */
+    uint16_t mass_concentration_pm10p0;     /** raw value is scaled with factor 10: PM10.0 [µg/m³] = value / 10 */
+    uint16_t number_concentration_pm0p5;    /** raw value is scaled with factor 10: PM0.5 [#/cm³] = value / 10 */
+    uint16_t number_concentration_pm1p0;    /** raw value is scaled with factor 10: PM1.0 [#/cm³] = value / 10 */
+    uint16_t number_concentration_pm2p5;    /** raw value is scaled with factor 10: PM2.5 [#/cm³] = value / 10 */
+    uint16_t number_concentration_pm4p0;    /** raw value is scaled with factor 10: PM4.0 [#/cm³] = value / 10 */
+    uint16_t number_concentration_pm10p0;   /** raw value is scaled with factor 10: PM10.0 [#/cm³] = value / 10 */
+    uint16_t typical_particle_size;         /** raw value is scaled with factor 1000: Size [µm] = value / 1000*/
+    int16_t ambient_humidity;               /** raw value is scaled with factor 100: RH [%] = value / 100 */
+    int16_t ambient_temperature;            /** raw value is scaled with factor 200: T [°C] = value / 200 */
+    int16_t voc_index;                      /** raw value is scaled with factor 10: VOC Index = value / 10 */
+    int16_t nox_index;                      /** raw value is scaled with factor 10: NOx Index = value / 10 */
+} sen5x_measurement_t;
+
+/**
+ * @brief   Device initialization parameters
+ */
+typedef struct {
+    i2c_t i2c_dev;                  /**< I2C device which is used */
+    uint8_t i2c_addr;               /**< I2C address */
+} sen5x_params_t;
+
+/**
+ * @brief   Device descriptor for the driver
+ */
+typedef struct {
+    sen5x_params_t params;                  /**< Device initialization parameters */
+} sen5x_t;
+
+/**
+ * @brief   Initialize the given device
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * @param[in]    params     Initialization parameters
+ * 
+ * @return 0 on success
+ * @return < 0 on error
+ */
+int sen5x_init(sen5x_t *dev, const sen5x_params_t *params);
+
+/**
+ * @brief   Execute a reset on the given device
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * 
+ * @return 0 on success
+ * @return < 0 on error
+ */
+int sen5x_reset(const sen5x_t *dev);
+
+/**
+ * @brief   Starts a continuous measurement
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ */
+void sen5x_wake(const sen5x_t *dev);
+
+/**
+ * @brief   Starts a continuous measurement without PM. Only humidity, temperature, VOC and NOx are measured.
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ */
+void sen5x_wake_no_pm(const sen5x_t *dev);
+
+/**
+ * @brief   Stops the measurement and returns to idle mode
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ */
+void sen5x_sleep(const sen5x_t *dev);
+
+/**
+ * @brief   Sets the fan to maximum speed, to clean it within 10 seconds
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ */
+void sen5x_clean_fan(const sen5x_t *dev);
+
+/**
+ * @brief   Sets the fan to maximum speed, to clean it within 10 seconds
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * 
+ * @return 0 if no new measurements are available
+ * @return 1 if new measuremtns are ready to be read
+ */
+bool sen5x_data_ready_flag(const sen5x_t *dev);
+
+/**
+ * @brief   Read measured mass concentration, humidity and temperature values
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * @param[out]   values     Pointer to wrapper containing all measured values
+ */
+void sen5x_read_values(const sen5x_t *dev, sen5x_measurement_t *values);
+
+/**
+ * @brief   Read measured particle matter values
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * @param[out]   values     Pointer to wrapper containing all measured values
+ */
+void sen5x_read_pm_values(const sen5x_t *dev, sen5x_measurement_t *values);
+
+/**
+ * @brief   Set a custom temperature offset to the ambient temperature
+ *
+ * @param[inout] dev            Device descriptor of the driver
+ * @param[in]    temp_offset    Temperature offset in °C
+ * @param[in]    slope          Normalized temperature offset slope
+ * @param[in]    time_constant  Time constant in seconds
+ */
+void sen5x_set_temperature_offset(const sen5x_t *dev, int16_t temp_offset, int16_t slope, uint16_t time_constant);
+
+/**
+ * @brief   Set a custom temperature offset to the ambient temperature
+ *
+ * @param[inout]  dev            Device descriptor of the driver
+ * @param[out]    temp_offset    Temperature offset in °C
+ * @param[out]    slope          Normalized temperature offset slope
+ * @param[out]    time_constant  Time constant in seconds
+ */
+void sen5x_get_temperature_offset(const sen5x_t *dev, int16_t *temp_offset, int16_t *slope, uint16_t *time_constant);
+
+/**
+ * @brief   Set the parameter for a warm start on the device, to improve initial accuracy of the ambient temperature output
+ *
+ * @param[inout] dev            Device descriptor of the driver
+ * @param[in]    warm_start     Warm start behavior as a value in the range from
+ *                              0 (cold start, default) to 65535 (warm start).
+ */
+void sen5x_set_warm_start(const sen5x_t *dev, uint16_t warm_start);
+
+/**
+ * @brief   Get the warm start paramater
+ *
+ * @param[inout] dev            Device descriptor of the driver
+ * @param[out]   warm_start     Warm start behavior as a value in the range from
+ *                              0 (cold start, default) to 65535 (warm start).
+ */
+void sen5x_get_warm_start(const sen5x_t *dev, uint16_t *warm_start);
+
+/**
+ * @brief   Set the parameters for the VOC Algorithm tuning
+ *
+ * @param[inout] dev                            Device descriptor of the driver
+ * @param[in]    index_offset                   VOC index representing typical (average) conditions
+ * @param[in]    learning_time_offset_hours     Time constant to estimate the VOC algorithm offset from the
+ *                                              history in hours
+ * @param[in]    learning_time_gain_hours       Time constant to estimate the VOC algorithm gain from the history
+ *                                              in hours
+ * @param[in]    gating_max_duration_minutes    Maximum duration of gating in minutes
+ * @param[in]    std_initial                    Initial estimate for standard deviation
+ * @param[in]    gain_factor                    Gain factor to amplify or to attenuate the VOC index output
+ */
+void sen5x_set_voc_algorithm_tuning(
+    const sen5x_t *dev, int16_t index_offset, int16_t learning_time_offset_hours,
+    int16_t learning_time_gain_hours, int16_t gating_max_duration_minutes,
+    int16_t std_initial, int16_t gain_factor);
+
+/**
+ * @brief   Get the VOC Algortihm tuning parameters
+ *
+ * @param[inout] dev                             Device descriptor of the driver
+ * @param[out]    index_offset                   VOC index representing typical (average) conditions
+ * @param[out]    learning_time_offset_hours     Time constant to estimate the VOC algorithm offset from the
+ *                                               history in hours
+ * @param[out]    learning_time_gain_hours       Time constant to estimate the VOC algorithm gain from the history
+ *                                               in hours
+ * @param[out]    gating_max_duration_minutes    Maximum duration of gating in minutes
+ * @param[out]    std_initial                    Initial estimate for standard deviation
+ * @param[out]    gain_factor                    Gain factor to amplify or to attenuate the VOC index output
+ */
+void sen5x_get_voc_algorithm_tuning(
+    const sen5x_t *dev, int16_t *index_offset, int16_t *learning_time_offset_hours,
+    int16_t *learning_time_gain_hours, int16_t *gating_max_duration_minutes,
+    int16_t *std_initial, int16_t *gain_factor);
+
+/**
+ * @brief   Set the parameters for the NOx Algorithm tuning
+ *
+ * @param[inout] dev                            Device descriptor of the driver
+ * @param[in]    index_offset                   NOx index representing typical (average) conditions
+ * @param[in]    learning_time_offset_hours     Time constant to estimate the NOx algorithm offset from the
+ *                                              history in hours
+ * @param[in]    learning_time_gain_hours       The time constant to estimate the NOx algorithm gain from the
+ *                                              history has no impact for NOx. This parameter is still in place for
+ *                                              consistency reasons with the VOC tuning parameters command.
+ *                                              This parameter must always be set to 12 hours
+ * @param[in]    gating_max_duration_minutes    Maximum duration of gating in minutes
+ * @param[in]    std_initial                    Initial estimate for standard deviation
+ * @param[in]    gain_factor                    Gain factor to amplify or to attenuate the NOx index output
+ */
+void sen5x_set_nox_algorithm_tuning(
+    const sen5x_t *dev, int16_t index_offset, int16_t learning_time_offset_hours,
+    int16_t learning_time_gain_hours, int16_t gating_max_duration_minutes,
+    int16_t std_initial, int16_t gain_factor);
+
+/**
+ * @brief   Get the NOx Algortihm tuning parameters
+ * 
+ * @param[inout]  dev                            Device descriptor of the driver
+ * @param[out]    index_offset                   NOx index representing typical (average) conditions
+ * @param[out]    learning_time_offset_hours     Time constant to estimate the NOx algorithm offset from the
+ *                                               history in hours
+ * @param[out]    learning_time_gain_hours       The time constant to estimate the NOx algorithm gain from the
+ *                                               history has no impact for NOx. This parameter is still in place for
+ *                                               consistency reasons with the VOC tuning parameters command.
+ *                                               This parameter must always be set to 12 hours
+ * @param[out]    gating_max_duration_minutes    Maximum duration of gating in minutes
+ * @param[out]    std_initial                    Initial estimate for standard deviation
+ * @param[out]    gain_factor                    Gain factor to amplify or to attenuate the NOx index output
+ */
+void sen5x_get_nox_algorithm_tuning(
+    const sen5x_t *dev, int16_t *index_offset, int16_t *learning_time_offset_hours,
+    int16_t *learning_time_gain_hours, int16_t *gating_max_duration_minutes,
+    int16_t *std_initial, int16_t *gain_factor);
+
+/**
+ * @brief   Set the mode for the RH/T acceleration algorithm
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * @param[in]    mode       RH/T accelaration mode:
+ *                              = 0: Low Acceleration
+ *                              = 1: High Acceleration
+ *                              = 2: Medium Acceleration
+ */
+void sen5x_set_rht_acceleration(const sen5x_t *dev, uint16_t mode);
+
+/**
+ * @brief   Get the mode for the RH/T acceleration algorithm
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * @param[out]   mode       RH/T accelaration mode:
+ *                              = 0: Low Acceleration
+ *                              = 1: High Acceleration
+ *                              = 2: Medium Acceleration
+ */
+void sen5x_get_rht_acceleration(const sen5x_t *dev, uint16_t *mode);
+
+/**
+ * @brief   Get the VOC Algorithm state
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * @param[in]    state      VOC Algorithm state
+ * @param[in]    state_size Size of the VOC Algorithm state
+ */
+void sen5x_set_voc_state(const sen5x_t *dev, const uint8_t *state, uint8_t state_size);
+
+/**
+ * @brief   Set the VOC Algorithm state
+ *
+ * @param[inout] dev        Device descriptor of the driver
+ * @param[out]   state      VOC Algorithm state
+ * @param[in]    state_size Size of the VOC Algorithm state
+ */
+void sen5x_get_voc_state(const sen5x_t *dev, uint8_t *state, uint8_t state_size);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* SEN5X_H */
+/** @} */