SHT3x driver minor changes
- new high level function sht3x_measure added, it comprises all three steps to perform one measurement in only one function - example with two sensors removed
This commit is contained in:
Gunar Schorcht
parent
a53586eb75
commit
b9add1ee48
9 changed files with 138 additions and 167 deletions
3
examples/sht3x/Makefile
Normal file
3
examples/sht3x/Makefile
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
PROGRAM=SHT3x
|
||||
EXTRA_COMPONENTS = extras/i2c extras/sht3x
|
||||
include ../../common.mk
|
||||
|
|
@ -33,14 +33,4 @@ If you want to run examples with **two sensors**, you could do this with only on
|
|||
|
||||
## Example description
|
||||
|
||||
Examples show how to use the driver in single shot as well as in periodic mode.
|
||||
|
||||
|
||||
### _sht3x_one_sensor_
|
||||
|
||||
The simple example show how to use the driver with one SHT3x sensor. It demonstrates two different user task implementations, one in *single shot mode* and one in *periodic mode*.
|
||||
|
||||
### _sht3x_two_sensors_
|
||||
|
||||
This simple example shows how to use the driver for two sensors. As with the example _sht3x_one_sensor_, it uses two different user task implementations.
|
||||
|
||||
It shows different user task implementations in *single shot mode* and *periodic mode*. In *single shot* mode either low level or high level functions are used. Constants SINGLE_SHOT_LOW_LEVEL and SINGLE_SHOT_HIGH_LEVEL controls which task implementation is used.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
/**
|
||||
* Simple example with one SHT3x sensor.
|
||||
* Simple example with SHT3x sensor.
|
||||
*
|
||||
* It shows two different user task implementations, one in *single shot mode*
|
||||
* and one in *periodic mode*.
|
||||
* It shows different user task implementations in *single shot mode* and
|
||||
* *periodic mode*. In *single shot* mode either low level or high level
|
||||
* functions are used.
|
||||
*
|
||||
* Which implementation is used is defined by constant SINGLE_SHOT_MODE.
|
||||
* Constants SINGLE_SHOT_LOW_LEVEL and SINGLE_SHOT_HIGH_LEVEL controls which
|
||||
* task implementation is used.
|
||||
*
|
||||
* Harware configuration:
|
||||
*
|
||||
|
|
@ -15,7 +17,8 @@
|
|||
* +------------------------+ +----------+
|
||||
*/
|
||||
|
||||
#define SINGLE_SHOT_MODE
|
||||
// #define SINGLE_SHOT_LOW_LEVEL
|
||||
// #define SINGLE_SHOT_HIGH_LEVEL
|
||||
|
||||
#include "espressif/esp_common.h"
|
||||
#include "esp/uart.h"
|
||||
|
|
@ -33,10 +36,11 @@
|
|||
|
||||
static sht3x_sensor_t* sensor; // sensor device data structure
|
||||
|
||||
#ifdef SINGLE_SHOT_MODE
|
||||
#if defined(SINGLE_SHOT_HIGH_LEVEL)
|
||||
/*
|
||||
* User task that triggers a measurement every 5 seconds. Due to
|
||||
* power efficiency reasons, it uses the SHT3x *sht3x_single_shot*.
|
||||
* User task that triggers a measurement every 5 seconds. Due to power
|
||||
* efficiency reasons it uses *single shot* mode. In this example it uses the
|
||||
* high level function *sht3x_measure* to perform one measurement in each cycle.
|
||||
*/
|
||||
void user_task (void *pvParameters)
|
||||
{
|
||||
|
|
@ -45,6 +49,35 @@ void user_task (void *pvParameters)
|
|||
|
||||
TickType_t last_wakeup = xTaskGetTickCount();
|
||||
|
||||
while (1)
|
||||
{
|
||||
// perform one measurement and do something with the results
|
||||
if (sht3x_measure (sensor, &temperature, &humidity))
|
||||
printf("%.3f SHT3x Sensor: %.2f °C, %.2f %%\n",
|
||||
(double)sdk_system_get_time()*1e-3, temperature, humidity);
|
||||
|
||||
// wait until 5 seconds are over
|
||||
vTaskDelayUntil(&last_wakeup, 5000 / portTICK_PERIOD_MS);
|
||||
}
|
||||
}
|
||||
|
||||
#elif defined(SINGLE_SHOT_LOW_LEVEL)
|
||||
/*
|
||||
* User task that triggers a measurement every 5 seconds. Due to power
|
||||
* efficiency reasons it uses *single shot* mode. In this example it starts the
|
||||
* measurement, waits for the results and fetches the results using separate
|
||||
* functions
|
||||
*/
|
||||
void user_task (void *pvParameters)
|
||||
{
|
||||
float temperature;
|
||||
float humidity;
|
||||
|
||||
TickType_t last_wakeup = xTaskGetTickCount();
|
||||
|
||||
// get the measurement duration for high repeatability;
|
||||
uint8_t duration = sht3x_get_measurement_duration(sht3x_high);
|
||||
|
||||
while (1)
|
||||
{
|
||||
// Trigger one measurement in single shot mode with high repeatability.
|
||||
|
|
@ -52,7 +85,7 @@ void user_task (void *pvParameters)
|
|||
|
||||
// Wait until measurement is ready (constant time of at least 30 ms
|
||||
// or the duration returned from *sht3x_get_measurement_duration*).
|
||||
vTaskDelay (sht3x_get_measurement_duration(sht3x_high));
|
||||
vTaskDelay (duration);
|
||||
|
||||
// retrieve the values and do something with them
|
||||
if (sht3x_get_results (sensor, &temperature, &humidity))
|
||||
|
|
@ -63,6 +96,7 @@ void user_task (void *pvParameters)
|
|||
vTaskDelayUntil(&last_wakeup, 5000 / portTICK_PERIOD_MS);
|
||||
}
|
||||
}
|
||||
|
||||
#else // PERIODIC MODE
|
||||
/*
|
||||
* User task that fetches latest measurement results of sensor every 2
|
||||
|
|
@ -108,7 +142,7 @@ void user_init(void)
|
|||
// (different busses are possible).
|
||||
i2c_init(I2C_BUS, I2C_SCL_PIN, I2C_SDA_PIN, I2C_FREQ_100K);
|
||||
|
||||
// Create the sensors.
|
||||
// Create the sensors, multiple sensors are possible.
|
||||
if ((sensor = sht3x_init_sensor (I2C_BUS, SHT3x_ADDR_2)))
|
||||
{
|
||||
// Create a user task that uses the sensors.
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
PROGRAM=SHT3x_One_Sensor
|
||||
EXTRA_COMPONENTS = extras/i2c extras/sht3x
|
||||
include ../../../common.mk
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
PROGRAM=SHT3x_Two_Sensors
|
||||
EXTRA_COMPONENTS = extras/i2c extras/sht3x
|
||||
include ../../../common.mk
|
||||
|
|
@ -1,130 +0,0 @@
|
|||
/**
|
||||
* Simple example with two SHT3x sensors.
|
||||
*
|
||||
* It shows two different user task implementations, one in *single shot mode*
|
||||
* and one in *periodic mode*.
|
||||
*
|
||||
* Harware configuration:
|
||||
*
|
||||
* +------------------------+ +----------+
|
||||
* | ESP8266 Bus 0 | | SHT3x_1 |
|
||||
* | GPIO 5 (SCL) ------> SCL |
|
||||
* | GPIO 4 (SDA) ------- SDA |
|
||||
* | | +----------+
|
||||
* | Bus 1 | | SHT3x_2 |
|
||||
* | GPIO 14 (SCL) ------> SCL |
|
||||
* | GPIO 12 (SDA) ------- SDA |
|
||||
* +------------------------+ +----------+
|
||||
*/
|
||||
|
||||
#include "espressif/esp_common.h"
|
||||
#include "esp/uart.h"
|
||||
|
||||
#include "FreeRTOS.h"
|
||||
#include "task.h"
|
||||
|
||||
// include SHT3x driver
|
||||
|
||||
#include "sht3x/sht3x.h"
|
||||
|
||||
// define I2C interfaces at which SHTx3 sensors are connected
|
||||
|
||||
#define I2C_1_BUS 0
|
||||
#define I2C_1_SCL_PIN GPIO_ID_PIN((5))
|
||||
#define I2C_1_SDA_PIN GPIO_ID_PIN((4))
|
||||
|
||||
#define I2C_2_BUS 1
|
||||
#define I2C_2_SCL_PIN GPIO_ID_PIN((14))
|
||||
#define I2C_2_SDA_PIN GPIO_ID_PIN((12))
|
||||
|
||||
static sht3x_sensor_t* sensor1;
|
||||
static sht3x_sensor_t* sensor2;
|
||||
|
||||
/*
|
||||
* User task that triggers measurements of sensor1 every 5 seconds. Due to
|
||||
* power efficiency reasons, it uses the SHT3x *sht3x_single_shot* mode.
|
||||
*/
|
||||
void user_task_sensor1 (void *pvParameters)
|
||||
{
|
||||
float temperature;
|
||||
float humidity;
|
||||
|
||||
TickType_t last_wakeup = xTaskGetTickCount();
|
||||
|
||||
while (1)
|
||||
{
|
||||
// Trigger one measurement in single shot mode with high repeatability.
|
||||
sht3x_start_measurement (sensor1, sht3x_single_shot, sht3x_high);
|
||||
|
||||
// Wait until measurement is ready (constant time of at least 30 ms
|
||||
// or the duration returned from *sht3x_get_measurement_duration*).
|
||||
vTaskDelay (sht3x_get_measurement_duration(sht3x_high));
|
||||
|
||||
// retrieve the values and do something with them
|
||||
if (sht3x_get_results (sensor1, &temperature, &humidity))
|
||||
printf("%.3f SHT3x Sensor 1: %.2f °C, %.2f %%\n",
|
||||
(double)sdk_system_get_time()*1e-3, temperature, humidity);
|
||||
|
||||
// wait until 5 seconds are over
|
||||
vTaskDelayUntil(&last_wakeup, 5000 / portTICK_PERIOD_MS);
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* User task that fetches latest measurement results of sensor2 every 2
|
||||
* seconds. It starts the SHT3x in periodic mode with 10 measurements per
|
||||
* second (*sht3x_periodic_10mps*).
|
||||
*/
|
||||
void user_task_sensor2 (void *pvParameters)
|
||||
{
|
||||
float temperature;
|
||||
float humidity;
|
||||
|
||||
// Start periodic measurement mode with high repeatability.
|
||||
sht3x_start_measurement (sensor2, sht3x_periodic_10mps, sht3x_high);
|
||||
|
||||
// Wait until measurement is ready (constant time of at least 30 ms
|
||||
// or the duration returned from *sht3x_get_measurement_duration*).
|
||||
vTaskDelay (sht3x_get_measurement_duration(sht3x_high));
|
||||
|
||||
TickType_t last_wakeup = xTaskGetTickCount();
|
||||
|
||||
while (1)
|
||||
{
|
||||
// Retrieve the values and do something with them.
|
||||
if (sht3x_get_results (sensor2, &temperature, &humidity))
|
||||
printf("%.3f SHT3x Sensor 2: %.2f °C, %.2f %%\n",
|
||||
(double)sdk_system_get_time()*1e-3, temperature, humidity);
|
||||
|
||||
// Wait until 2 seconds are over.
|
||||
vTaskDelayUntil(&last_wakeup, 2000 / portTICK_PERIOD_MS);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
void user_init(void)
|
||||
{
|
||||
// Set UART Parameter
|
||||
uart_set_baud(0, 115200);
|
||||
|
||||
// Give the UART some time to settle.
|
||||
sdk_os_delay_us(500);
|
||||
|
||||
// Init I2C bus interfaces at which SHT3x sensors are connected
|
||||
// (different busses are possible).
|
||||
i2c_init(I2C_1_BUS, I2C_1_SCL_PIN, I2C_1_SDA_PIN, I2C_FREQ_100K);
|
||||
i2c_init(I2C_2_BUS, I2C_2_SCL_PIN, I2C_2_SDA_PIN, I2C_FREQ_100K);
|
||||
|
||||
// Create sensors.
|
||||
sensor1 = sht3x_init_sensor (I2C_1_BUS, SHT3x_ADDR_2);
|
||||
sensor2 = sht3x_init_sensor (I2C_2_BUS, SHT3x_ADDR_1);
|
||||
|
||||
if (sensor1 && sensor2)
|
||||
{
|
||||
// Create the tasks that use the sensors.
|
||||
xTaskCreate(user_task_sensor1, "user_task_sensor1", 256, NULL, 2, 0);
|
||||
xTaskCreate(user_task_sensor2, "user_task_sensor2", 256, NULL, 2, 0);
|
||||
}
|
||||
|
||||
// That's it.
|
||||
}
|
||||
|
|
@ -24,6 +24,8 @@ Due to the measurement duration of up to 15 ms, the measurement process is separ
|
|||
|
||||
In the *single shot mode*, the user task has to perform all steps every time new sensor values are needed.
|
||||
|
||||
For convenience a high level function ```sht3x_measure``` that comprises all three steps above in only one function to perform a measurement. This function is the easiest way to use the sensor. It is most suitable for users that don't want to have the control on sensor details.
|
||||
|
||||
The advantage of this mode is that the sensor can switch between successive measurements into the sleep mode, which is more energy-efficient. This is particularly useful when the measurement rate is less than 1 measurement per second.
|
||||
|
||||
### Periodic mode
|
||||
|
|
@ -40,7 +42,7 @@ As in *single shot mode*, the measurement process is separated into the followin
|
|||
|
||||
However, in contrast to the *single shot mode*, steps 1 and 2 have to be executed only once. Once the measurement is started, the user task hast can simply fetch data periodically.
|
||||
|
||||
**Please note:** The rate of fetching the measurement results must be not greater than the rate of periodic measurements of the sensor, however, it *should be less* to avoid conflicts caused by the timing tolerance of the sensor.
|
||||
**Please note:** The rate of fetching the measurement results must not be greater than the rate of periodic measurements of the sensor. Even more, it *should be less* to avoid conflicts caused by the timing tolerance of the sensor.
|
||||
|
||||
## Measurement results
|
||||
|
||||
|
|
@ -66,7 +68,7 @@ The repeatability settings influences the measurement duration as well as the po
|
|||
|
||||
While the sensor measures at the lowest repeatability, the average current consumption is 800 μA. That is, the higher the repeatability level, the longer the measurement takes and the higher the power consumption. The sensor consumes only 0.2 μA in standby mode.
|
||||
|
||||
The repeatability used for a measurement is specified as parameter of ```sht3x_start_measurement```.
|
||||
The repeatability used for a measurement is specified as parameter of function ```sht3x_start_measurement```.
|
||||
|
||||
|
||||
## Usage
|
||||
|
|
@ -154,6 +156,8 @@ void user_task (void *pvParameters)
|
|||
|
||||
TickType_t last_wakeup = xTaskGetTickCount();
|
||||
|
||||
uint8_t duration = sht3x_get_measurement_duration(sht3x_high);
|
||||
|
||||
while (1)
|
||||
{
|
||||
// Trigger one measurement in single shot mode with high repeatability.
|
||||
|
|
@ -161,7 +165,7 @@ void user_task (void *pvParameters)
|
|||
|
||||
// Wait until measurement is ready (constant time of at least 30 ms
|
||||
// or the duration returned from *sht3x_get_measurement_duration*).
|
||||
vTaskDelay (sht3x_get_measurement_duration(sht3x_high));
|
||||
vTaskDelay (duration);
|
||||
|
||||
// retrieve the values and do something with them
|
||||
if (sht3x_get_results (sensor, &temperature, &humidity))
|
||||
|
|
@ -176,7 +180,31 @@ void user_task (void *pvParameters)
|
|||
|
||||
In contrast to the *periodic mode*, the function ```sht3x_start_measurement``` is called inside the task loop to start exactly one measurement in each cycle. The task is then also delayed every time using function ```vTaskDelay``` before the results are fetched with function ```sht3x_get_results```.
|
||||
|
||||
The code could be extended by an error handling. In the event of an error, most driver functions set the ```error_code``` element of the sensor device data structure. This indicates which error has occurred. Error codes are a combination of I2C communication error codes and SHT3x sensor error codes. To test for a particular error, the *error code* can be AND with one of the error masks ```SHT3x_I2C_ERROR_MASK``` or ```SHT3x_DRV_ERROR_MASK```.
|
||||
Alternatively, user task can use the high level function ```sht3x_measure``` that comprises these steps in only one function. This would simplify the user task that would then look like the following:
|
||||
|
||||
```
|
||||
void user_task (void *pvParameters)
|
||||
{
|
||||
float temperature;
|
||||
float humidity;
|
||||
|
||||
TickType_t last_wakeup = xTaskGetTickCount();
|
||||
|
||||
while (1)
|
||||
{
|
||||
// perform one measurement and do something with the results
|
||||
if (sht3x_measure (sensor, &temperature, &humidity))
|
||||
printf("%.3f SHT3x Sensor: %.2f °C, %.2f %%\n",
|
||||
(double)sdk_system_get_time()*1e-3, temperature, humidity);
|
||||
|
||||
// wait until 5 seconds are over
|
||||
vTaskDelayUntil(&last_wakeup, 5000 / portTICK_PERIOD_MS);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
The code could be extended by an error handling. In the event of an error, most driver functions set the ```error_code``` element of the sensor device data structure. This indicates which error has occurred. Error codes are a combination of I2C communication error codes and SHT3x sensor error codes. To test for a particular error, the *error code* has to be ANDed with one of the error masks ```SHT3x_I2C_ERROR_MASK``` or ```SHT3x_DRV_ERROR_MASK``` and then tested for a certain value.
|
||||
|
||||
For example, error handling for ```sht3x_get_results``` could look like:
|
||||
```
|
||||
|
|
@ -230,6 +258,9 @@ void user_task (void *pvParameters)
|
|||
float humidity;
|
||||
|
||||
TickType_t last_wakeup = xTaskGetTickCount();
|
||||
|
||||
// get the measurement duration for high repeatability;
|
||||
uint8_t duration = sht3x_get_measurement_duration(sht3x_high);
|
||||
|
||||
while (1)
|
||||
{
|
||||
|
|
@ -238,7 +269,7 @@ void user_task (void *pvParameters)
|
|||
|
||||
// Wait until measurement is ready (constant time of at least 30 ms
|
||||
// or the duration returned from *sht3x_get_measurement_duration*).
|
||||
vTaskDelay (sht3x_get_measurement_duration(sht3x_high));
|
||||
vTaskDelay (duration);
|
||||
|
||||
// retrieve the values and do something with them
|
||||
if (sht3x_get_results (sensor, &temperature, &humidity))
|
||||
|
|
|
|||
|
|
@ -160,6 +160,24 @@ sht3x_sensor_t* sht3x_init_sensor(uint8_t bus, uint8_t addr)
|
|||
}
|
||||
|
||||
|
||||
bool sht3x_measure (sht3x_sensor_t* dev, float* temperature, float* humidity)
|
||||
{
|
||||
if (!dev || (!temperature && !humidity)) return false;
|
||||
|
||||
if (!sht3x_start_measurement (dev, sht3x_single_shot, sht3x_high))
|
||||
return false;
|
||||
|
||||
vTaskDelay (SHT3x_MEAS_DURATION_TICKS[sht3x_high]);
|
||||
|
||||
sht3x_raw_data_t raw_data;
|
||||
|
||||
if (!sht3x_get_raw_data (dev, raw_data))
|
||||
return false;
|
||||
|
||||
return sht3x_compute_values (raw_data, temperature, humidity);
|
||||
}
|
||||
|
||||
|
||||
bool sht3x_start_measurement (sht3x_sensor_t* dev, sht3x_mode_t mode, sht3x_repeat_t repeat)
|
||||
{
|
||||
if (!dev) return false;
|
||||
|
|
|
|||
|
|
@ -150,7 +150,32 @@ sht3x_sensor_t* sht3x_init_sensor (uint8_t bus, uint8_t addr);
|
|||
|
||||
|
||||
/**
|
||||
* @brief Start single shot or periodic measurements
|
||||
* @brief High level measurement function
|
||||
*
|
||||
* For convenience this function comprises all three steps to perform
|
||||
* one measurement in only one function:
|
||||
*
|
||||
* 1. Starts a measurement in single shot mode with high reliability
|
||||
* 2. Waits using *vTaskDelay* until measurement results are available
|
||||
* 3. Returns the results in kind of floating point sensor values
|
||||
*
|
||||
* This function is the easiest way to use the sensor. It is most suitable
|
||||
* for users that don't want to have the control on sensor details.
|
||||
*
|
||||
* Please note: The function delays the calling task up to 30 ms to wait for
|
||||
* the the measurement results. This might lead to problems when the function
|
||||
* is called from a software timer callback function.
|
||||
*
|
||||
* @param dev pointer to sensor device data structure
|
||||
* @param temperature returns temperature in degree Celsius
|
||||
* @param humidity returns humidity in percent
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
bool sht3x_measure (sht3x_sensor_t* dev, float* temperature, float* humidity);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Start the measurement in single shot or periodic mode
|
||||
*
|
||||
* The function starts the measurement either in *single shot mode*
|
||||
* (exactly one measurement) or *periodic mode* (periodic measurements)
|
||||
|
|
@ -164,10 +189,11 @@ sht3x_sensor_t* sht3x_init_sensor (uint8_t bus, uint8_t addr);
|
|||
* the measurement duration has to be waited only once until the first
|
||||
* results are available. After this first measurement, the sensor then
|
||||
* automatically performs all subsequent measurements. The rate of periodic
|
||||
* measurements can be 10, 4, 2, 1 or 0.5 measurements per second (mps). Due
|
||||
* to inaccuracies in timing of the sensor, the user task should fetch the
|
||||
* results at a lower rate. The rate of the periodic measurements is defined
|
||||
* by the parameter *mode*.
|
||||
* measurements can be 10, 4, 2, 1 or 0.5 measurements per second (mps).
|
||||
*
|
||||
* Please note: Due to inaccuracies in timing of the sensor, the user task
|
||||
* should fetch the results at a lower rate. The rate of the periodic
|
||||
* measurements is defined by the parameter *mode*.
|
||||
*
|
||||
* @param dev pointer to sensor device data structure
|
||||
* @param mode measurement mode, see type *sht3x_mode_t*
|
||||
|
|
@ -186,6 +212,9 @@ bool sht3x_start_measurement (sht3x_sensor_t* dev, sht3x_mode_t mode,
|
|||
* duration in RTOS ticks directly to wait with function *vTaskDelay* until
|
||||
* the measurement results can be fetched.
|
||||
*
|
||||
* Please note: The duration only depends on repeatability level. Therefore,
|
||||
* it can be considered as constant for a repeatibility.
|
||||
*
|
||||
* @param repeat repeatability, see type *sht3x_repeat_t*
|
||||
* @return measurement duration given in RTOS ticks
|
||||
*/
|
||||
|
|
@ -213,6 +242,7 @@ uint8_t sht3x_get_measurement_duration (sht3x_repeat_t repeat);
|
|||
*/
|
||||
bool sht3x_get_raw_data(sht3x_sensor_t* dev, sht3x_raw_data_t raw_data);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Computes sensor values from raw data
|
||||
*
|
||||
|
|
@ -224,6 +254,7 @@ bool sht3x_get_raw_data(sht3x_sensor_t* dev, sht3x_raw_data_t raw_data);
|
|||
bool sht3x_compute_values (sht3x_raw_data_t raw_data,
|
||||
float* temperature, float* humidity);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Get measurement results in form of sensor values
|
||||
*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue