Crate shtcx

Expand description

Introduction

This is a platform agnostic Rust driver for the Sensirion SHTCx temperature / humidity sensor series, based on the embedded-hal traits.

Supported Devices

Tested with the following sensors:

SHTC1
SHTC3

The following sensors were not tested, but should work out-of-the-box:

SHTW2

This driver provides blocking and non-blocking calls. The blocking calls delay the execution until the measurement is done and return the results. The non-blocking ones just start the measurement and allow the application code to do other stuff and get the results afterwards.

Clock Stretching

While the sensor would provide measurement commands with clock stretching to indicate when the measurement is done, this is not implemented and probably won’t be.

Examples

There are a few examples in the examples directory: The linux-<target> example queries the sensor a few times using linux-embedded-hal, while the monitor-<target> example implements a terminal based real-time graphical temperature/humidity monitoring tool.

gif

Usage

Setup

Instantiate a new driver instance using a blocking I²C HAL implementation and a blocking Delay instance. For example, using linux-embedded-hal and an SHTC3 sensor:

use linux_embedded_hal::{Delay, I2cdev};
use shtcx;

let dev = I2cdev::new("/dev/i2c-1").unwrap();
let mut sht = shtcx::shtc3(dev);

Device Info

Then, you can query information about the sensor:

let device_id = sht.device_identifier().unwrap();
let raw_id = sht.raw_id_register().unwrap();

Measurements (Blocking)

For measuring your environment, you can either measure just temperature, just humidity, or both:

use shtcx::PowerMode;
let mut delay = Delay;

let temperature = sht.measure_temperature(PowerMode::NormalMode, &mut delay).unwrap();
let humidity = sht.measure_humidity(PowerMode::NormalMode, &mut delay).unwrap();
let combined = sht.measure(PowerMode::NormalMode, &mut delay).unwrap();

println!("Temperature: {} °C", temperature.as_degrees_celsius());
println!("Humidity: {} %RH", humidity.as_percent());
println!("Combined: {} °C / {} %RH",
         combined.temperature.as_degrees_celsius(),
         combined.humidity.as_percent());

You can also use the low power mode for less power consumption, at the cost of reduced repeatability and accuracy of the sensor signals. For more information, see the “Low Power Measurement Mode” application note.

let mut delay = Delay;
let measurement = sht.measure(PowerMode::LowPower, &mut delay).unwrap();

Measurements (Non-Blocking)

If you want to avoid blocking measurements, you can use the non-blocking commands instead. You are, however, responsible for ensuring the correct timing of the calls.

use shtcx::PowerMode;

sht.start_measurement(PowerMode::NormalMode).unwrap();
// Wait for at least `max_measurement_duration(&sht, PowerMode::NormalMode)` µs
let result = sht.get_measurement_result().unwrap();

In non-blocking mode, if desired, you can also read the raw 16-bit measurement results from the sensor by using the following two methods instead:

The raw values are of type u16. They require a conversion formula for conversion to a temperature / humidity value (see datasheet).

Low Power Mode

Some of the sensors (e.g. the SHTC3, but not the SHTC1) support a low power mode, where the sensor can be set to sleep mode when in idle state.

For this, the LowPower trait needs to be imported:

use shtcx::LowPower;

Then you can send the sensor to sleep and wake it up again before triggering a new measurement:

let mut delay = Delay;
sht.sleep().unwrap();
// ...
sht.wakeup(&mut delay).unwrap();

Invoking any command other than wakeup while the sensor is in sleep mode will result in an error.

Soft Reset

The SHTCx provides a soft reset mechanism that forces the system into a well-defined state without removing the power supply. If the system is in its idle state (i.e. if no measurement is in progress) the soft reset command can be sent. This triggers the sensor to reset all internal state machines and reload calibration data from the memory.

let mut delay = Delay;
sht.reset(&mut delay).unwrap();

Generic Driver

The shtcx driver supports use cases where the exact model of the sensor is not known in advance. In that case, use the generic factory function to create an instance of the driver that supports all features available in all supported sensor types.

Note however that sending commands to sensors that don’t implement them (e.g. sending a sleep-command to an SHTC1 sensor) will result in a runtime error. Furthermore, maximal timing tolerances will be ensured, so using the generic driver with the SHTC3 will result in slightly slower measurements (and slightly higher power consumption) than when using the SHTC3 specific driver.