add clearStatus() (#43)

- add **clearStatus()**, kudos to Elbandi
- update readme.md
- removed **heatUp** from documentation, labelled as depreciated.
- add example SHT31_demo_plotter.ino
- update keywords.txt
- minor edits

Author: RobTillaart

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.5.1] - 2025-04-28
+- add **clearStatus()**, kudos to Elbandi
+- update readme.md
+- removed **heatUp** from documentation, labelled as depreciated.
+- add example SHT31_demo_plotter.ino
+- update keywords.txt
+- minor edits
+
 ## [0.5.0] - 2023-12-09
 - refactor API, constructor and begin()
 - add **getAddress()**

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019-2024 Rob Tillaart
+Copyright (c) 2019-2025 Rob Tillaart
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -18,19 +18,19 @@ Relates to the SHT85 library - https://github.com/RobTillaart/SHT85
 
 ## Description
 
-The SHT3x family of sensors should work up to 1 MHz I2C
+The SHT3x family of sensors should work up to 1 MHz I2C.
 
-This library should also work for SHT30 and SHT35 but these are 
+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       |
+|  Sensor  |  Temperature  |  Humidity  |  Verified  }
+|:--------:|:-------------:|:----------:|:----------:|
+|   SHT30  |      ~0.3°    |     2.0%   |     N      |
+|   SHT31  |      ~0.3°    |     1.5%   |     Y      |
+|   SHT35  |      ~0.2°    |     1.5%   |     N      |
+|   SHT85  |      ~0.2°    |     1.5%   |     Y      |
 
 
 An elaborated library for the SHT31 sensor can be found here
@@ -40,7 +40,25 @@ A derived class for using the SHT31 sensor with SoftWire (soft I2C) can be found
 - https://github.com/RobTillaart/SHT31_SW
 
 
-#### 0.5.0 Breaking change
+### I2C multiplexing
+
+Sometimes you need to control more devices than possible with the default
+address range the device provides.
+This is possible with an I2C multiplexer e.g. TCA9548 which creates up
+to eight channels (think of it as I2C subnets) which can use the complete
+address range of the device.
+
+Drawback of using a multiplexer is that it takes more administration in
+your code e.g. which device is on which channel.
+This will slow down the access, which must be taken into account when
+deciding which devices are on which channel.
+Also note that switching between channels will slow down other devices
+too if they are behind the multiplexer.
+
+- https://github.com/RobTillaart/TCA9548
+
+
+### 0.5.0 Breaking change
 
 Version 0.5.0 introduced a breaking change.
 You cannot set the pins in **begin()** any more.
@@ -49,12 +67,32 @@ The user has to call **Wire.begin()** and can optionally set the Wire pins
 before calling **begin()**.
 
 
-#### Related
+### Related
 
-- https://github.com/RobTillaart/SHT31
-- https://github.com/RobTillaart/SHT31_SW
-- https://github.com/RobTillaart/SHT31_SWW
-- https://github.com/RobTillaart/SHT85
+SHT series temperature sensors
+
+- https://github.com/RobTillaart/SHT2x
+- https://github.com/RobTillaart/SHT31 Sensirion humidity / temperature sensor
+- https://github.com/RobTillaart/SHT31_SW  = softWire based I2C.
+- https://github.com/RobTillaart/SHT31_SWW = softWire based I2C.
+- https://github.com/RobTillaart/SHT85 Sensirion humidity / temperature sensor
+- https://github.com/RobTillaart/tinySHT2x
+
+Other temperature sensors
+
+- https://github.com/RobTillaart/DHTNew DHT11/22 etc
+- https://github.com/RobTillaart/DHTStable DHT11/22 etc
+- https://github.com/RobTillaart/DHT_Simulator
+- https://github.com/RobTillaart/DS18B20_INT OneWire temperature sensor
+- https://github.com/RobTillaart/DS18B20_RT OneWire temperature sensor
+
+An elaborated library for the SHT31 sensor can be found here
+- https://github.com/hawesg/SHT31D_Particle_Photon_ClosedCube
+
+Other, including Dewpoint, heatindex, related functions and conversions.
+
+- https://www.kandrsmith.org/RJS/Misc/Hygrometers/calib_many.html (interesting)
+- https://github.com/RobTillaart/Temperature (conversions, dewPoint, heat index etc.)
 
 
 ## Interface
@@ -63,7 +101,7 @@ before calling **begin()**.
 #include "SHT31.h"
 ```
 
-#### Constructor
+### Constructor
 
 - **SHT31(uint8_t address = SHT_DEFAULT_ADDRESS, TwoWire \*wire = &Wire)** constructor. 
 Optional select address and the I2C bus (Wire, Wire1 etc).
@@ -73,16 +111,29 @@ Returns false if device address is incorrect or device cannot be reset.
 - **uint8_t getAddress()** returns address set in the constructor.
 
 
-#### Read
+### 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.
+
+Meta information about the sensor.
+
+- **uint16_t readStatus()** returns bit mask, details see **Status fields** below (and datasheet).
+- **bool clearStatus()** clear status register, see **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.
+- **bool reset(bool hard = false)** resets the sensor, soft reset by default. Returns false if call fails.
+
+The following functions will return the same value until a new **read()** call (or async) is made.
+
 - **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..
+
+
+The **getRawHumidity()** and **getRawTemperature()** can be used to minimize storage or communication as the data type is 50% smaller.
+Another application is faster comparison with a previous value or threshold.
+However comparisons are quite fast.
+
 - **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.
 
@@ -91,26 +142,27 @@ If you're worried about the extra cycles, you should make sure to cache these va
 you've performed a new reading.
 
 
-#### Error interface
+### 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.
+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   |
+|  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      |
+|  0x89   |  SHT31_ERR_HEATER_ON        |  Could not switch on heater    |
 
 
-#### Heater interface
+### Heater interface
 
 **WARNING:** Do not use heater for long periods. 
 
@@ -121,22 +173,21 @@ within **180** seconds of the last switch off. Note: this guarding is not reboot
 **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()**.
+Switch off the heater by explicitly 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** 
+- **uint8_t getHeatTimeout()** returns the value set.
+- **bool heatOn()** switches the heat cycle on if not already on.
+Returns false if the call fails, setting error to **SHT31_ERR_HEATER_COOLDOWN** 
 or to **SHT31_ERR_HEATER_ON**. 
-- **bool heatOff()** switches heat cycle off. 
+- **bool heatOff()** switches the 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()**
+- **bool isHeaterOn()** is the sensor still in a heating cycle? Replaces **heatUp()**.
+Will switch the heater off if maximum heating time has passed.
 
 
-#### Async interface
+### Async interface
 
 See async example for usage
 
@@ -160,7 +211,7 @@ Returns false if reading fails or in case of a CRC failure.
 |       |                              |  1      | alert
 |  10   |  Temperature tracking alert  |  0      | no alert - default
 |       |                              |  1      | alert
-|  9-5  |  Reserved                    |  00000  |
+|  9-5  |  Reserved                    |  00000  | reserved
 |   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     |
@@ -169,17 +220,15 @@ Returns false if reading fails or in case of a CRC failure.
 |   0   |  Write data checksum status  |  0      | checksum of last write correct
 |       |                              |  1      | checksum of last write transfer failed
 
-
-
-## Operation
-
-See examples.
+**bool clearStatus()** clears 15, 11, 10 and 4.
 
 
 ## Future
 
 #### Must
 
+- improve documentation.
+  - reorder interface
 - keep in sync with SHT85 library.
 - keep derived SHT31_SW builds green
 

SHT31.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: SHT31.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.0
+// VERSION: 0.5.1
 //    DATE: 2019-02-08
 // PURPOSE: Arduino library for the SHT31 temperature and humidity sensor
 //          https://www.adafruit.com/product/2857
@@ -77,10 +77,14 @@ bool SHT31::read(bool fast)
 }
 
 
+/////////////////////////////////////////////////////////////////
+//
+//  STATUS
+//
 #ifdef doc
 //  bit - description
 //  ==================
-//  15   Alert pending status
+//  15  Alert pending status
 //        '0': no pending alerts
 //        '1': at least one pending alert - default
 //  14  Reserved ‘0’
@@ -131,13 +135,18 @@ uint16_t SHT31::readStatus()
   return (uint16_t) (status[0] << 8) + status[1];
 }
 
+
+//  resets the following bits
+//  15  Alert pending status
+//  11  Humidity tracking alert
+//  10  Temp tracking alert
+//  4   System reset detected
 bool SHT31::clearStatus()
 {
   if (writeCmd(SHT31_CLEAR_STATUS) == false)
   {
     return false;
   }
-  _lastRequest = millis();
   return true;
 }
 
@@ -160,6 +169,10 @@ void SHT31::setHeatTimeout(uint8_t seconds)
 }
 
 
+/////////////////////////////////////////////////////////////////
+//
+//  HEATER
+//
 bool SHT31::heatOn()
 {
   if (isHeaterOn()) return true;
@@ -209,6 +222,10 @@ bool SHT31::isHeaterOn()
 }
 
 
+/////////////////////////////////////////////////////////////////
+//
+//  ASYNC
+//
 bool SHT31::requestData()
 {
   if (writeCmd(SHT31_MEASUREMENT_SLOW) == false)
@@ -265,8 +282,10 @@ int SHT31::getError()
 }
 
 
-//////////////////////////////////////////////////////////
-
+/////////////////////////////////////////////////////////////////
+//
+//  PROTECTED
+//
 uint8_t SHT31::crc8(const uint8_t *data, uint8_t len)
 {
   //  CRC-8 formula from page 14 of SHT spec pdf

SHT31.h

@@ -2,7 +2,7 @@
 //
 //    FILE: SHT31.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.0
+// VERSION: 0.5.1
 //    DATE: 2019-02-08
 // PURPOSE: Arduino library for the SHT31 temperature and humidity sensor
 //          https://www.adafruit.com/product/2857
@@ -13,7 +13,7 @@
 #include "Wire.h"
 
 
-#define SHT31_LIB_VERSION             (F("0.5.0"))
+#define SHT31_LIB_VERSION             (F("0.5.1"))
 
 #ifndef SHT_DEFAULT_ADDRESS
 #define SHT_DEFAULT_ADDRESS           0x44
@@ -72,16 +72,20 @@ class SHT31
   bool heatOn();
   bool heatOff();
   bool isHeaterOn();  // is the sensor still heating up?
-  bool heatUp() { return isHeaterOn(); };   // will be obsolete in future
+  //  [[deprecated("Use isHeaterOn() instead")]]
+  bool heatUp() { return isHeaterOn(); };   // will be obsolete
 
+  //  0..100%
   float    getHumidity()       { return _rawHumidity    * (100.0 / 65535); };
+  //  getTemperature returns Celsius
   float    getTemperature()    { return _rawTemperature * (175.0 / 65535) - 45; };
   float    getFahrenheit()     { return _rawTemperature * (63.0 /13107.0) - 49; };
+  //  raw data e.g. debugging or efficient logging / transmit.
   uint16_t getRawHumidity()    { return _rawHumidity; };
   uint16_t getRawTemperature() { return _rawTemperature; };
 
 
-  // ASYNC INTERFACE
+  //  ASYNC INTERFACE
   bool requestData();
   bool dataReady();
   bool readData(bool fast = true);