0.2.0 SHT2x

Author: RobTillaart

libraries/SHT2x/README.md

@@ -64,7 +64,7 @@ for platforms with multiple I2C buses. **begin()** calls **reset()** which can t
 - **bool read()** Reads both the temperature and humidity.  
 Initial release has a blocking delay. 
 - **bool isConnected()** check if sensor is reachable over I2C. Returns false if not connected.
-- **uint16_t getStatus()** returns a 2 bit status. See below.
+- **uint16_t getStatus()** returns a 2 bit status. See Status fields below.
 - **uint32_t lastRead()** in milliSeconds since start of program.
 - **bool reset()** resets the sensor, soft reset, no hard reset supported.
 - **float getHumidity()** computes the relative humidity in % based off the latest raw reading, and returns it.
@@ -76,6 +76,8 @@ Note that the temperature and humidity values are recalculated on every call to
 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 **read()**.
 
+Note: The raw temperature and raw humidity are ideal to minimize storage or to minimize communication.
+
 
 ### Error interface
 
@@ -125,9 +127,11 @@ Returns false if fails, setting error to **SHT2x_ERR_HEATER_OFF**.
 
 ### Electronic ID
 
-- **uint32_t getEIDA()** not tested yet.
-- **uint32_t getEIDB()** not tested yet.
-- **uint8_t getFirmwareVersion()** not tested yet.
+To be tested.
+
+- **uint32_t getEIDA()** returns unique ID part A.
+- **uint32_t getEIDB()** returns unique ID part B.
+- **uint8_t getFirmwareVersion()** returns firmware version.
 
 
 ### Status fields
@@ -142,29 +146,70 @@ From HTU20 datasheet
 |  11    |   3    | closed circuit      |
 
 
-## Operation
+### Resolution
+
+**Warning experimental** 
+- needs more testing as results are not in line with the datasheet.
+- only tested on a HTUxx sensor.
+- tested with **SHT2X_resolution.ino**
+
+- **void setResolution(uint8_t res)** res = 0..3, other values return false.
+- **uint8_t getResolution()** returns resolution set 0..3.
+
+
+Datasheet SHT20 Table 8: (resolution)
+
+|  RES  |  Humidity | Temperature |
+|:-----:|:---------:|:-----------:|
+|   0   |  12 bit   |    14 bit   |
+|   1   |  08 bit   |    12 bit   |
+|   2   |  10 bit   |    13 bit   |
+|   3   |  11 bit   |    11 bit   |
+
+Datasheet SHT20 Table 7: (timing) and results of real measurements.
+( https://github.com/RobTillaart/SHT2x/pull/11 )
+
+|  RES  |  HUM  |  TEMP  |  TOTAL  |  REAL  |
+|:-----:|:-----:|:------:|:-------:|:------:|
+|   0   |   29  |   85   |   114   |   116  |
+|   1   |    4  |   22   |    26   |   113  |
+|   2   |    9  |   43   |    52   |   084  |
+|   3   |   15  |   11   |    26   |   102  |
+
+Timing in milliseconds.
 
-See examples
+
+ 
+### Battery
+
+- **bool batteryOK()** returns true if VCC > 2.5 Volts.
 
 
 ## Future
 
-- test
+- test test test
   - get hardware
+- investigate resolution anomalies
 - improve documentation
-- add **getSerialNumber()**
-  **getEIDA()** and **getEIDB()** covers this
+- fix TODO in code (.cpp and .h)
+- add examples
+  - test resolutions
+  - performance different resolutions
+  - test battery
+- update unit tests
+
+
+#### 0.3.0
+
+- add crc8 check (need sensor)
 - improve error handling (all code paths)
 - investigate blocking delay() in read 
-  - optimize... Q: need async interface?
-- add crc8 check
-- fix TODO in code (4 in CPP)
+  - **ASYNC** NO HOLD call to read T or H
+  - **void requestTemperature()** ==> **void readTemperature()**
+  - **void requestHumidity()** ==> **void readHumidity()**
 
+#### wont
 
-### 0.2.0
+- add **getSerialNumber()**
+  **getEIDA()** and **getEIDB()** covers this
 
-- add **setResolution()** and **getResolution()** 
-  - write user register E6
-  - read user register R7
-  (note table 8 + FIgure 16 code)
-- add **getBatteryStatus()**

libraries/SHT2x/SHT2x.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: SHT2x.cpp
 //  AUTHOR: Rob Tillaart, Viktor Balint
-// VERSION: 0.1.4
+// VERSION: 0.2.0
 //    DATE: 2021-09-25
 // PURPOSE: Arduino library for the SHT2x temperature and humidity sensor
 //     URL: https://github.com/RobTillaart/SHT2x
@@ -17,6 +17,12 @@
 //  0.1.3   2021-12-28  update library.json, license, minor edits
 //  0.1.4   2022-06-21  Fix #9 ESP32 wire.begin()
 //                      Fix getEIDB() bug.
+//
+//  0.2.0   2022-07-10  Fix #11 RawTemp + rawHum (kudos to theandy94)
+//                      add experimental getResolution() + setResolution()
+//                      adjust read delay
+//                      add experimental batteryOK()
+//                      add CRC in read() - no fail.
 
 
 #include "SHT2x.h"
@@ -34,6 +40,11 @@
 #define SHT2x_ADDRESS                   0x40
 
 
+#define SHT2x_USRREG_RESOLUTION         0x81
+#define SHT2x_USRREG_BATTERY            0x20
+#define SHT2x_USRREG_HEATER             0x04
+
+
 SHT2x::SHT2x()
 {
   _lastRead       = 0;
@@ -45,6 +56,7 @@ SHT2x::SHT2x()
   _heaterOn       = false;
   _error          = SHT2x_OK;
   _status         = 0;
+  _resolution     = 0;
 }
 
 
@@ -86,40 +98,56 @@ bool SHT2x::read()
 
   //  TEMPERATURE
   writeCmd(SHT2x_GET_TEMPERATURE_NO_HOLD);
-  delay(70);
+  //  table 7 
+  if      (_resolution == 3) delay(11);  //  11 bit
+  else if (_resolution == 1) delay(22);  //  12 bit
+  else if (_resolution == 2) delay(43);  //  13 bit
+  else                       delay(85);  //  14 bit
+
   if (readBytes(3, (uint8_t*) &buffer[0], 90) == false)
   {
     _error = SHT2x_ERR_READBYTES;
     return false;
   }
-  // TODO CRC8 check
-  // error = SHT2x_ERR_CRC_TEMP;
-  _rawTemperature = buffer[0] << 8;
+  if (crc8(buffer, 2) != buffer[2])
+  {
+    _error = SHT2x_ERR_CRC_TEMP;
+  //  return false;  // do not fail yet
+  }
+  _rawTemperature  = buffer[0] << 8;
   _rawTemperature += buffer[1];
   _rawTemperature &= 0xFFFC;
 
   _status = buffer[1] & 0x0003;
-  if (_status == 0xFF)  // TODO  != 0x01
+  if (_status == 0xFF)  // TODO  != 0x01  (need HW to test)
   {
     _error = SHT2x_ERR_READBYTES;
     return false;
   }
 
   //  HUMIDITY
   writeCmd(SHT2x_GET_HUMIDITY_NO_HOLD);
-  delay(30);
+  //  table 7 
+  if      (_resolution == 1) delay(4);   //   8 bit
+  else if (_resolution == 2) delay(9);   //  10 bit
+  else if (_resolution == 3) delay(15);  //  11 bit
+  else                       delay(29);  //  12 bit
+
   if (readBytes(3, (uint8_t*) &buffer[0], 30) == false)
   {
     return false;
   }
-  // TODO CRC8 check
-  // _error = SHT2x_ERR_CRC_HUM;
-  _rawHumidity = buffer[0] << 8;
+  if (crc8(buffer, 2) != buffer[2])
+  {
+    _error = SHT2x_ERR_CRC_HUM;
+  //    return false;  // do not fail yet
+  }
+  _rawHumidity  = buffer[0] << 8;
   _rawHumidity += buffer[1];
-  _rawHumidity &= 0xFFFC;
+  _rawHumidity &= 0xFFFC;     //  TODO is this mask OK? as humidity is max 12 bit..
 
   _status = buffer[1] & 0x0003;
-  if (_status == 0xFF)  // TODO  != 0x02
+  if (_status == 0xFF)        //  TODO  != 0x02  (need HW to test)
   {
     _error = SHT2x_ERR_READBYTES;
     return false;
@@ -148,8 +176,7 @@ float SHT2x::getHumidity()
 bool SHT2x::reset()
 {
   bool b = writeCmd(SHT2x_SOFT_RESET);
-  if (b == false) return false;
-  return true;
+  return b;
 }
 
 
@@ -184,7 +211,9 @@ bool SHT2x::heatOn()
     _error = SHT2x_ERR_READBYTES;
     return false;
   }
-  userReg |= 0x04;      // HEAT BIT ON
+
+  //  HEAT BIT ON
+  userReg |= SHT2x_USRREG_HEATER;
 
   if (writeCmd(SHT2x_READ_USER_REGISTER, userReg) == false)
   {
@@ -206,7 +235,10 @@ bool SHT2x::heatOff()
     _error = SHT2x_ERR_READBYTES;
     return false;
   }
-  userReg &= ~0x04;      // HEAT BIT OFF
+
+  //  HEAT BIT OFF
+  userReg &= ~SHT2x_USRREG_HEATER;
+
   if (writeCmd(SHT2x_READ_USER_REGISTER, userReg) == false)
   {
     _error = SHT2x_ERR_HEATER_OFF;  // can be serious!
@@ -338,15 +370,65 @@ uint8_t SHT2x::getFirmwareVersion()
 }
 
 
+bool SHT2x::setResolution(uint8_t res)
+{
+  if (res > 3) return false;
+
+  uint8_t userReg = 0x00;
+  writeCmd(SHT2x_READ_USER_REGISTER);
+  if (readBytes(1, (uint8_t *) &userReg, 5) == false)
+  {
+    _error = SHT2x_ERR_READBYTES;
+    return false;
+  }
+
+  //  clear old resolution and set new
+  userReg &= ~SHT2x_USRREG_RESOLUTION;
+  //  resolution is bit 7 and bit 0.
+  userReg |= ((res & 0x02) << 6);
+  userReg |= (res & 0x01);
+
+  if (writeCmd(SHT2x_READ_USER_REGISTER, userReg) == false)
+  {
+    _error = SHT2x_ERR_RESOLUTION;
+    return false;
+  }
+  _resolution = res;
+  return true;
+}
+
+
+uint8_t SHT2x::getResolution()
+{
+  return _resolution;
+};
+
+
+bool SHT2x::batteryOK()
+{
+  uint8_t userReg = 0x00;
+  writeCmd(SHT2x_READ_USER_REGISTER);
+  if (readBytes(1, (uint8_t *) &userReg, 5) == false)
+  {
+    _error = SHT2x_ERR_READBYTES;
+    return false;
+  }
+  return (userReg & SHT2x_USRREG_BATTERY) == 0;
+}
+
+
+
+
 //////////////////////////////////////////////////////////
 //
 //  PRIVATE
 //
 uint8_t SHT2x::crc8(const uint8_t *data, uint8_t len)
 {
   // CRC-8 formula from page 14 of SHT spec pdf
-  const uint8_t POLY(0x31);
-  uint8_t crc(0xFF);
+  // Sensirion_Humidity_Sensors_SHT2x_CRC_Calculation.pdf
+  const uint8_t POLY = 0x31;
+  uint8_t crc = 0x00;
 
   for (uint8_t j = len; j; --j)
   {