robtillaart / sht31

Arduino library for the SHT31 temperature and humidity sensor

SHT31

Arduino library for the SHT31 temperature and humidity sensor.

Relates to the SHT85 library - https://github.com/RobTillaart/SHT85

Description

The SHT3x family of sensors should work up to 1 MHz I2C

This library should also work for SHT30 and SHT35 but these are not tested yet.

Accuracy table

SENSOR	Temperature	Humidity
SHT30	~0.3	2.0
SHT31	~0.3	1.5
SHT35	~0.2	1.5
SHT85	~0.2	1.5

An elaborated library for the SHT31 sensor can be found here

• https://github.com/hawesg/SHT31D_Particle_Photon_ClosedCube

A derived class for using the SHT31 sensor with SoftWire (soft I2C) can be found here

• https://github.com/RobTillaart/SHT31_SW

0.5.0 Breaking change

Version 0.5.0 introduced a breaking change. You cannot set the pins in begin() any more. This reduces the dependency of processor dependent Wire implementations. The user has to call Wire.begin() and can optionally set the Wire pins before calling begin().

Related

• https://github.com/RobTillaart/SHT31
• https://github.com/RobTillaart/SHT31_SW
• https://github.com/RobTillaart/SHT31_SWW
• https://github.com/RobTillaart/SHT85

Interface

#include "SHT31.h"

Constructor

• SHT31(uint8_t address = SHT_DEFAULT_ADDRESS, TwoWire *wire = &Wire) constructor. Optional select address and the I2C bus (Wire, Wire1 etc).
• bool begin() Returns false if device address is incorrect or device cannot be reset.
• bool isConnected() check sensor is reachable over I2C. Returns false if not connected.
• uint8_t getAddress() returns address set in the constructor.

Read

• bool read(bool fast = true) blocks 4 (fast) or 15 (slow) milliseconds + actual read + math. Does read both the temperature and humidity.
• uint16_t readStatus() details see datasheet and Status fields below.
• uint32_t lastRead() in milliSeconds since start of program.
• bool reset(bool hard = false) resets the sensor, soft reset by default. Returns false if it fails.
• float getHumidity() computes the relative humidity in % based on the latest raw reading, and returns it.
• float getTemperature() computes the temperature in °C based on the latest raw reading, and returns it.
• float getFahrenheit() computes the temperature in °F based on the latest raw reading, and returns it..
• uint16_t getRawHumidity() returns the raw two-byte representation of humidity directly from the sensor.
• uint16_t getRawTemperature() returns the raw two-byte representation of temperature directly from the sensor.

Note that the temperature and humidity values are recalculated on every call to getHumidity() and getTemperature(). If you're worried about the extra cycles, you should make sure to cache these values or only request them after you've performed a new reading.

Error interface

• int getError() returns last set error flag and clear it. Be sure to clear the error flag by calling getError() before calling any command as the error flag could be from a previous command.

Error	Symbolic	Description
0x00	SHT31_OK	no error
0x81	SHT31_ERR_WRITECMD	I2C write failed
0x82	SHT31_ERR_READBYTES	I2C read failed
0x83	SHT31_ERR_HEATER_OFF	Could not switch off heater
0x84	SHT31_ERR_NOT_CONNECT	Could not connect
0x85	SHT31_ERR_CRC_TEMP	CRC error in temperature
0x86	SHT31_ERR_CRC_HUM	CRC error in humidity
0x87	SHT31_ERR_CRC_STATUS	CRC error in status field
0x88	SHT31_ERR_HEATER_COOLDOWN	Heater need to cool down
0x88	SHT31_ERR_HEATER_ON	Could not switch on heater

Heater interface

WARNING: Do not use heater for long periods.

Use the heater for max 180 seconds, and let it cool down 180 seconds = 3 minutes. Version 0.3.3 and up guards the cool down time by preventing switching the heater on within 180 seconds of the last switch off. Note: this guarding is not reboot persistent.

WARNING: The user is responsible to switch the heater off manually!

The class does NOT do this automatically. Switch off the heater by directly calling heatOff() or indirectly by calling isHeaterOn().

• void setHeatTimeout(uint8_t seconds) Set the time out of the heat cycle. This value is truncated to max 180 seconds.
• **uint8_t getHeatTimeout
• bool heatOn() switches heat cycle on if not already on. Returns false if fails, setting error to SHT31_ERR_HEATER_COOLDOWN or to SHT31_ERR_HEATER_ON.
• bool heatOff() switches heat cycle off. Returns false if fails, setting error to SHT31_ERR_HEATER_OFF.
• bool isHeaterOn() is the sensor still in heating cycle? replaces heatUp(). Will switch the heater off if max heating time has passed.
• bool heatUp() will be obsolete in the future. replaced by isHeaterOn()

Async interface

See async example for usage

• bool requestData() requests a new measurement. Returns false if this fails.
• bool dataReady() checks if enough time has passed to read the data. (15 milliseconds)
• bool readData(bool fast = true) fast = true skips the CRC check. Returns false if reading fails or in case of a CRC failure.

Status fields

BIT	Description	value	notes
15	Alert pending status	0	no pending alerts
		1	at least one pending alert - default
14	Reserved	0
13	Heater status	0	Heater OFF - default
		1	Heater ON
12	Reserved	0
11	Humidity tracking alert	0	no alert - default
		1	alert
10	Temperature tracking alert	0	no alert - default
		1	alert
9-5	Reserved	00000
4	System reset detected	0	no reset since last ‘clear status register’ command
		1	reset detected (hard or soft reset command or supply fail) - default
3-2	Reserved	00
1	Command status	0	last command executed successfully
		1	last command not processed. Invalid or failed checksum
0	Write data checksum status	0	checksum of last write correct
		1	checksum of last write transfer failed

Operation

See examples.

Future

Must

• keep in sync with SHT85 library.
• keep derived SHT31_SW builds green

Should

• check TODO in code.
• rename MAGIC numbers. e.g. in dataReady()

Could

• move code from .h to .cpp

Wont

Support

If you appreciate my libraries, you can support the development and maintenance. Improve the quality of the libraries by providing issues and Pull Requests, or donate through PayPal or GitHub sponsors.

Thank you,

sht31's Issues

Return 0.0C and 0.0%

Hi, I'm using an Heltec Wireless Stick (ESP32 LoRa, wifi, ble etc).
I wired the sensor and launched the SHT31_IsCOnnected.ino but the result is
23:08:36.642 -> 194035 160 0.0 0.0
23:08:37.644 -> 195035 160 0.0 0.0
23:08:38.644 -> 196035 160 0.0 0.0
23:08:39.644 -> 197035 160 0.0 0.0
23:08:40.644 -> 198035 160 0.0 0.0
23:08:41.648 -> 199035 160 0.0 0.0
23:08:42.660 -> 200035 160 0.0 0.0
23:08:43.660 -> 201035 160 0.0 0.0
23:08:44.661 -> 202035 160 0.0 0.0
23:08:45.661 -> 203035 160 0.0 0.0

what I wrong?
Thank you, bye

SHT31 library two I2C interfaces: example, advice needed

Hi Rob,

I have a custom ATSAMD21G18A based board where I try to read 4 SHT31 sensors connected to 2 I2C interfaces.
I have had no luck with Adafruit_SHT31.h library reading both them (switching back and forth to read).

If I declare TwoWire myWire(&sercom5, 16, 17); , I can read only sensors in the second I2C interface.
If I leave out the declaration, I can read only sensors in default I2C interface.

Your library mentions:

• begin(address, TwoWire *wire) for platforms with multiple I2C busses.

Does it mean I could accomplish the task of reading from 2 I2C interfaces with your library?
Could you give an example how to do it exactly? How to switch back on forth reading with 2 interfaces?

Thanks,
Tipo

Heater

Hi, how to effectively use a heater in a real environment? Should it be full time on?

prototype for 'bool SHT31::begin(uint8_t, uint8_t, uint8_t)' does not match any in class 'SHT31'

I tried to compile the example SHT31_I2Cspeed but get a compiler-error

That's what I love best about "examples" if not even the examples compile
heres the full error-message

`C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:47:6: error: prototype for 'bool SHT31::begin(uint8_t, uint8_t, uint8_t)' does not match any in class 'SHT31'

bool SHT31::begin(const uint8_t address, const uint8_t dataPin, const uint8_t clockPin)

  ^

In file included from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:21:0:

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.h:35:8: error: candidates are: bool SHT31::begin(uint8_t, TwoWire*)

bool begin(const uint8_t address, TwoWire *wire);

    ^

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.h:34:8: error: bool SHT31::begin(uint8_t)

bool begin(const uint8_t address);

    ^

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.h:32:8: error: void SHT31::begin(uint8_t, uint8_t, uint8_t)

void begin(const uint8_t address, uint8_t dataPin, uint8_t clockPin);

    ^

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp: In member function 'void SHT31::setHeatTimeout(uint8_t)':

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:137:34: error: no matching function for call to 'min(int, uint8_t&)'

_heatTimeOut = min(180, seconds);

                              ^

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:137:34: note: candidates are:

In file included from c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\algorithm:62:0,

             from C:\Users\Stefan\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.6.3\cores\esp8266/Arduino.h:237,

             from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.h:12,

             from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:21:

c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\bits\stl_algo.h:4226:5: note: template<class _Tp, class _Compare> _Tp std::min(std::initializer_list<_Tp>, _Compare)

 min(initializer_list<_Tp> __l, _Compare __comp)

 ^

c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\bits\stl_algo.h:4226:5: note: template argument deduction/substitution failed:

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:137:34: note: mismatched types 'std::initializer_list<_Tp>' and 'int'

_heatTimeOut = min(180, seconds);

                              ^

In file included from c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\algorithm:62:0,

             from C:\Users\Stefan\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.6.3\cores\esp8266/Arduino.h:237,

             from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.h:12,

             from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:21:

c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\bits\stl_algo.h:4221:5: note: template _Tp std::min(std::initializer_list<_Tp>)

 min(initializer_list<_Tp> __l)

 ^

c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\bits\stl_algo.h:4221:5: note: template argument deduction/substitution failed:

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:137:34: note: mismatched types 'std::initializer_list<_Tp>' and 'int'

_heatTimeOut = min(180, seconds);

                              ^

In file included from c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\algorithm:61:0,

             from C:\Users\Stefan\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.6.3\cores\esp8266/Arduino.h:237,

             from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.h:12,

             from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:21:

c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\bits\stl_algobase.h:239:5: note: template<class _Tp, class _Compare> const _Tp& std::min(const _Tp&, const _Tp&, _Compare)

 min(const _Tp& __a, const _Tp& __b, _Compare __comp)

 ^

c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\bits\stl_algobase.h:239:5: note: template argument deduction/substitution failed:

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:137:34: note: deduced conflicting types for parameter 'const _Tp' ('int' and 'uint8_t {aka unsigned char}')

_heatTimeOut = min(180, seconds);

                              ^

In file included from c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\algorithm:61:0,

             from C:\Users\Stefan\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.6.3\cores\esp8266/Arduino.h:237,

             from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.h:12,

             from C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:21:

c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\bits\stl_algobase.h:193:5: note: template const _Tp& std::min(const _Tp&, const _Tp&)

 min(const _Tp& __a, const _Tp& __b)

 ^

c:\users\stefan\appdata\local\arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-4-b40a506\xtensa-lx106-elf\include\c++\4.8.2\bits\stl_algobase.h:193:5: note: template argument deduction/substitution failed:

C:\Users\Stefan\Documents\Arduino\libraries\SHT31\SHT31.cpp:137:34: note: deduced conflicting types for parameter 'const _Tp' ('int' and 'uint8_t {aka unsigned char}')

_heatTimeOut = min(180, seconds);

                              ^

Bibliothek Wire in Version 1.0 im Ordner: C:\Users\Stefan\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.6.3\libraries\Wire wird verwendet
Bibliothek SHT31 in Version 0.2.1 im Ordner: C:\Users\Stefan\Documents\Arduino\libraries\SHT31 wird verwendet
exit status 1
Fehler beim Kompilieren für das Board Generic ESP8266 Module.
`

isConnected returns true if voltaje to SHT31 is not connected.

Hello!

I'm making a small tester for an SHT31 that passes though a connector. I'm making a small test to check if the connetor is well made. I tried using the isConnected function and simulate different connection errors and turns out that the funcion returns true when no power is provided to the sensor.

Is this normal or there is an issue?

Using an Arduino Nano board and a common SHT31 sensor board. To trigger this issue, just attach or detach the respective pins

Regards!

SHT31tester.zip

SHT31 library with Arduino-ESP32 v2.0.5

Hi Rob,

I recently installed your library for my ESP32 T-Beam which I am building with the arduino-esp32 v1.0.6 (from this url). Everything works fine!
However, I decided to update the arduino-esp32 version to 2.0.5 and same code does not work.
This is the conflicting code itself:

SensorX::SensorX() {
    Wire.begin();
    bool sht_begin = sht.begin(SHT31_ADDRESS);
    sht.reset();
    Wire.setClock(100000);
}

When commenting sht (declared as SHT31 sht;) calls, the rest of the code continues working.

I am using SHT31 v0.3.4 and TinyWireM v1.1.0.

Any help?

Exposing the raw temperature and humidity?

Hi there! I'm using your awesome library for a low-power wireless temperature sensor I'm building.

To save power on my wireless node, I want to transmit the raw two-byte values for temperature and humidity instead of the four-byte floats. Would you be open to a PR that:

• Saves those raw values and exposes them
• Moves the conversion to actual floating point values to the getTemperature() and getHumidity() functions?
• Optionally: create a pair of boolean flags _needToRecomputeTemp/_needToRecomputeHumidity that are set to True when the raw values are read in readData(bool). Then, every time getTemperature() or getHumidity() check those flags and if they're true, then recompute the value based off the raw two-byte values, store it in the appropriate variable, and set the flag to false, so that if getTemperature() or getHumidity() is called again, we skip redundant recomputation and just return the cached value.

WDYT?

If this is all too complicated for you and you'd rather not accept a PR like this, no worries--I can always fork the library for my own purposes. I just thought since I was going to do the work anyway, I'd offer to share it back upstream.

Question on i2c error handling

Do you have a suggested way of handling errors? I didn't see it in the examples.

Currently I am checking the status and if its less that FFFF then I am assuming I found the sensor.

I am using the sht31 on a probe that can be plugged or unplugged and I noticed that during an unplug I got invalid data as it probably interrupted the read stream. The humidity then showed 100 and the temp showed 1085. Is there a way to to check if the data read back is valid?

SoftWire library + SHT31 library

Hi, Rob!
I have: Arduino ATmega2560, 4 pcs SHT31.
2 sensors (addr. 0x44 and 0x45) connect to hardware I2C, with you library and wire,
2 senors (addr. 0x44 and 0x45) connect to software I2C, with library https://github.com/felias-fogg/SoftI2CMaster (SoftWire.h)
Everything works fine! But ...I can't make friends SoftWire + SHT31 libraries, to use all the charms of your library.
You could contact the author: https://github.com/felias-fogg and develop a joint decision? or specify me the possible solutions.
Thank you in advance.

Using SHT31 in High Humidity Environment

I'm planning on using an SHT31 in an environment that's 70 - 100% humidity, I was going to leave the heater on permanently to keep condensation away from the sensor (To both extend its lifespan and provide more accurate humidity readings) and then calculate/compensate for the increased temperature and decreased humidity in code, but I see you have a warning about leaving the heater on for long periods.

Do you have any recommendations (in your experience) with using the heater long term? Is there a minimum heat up and cool down period before taking readings?

Add lastHeaterStopTime variable to prevent switching on the heater too early

Goal is to prevent that the heater is switched on after it just have been switched of.

The library cannot prevent heating over reboots, but at least it can in normal operation.

if this works the SHT85 needs similar fix.

check SHT2x functions added

check latest PR

support Wire2 for ESP32

Move TwoWire from begin to constructor