0.2.2 SHT2x

libraries/SHT2x/CHANGELOG.md

@@ -6,11 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.2.2] - 2022-12-14
+- add experimental asynchronous interface
+- add async example
+
+
 ## [0.2.1] - 2022-11-24
 - Add RP2040 support to build-CI.
 - Add CHANGELOG.md
 
-
 ## [0.2.0] - 2022-07-10
 - Fix #11 RawTemp + rawHum (kudos to theandy94)
 - add experimental getResolution() + setResolution()

libraries/SHT2x/README.md

@@ -40,7 +40,7 @@ or one should switch sensors on/off like the select in SPI communication.
 
 ## Interface
 
-### Constructors
+#### Constructors
 
 All classes below are derived from SHT2x class.
 
@@ -55,7 +55,7 @@ All classes below are derived from SHT2x class.
 - **Si7021()** constructor.
 
 
-### Base interface
+#### Base interface
 
 - **bool begin(int dataPin, int clockPin)** begin function for ESP8266 & ESP32;
 returns false if device address is incorrect or device cannot be reset.
@@ -79,7 +79,23 @@ 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
+#### Asynchronous interface
+
+Experimental since 0.2.2 this interface can change in the future
+Discussion see https://github.com/RobTillaart/SHT2x/issues/16
+
+- **bool requestTemperature()**
+- **bool requestHumidity()**
+- **bool reqTempReady()**
+- **bool reqHumReady()**
+- **bool readTemperature()**
+- **bool readHumidity()**
+- **uint32_t lastRequest()**
+
+TODO elaborate documentation.
+
+
+#### 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.
@@ -100,7 +116,7 @@ Be sure to clear the error flag by calling **getError()** before calling any com
 Note: the HTU20 / HTU21 classes share the same error codes.
 
 
-### Heater interface
+#### Heater interface
 
 **WARNING:** Do not use heater for long periods.  
 Datasheet SHT2x does not mention max time so the maximum time of the SHT3x series is assumed here.
@@ -125,7 +141,7 @@ Returns false if fails, setting error to **SHT2x_ERR_HEATER_OFF**.
 - **bool isHeaterOn()** is the sensor still in heating cycle?
 
 
-### Electronic ID
+#### Electronic ID
 
 To be tested.
 
@@ -134,7 +150,7 @@ To be tested.
 - **uint8_t getFirmwareVersion()** returns firmware version.
   
 
-### Status fields
+#### Status fields
 
 From HTU20 datasheet
 
@@ -146,7 +162,7 @@ From HTU20 datasheet
 |  11    |   3    | closed circuit      |
 
 
-### Resolution
+#### Resolution
 
 **Warning experimental** 
 - needs more testing as results are not in line with the datasheet.
@@ -180,27 +196,37 @@ Timing in milliseconds.
 
 
  
-### Battery
+#### Battery
 
 - **bool batteryOK()** returns true if VCC > 2.5 Volts.
 
 
 ## Future
 
-#### must
+#### Must
 - improve documentation
+- clean up code.
 
 
 #### 0.3.0
 - add crc8 check (need sensor)
 - improve error handling (all code paths)
 - investigate blocking delay() in read 
-  - **ASYNC** NO HOLD call to read T or H
+- add offset for temperature and humidity
-  - **void requestTemperature()** ==> **void readTemperature()**
+- move code from .h to .cpp 
-  - **void requestHumidity()** ==> **void readHumidity()**
+- add GY21 as derived class name
 
 
-#### should
+#### ASYNC 0.3.0
+improvements for interface.
+
+- **bool requestReady()** checks both. 
+- **bool requestPending()** checks . 
+- **uint8_t getRequestType()** returns 0, 1, 2
+- documentation
+
+
+#### Should
 - test test test
   - get hardware
 - add examples
@@ -209,13 +235,13 @@ Timing in milliseconds.
   - test battery
 
 
-#### could
+#### Could
 - investigate resolution anomalies
-- fix TODO in code (.cpp and .h)
+- fix TODO in code (.cpp and .h) and documentation
 - update unit tests
 
 
-#### wont
+#### Wont
 
 - add **getSerialNumber()**
   **getEIDA()** and **getEIDB()** covers this

libraries/SHT2x/SHT2x.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: SHT2x.cpp
 //  AUTHOR: Rob Tillaart, Viktor Balint
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 //    DATE: 2021-09-25
 // PURPOSE: Arduino library for the SHT2x temperature and humidity sensor
 //     URL: https://github.com/RobTillaart/SHT2x
@@ -26,10 +26,20 @@
 #define SHT2x_USRREG_BATTERY            0x20
 #define SHT2x_USRREG_HEATER             0x04
 
+#define SHT2x_REQ_NONE                  0x00
+#define SHT2x_REQ_TEMPERATURE           0x01
+#define SHT2x_REQ_HUMIDITY              0x02
 
+
+//////////////////////////////////////////////////////////////
+//
+//  PUBLIC
+//
 SHT2x::SHT2x()
 {
   _lastRead       = 0;
+  _lastRequest    = 0;
+  _requestType    = 0;
   _rawTemperature = 0;
   _rawHumidity    = 0;
   _heatTimeout    = 0;
@@ -74,17 +84,90 @@ bool SHT2x::isConnected()
 }
 
 
+/////////////////////////////////////////////////////////
+//
+//  SYNCHRONOUS INTERFACE
+//
 bool SHT2x::read()
 {
-  uint8_t buffer[3];
-
   //  TEMPERATURE
+  if (requestTemperature() == false) return false;
+  while (reqTempReady() == false)
+  {
+    yield();
+  };
+  if (readTemperature() == false) return false;
+
+  //  HUMIDITY
+  if (requestHumidity() == false) return false;
+  while (reqHumReady() == false)
+  {
+    yield();
+  };
+  if (readHumidity() == false) return false;
+  return true;
+}
+
+
+/////////////////////////////////////////////////////////
+//
+//  ASYNCHRONOUS INTERFACE
+//
+bool SHT2x::requestTemperature()
+{
   writeCmd(SHT2x_GET_TEMPERATURE_NO_HOLD);
-  //  table 7 
+  _lastRequest = millis();
-  if      (_resolution == 3) delay(11);  //  11 bit
+  _requestType = SHT2x_REQ_TEMPERATURE;
-  else if (_resolution == 1) delay(22);  //  12 bit
+  return true;
-  else if (_resolution == 2) delay(43);  //  13 bit
+}
-  else                       delay(85);  //  14 bit
+
+
+bool SHT2x::requestHumidity()
+{
+  writeCmd(SHT2x_GET_HUMIDITY_NO_HOLD);
+  _lastRequest = millis();
+  _requestType = SHT2x_REQ_HUMIDITY;
+  return true;
+}
+
+
+bool SHT2x::reqTempReady()
+{
+  if (_requestType != SHT2x_REQ_TEMPERATURE) return false;
+
+  uint32_t waiting = millis() - _lastRequest;
+  //  table 7
+  if (waiting < 11)     return false;
+  if (_resolution == 3) return true;
+  if (waiting < 22)     return false;
+  if (_resolution == 1) return true;
+  if (waiting < 43)     return false;
+  if (_resolution == 2) return true;
+  if (waiting < 85)     return false;
+  return true;
+}
+
+
+bool SHT2x::reqHumReady()
+{
+  if (_requestType != SHT2x_REQ_HUMIDITY) return false;
+
+  uint32_t waiting = millis() - _lastRequest;
+  //  table 7
+  if (waiting < 4)      return false;
+  if (_resolution == 1) return true;      //   8 bit
+  if (waiting < 9)      return false;
+  if (_resolution == 2) return true;      //  10 bit
+  if (waiting < 15)     return false;
+  if (_resolution == 3) return true;      //  11 bit
+  if (waiting < 29)     return false;
+  return true;                            //  12 bit
+}
+
+
+bool SHT2x::readTemperature()
+{
+  uint8_t buffer[3];
 
   if (readBytes(3, (uint8_t*) &buffer[0], 90) == false)
   {
@@ -100,20 +183,22 @@ bool SHT2x::read()
   _rawTemperature += buffer[1];
   _rawTemperature &= 0xFFFC;
 
+  //  clear requestType
+  _requestType = SHT2x_REQ_NONE;
+
   _status = buffer[1] & 0x0003;
   if (_status == 0xFF)  // TODO  != 0x01  (need HW to test)
   {
     _error = SHT2x_ERR_READBYTES;
     return false;
   }
+  return true;
+}
 
-  //  HUMIDITY
+
-  writeCmd(SHT2x_GET_HUMIDITY_NO_HOLD);
+bool SHT2x::readHumidity()
-  //  table 7 
+{
-  if      (_resolution == 1) delay(4);   //   8 bit
+  uint8_t buffer[3];
-  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)
   {
@@ -128,6 +213,9 @@ bool SHT2x::read()
   _rawHumidity += buffer[1];
   _rawHumidity &= 0xFFFC;     //  TODO is this mask OK? as humidity is max 12 bit..
 
+  //  clear requestType
+  _requestType = SHT2x_REQ_NONE;
+
   _status = buffer[1] & 0x0003;
   if (_status == 0xFF)        //  TODO  != 0x02  (need HW to test)
   {
@@ -141,6 +229,16 @@ bool SHT2x::read()
 }
 
 
+uint32_t SHT2x::lastRequest()
+{
+  return _lastRequest;
+}
+
+
+/////////////////////////////////////////////////////////
+//
+//  TEMPERATURE AND HUMIDTY
+//
 float SHT2x::getTemperature()
 {
   // par 6.2
@@ -167,9 +265,10 @@ uint8_t SHT2x::getStatus()
   return _status;
 }
 
-
+/////////////////////////////////////////////////////////
+//
 //  HEATER
-
+//
 void SHT2x::setHeatTimeout(uint8_t seconds)
 {
   _heatTimeout = seconds;
@@ -295,6 +394,10 @@ int SHT2x::getError()
 }
 
 
+/////////////////////////////////////////////////////////
+//
+//  Electronic Identification Code
+//
 //  Sensirion_Humidity_SHT2x_Electronic_Identification_Code_V1.1.pdf
 uint32_t SHT2x::getEIDA()
 {
@@ -352,6 +455,10 @@ uint8_t SHT2x::getFirmwareVersion()
 }
 
 
+/////////////////////////////////////////////////////////
+//
+//  RESOLUTION
+//
 bool SHT2x::setResolution(uint8_t res)
 {
   if (res > 3) return false;
@@ -386,6 +493,10 @@ uint8_t SHT2x::getResolution()
 };
 
 
+/////////////////////////////////////////////////////////
+//
+//  OTHER
+//
 bool SHT2x::batteryOK()
 {
   uint8_t userReg = 0x00;
@@ -403,7 +514,7 @@ bool SHT2x::batteryOK()
 
 //////////////////////////////////////////////////////////
 //
-//  PRIVATE
+//  PROTECTED
 //
 uint8_t SHT2x::crc8(const uint8_t *data, uint8_t len)
 {

libraries/SHT2x/SHT2x.h

@@ -2,7 +2,7 @@
 //
 //    FILE: SHT2x.h
 //  AUTHOR: Rob Tillaart, Viktor Balint
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 //    DATE: 2021-09-25
 // PURPOSE: Arduino library for the SHT2x temperature and humidity sensor
 //     URL: https://github.com/RobTillaart/SHT2x
@@ -13,7 +13,7 @@
 #include "Wire.h"
 
 
-#define SHT2x_LIB_VERSION             (F("0.2.1"))
+#define SHT2x_LIB_VERSION             (F("0.2.2"))
 
 
 //  fields getStatus
@@ -97,9 +97,9 @@ public:
   int getError(); // clears error flag
 
   //  Electronic ID bytes
-  uint32_t  getEIDA();
+  uint32_t getEIDA();
-  uint32_t  getEIDB();
+  uint32_t getEIDB();
-  uint8_t   getFirmwareVersion();
+  uint8_t  getFirmwareVersion();
 
   //  experimental 0.2.0 - needs testing.
   //  table 8 SHT20 datasheet
@@ -111,12 +111,20 @@ public:
   //   2      10 bit    13  bit
   //   3      11 bit    11  bit
   //   4..255 returns false
-  bool      setResolution(uint8_t res = 0);
+  bool     setResolution(uint8_t res = 0);
   //  returns RES set (cached value)
-  uint8_t   getResolution();
+  uint8_t  getResolution();
 
+  bool     batteryOK();
 
-  bool      batteryOK();
+  //  Experimental ASYNC interface
+  bool     requestTemperature();
+  bool     requestHumidity();
+  bool     reqTempReady();
+  bool     reqHumReady();
+  bool     readTemperature();
+  bool     readHumidity();
+  uint32_t lastRequest();
 
 
 protected:
@@ -127,9 +135,14 @@ protected:
   bool      readBytes(uint8_t n, uint8_t *val, uint8_t maxDuration);
   TwoWire* _wire;
 
-  uint8_t   _heatTimeout;   //  seconds
   uint32_t  _lastRead;
-  uint32_t  _lastRequest;   //  for async interface
+
+  //  for async interface
+  uint32_t  _lastRequest;
+  //  0 = none  1 = temp  2 = hum
+  uint8_t   _requestType;
+
+  uint8_t   _heatTimeout;   //  seconds
   uint32_t  _heaterStart;
   uint32_t  _heaterStop;
   bool      _heaterOn;

libraries/SHT2x/examples/SHT2x_demo_async/SHT2x_demo_async.ino

@@ -0,0 +1,46 @@
+//
+//    FILE: SHT2x_demo_async.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo asynchronous interface
+//     URL: https://github.com/RobTillaart/SHT2x
+
+
+#include "Wire.h"
+#include "SHT2x.h"
+
+SHT2x sht;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("SHT2x_LIB_VERSION: \t");
+  Serial.println(SHT2x_LIB_VERSION);
+
+  sht.begin();
+
+  uint8_t stat = sht.getStatus();
+  Serial.print(stat, HEX);
+  Serial.println();
+
+  sht.requestTemperature();
+}
+
+
+void loop()
+{
+  if (sht.reqTempReady())
+  {
+    sht.readTemperature();
+    Serial.print("TEMP:\t");
+    Serial.println(sht.getTemperature(), 1);
+    sht.requestTemperature();
+  }
+
+  // do other things here
+  delay(1000);
+}
+
+
+// -- END OF FILE --

libraries/SHT2x/keywords.txt

@@ -38,6 +38,14 @@ getEIDA	KEYWORD2
 getEIDB	KEYWORD2
 getFirmwareVersion	KEYWORD2
 
+requestTemperatureta	KEYWORD2
+requestHumidity	KEYWORD2
+reqTempReady	KEYWORD2
+reqHumReady	KEYWORD2
+readTemperature	KEYWORD2
+readHumidity	KEYWORD2
+lastRequest	KEYWORD2
+
 
 # Instances (KEYWORD2)
 

libraries/SHT2x/library.json

@@ -18,7 +18,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/SHT2x.git"
   },
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

libraries/SHT2x/library.properties

@@ -1,5 +1,5 @@
 name=SHT2x
-version=0.2.1
+version=0.2.2
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for the I2C SHT20 SHT21 SHT25 series temperature and humidity sensor.