Average value computation can be disabled now
This commit is contained in:
Gunar Schorcht
GitHub
parent
88bf000942
commit
c719d73139
3 changed files with 239 additions and 89 deletions
|
|
@ -1,12 +1,43 @@
|
|||
/*
|
||||
* The BSD License (3-clause license)
|
||||
*
|
||||
* Copyright (c) 2017 Gunar Schorcht (https://github.com/gschorcht
|
||||
* All rights reserved.
|
||||
*
|
||||
* 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 the copyright holder 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.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Driver for Sensirion SHT3x digital temperature and humity sensor
|
||||
* connected to I2C
|
||||
*
|
||||
* Part of esp-open-rtos
|
||||
* Copyright (C) 2017 Gunar Schorcht (https://github.com/gschorcht)
|
||||
* BSD Licensed as described in the file LICENSE
|
||||
*/
|
||||
|
||||
|
||||
#ifndef DRIVER_SHT3x_H_
|
||||
#define DRIVER_SHT3x_H_
|
||||
|
||||
|
|
@ -28,21 +59,28 @@
|
|||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief actual or average value set type
|
||||
*/
|
||||
typedef struct {
|
||||
float temperature_c; // temperature in degree Fahrenheit
|
||||
float temperature_f; // temperature in degree Celcius
|
||||
float humidity; // humidity in percent
|
||||
} sht3x_value_set_t;
|
||||
|
||||
/**
|
||||
* @brief callback unction type to pass result of measurement to user tasks
|
||||
*/
|
||||
typedef void (*sht3x_cb_function_t)(uint32_t sensor,
|
||||
sht3x_value_set_t actual,
|
||||
sht3x_value_set_t average);
|
||||
|
||||
// SHT3x sensor data structure
|
||||
/**
|
||||
* @brief SHT3x sensor device data structure type
|
||||
*/
|
||||
typedef struct {
|
||||
|
||||
bool active;
|
||||
bool first_measurement;
|
||||
|
||||
uint8_t bus;
|
||||
uint8_t addr;
|
||||
|
|
@ -52,6 +90,8 @@ typedef struct {
|
|||
sht3x_value_set_t actual;
|
||||
sht3x_value_set_t average;
|
||||
|
||||
bool average_computation;
|
||||
bool average_first_measurement;
|
||||
float average_weight;
|
||||
|
||||
sht3x_cb_function_t cb_function;
|
||||
|
|
@ -61,8 +101,10 @@ typedef struct {
|
|||
|
||||
|
||||
/**
|
||||
* Initialize the SHT3x driver. This function must be called only once at the
|
||||
* beginning.
|
||||
* @brief Initialize the SHT3x driver
|
||||
*
|
||||
* This function initializes all internal data structures. It must be called
|
||||
* exactly once at the beginning.
|
||||
*
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
|
|
@ -70,39 +112,50 @@ bool sht3x_init ();
|
|||
|
||||
|
||||
/**
|
||||
* Initialize the SHT3x sensor connected to a certain bus with slave
|
||||
* address, check its availability and start a background task for
|
||||
* measurements.
|
||||
* @brief Initialize a SHT3x sensor
|
||||
*
|
||||
* The background task carries out measurements periodically using SHT3x's
|
||||
* single shot data acquisition mode with a default period of 1000 ms.
|
||||
* This period be changed using function @set_measurment_period.
|
||||
*
|
||||
* At each measurement, actual sensor values are determined and exponential
|
||||
* moving average values are computed. The weight (smoothing factor) for this
|
||||
* average computation is 0.2 by default. It can be changed using function
|
||||
* @sht3x_set_average_weight.
|
||||
* This function initializes the SHT3x sensor connected to a certain
|
||||
* bus with given slave address and checks its availability.
|
||||
*
|
||||
* If a callback method is registered using function
|
||||
* @sht3x_set_callback_function, it is called after each measurement to pass
|
||||
* measurement results to user tasks. Otherwise, user tasks have to use
|
||||
* function @sht3x_get_values explicitly to get the results.
|
||||
* Furthermore, it starts a background task for measurements with
|
||||
* the sensor. The background task carries out the measurements periodically
|
||||
* using SHT3x's single shot data acquisition mode with a default period
|
||||
* of 1000 ms. This period be changed using function *set_measurment_period*.
|
||||
*
|
||||
* During each measurement the background task
|
||||
*
|
||||
* 1. determines *actual sensor values*
|
||||
* 2. computes optionally *average sensor values*
|
||||
* 3. calls back optionally a registered function of user task.
|
||||
*
|
||||
* The average value computation uses an exponential moving average
|
||||
* and can be activated (default) or deactivated with function
|
||||
* *sht3x_enable_average_computation*. If the average value computation is
|
||||
* deactivated, *average sensor values* correspond to *actual sensor values*.
|
||||
* The weight (smoothing factor) used in the average value computatoin is 0.2
|
||||
* by default and can be changed with function *sht3x_set_average_weight*.
|
||||
*
|
||||
* If a callback method has been registered with function
|
||||
* *sht3x_set_callback_function*, it is called after each measurement
|
||||
* to pass measurement results to user tasks. Otherwise, user tasks have to
|
||||
* use function *sht3x_get_values* explicitly to get the results.
|
||||
*
|
||||
* @param bus I2C bus at which SHT3x sensor is connected
|
||||
* @param addr I2C addr of the SHT3x sensor
|
||||
*
|
||||
* @return id of the sensor (0 or greater on success or -1 on error)
|
||||
* @return ID of the sensor (0 or greater on success or -1 on error)
|
||||
*/
|
||||
uint32_t sht3x_create_sensor (uint8_t bus, uint8_t addr);
|
||||
|
||||
|
||||
/**
|
||||
* Set the period of the background measurement task for a certain sensor.
|
||||
* @brief Set the period of the background measurement task for the given
|
||||
* sensor
|
||||
*
|
||||
* Please note the minimum period is 20 ms since the measurement takes
|
||||
* Please note: The minimum period is 20 ms since each measurement takes
|
||||
* about 20 ms.
|
||||
*
|
||||
* @param sensor id of the sensor
|
||||
* @param sensor ID of the sensor
|
||||
* @param period Measurement period in ms (default 1000 ms)
|
||||
*
|
||||
* @return true on success, false on error
|
||||
|
|
@ -111,14 +164,14 @@ bool sht3x_set_measurement_period (uint32_t sensor, uint32_t period);
|
|||
|
||||
|
||||
/**
|
||||
* Set the callback function for the background measurement task for a certain
|
||||
* sensor.
|
||||
* @brief Set the callback function for the background measurement task for
|
||||
* the given sensor
|
||||
*
|
||||
* If a callback method is registered, it is called after each measurement to
|
||||
* pass measurement results to user tasks. Thus, callback function is executed
|
||||
* at the same rate as measurements.
|
||||
* at the same rate as the measurements.
|
||||
*
|
||||
* @param sensor id of the sensor
|
||||
* @param sensor ID of the sensor
|
||||
* @param function user function called after each measurement
|
||||
* (NULL to delete it for the sensor)
|
||||
*
|
||||
|
|
@ -129,9 +182,9 @@ bool sht3x_set_callback_function (uint32_t sensor,
|
|||
|
||||
|
||||
/**
|
||||
* Deletes the SHT3x sensor given by its id.
|
||||
* @brief Deletes the SHT3x sensor given by its ID
|
||||
*
|
||||
* @param sensor id of the sensor
|
||||
* @param sensor ID of the sensor
|
||||
*
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
|
|
@ -139,17 +192,23 @@ bool sht3x_delete_sensor (uint32_t sensor);
|
|||
|
||||
|
||||
/**
|
||||
* Returns actual and average sensor values of last measurement. Parameters
|
||||
* @actual and @average are pointer to data structures of type
|
||||
* @sht3x_value_set_t which are filled with measurement results. Use NULL for
|
||||
* that pointers parameters, if you are not interested on certain results.
|
||||
* @brief Get actual and average sensor values
|
||||
*
|
||||
* This function is only needed, if there is no callback function registered
|
||||
* for the sensor.
|
||||
* This function returns the actual and average sensor values of the last
|
||||
* measurement. The parameters *actual* and *average* are pointers to data
|
||||
* structures of the type *sht3x_value_set_t*, which are filled with the
|
||||
* of last measurement. Use NULL for the appropriate parameter if you are
|
||||
* not interested in specific results.
|
||||
*
|
||||
* @param sensor id of the sensor
|
||||
* @param actual pointer to a data structure for actual sensor values
|
||||
* @param average pointer to a data structure for average sensor values
|
||||
* If average value computation is deactivated, average sensor values
|
||||
* correspond to the actual sensor values.
|
||||
*
|
||||
* Please note: Calling this function is only necessary if no callback
|
||||
* function has been registered for the sensor.
|
||||
*
|
||||
* @param sensor ID of the sensor
|
||||
* @param actual Pointer to a data structure for actual sensor values
|
||||
* @param average Pointer to a data structure for average sensor values
|
||||
*
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
|
|
@ -157,16 +216,34 @@ bool sht3x_get_values (uint32_t sensor,
|
|||
sht3x_value_set_t *actual,
|
||||
sht3x_value_set_t *average);
|
||||
|
||||
|
||||
/**
|
||||
* At each measurement carried out by the background task, actual
|
||||
* sensor values are determined and exponential moving average values are
|
||||
* computed according to following equation
|
||||
* @brief Enable (default) or disable average value computation
|
||||
*
|
||||
* In case, the average value computation is disabled, average sensor values
|
||||
* correspond to the actual sensor values.
|
||||
*
|
||||
* @param sensor id of the sensor
|
||||
* @param enabled true to enable or false to disable average computation
|
||||
*
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
bool sht3x_enable_average_computation (uint32_t sensor, bool enabled);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Set weight (smoothing factor) for average value computation
|
||||
*
|
||||
* At each measurement carried out by the background task, actual sensor
|
||||
* values are determined. If average value computation is enabled (default),
|
||||
* exponential moving average values are computed according to following
|
||||
* equation
|
||||
*
|
||||
* Average[k] = W * Value + (1-W) * Average [k-1]
|
||||
*
|
||||
* where coefficient W represents the degree of weighting decrease, a
|
||||
* constant smoothing factor between 0 and 1. A higher W discounts older
|
||||
* observations faster.
|
||||
* where coefficient W represents the degree of weighting decrease, a constant
|
||||
* smoothing factor between 0 and 1. A higher W discounts older observations
|
||||
* faster. W is 0.2 by default.
|
||||
*
|
||||
* @param sensor id of the sensor
|
||||
* @param weight coefficient W (default is 0.2)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue