SHT3x Humidity and Temperature Sensor Series

Device Driver for Sensirion SHT30/SHT31/SHT35 Humidity and Temperature Sensors. More...

Detailed Description

Device Driver for Sensirion SHT30/SHT31/SHT35 Humidity and Temperature Sensors.

Driver for SHT3x Digital Temperature and Humidity Sensors

The driver is for the usage with RIOT-OS. It supports the Sensirion SHT30, SHT31, and SHT35 digital temperature and humidity sensors.

About the sensors

SHT3x are a digital temperature and humidity sensors that use an I2C interface with up to 1 MHz communication speed. They can operate with three levels of repeatability (sht3x_repeat_t)

and in two different modes (sht3x_mode_t)

In periodic mode, the SHT3x sensors support an Alert Mode, which allows to define temperature and humidity limits and indicate an alert by a dedicated ALERT pin or a status flag if any of the limits is reached reached.

Note
The Alert Mode is not yet supported.

Measurement process

Once a SHT3x sensor is initialized using the sht3x_init function, 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 16 ms, the measurement process is separated into steps to avoid blocking of the system during measurements:

  1. Send a measurement command to the sensor to start exactly one single measurement.
  2. Wait for the sensor to complete the measurement depending on the configured repeatability.
  3. Fetch the results.

For convenience the high level function sht3x_read comprises all three steps above in only one function to perform a measurement.

Note
Since in single-shot measurement mode the measurement is only started when sht3x_read function is called, it delays the calling task up to 16 ms, depending on the configured repeatability, in order to wait for the results of the measurement.

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. Send a measurement command to the sensor to start periodic measurements.
  2. Wait for the sensor to complete the measurement depending on the configured repeatability and measurement period.
  3. Fetch the results.

While periodic measurement is started (step 1) already in the sht3x_init function, the application has to call the sht3x_read function on a regular base to fetch the results from last periodic measurement. Possible periodic measurement modes are defined by sht3x_mode_t.

Note
The sht3x_read function should be called less frequently than the periodic measurements are performed. Otherwise, the function implicitly delays the calling task until the results of the next measurement cycle become available to avoid data underrun and sensor blocking.

Measurement results

Once new measurement results are available, the sht3x_read function

These measured data are:

For either the temp or hum parameter also NULL can be passed, if only one value is of interest.

Error Handling

All driver functions return 0 on success or one of a negative error code defined by sht3x_error_codes.

Repeatability

The SHT3x sensor supports three levels of repeatability (low, medium and high). The stated repeatability is 3 times the standard deviation of multiple consecutive measurements at the stated repeatability and at constant ambient conditions. It is a measure for the noise on the physical sensor output. Different measurement modes allow for high/medium/low repeatability. Datasheet SHT3x-DIS

The repeatability settings influences the measurement duration as well as the power consumption of the sensor. The measurement takes typically 2.5 ms with low repeatability, 4.5 ms with medium repeatability and 12.5 ms with high repeatability. That is, the measurement produces a noticeable delay in execution.

Reapeatability T typ. RH typ. Maximum Measurement Duration
high 0.04 0.08 15.5 ms
medium 0.08 0.15 6.5 ms
low 0.15 0.21 4.5 ms

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.

Possible repeatabilities are defined by sht3x_repeat_t.

Usage

Before using the SHT3x driver, the configuration has to be defined and the sht3x_init function needs to be called to initialize and configure the sensor device of type sht3x_dev_t.

The structure of a configuration is defined in sht3x_params_t and consists of the following parameters:

Parameter Symbol Default
I2C device SHT3X_PARAM_I2C_DEV I2C_DEV(0)
I2C address SHT3X_PARAM_I2C_ADDR SHT3X_I2C_ADDR_2
Measurement mode SHT3X_PARAM_MODE SHT3X_PERIODIC_2_MPS
Repeatability SHT3X_PARAM_REPEAT SHT3X_HIGH

The default configuration is defined sht3x_params.h and can be overridden by the application before including sht3x_params.h.

Example:

#define SHT3X_PARAM_MODE (SHT3X_SINGLE_SHOT)
#define SHT3X_PARAM_REPEAT (SHT3X_MEDIUM)
...
#include "sht3x.h"
#include "sht3x_params.h"
...

The sht3x_init function has to be called for each SHT3x sensor to initialize the sensor and to check its availability as well as its error state.

if ((res = sht3x_init(&dev, &sht3x_params[0])) != SHT3X_OK) {
... /* error handling */
}

Parameter sht3x_params is also defined by default in file sht3x_params.h and can be overridden by the application before including sht3x_params.h.

Example:

...
#include "sht3x.h"
#include "sht3x_params.h"
...
#define SHT3X_PARAMS { .i2c_dev = I2C_DEV(0), \
.i2c_addr = SHT3X_I2C_ADDR_1, \
.repeat = SHT3X_HIGH \
}, \
{ .i2c_dev = I2C_DEV(0), \
.i2c_addr = SHT3X_I2C_ADDR_2, \
.mode = SHT3X_SINGLE_SHOT, \
.repeat = SHT3X_LOW \
}, \
...
sht3x_dev_t dev1;
if ((res = sht3x_init(&dev1, &sht3x_params[0])) != SHT3X_OK) {
... /* error handling */
}
if ((res = sht3x_init(&dev2, &sht3x_params[1])) != SHT3X_OK) {
... /* error handling */
}

In this example the configuration for two devices is defined.

Once the sensor devices are initialized and configured, the sht3x_read function can be used to read measurement results from the sensor.

Example:

while (1) {
int16_t temp;
int16_t hum;
if ((res = sht3x_read(&dev, &temp, &hum)) == SHT3X_OK) {
printf("Temperature [°C]: %d.%d\n"
"Relative Humidity [%%]: %d.%d\n"
"+-------------------------------------+\n",
temp / 100, temp % 100,
hum / 100, hum % 100);
}
else {
printf("Could not read data from sensor, error %d\n", res);
}
xtimer_usleep(1000000);
}

Files

file  sht3x.h
 Device Driver for Sensirion SHT30/SHT31/SHT35 Humidity and Temperature Sensors.
 
file  sht3x_params.h
 Default configuration for Sensirion SHT30/SHT31/SHT35 devices.
 
sht3x_init
int sht3x_init(sht3x_dev_t *dev, const sht3x_params_t *params)
Initialize the SHT3x sensor device.
sht3x_params
static const sht3x_params_t sht3x_params[]
SHT3x configuration.
Definition: sht3x_params.h:61
SHT3X_HIGH
@ SHT3X_HIGH
high repeatability
Definition: sht3x.h:76
SHT3X_I2C_ADDR_1
#define SHT3X_I2C_ADDR_1
possible I2C slave addresses
Definition: sht3x.h:30
SHT3X_LOW
@ SHT3X_LOW
low repeatability
Definition: sht3x.h:78
I2C_DEV
#define I2C_DEV(x)
Default I2C device access macro.
Definition: i2c.h:133
sht3x_read
int sht3x_read(sht3x_dev_t *dev, int16_t *temp, int16_t *hum)
Read SHT3x measurement results (temperature and humidity)
SHT3X_SINGLE_SHOT
@ SHT3X_SINGLE_SHOT
single shot measurement
Definition: sht3x.h:48
xtimer_usleep
static void xtimer_usleep(uint32_t microseconds)
Pause the execution of a thread for some microseconds.
sht3x_params.h
Default configuration for Sensirion SHT30/SHT31/SHT35 devices.
sht3x_dev_t
SHT3x sensor device data structure.
Definition: sht3x.h:95
SHT3X_I2C_ADDR_2
#define SHT3X_I2C_ADDR_2
ADDR pin connected to VDD.
Definition: sht3x.h:31
SHT3X_OK
@ SHT3X_OK
no error
Definition: sht3x.h:37
SHT3X_PERIODIC_2_MPS
@ SHT3X_PERIODIC_2_MPS
periodic with 2 measurements per second (mps)
Definition: sht3x.h:51