Skip to content

Commit 8bfec2f

Browse files
RobTillaartRobTillaart
committed
0.3.3 SHT31
1 parent 5c68ece commit 8bfec2f

File tree

6 files changed

+129
-89
lines changed

6 files changed

+129
-89
lines changed

‎libraries/SHT31/README.md‎

Lines changed: 78 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11

22
[![Arduino CI](https://github.com/robtillaart/SHT31/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
3-
[![GitHub release](https://img.shields.io/github/release/RobTillaart/SHT31.svg?maxAge=3600)](https://github.com/RobTillaart/SHT31/releases)
3+
[![JSON check](https://github.com/RobTillaart/SHT31/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/SHT31/actions/workflows/jsoncheck.yml)
4+
[![Arduino-lint](https://github.com/RobTillaart/SHT31/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/SHT31/actions/workflows/arduino-lint.yml)
45
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/SHT31/blob/master/LICENSE)
6+
[![GitHub release](https://img.shields.io/github/release/RobTillaart/SHT31.svg?maxAge=3600)](https://github.com/RobTillaart/SHT31/releases)
57

68

79
# SHT31
810

911
Arduino library for the SHT31 temperature and humidity sensor
1012

11-
Relates to the SHT85 library - https://github.com/RobTillaart/SHT85
13+
Relates to the SHT85 library - https://github.com/RobTillaart/SHT85
1214

1315

1416
## Description
@@ -19,11 +21,11 @@ This library should also work for SHT30 and SHT35 but these are
1921
not tested yet.
2022

2123
| SENSOR | Temperature accuracy | Humidity accuracy |
22-
|:----:|:----:|:----:|
23-
| SHT30 | ~0.3 | 2.0 |
24-
| SHT31 | ~0.3 | 1.5 |
25-
| SHT35 | ~0.2 | 1.5 |
26-
| SHT85 | ~0.2 | 1.5 |
24+
|:------:|:------:|:-----:|
25+
| SHT30 | ~0.3 | 2.0 |
26+
| SHT31 | ~0.3 | 1.5 |
27+
| SHT35 | ~0.2 | 1.5 |
28+
| SHT85 | ~0.2 | 1.5 |
2729

2830

2931
An elaborated library for the SHT31 sensor can be found here
@@ -34,97 +36,110 @@ https://github.com/hawesg/SHT31D_Particle_Photon_ClosedCube
3436

3537
#### Base interface
3638

37-
- **SHT31()** constructor.
38-
- **begin(address, dataPin, clockPin)** begin function for ESP8266 & ESP32;
39+
- **SHT31()** constructor.
40+
- **bool begin(address, dataPin, clockPin)** begin function for ESP8266 & ESP32;
3941
returns false if device address is incorrect or device cannot be reset.
40-
- **begin(address)** for single I2C bus platforms, e.g UNO.
41-
- **begin(address, TwoWire \*wire)** for platforms with multiple I2C busses.
42-
- **read(bool fast = true)** blocks 4 (fast) or 15 (slow) milliseconds + actual read + math.
42+
- **bool begin(address)** for single I2C bus platforms, e.g UNO.
43+
- **bool begin(address, TwoWire \*wire)** for platforms with multiple I2C busses.
44+
- **bool read(bool fast = true)** blocks 4 (fast) or 15 (slow) milliseconds + actual read + math.
4345
Does read both the temperature and humidity.
44-
- **isConnected()** check sensor is reachable over I2C. Returns false if not connected.
45-
- **uint16_t readStatus()** details see datasheet and **Status fields** below
46+
- **bool isConnected()** check sensor is reachable over I2C. Returns false if not connected.
47+
- **uint16_t readStatus()** details see datasheet and **Status fields** below.
4648
- **uint32_t lastRead()** in milliSeconds since start of program.
47-
- **reset(bool hard = false)** resets the sensor, soft reset by default. Returns false if fails.
48-
- **getHumidity()** computes the relative humidity in % based off the latest raw reading, and returns it
49-
- **getTemperature()** computes the temperature in °C based off the latest raw reading, and returns it
50-
- **getRawHumidity()** returns the raw two-byte representation of humidity directly from the sensor
51-
- **getRawTemperature()** returns the raw two-byte representation of temperature directly from the sensor
49+
- **bool reset(bool hard = false)** resets the sensor, soft reset by default. Returns false if fails.
50+
- **float getHumidity()** computes the relative humidity in % based off the latest raw reading, and returns it.
51+
- **float getTemperature()** computes the temperature in °C based off the latest raw reading, and returns it.
52+
- **uint16_t getRawHumidity()** returns the raw two-byte representation of humidity directly from the sensor.
53+
- **uint16_t getRawTemperature()** returns the raw two-byte representation of temperature directly from the sensor.
5254

5355
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.
5456

5557

5658
#### Error interface
5759

58-
- **getError()** returns last set error flag and clear it.
60+
- **int getError()** returns last set error flag and clear it.
5961
Be sure to clear the error flag by calling **getError()** before calling any command as the error flag could be from a previous command.
6062

61-
| Error | Symbolic | Description |
62-
|:----:|:----|:----|
63-
| 0x00 | SHT31_OK | no error |
64-
| 0x81 | SHT31_ERR_WRITECMD | I2C write failed |
65-
| 0x82 | SHT31_ERR_READBYTES | I2C read failed |
66-
| 0x83 | SHT31_ERR_HEATER_OFF | Could not switch off heater |
67-
| 0x84 | SHT31_ERR_NOT_CONNECT | Could not connect |
68-
| 0x85 | SHT31_ERR_CRC_TEMP | CRC error in temperature |
69-
| 0x86 | SHT31_ERR_CRC_HUM | CRC error in humidity |
70-
| 0x87 | SHT31_ERR_CRC_STATUS | CRC error in statusfield |
63+
| Error | Symbolic | Description
64+
|:-----:|:--------------------------|:----------------------------|
65+
| 0x00 | SHT31_OK | no error |
66+
| 0x81 | SHT31_ERR_WRITECMD | I2C write failed |
67+
| 0x82 | SHT31_ERR_READBYTES | I2C read failed |
68+
| 0x83 | SHT31_ERR_HEATER_OFF | Could not switch off heater |
69+
| 0x84 | SHT31_ERR_NOT_CONNECT | Could not connect |
70+
| 0x85 | SHT31_ERR_CRC_TEMP | CRC error in temperature |
71+
| 0x86 | SHT31_ERR_CRC_HUM | CRC error in humidity |
72+
| 0x87 | SHT31_ERR_CRC_STATUS | CRC error in statusfield |
73+
| 0x88 | SHT31_ERR_HEATER_COOLDOWN | Heater need to cool down |
74+
| 0x88 | SHT31_ERR_HEATER_ON | Could not switch on heater |
7175

7276

7377
#### Heater interface
7478

75-
Use the heater for max **180** seconds, and let it cool down an equal period of time.
79+
**WARNING:** Do not use heater for long periods.
7680

77-
**WARNING:** Do not use heater for long periods.
81+
Use the heater for max **180** seconds, and let it cool down **180** seconds = 3 minutes.
82+
Version 0.3.3 and up guards the cool down time by preventing switching the heater on
83+
within **180** seconds of the last switch off. Note: this guarding is not reboot persistent.
84+
85+
**WARNING:** The user is responsible to switch the heater off manually!
7886

79-
**WARNING:** The user is responsible to switch the heater off manually!
8087
The class does **NOT** do this automatically.
88+
Switch off the heater by directly calling **heatOff()** or indirectly by calling **isHeaterOn()**.
8189

82-
- **setHeatTimeout(uint8_t seconds)** Set the time out of the heat cycle.
90+
- **void setHeatTimeout(uint8_t seconds)** Set the time out of the heat cycle.
8391
This value is truncated to max 180 seconds.
84-
- **heatOn()** switches heat cycle on. Returns false if fails.
85-
- **heatOff()** switches heat cycle off. Returns false if fails.
86-
- **isHeaterOn()** is the sensor still in heating cycle? replaces **heatUp()**.
87-
Will switch heat off if max heating time has passed.
88-
- **heatUp()** will be obsolete in the future.
92+
- **uint8_t getHeatTimeout
93+
- **bool heatOn()** switches heat cycle on if not already on.
94+
Returns false if fails, setting error to **SHT31_ERR_HEATER_COOLDOWN**
95+
or to **SHT31_ERR_HEATER_ON**.
96+
- **bool heatOff()** switches heat cycle off.
97+
Returns false if fails, setting error to **SHT31_ERR_HEATER_OFF**.
98+
- **bool isHeaterOn()** is the sensor still in heating cycle? replaces **heatUp()**.
99+
Will switch the heater off if max heating time has passed.
100+
- **bool heatUp()** will be obsolete in the future. replaced by **isHeaterOn()**
89101

90102

91103
#### Async interface
92104

93105
See async example for usage
94106

95-
- **requestData()** requests a new measurement. Returns false if this fails.
96-
- **dataReady()** checks if enough time has passed to read the data. (15 millis)
97-
- **readData(bool fast = true)** fast skips CRC check. Returns false if reading fails or in case of a CRC fail.
107+
- **bool requestData()** requests a new measurement. Returns false if this fails.
108+
- **bool dataReady()** checks if enough time has passed to read the data. (15 milliseconds)
109+
- **bool readData(bool fast = true)** fast = true skips the CRC check.
110+
Returns false if reading fails or in case of a CRC failure.
98111

99112

100113
## Status fields
101114

102-
| BIT | Description | values |
103-
|:----:|:----|:----|
104-
| 15 | Alert pending status | '0': no pending alerts|
105-
| | | '1': at least one pending alert - default |
106-
| 14 | Reserved | '0' |
107-
| 13 | Heater status | '0’ : Heater OFF - default |
108-
| | | '1’ : Heater ON |
109-
| 12 | Reserved | '0' |
110-
| 11 | Humidity tracking alert | '0’ : no alert - default |
111-
| | | '1’ : alert |
112-
| 10 | Temperature tracking alert | '0’ : no alert - default |
113-
| | | '1’ : alert |
114-
| 9-5 | Reserved | '00000' |
115-
| 4 | System reset detected | '0': no reset since last ‘clear status register’ command |
116-
| | | '1': reset detected (hard or soft reset command or supply fail) - default |
117-
| 3-2 | Reserved | '00' |
118-
| 1 | Command status | '0': last cmd executed successfully |
119-
| | | '1': last cmd not processed. Invalid or failed checksum |
120-
| 0 | Write data checksum status | '0': checksum of last write correct |
121-
| | | '1': checksum of last write transfer failed |
115+
| BIT | Description | value | notes |
116+
|:-----|:---------------------------|:--------|:------|
117+
| 15 | Alert pending status | 0 | no pending alerts
118+
| | | 1 | at least one pending alert - default
119+
| 14 | Reserved | 0 |
120+
| 13 | Heater status | 0 | Heater OFF - default
121+
| | | 1 | Heater ON
122+
| 12 | Reserved | 0 |
123+
| 11 | Humidity tracking alert | 0 | no alert - default
124+
| | | 1 | alert
125+
| 10 | Temperature tracking alert | 0 | no alert - default
126+
| | | 1 | alert
127+
| 9-5 | Reserved | 00000 |
128+
| 4 | System reset detected | 0 | no reset since last ‘clear status register’ command
129+
| | | 1 | reset detected (hard or soft reset command or supply fail) - default
130+
| 3-2 | Reserved | 00 |
131+
| 1 | Command status | 0 | last cmd executed successfully
132+
| | | 1 | last cmd not processed. Invalid or failed checksum
133+
| 0 | Write data checksum status | 0 | checksum of last write correct
134+
| | | 1 | checksum of last write transfer failed
122135

123136

124137
## Future
125138

126139
- merge with other SHT sensors if possible
127-
- direct Fahrenheit formula
140+
- direct Fahrenheit formula ?
141+
- improve error handling / status. (all code paths)
142+
128143

129144
## Operation
130145

‎libraries/SHT31/SHT31.cpp‎

Lines changed: 31 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
//
22
// FILE: SHT31.cpp
33
// AUTHOR: Rob Tillaart
4-
// VERSION: 0.3.2
4+
// VERSION: 0.3.3
55
// DATE: 2019-02-08
66
// PURPOSE: Arduino library for the SHT31 temperature and humidity sensor
77
// https://www.adafruit.com/product/2857
@@ -26,6 +26,8 @@
2626
// 0.3.0 2021-01-04 arduino-ci
2727
// 0.3.1 2021-05-27 arduino-lint fixes
2828
// 0.3.2 2021-08-05 expose raw data from sensor
29+
// 0.3.3 2021-08-24 fix #22 prevent heater to switch on too fast.
30+
// update readme
2931

3032

3133
#include "SHT31.h"
@@ -43,15 +45,18 @@
4345

4446
#define SHT31_HEAT_ON 0x306D
4547
#define SHT31_HEAT_OFF 0x3066
46-
48+
#define SHT31_HEATER_TIMEOUT 180000UL // milliseconds
4749

4850
SHT31::SHT31()
4951
{
50-
_addr = 0;
52+
_address = 0;
5153
_lastRead = 0;
5254
rawTemperature = 0;
5355
rawHumidity = 0;
56+
_heatTimeout = 0;
5457
_heaterStart = 0;
58+
_heaterStop = 0;
59+
_heaterOn = false;
5560
_error = SHT31_OK;
5661
}
5762

@@ -63,7 +68,7 @@ bool SHT31::begin(const uint8_t address, const uint8_t dataPin, const uint8_t cl
6368
{
6469
return false;
6570
}
66-
_addr = address;
71+
_address = address;
6772

6873
_wire = &Wire;
6974
if ((dataPin < 255) && (clockPin < 255))
@@ -89,8 +94,8 @@ bool SHT31::begin(const uint8_t address, TwoWire *wire)
8994
{
9095
return false;
9196
}
92-
_addr = address;
93-
_wire = wire;
97+
_address = address;
98+
_wire = wire;
9499
_wire->begin();
95100
return reset();
96101
}
@@ -109,7 +114,7 @@ bool SHT31::read(bool fast)
109114

110115
bool SHT31::isConnected()
111116
{
112-
_wire->beginTransmission(_addr);
117+
_wire->beginTransmission(_address);
113118
int rv = _wire->endTransmission();
114119
if (rv != 0) _error = SHT31_ERR_NOT_CONNECT;
115120
return (rv == 0);
@@ -184,46 +189,56 @@ bool SHT31::reset(bool hard)
184189

185190
void SHT31::setHeatTimeout(uint8_t seconds)
186191
{
187-
_heatTimeOut = seconds;
188-
if (_heatTimeOut > 180) _heatTimeOut = 180;
192+
_heatTimeout = seconds;
193+
if (_heatTimeout > 180) _heatTimeout = 180;
189194
}
190195

191196

192197
bool SHT31::heatOn()
193198
{
199+
if (isHeaterOn()) return true;
200+
if ((_heaterStop > 0) && (millis() - _heaterStop < SHT31_HEATER_TIMEOUT))
201+
{
202+
_error = SHT31_ERR_HEATER_COOLDOWN;
203+
return false;
204+
}
194205
if (writeCmd(SHT31_HEAT_ON) == false)
195206
{
207+
_error = SHT31_ERR_HEATER_ON;
196208
return false;
197209
}
198210
_heaterStart = millis();
211+
_heaterOn = true;
199212
return true;
200213
}
201214

202215

203216
bool SHT31::heatOff()
204217
{
218+
// always switch off the heater - ignore _heaterOn flag.
205219
if (writeCmd(SHT31_HEAT_OFF) == false)
206220
{
207221
_error = SHT31_ERR_HEATER_OFF; // can be serious!
208222
return false;
209223
}
210-
_heaterStart = 0;
224+
_heaterStop = millis();
225+
_heaterOn = false;
211226
return true;
212227
}
213228

214229

215230
bool SHT31::isHeaterOn()
216231
{
217-
if (_heaterStart == 0)
232+
if (_heaterOn == false)
218233
{
219234
return false;
220235
}
221236
// did not exceed time out
222-
if (millis() - _heaterStart < (_heatTimeOut * 1000UL))
237+
if (millis() - _heaterStart < (_heatTimeout * 1000UL))
223238
{
224239
return true;
225240
}
226-
heatOff(); // should this be done here?
241+
heatOff();
227242
return false;
228243
}
229244

@@ -268,7 +283,7 @@ bool SHT31::readData(bool fast)
268283
}
269284

270285
rawTemperature = (buffer[0] << 8) + buffer[1];
271-
rawHumidity = (buffer[3] << 8) + buffer[4];
286+
rawHumidity = (buffer[3] << 8) + buffer[4];
272287

273288
_lastRead = millis();
274289

@@ -307,7 +322,7 @@ uint8_t SHT31::crc8(const uint8_t *data, uint8_t len)
307322

308323
bool SHT31::writeCmd(uint16_t cmd)
309324
{
310-
_wire->beginTransmission(_addr);
325+
_wire->beginTransmission(_address);
311326
_wire->write(cmd >> 8 );
312327
_wire->write(cmd & 0xFF);
313328
if (_wire->endTransmission() != 0)
@@ -321,7 +336,7 @@ bool SHT31::writeCmd(uint16_t cmd)
321336

322337
bool SHT31::readBytes(uint8_t n, uint8_t *val)
323338
{
324-
int rv = _wire->requestFrom(_addr, (uint8_t) n);
339+
int rv = _wire->requestFrom(_address, (uint8_t) n);
325340
if (rv == n)
326341
{
327342
for (uint8_t i = 0; i < n; i++)

0 commit comments

Comments
 (0)