j3d1/esp-open-rtos
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

some changes

Browse source
This commit is contained in:
Gunar Schorcht 2017-09-15 10:10:49 +02:00 committed by GitHub
parent 5d0d211df0
commit 9f60c98324
1 changed files with 30 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
extras/sht3x/README.md
View file

@ -2,63 +2,67 @@
This driver is written for usage with the ESP8266 and FreeRTOS ([esp-open-rtos](https://github.com/SuperHouse/esp-open-rtos) and [esp-open-rtos-driver-i2c](https://github.com/kanflo/esp-open-rtos-driver-i2c)). This driver is written for usage with the ESP8266 and FreeRTOS ([esp-open-rtos](https://github.com/SuperHouse/esp-open-rtos) and [esp-open-rtos-driver-i2c](https://github.com/kanflo/esp-open-rtos-driver-i2c)).
Please note: The driver supports multiple sensors connected to different I2C with differen addresses. Please note: The driver supports multiple sensors connected to different I2C interfaces and different addresses.
## About the sensor ## About the sensor
SHT3x is a digital temperature and humidity sensor that uses I2C interface as slave with up to 1 MHz communication speed. It can operate with three levels of *repeatability* (low, medium and high) in two different modes, the *single shot data aquisition mode* and the *periodic data aquisition mode*. SHT3x is a digital temperature and humidity sensor that uses I2C interface with up to 1 MHz communication speed. It can operate with three levels of *repeatability* (low, medium and high) in two different modes, the *single shot data acquisition mode* and the *periodic data aquisition mode*.
### Single shot data aquisition mode ### Single shot data acquisition mode
In this mode one issued measurement command triggers the acquisition of one data pair. Each data pair In this mode one issued measurement command triggers the acquisition of one data pair. Each data pair
consists of temperature and humidity as 16 bit decimal values. consists of temperature and humidity as 16 bit decimal values.
Repeatability setting influences the measurement duration as well as the current consumption of the sensor. The measuerment takes 3 ms at low repeatability, 5 ms at low repeatability, and 13.5 ms at high respectively. Average current consumption while sensor is measuring at lowest repeatability is 800 uA. That is, the higher repeatability level is, the longer the measurement takes and the higher the power consumption is. In standby the sensor consumes only 0.2 uA. Repeatability setting influences the measurement duration as well as the current consumption of the sensor. The measurement takes 3 ms at low repeatability, 5 ms at low repeatability, and 13.5 ms at high repeatability, respectively. That is, the measurement produces a noticeable delay in execution.
### Periodic data aquisition mode Average current consumption of while sensor is measuring at lowest repeatability is 800 uA. That is, the higher the repeatability level is, the longer the measurement takes and the higher the power consumption is. The sensor consumes only 0.2 uA in standby mode.
### Periodic data acquisition mode
In this mode one issued measurement command yields a stream of data pairs. Each data pair In this mode one issued measurement command yields a stream of data pairs. Each data pair
consists of temperature and humidity as 16 bit decimal values. Once the measurement command is sent to the sensor, it executes measurements periodically by itself with a rate of 0.5, 1, 2, 4 or 10 measurements per second (mps). The data pairs can be read by a fetch command at the same rate. consists of temperature and humidity as 16 bit decimal values. Once the measurement command is sent to the sensor, it executes measurements periodically by itself at a rate of 0.5, 1, 2, 4 or 10 measurements per second (mps). The data pairs can be read by a fetch command at the same rate.
As in single shot data aquisition mode, the repeatability setting influences the measurement duration as well as the current consumption of the sensor, see above. As in *single shot data acquisition mode*, the repeatability setting influences the measurement duration as well as the current consumption of the sensor, see above.
## How the driver works ## How the driver works
To avoid blocking of user tasks during the measurements, a seperate task running in background is created for each connectd SHT3x sensor using the function *sht3x_create_sensor*. The background task realizes the measurement procedure which is executed periodically at a rate that can be defined by the user using function *sht3x_set_measurement_period* (default period is 1000 ms). To avoid blocking of user tasks during measurements due to their duration, separate tasks running in background are used to realize the measurements. These task are created implicitly when a user task calls function *sht3x_create_sensor* for each connected SHT3x sensor. The background tasks realize the measurement procedures which are executed periodically at a rate that can be defined by the user for each sensor separately using function *sht3x_set_measurement_period* (default period is 1000 ms).
### Measurement ### Measurement
Since predefined rates of *periodic data aquisition mode* of the sensor itself are normally not compatible with user requirements, the measurement procedure is realized in *single shot data aquisition mode* at the highest level of repeatability. Because of the sensor power characteristics, *single shot data aquisition mode* is more power efficient than using *periodic data aquisition mode* in most use cases. Since predefined rates of *periodic data acquisition mode* of the sensor itself are normally not compatible with user requirements, the measurement procedures are realized in *single shot data acquisition mode* at the highest level of repeatability. Because of the sensor power characteristics, *single shot data acquisition mode* is more power efficient than using *periodic data acquisition mode* in most use cases.
However, using the *single shot data aquisition mode* produces a delay of 20 ms for each measurement. This is the time needed from issuing the measurement command until measured sensor data are available and can be read. Since the delay is realized using *vTaskDelay* function in the background task, neither the system nor any user task is blocked during the measurement. However, using the *single shot data acquisition mode* produces a delay of 20 ms for each measurement. This is the time needed from issuing the measurement command until measured sensor data are available and can be read. Since the delay is realized using *vTaskDelay* function in the background tasks, neither the system nor any user task is blocked during the measurements.
Please note: Since each measurement produces a delay of 20 ms, the minimum period that can be defined with function *sht3x_set_measurement_period* is 20 ms. Therefore, a maximum measurement rate of 50 mps could be reached. Please note: Since each measurement produces a delay of 20 ms, the minimum period that can be defined with function *sht3x_set_measurement_period* is 20 ms. Therefore, a maximum measurement rate of 50 mps could be reached.
### Measured data ### Measured data
At each measurement, *actual sensor values* for temperature as well as humidity are determined as floating point values from measuered data pairs. Temerature is given in °C as well in °F. Humiditiy is given in percent. Based on these *actual sensor values* the background task also computes *average sensor values* successive at each measurement using the exponential moving average At each measurement, *actual sensor values* for temperature as well as humidity are determined as floating point values from measured data pairs. Temperature is given in °C as well in °F. Humidity is given in percent. Based on these *actual sensor values* the background task also computes successively with each measurement the *average sensor values* using the exponential moving average
Average[k] = W * Value + (1-W) * Average [k-1] Average[k] = W * Actual + (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. The coefficient W (smoothing factor) can be defined by the user (default W is 0.2) using function *sht3x_set_average_weight*. where coefficient W represents the degree of weighting decrease, a constant smoothing factor between 0 and 1. A higher W discounts older observations faster. The coefficient W (smoothing factor) can be defined by the user using function *sht3x_set_average_weight*. The default value of W is 0.2.
### Getting results. ### Getting results.
To get measured values by a user task, there are two possibilities, the defining a callback function or calling function *sht3x_get_values*. Once a measurement has been finished, *actual sensor values* and *average sensor values* can be read by user tasks. There are two possibilities to do that, defining a callback function or the calling function *sht3x_get_values* explicitly.
#### Using callback function #### Using callback function
For each connected SHT3 sensor, the user can register a callback function using function *sht3x_set_callback_function*. If a callback function is registered, it is called after each measurement by the background task to pass the *actual sensor values* and *average sensor values* to user tasks. Thus, the user gets the results automatically with same rate as the periodic measurement is executed. For each connected SHT3 sensor, the user can register a callback function using function *sht3x_set_callback_function*. If a callback function is registered, it is called by the background task after each measurement to pass *actual sensor values* and *average sensor values* to user tasks. Thus, the user gets the results of measurements automatically with same rate as the periodic measurements are executed.
Using the callback function is the easiest way to get the results. Using the callback function is the easiest way to get the results.
#### Using function sht3x_get_values #### Using function sht3x_get_values
If there is no callback function registered, the user has to use function *sht3x_get_values* explicitly to get *actual sensor values* and *average sensor values*. To ensure that these values are up-to-date, the rate of periodic measurement in background task should be at least the same as the rate of using function *sht3x_get_values* If there is no callback function registered, the user has to use function *sht3x_get_values* explicitly to get *actual sensor values* and *average sensor values*. To ensure that these values are up-to-date, the rate of periodic measurement in background task should be at least the same or higher as the rate of using function *sht3x_get_values*. That is, the period of measurements in background task set with function *sht3x_set_measurement_period* has to be less or equal than the rate of using function *sht3x_get_values*.
Please remember: The minimum measurement period can be 20 ms.
## Usage ## Usage
Before using the sht3x driver, function *sht3x_init* needs to be called to setup each I2C interface. Before using the SHT3x driver, function *i2c_init* needs to be called to setup each I2C interface.
``` ```
#define I2C_BUS 0 #define I2C_BUS 0
@ -78,15 +82,15 @@ Next, the SHT3x driver itself has to be initialized using function *sht3x_init*.
sht3x_init(); sht3x_init();
``` ```
If SHT3x driver initialisation was successful, function *sht3x_create_sensor* has to be called for each sensor to initialize the sensor connected to a certain bus with slave address, to check its availability and to start a background task for measurments. If SHT3x driver initialization was successful, function *sht3x_create_sensor* has to be called for each sensor to initialize the sensor connected to a certain bus with given slave address, to check its availability and to start the background task for measurements.
``` ```
sensor = sht3x_create_sensor (I2C_BUS, SHT3x_ADDR); sensor = sht3x_create_sensor (I2C_BUS, SHT3x_ADDR);
``` ```
This function returns the id of the sensor between 0 and *SHT3x_MAX_SENSORS* on success or -1 on error. This id is used to identify the sensor in all other functions used later. On success this function returns the *ID* of a sensor descriptor between 0 and *SHT3x_MAX_SENSORS* or -1 otherwise. This *ID* is used to identify the sensor in all other functions used later.
If you want to use a callback function defined like following If you want to use a callback function defined like following to get the measurement results
``` ```
static void my_callback_function (uint32_t sensor, static void my_callback_function (uint32_t sensor,
@ -97,7 +101,7 @@ static void my_callback_function (uint32_t sensor,
} }
``` ```
you have to register it using *sht3x_set_callback_function* you have to register this callback function using *sht3x_set_callback_function*.
``` ```
sht3x_set_callback_function (sensor, &my_callback_function); sht3x_set_callback_function (sensor, &my_callback_function);
@ -110,8 +114,7 @@ sht3x_set_measurement_period (sensor, 1000);
sht3x_set_average_weight (sensor, 0.2); sht3x_set_average_weight (sensor, 0.2);
``` ```
All functions return a boolean that allows effecitve error handling. All functions return a boolean that allows effective error handling.
## Full Example ## Full Example
@ -140,8 +143,8 @@ static void my_callback_function (uint32_t sensor,
{ {
printf("%.3f Sensor %d: %.2f (%.2f) C, %.2f (%.2f) F, %.2f (%.2f) \n", printf("%.3f Sensor %d: %.2f (%.2f) C, %.2f (%.2f) F, %.2f (%.2f) \n",
(double)sdk_system_get_time()*1e-3, sensor, (double)sdk_system_get_time()*1e-3, sensor,
actual.c_temperature, average.c_temperature, actual.temperature_c, average.temperature_c,
actual.f_temperature, average.f_temperature, actual.temperature_f, average.temperature_f,
actual.humidity, average.humidity); actual.humidity, average.humidity);
} }
@ -186,7 +189,7 @@ void user_init(void)
return; return;
} }
// Optional: Set the weight for expontial moving average (default 0.2) // Optional: Set the weight for exponential moving average (default 0.2)
if (!sht3x_set_average_weight (sensor, 0.2)) if (!sht3x_set_average_weight (sensor, 0.2))
{ {
// error message // error message
@ -200,7 +203,7 @@ void user_init(void)
## Further Examples ## Further Examples
For further examples see [Examples directory](../../examples/sht3x/README.md) For further examples see [examples directory](../../examples/sht3x/README.md)