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

Driver for Sensirion SHT3x temperature and humidity sensor readded (#453)

Browse source 
* Driver for Sensirion SHT3x sensor added

This is a driver for Sensirion SHT3x temperature and humidity sensors
connected via I2C.

This commit is a rebasing and contains some interface changes based on
the review from @ourairquality.

* SHT3x driver changes

Additional include to satisfy the Travis CI test build

* SHT3x driver - small changes

README.md has been shortened

* SHT3x driver - small changes

* SHT3x driver - small changes

- crc8 lookup table is now static to be held in flash memory
- special handling for the timer overflow in sht3x_is_measuring removed
- initialization reduced to availability check

* SHT3x driver - some small changes

- crc8 lookup table is now static to be held in flash memory
- special handling for the timer overflow in sht3x_is_measuring removed
- some whitespace removed
- initialization reduced to availability check

* SHT3x driver - some minor changes

- lookup tables made const to be held in flash
- crc8 computation changed to a non table lookup version
- measurement duration is now given in ticks and can be used directly
  for vTaskDelay (documentation and examples changed accordingly)

* SHT3x driver - documentation changed

* SHT3x driver - minor correction

- number of ticks for measurement duration takes now into account
  portTICK_PERIOD_MS

* SHT3x driver - minor correction

- number of ticks for measurement duration takes now into account
  portTICK_PERIOD_MS

* SHT3x driver - minor correction

- number of ticks for measurement duration takes now into account
  portTICK_PERIOD_MS

* SHT3x driver - minor correction

- number of ticks for measurement duration takes now into account
  portTICK_PERIOD_MS

* SHT3x driver - minor corrections

* SHT3x driver - minor corrections

* Driver for Sensirion SHT3x sensor added

This is a driver for Sensirion SHT3x temperature and humidity sensors
connected via I2C.

This commit is a rebasing and contains some interface changes based on
the review from @ourairquality.

SHT3x driver changes

- additional include to satisfy the Travis CI test build
- README.md has been shortened
- special handling for the timer overflow in sht3x_is_measuring removed
- some whitespaces removed
- crc8 computation changed to a non table lookup version
- measurement duration is now given in ticks and can be used directly
  for vTaskDelay (documentation and examples changed accordingly)
- number of ticks for measurement duration takes now into account
  portTICK_PERIOD_MS
- clock stretching disabled on sensor to avoid blocking when data are
  not ready to read
- calculation of maesurement duration adds now one and a half ticks to
  be sure that measurement duration is not too short
- function sht3x_is_measuring is now private and only for internal use,
  user task has always to use function vTaskDelay to wait for
  measurement results
- function sht3x_is_measuring was simplified and returns now just a
  boolean value
- private function sht3x_reset added which is used to reset the sensor
  during initialization
- active flag in sensor data structure not needed anymore
- function sht3_get_raw_data simplified
- function sht3x_start_measurement returns now only a boolean
- function sht3x_start_measurement does not check anymore whether there is
  already a measurment running
- new function sht3x_get_measurement_duration which returns the measurement
  duration in ticks for configured repeatability

* SHT3x driver minor changes

- type sht3x_values_t replaced by separate float values
- additional repeatability parameter defined for function sht3x_start_measurement
- parameter of function sht3x_get_measurement_duration changed from
  sht3x_sensort_t to sht3_repeat_t
- sensor modes and repeatability levels extended by prefix sht3x_

* 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

* SHT3x driver small correction
This commit is contained in:
Gunar Schorcht 2017-10-23 23:39:48 +02:00 committed by Johan Kanflo
parent 5fa48d0298
commit ac6797e916
7 changed files with 1236 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
examples/sht3x/Makefile Normal file
View file

@ -0,0 +1,3 @@
PROGRAM=SHT3x
EXTRA_COMPONENTS = extras/i2c extras/sht3x
include ../../common.mk

36
examples/sht3x/README.md Normal file
View file

@ -0,0 +1,36 @@
# SHT3x Driver Examples
These examples demonstrate the usage of the SHT3x driver with only one and multiple SHT3x sensors.
## Hardware setup
There are examples for only one sensor and examples for two sensors.
To run examples with **one sensor**, just use GPIO5 (SCL) and GPIO4 (SDA) to connect to the SHT3x sensor's I2C interface.
```
+------------------------+ +--------+
| ESP8266 Bus 0 | | SHT3x |
| GPIO 5 (SCL) >---- > SCL |
| GPIO 4 (SDA) ------- SDA |
| | +--------+
+------------------------+
```
If you want to run examples with **two sensors**, you could do this with only one bus and different I2C addresses or with two buses and the same or different I2C addresses. In later case, use GPIO14 (SCL) and GPIO12 (SDA) for the second bus to connect to the second SHT3x sensor's I2C interface.
```
+------------------------+ +----------+
| 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 |
+------------------------+ +----------+
```
## Example description
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.

153
examples/sht3x/sht3x.c Normal file
View file

@ -0,0 +1,153 @@
/**
* Simple example with SHT3x sensor.
*
* 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.
*
* Harware configuration:
*
* +------------------------+ +----------+
* | ESP8266 Bus 0 | | SHT3x |
* | GPIO 5 (SCL) ------> SCL |
* | GPIO 4 (SDA) ------- SDA |
* +------------------------+ +----------+
*/
// #define SINGLE_SHOT_LOW_LEVEL
// #define SINGLE_SHOT_HIGH_LEVEL
#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_BUS 0
#define I2C_SCL_PIN GPIO_ID_PIN((5))
#define I2C_SDA_PIN GPIO_ID_PIN((4))
static sht3x_sensor_t* sensor; // sensor device data structure
#if defined(SINGLE_SHOT_HIGH_LEVEL)
/*
* 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)
{
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);
}
}
#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.
sht3x_start_measurement (sensor, 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 (duration);
// retrieve the values and do something with them
if (sht3x_get_results (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);
}
}
#else // PERIODIC MODE
/*
* User task that fetches latest measurement results of sensor every 2
* seconds. It starts the SHT3x in periodic mode with 1 measurements per
* second (*sht3x_periodic_1mps*).
*/
void user_task (void *pvParameters)
{
float temperature;
float humidity;
// Start periodic measurements with 1 measurement per second.
sht3x_start_measurement (sensor, sht3x_periodic_1mps, sht3x_high);
// Wait until first 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)
{
// Get the values and do something with them.
if (sht3x_get_results (sensor, &temperature, &humidity))
printf("%.3f SHT3x Sensor: %.2f °C, %.2f %%\n",
(double)sdk_system_get_time()*1e-3, temperature, humidity);
// Wait until 2 seconds (cycle time) are over.
vTaskDelayUntil(&last_wakeup, 2000 / portTICK_PERIOD_MS);
}
}
#endif
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_BUS, I2C_SCL_PIN, I2C_SDA_PIN, I2C_FREQ_100K);
// 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.
xTaskCreate(user_task, "user_task", 256, NULL, 2, 0);
}
// That's it.
}

309
extras/sht3x/README.md Normal file
View file

@ -0,0 +1,309 @@
# Driver for **SHT3x** digital **temperature and humidity sensor**
This driver is written for usage with the ESP8266 and FreeRTOS using the I2C interface driver. It supports multiple SHT3x sensors connected to the same or different I2C interfaces.
## About the sensor
SHT3x is a digital temperature and humidity sensor that uses an I2C interface with up to 1 MHz communication speed. It can operate with **three levels of repeatability** (low, medium and high) and in two different modes, the **single shot data acquisition mode** (or short **single shot mode**) and the **periodic data acquisition mode** (or short **periodic mode**).
## Measurement process
Once the SHT3x sensor is initialized, it can be used for measurements.
### Single shot mode
In **single shot mode**, a measurement command triggers the acquisition of **exactly one data pair**. Each data pair consists of temperature and humidity as 16-bit decimal values.
Due to the measurement duration of up to 15 ms, the measurement process is separated into steps to avoid blocking the user task during measurements:
1. Trigger the sensor with function ```sht3x_start_measurement``` to perform exactly one single measurement.
2. Wait the measurement duration using function ```vTaskDelay``` until the results are available . Use either a constant duration of at least 30 ms or the duration in RTOS ticks returned from function ```sht3x_get_measurement_duration``` to wait.
3. Fetch the results as floating point sensor values with function ```sht3x_get_results``` or as raw data with function ```sht3x_get_raw_data```.
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
In this mode, one issued measurement command yields a stream of data pairs. Each data pair consists again of temperature and humidity as 16-bit decimal values. As soon as the measurement command has been sent to the sensor, it automatically performs measurements **periodically at a rate of 0.5, 1, 2, 4 or 10 measurements per second (mps)**. The data pairs can be fetched with the same rate or a lower rate.
As in *single shot mode*, the measurement process is separated into the following steps:
1. Trigger the sensor with function ```sht3x_start_measurement``` with a given rate to start periodic measurements.
2. Wait the measurement duration using function ```vTaskDelay``` until the first results are available . Use either a constant duration of at least 30 ms or the duration in RTOS ticks returned from function ```sht3x_get_measurement_duration``` to wait.
3. Fetch the results as floating point sensor values with function ```sht3x_get_results``` or as raw data with function ```sht3x_get_raw_data```.
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 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
Once new measurement results are available, either function ```sht3x_get_raw_data``` or function ```sht3x_get_results``` can be used to fetch the results.
Function ```_sht3x_get_raw_data``` fetches only raw sensor data in 16-decimal format, checks the CRC checksums and stores them in an byte array of type ```sht3x_raw_data_t```. The user task then can use them directly or to call function ```sht3x_compute_values``` to compute floating point sensor values from them.
Function ```sht3x_get_results``` combines function ```sht3x_read_raw_data``` and function
```sht3x_compute_values``` to get the sensor values. This is the preferred approach to get sensor values by the user task.
## Error Handling
Most driver functions return a simple boolean value to indicate whether its execution was successful or an error happened. In the latter case, the member ```error_code``` of the sensor device data structure is set which indicates what error happened.
There are two different error levels that are ORed into one single ```error_code```, errors in the I2C communication and errors with the SHT3x sensor itself. To test for a certain error you can AND the *error_code* with one of the error masks, ```SHT3x_I2C_ERROR_MASK``` for I2C errors and ```SHT3x_DRV_ERROR_MASK``` for other errors and then test for a certain error code.
## Repeatability
The SHT3x sensor supports **three levels of repeatability** (low, medium and high). Repeatability is the variation in measurement results taken by the sensor under the same conditions, and in a short period of time. It is a measure for the noise on the physical sensor output. The higher the repeatability the smaller are changes in the output of subsequent measurements.
The repeatability settings influences the measurement duration as well as the power consumption of the sensor. The measurement takes 3 ms with low repeatability, 5 ms with medium repeatability and 13.5 ms with high repeatability. That is, the measurement produces a noticeable delay in execution.
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 function ```sht3x_start_measurement```.
## Usage
Before using the SHT3x driver, function ```i2c_init``` needs to be called for each I2C interface to setup them.
```
#include "sht3x/sht3x.h"
...
#define I2C_BUS 0
#define I2C_SCL_PIN GPIO_ID_PIN((5))
#define I2C_SDA_PIN GPIO_ID_PIN((4))
...
i2c_init(I2C_BUS, I2C_SCL_PIN, I2C_SDA_PIN, I2C_FREQ_100K))
...
```
Once I2C interfaces to be used are initialized, function ```sht3x_init_sensor``` has to be called for each SHT3x sensor to initialize the sensor and to check its availability as well as its error state. The parameters specify the I2C bus to which it is connected and its I2C slave address.
```
static sht3x_sensor_t* sensor; // pointer to sensor device data structure
...
if ((sensor = sht3x_init_sensor (I2C_BUS, SHT3x_ADDR_2)))
{
...
}
```
Function ```sht3x_init_sensor``` returns a pointer to the sensor device data structure or NULL in case of error.
Last, the user task that uses the sensor has to be created.
```
xTaskCreate(user_task, "user_task", 256, NULL, 2, 0);
```
In **periodic mode**, the user task has to start the periodic measurement only once at the beginning of the task. After that, it has only to wait for the results of the first measurement. In the task loop itself, it simply fetches the next measurement results in each cycle.
Thus, in this mode the user task could look like the following:
```
void user_task (void *pvParameters)
{
float temperature;
float humidity;
// Start periodic measurements with 1 measurement per second.
sht3x_start_measurement (sensor, sht3x_periodic_1mps, sht3x_high);
// Wait until first 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)
{
// Get the values and do something with them.
if (sht3x_get_results (sensor, &temperature, &humidity))
printf("%.3f SHT3x Sensor: %.2f °C, %.2f %%\n",
(double)sdk_system_get_time()*1e-3, temperature, humidity);
// Wait until 2 seconds (cycle time) are over.
vTaskDelayUntil(&last_wakeup, 2000 / portTICK_PERIOD_MS);
}
}
```
At the beginning of the task, the periodic measurement is started with function ```sht3x_start_measurement``` at high repeatability level and a rate of 1 measurement per second. The task is then delayed with function ```vTaskDelay``` to wait for first measurement results. The duration can be either a constant time of at least 30 ms or the duration returned by ```sht3x_get_measurement_duration```, as in the example. Inside the task loop, simply the measurement results are fetched periodically using function ```sht3x_get_results``` every 2 seconds.
**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.
In **single shot mode**, the measurement has to be triggered
in each cycle. Also the waiting for measurement results is required in each cylce, before the results can be fetched.
Thus the user task could look like the following:
```
void user_task (void *pvParameters)
{
float temperature;
float humidity;
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.
sht3x_start_measurement (sensor, 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 (duration);
// retrieve the values and do something with them
if (sht3x_get_results (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);
}
}
```
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```.
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:
```
if (!sht3x_get_results (sensor, &values))
{
// error happened
switch (sensor->error_code & SHT3x_I2C_ERROR_MASK)
{
case SHT3x_I2C_BUSY: ...
case SHT3x_I2C_READ_FAILED: ...
...
}
switch (sensor->error_code & SHT3x_DRV_ERROR_MASK)
{
case SHT3x_MEAS_NOT_RUNNING: ...
case SHT3x_READ_RAW_DATA_FAILED: ...
case SHT3x_WRONG_CRC_TEMPERATURE: ...
...
}
}
```
## Full Example
```
#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_BUS 0
#define I2C_SCL_PIN GPIO_ID_PIN((5))
#define I2C_SDA_PIN GPIO_ID_PIN((4))
static sht3x_sensor_t* sensor; // sensor device data structure
/*
* User task that triggers a measurement every 5 seconds. Due to
* power efficiency reasons, it uses the SHT3x *sht3x_single_shot*.
*/
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.
sht3x_start_measurement (sensor, 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 (duration);
// retrieve the values and do something with them
if (sht3x_get_results (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);
}
}
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_BUS, I2C_SCL_PIN, I2C_SDA_PIN, I2C_FREQ_100K);
// Create the sensors.
if ((sensor = sht3x_init_sensor (I2C_BUS, SHT3x_ADDR_2)))
{
// Create a user task that uses the sensors.
xTaskCreate(user_task, "user_task", 256, NULL, 2, 0);
}
// That's it.
}
```
## Further Examples
See also the examples in the examples directory [examples directory](../../examples/sht3x/README.md).

9
extras/sht3x/component.mk Normal file
View file

@ -0,0 +1,9 @@
# Component makefile for extras/sht3x
# expected anyone using SHT3x driver includes it as 'sht3x/sht3x.h'
INC_DIRS += $(sht3x_ROOT)..
# args for passing into compile rule generation
sht3x_SRC_DIR = $(sht3x_ROOT)
$(eval $(call component_compile_rules,sht3x))

447
extras/sht3x/sht3x.c Normal file
View file

@ -0,0 +1,447 @@
/*
* Driver for Sensirion SHT3x digital temperature and humidity sensor
* connected to I2C
*
* Part of esp-open-rtos
*
* ----------------------------------------------------------------
*
* 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
*/
#include <string.h>
#include "sht3x.h"
#include "FreeRTOS.h"
#include "task.h"
#include "espressif/esp_common.h"
#include "espressif/sdk_private.h"
#define SHT3x_STATUS_CMD 0xF32D
#define SHT3x_CLEAR_STATUS_CMD 0x3041
#define SHT3x_RESET_CMD 0x30A2
#define SHT3x_FETCH_DATA_CMD 0xE000
#define SHT3x_HEATER_OFF_CMD 0x3066
const uint16_t SHT3x_MEASURE_CMD[6][3] = {
{0x2400,0x240b,0x2416}, // [SINGLE_SHOT][H,M,L] without clock stretching
{0x2032,0x2024,0x202f}, // [PERIODIC_05][H,M,L]
{0x2130,0x2126,0x212d}, // [PERIODIC_1 ][H,M,L]
{0x2236,0x2220,0x222b}, // [PERIODIC_2 ][H,M,L]
{0x2234,0x2322,0x2329}, // [PERIODIC_4 ][H,M,L]
{0x2737,0x2721,0x272a} }; // [PERIODIC_10][H,M,L]
// due to the fact that ticks can be smaller than portTICK_PERIOD_MS, one and
// a half tick period added to the duration to be sure that waiting time for
// the results is long enough
#define TIME_TO_TICKS(ms) (1 + ((ms) + (portTICK_PERIOD_MS-1) + portTICK_PERIOD_MS/2 ) / portTICK_PERIOD_MS)
#define SHT3x_MEAS_DURATION_REP_HIGH 15
#define SHT3x_MEAS_DURATION_REP_MEDIUM 6
#define SHT3x_MEAS_DURATION_REP_LOW 4
// measurement durations in us
const uint16_t SHT3x_MEAS_DURATION_US[3] = { SHT3x_MEAS_DURATION_REP_HIGH * 1000,
SHT3x_MEAS_DURATION_REP_MEDIUM * 1000,
SHT3x_MEAS_DURATION_REP_LOW * 1000 };
// measurement durations in RTOS ticks
const uint8_t SHT3x_MEAS_DURATION_TICKS[3] = { TIME_TO_TICKS(SHT3x_MEAS_DURATION_REP_HIGH),
TIME_TO_TICKS(SHT3x_MEAS_DURATION_REP_MEDIUM),
TIME_TO_TICKS(SHT3x_MEAS_DURATION_REP_LOW) };
#if defined(SHT3x_DEBUG_LEVEL_2)
#define debug(s, f, ...) printf("%s %s: " s "\n", "SHT3x", f, ## __VA_ARGS__)
#define debug_dev(s, f, d, ...) printf("%s %s: bus %d, addr %02x - " s "\n", "SHT3x", f, d->bus, d->addr, ## __VA_ARGS__)
#else
#define debug(s, f, ...)
#define debug_dev(s, f, d, ...)
#endif
#if defined(SHT3x_DEBUG_LEVEL_1) || defined(SHT3x_DEBUG_LEVEL_2)
#define error(s, f, ...) printf("%s %s: " s "\n", "SHT3x", f, ## __VA_ARGS__)
#define error_dev(s, f, d, ...) printf("%s %s: bus %d, addr %02x - " s "\n", "SHT3x", f, d->bus, d->addr, ## __VA_ARGS__)
#else
#define error(s, f, ...)
#define error_dev(s, f, d, ...)
#endif
/** Forward declaration of function for internal use */
static bool sht3x_is_measuring (sht3x_sensor_t*);
static bool sht3x_send_command (sht3x_sensor_t*, uint16_t);
static bool sht3x_read_data (sht3x_sensor_t*, uint8_t*, uint32_t);
static bool sht3x_get_status (sht3x_sensor_t*, uint16_t*);
static bool sht3x_reset (sht3x_sensor_t*);
static uint8_t crc8 (uint8_t data[], int len);
/** ------------------------------------------------ */
bool sht3x_init_driver()
{
return true;
}
sht3x_sensor_t* sht3x_init_sensor(uint8_t bus, uint8_t addr)
{
sht3x_sensor_t* dev;
if ((dev = malloc (sizeof(sht3x_sensor_t))) == NULL)
return NULL;
// inititalize sensor data structure
dev->bus = bus;
dev->addr = addr;
dev->mode = sht3x_single_shot;
dev->meas_start_time = 0;
dev->meas_started = false;
dev->meas_first = false;
uint16_t status;
// reset the sensor
if (!sht3x_reset(dev))
{
error_dev ("could not reset the sensor", __FUNCTION__, dev);
free(dev);
return NULL;
}
// check again the status after clear status command
if (!sht3x_get_status(dev, &status))
{
error_dev ("could not get sensor status", __FUNCTION__, dev);
free(dev);
return NULL;
}
debug_dev ("sensor initialized", __FUNCTION__, dev);
return dev;
}
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;
dev->error_code = SHT3x_OK;
dev->mode = mode;
dev->repeatability = repeat;
// start measurement according to selected mode and return an duration estimate
if (!sht3x_send_command(dev, SHT3x_MEASURE_CMD[mode][repeat]))
{
error_dev ("could not send start measurment command", __FUNCTION__, dev);
dev->error_code |= SHT3x_SEND_MEAS_CMD_FAILED;
return false;
}
dev->meas_start_time = sdk_system_get_time ();
dev->meas_started = true;
dev->meas_first = true;
return true;
}
uint8_t sht3x_get_measurement_duration (sht3x_repeat_t repeat)
{
return SHT3x_MEAS_DURATION_TICKS[repeat]; // in RTOS ticks
}
bool sht3x_get_raw_data(sht3x_sensor_t* dev, sht3x_raw_data_t raw_data)
{
if (!dev || !raw_data) return false;
dev->error_code = SHT3x_OK;
if (!dev->meas_started)
{
debug_dev ("measurement is not started", __FUNCTION__, dev);
dev->error_code = SHT3x_MEAS_NOT_STARTED;
return sht3x_is_measuring (dev);
}
if (sht3x_is_measuring(dev))
{
error_dev ("measurement is still running", __FUNCTION__, dev);
dev->error_code = SHT3x_MEAS_STILL_RUNNING;
return false;
}
// send fetch command in any periodic mode (mode > 0) before read raw data
if (dev->mode && !sht3x_send_command(dev, SHT3x_FETCH_DATA_CMD))
{
debug_dev ("send fetch command failed", __FUNCTION__, dev);
dev->error_code |= SHT3x_SEND_FETCH_CMD_FAILED;
return false;
}
// read raw data
if (!sht3x_read_data(dev, raw_data, sizeof(sht3x_raw_data_t)))
{
error_dev ("read raw data failed", __FUNCTION__, dev);
dev->error_code |= SHT3x_READ_RAW_DATA_FAILED;
return false;
}
// reset first measurement flag
dev->meas_first = false;
// reset measurement started flag in single shot mode
if (dev->mode == sht3x_single_shot)
dev->meas_started = false;
// check temperature crc
if (crc8(raw_data,2) != raw_data[2])
{
error_dev ("CRC check for temperature data failed", __FUNCTION__, dev);
dev->error_code |= SHT3x_WRONG_CRC_TEMPERATURE;
return false;
}
// check humidity crc
if (crc8(raw_data+3,2) != raw_data[5])
{
error_dev ("CRC check for humidity data failed", __FUNCTION__, dev);
dev->error_code |= SHT3x_WRONG_CRC_HUMIDITY;
return false;
}
return true;
}
bool sht3x_compute_values (sht3x_raw_data_t raw_data, float* temperature, float* humidity)
{
if (!raw_data) return false;
if (temperature)
*temperature = ((((raw_data[0] * 256.0) + raw_data[1]) * 175) / 65535.0) - 45;
if (humidity)
*humidity = ((((raw_data[3] * 256.0) + raw_data[4]) * 100) / 65535.0);
return true;
}
bool sht3x_get_results (sht3x_sensor_t* dev, float* temperature, float* humidity)
{
if (!dev || (!temperature && !humidity)) return false;
sht3x_raw_data_t raw_data;
if (!sht3x_get_raw_data (dev, raw_data))
return false;
return sht3x_compute_values (raw_data, temperature, humidity);
}
/* Functions for internal use only */
static bool sht3x_is_measuring (sht3x_sensor_t* dev)
{
if (!dev) return false;
dev->error_code = SHT3x_OK;
// not running if measurement is not started at all or
// it is not the first measurement in periodic mode
if (!dev->meas_started || !dev->meas_first)
return false;
// not running if time elapsed is greater than duration
uint32_t elapsed = sdk_system_get_time() - dev->meas_start_time;
return elapsed < SHT3x_MEAS_DURATION_US[dev->repeatability];
}
static bool sht3x_send_command(sht3x_sensor_t* dev, uint16_t cmd)
{
if (!dev) return false;
uint8_t data[2] = { cmd >> 8, cmd & 0xff };
debug_dev ("send command MSB=%02x LSB=%02x", __FUNCTION__, dev, data[0], data[1]);
int err;
int count = 10;
// in case i2c is busy, try to write up to ten ticks (normally 100 ms)
// tested with a task that is disturbing by using i2c bus almost all the time
while ((err=i2c_slave_write(dev->bus, dev->addr, 0, data, 2)) == -EBUSY && count--)
vTaskDelay (1);
if (err)
{
dev->error_code |= (err == -EBUSY) ? SHT3x_I2C_BUSY : SHT3x_I2C_SEND_CMD_FAILED;
error_dev ("i2c error %d on write command %02x", __FUNCTION__, dev, err, cmd);
return false;
}
return true;
}
static bool sht3x_read_data(sht3x_sensor_t* dev, uint8_t *data, uint32_t len)
{
if (!dev) return false;
int err;
int count = 10;
// in case i2c is busy, try to read up to ten ticks (normally 100 ms)
while ((err=i2c_slave_read(dev->bus, dev->addr, 0, data, len)) == -EBUSY && count--)
vTaskDelay (1);
if (err)
{
dev->error_code |= (err == -EBUSY) ? SHT3x_I2C_BUSY : SHT3x_I2C_READ_FAILED;
error_dev ("error %d on read %d byte", __FUNCTION__, dev, err, len);
return false;
}
# ifdef SHT3x_DEBUG_LEVEL_2
printf("SHT3x %s: bus %d, addr %02x - read following bytes: ",
__FUNCTION__, dev->bus, dev->addr);
for (int i=0; i < len; i++)
printf("%02x ", data[i]);
printf("\n");
# endif
return true;
}
static bool sht3x_reset (sht3x_sensor_t* dev)
{
if (!dev) return false;
debug_dev ("soft-reset triggered", __FUNCTION__, dev);
dev->error_code = SHT3x_OK;
// send reset command
if (!sht3x_send_command(dev, SHT3x_RESET_CMD))
{
dev->error_code |= SHT3x_SEND_RESET_CMD_FAILED;
return false;
}
// wait for small amount of time needed (according to datasheet 0.5ms)
vTaskDelay (100 / portTICK_PERIOD_MS);
uint16_t status;
// check the status after reset
if (!sht3x_get_status(dev, &status))
return false;
return true;
}
static bool sht3x_get_status (sht3x_sensor_t* dev, uint16_t* status)
{
if (!dev || !status) return false;
dev->error_code = SHT3x_OK;
uint8_t data[3];
if (!sht3x_send_command(dev, SHT3x_STATUS_CMD) || !sht3x_read_data(dev, data, 3))
{
dev->error_code |= SHT3x_SEND_STATUS_CMD_FAILED;
return false;
}
*status = data[0] << 8 | data[1];
debug_dev ("status=%02x", __FUNCTION__, dev, *status);
return true;
}
const uint8_t g_polynom = 0x31;
static uint8_t crc8 (uint8_t data[], int len)
{
// initialization value
uint8_t crc = 0xff;
// iterate over all bytes
for (int i=0; i < len; i++)
{
crc ^= data[i];
for (int i = 0; i < 8; i++)
{
bool xor = crc & 0x80;
crc = crc << 1;
crc = xor ? crc ^ g_polynom : crc;
}
}
return crc;
}

279
extras/sht3x/sht3x.h Normal file
View file

@ -0,0 +1,279 @@
/*
* Driver for Sensirion SHT3x digital temperature and humidity sensor
* connected to I2C
*
* Part of esp-open-rtos
*
* ----------------------------------------------------------------
*
* 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.
*/
#ifndef DRIVER_SHT3x_H_
#define DRIVER_SHT3x_H_
#include "stdint.h"
#include "stdbool.h"
#include "FreeRTOS.h"
#include "i2c/i2c.h"
// Uncomment to enable debug output
// #define SHT3x_DEBUG_LEVEL_1 // only error messages
// #define SHT3x_DEBUG_LEVEL_2 // error and debug messages
#ifdef __cplusplus
extern "C" {
#endif
// definition of possible I2C slave addresses
#define SHT3x_ADDR_1 0x44 // ADDR pin connected to GND/VSS (default)
#define SHT3x_ADDR_2 0x45 // ADDR pin connected to VDD
// definition of error codes
#define SHT3x_OK 0
#define SHT3x_NOK -1
#define SHT3x_I2C_ERROR_MASK 0x000f
#define SHT3x_DRV_ERROR_MASK 0xfff0
// error codes for I2C interface ORed with SHT3x error codes
#define SHT3x_I2C_READ_FAILED 1
#define SHT3x_I2C_SEND_CMD_FAILED 2
#define SHT3x_I2C_BUSY 3
// SHT3x driver error codes OR ed with error codes for I2C interface
#define SHT3x_MEAS_NOT_STARTED (1 << 8)
#define SHT3x_MEAS_ALREADY_RUNNING (2 << 8)
#define SHT3x_MEAS_STILL_RUNNING (3 << 8)
#define SHT3x_READ_RAW_DATA_FAILED (4 << 8)
#define SHT3x_SEND_MEAS_CMD_FAILED (5 << 8)
#define SHT3x_SEND_RESET_CMD_FAILED (6 << 8)
#define SHT3x_SEND_STATUS_CMD_FAILED (7 << 8)
#define SHT3x_SEND_FETCH_CMD_FAILED (8 << 8)
#define SHT3x_WRONG_CRC_TEMPERATURE (9 << 8)
#define SHT3x_WRONG_CRC_HUMIDITY (10 << 8)
#define SHT3x_RAW_DATA_SIZE 6
/**
* @brief raw data type
*/
typedef uint8_t sht3x_raw_data_t [SHT3x_RAW_DATA_SIZE];
/**
* @brief possible measurement modes
*/
typedef enum {
sht3x_single_shot = 0, // one single measurement
sht3x_periodic_05mps, // periodic with 0.5 measurements per second (mps)
sht3x_periodic_1mps, // periodic with 1 measurements per second (mps)
sht3x_periodic_2mps, // periodic with 2 measurements per second (mps)
sht3x_periodic_4mps, // periodic with 4 measurements per second (mps)
sht3x_periodic_10mps // periodic with 10 measurements per second (mps)
} sht3x_mode_t;
/**
* @brief possible repeatability modes
*/
typedef enum {
sht3x_high = 0,
sht3x_medium,
sht3x_low
} sht3x_repeat_t;
/**
* @brief SHT3x sensor device data structure type
*/
typedef struct {
uint32_t error_code; // combined error codes
uint8_t bus; // I2C bus at which sensor is connected
uint8_t addr; // I2C slave address of the sensor
sht3x_mode_t mode; // used measurement mode
sht3x_repeat_t repeatability; // used repeatability
bool meas_started; // indicates whether measurement started
uint32_t meas_start_time; // measurement start time in us
bool meas_first; // first measurement in periodic mode
} sht3x_sensor_t;
/**
* @brief Initialize a SHT3x sensor
*
* The function creates a data structure describing the sensor and
* initializes the sensor device.
*
* @param bus I2C bus at which the sensor is connected
* @param addr I2C slave address of the sensor
* @return pointer to sensor data structure, or NULL on error
*/
sht3x_sensor_t* sht3x_init_sensor (uint8_t bus, uint8_t addr);
/**
* @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)
* with given repeatabilty.
*
* In the *single shot mode*, this function has to be called for each
* measurement. The measurement duration has to be waited every time
* before the results can be fetched.
*
* In the *periodic mode*, this function has to be called only once. Also
* 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).
*
* 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*
* @param repeat repeatability, see type *sht3x_repeat_t*
* @return true on success, false on error
*/
bool sht3x_start_measurement (sht3x_sensor_t* dev, sht3x_mode_t mode,
sht3x_repeat_t repeat);
/**
* @brief Get the duration of a measurement in RTOS ticks.
*
* The function returns the duration in RTOS ticks required by the sensor to
* perform a measurement for the given repeatability. Once a measurement is
* started with function *sht3x_start_measurement* the user task can use this
* 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
*/
uint8_t sht3x_get_measurement_duration (sht3x_repeat_t repeat);
/**
* @brief Read measurement results from sensor as raw data
*
* The function read measurement results from the sensor, checks the CRC
* checksum and stores them in the byte array as following.
*
* data[0] = Temperature MSB
* data[1] = Temperature LSB
* data[2] = Temperature CRC
* data[3] = Pressure MSB
* data[4] = Pressure LSB
* data[2] = Pressure CRC
*
* In case that there are no new data that can be read, the function fails.
*
* @param dev pointer to sensor device data structure
* @param raw_data byte array in which raw data are stored
* @return true on success, false on error
*/
bool sht3x_get_raw_data(sht3x_sensor_t* dev, sht3x_raw_data_t raw_data);
/**
* @brief Computes sensor values from raw data
*
* @param raw_data byte array that contains raw data
* @param temperature returns temperature in degree Celsius
* @param humidity returns humidity in percent
* @return true on success, false on error
*/
bool sht3x_compute_values (sht3x_raw_data_t raw_data,
float* temperature, float* humidity);
/**
* @brief Get measurement results in form of sensor values
*
* The function combines function *sht3x_read_raw_data* and function
* *sht3x_compute_values* to get the measurement results.
*
* In case that there are no results that can be read, the function fails.
*
* @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_get_results (sht3x_sensor_t* dev,
float* temperature, float* humidity);
#ifdef __cplusplus
}
#endif
#endif /* DRIVER_SHT3x_H_ */