refactor API, begin + constructor (#40)

- refactor API, constructor and begin()
- add **getAddress()**
- update readme.md
- update examples
- minor edits

Author: RobTillaart

CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.5.0] - 2023-12-09
+- refactor API, constructor and begin()
+- add **getAddress()**
+- update readme.md
+- update examples
+- minor edits
+
+----
+
 ## [0.4.0] - 2023-09-21
 - fix #38 support for Wire1 for ESP32
 - update examples

README.md

@@ -40,24 +40,43 @@ 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
+
+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
 
 ```cpp
 #include "SHT31.h"
 ```
 
+#### Constructor
 
-#### Base interface
-
-- **SHT31(TwoWire \*wire = &Wire)** constructor. Optional select the I2C bus (Wire, Wire1 etc).
-- **bool begin(uint8_t address, uint8_t dataPin, uint8_t clockPin)** begin function for ESP8266 & ESP32;
-returns false if device address is incorrect or device cannot be reset.
-- **bool begin(uint8_t dataPin, uint8_t clockPin)** same as above. With default SHT_DEFAULT_ADDRESS.
-- **bool begin(uint8_t address = SHT_DEFAULT_ADDRESS)** 
+- **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.
-- **bool isConnected()** check sensor is reachable over I2C. Returns false if not connected.
 - **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.

SHT31.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: SHT31.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.4.0
+// VERSION: 0.5.0
 //    DATE: 2019-02-08
 // PURPOSE: Arduino library for the SHT31 temperature and humidity sensor
 //          https://www.adafruit.com/product/2857
@@ -26,10 +26,10 @@
 #define SHT31_HEATER_TIMEOUT    180000UL   //  milliseconds
 
 
-SHT31::SHT31(TwoWire *wire)
+SHT31::SHT31(uint8_t address, TwoWire *wire)
 {
   _wire           = wire;
-  _address        = 0;
+  _address        = address;
   _lastRead       = 0;
   _rawTemperature = 0;
   _rawHumidity    = 0;
@@ -41,41 +41,28 @@ SHT31::SHT31(TwoWire *wire)
 }
 
 
-#if defined(ESP8266) || defined(ESP32)
-bool SHT31::begin(const uint8_t address, const uint8_t dataPin, const uint8_t clockPin)
+bool SHT31::begin()
 {
-  if ((address != 0x44) && (address != 0x45))
+  if ((_address != 0x44) && (_address != 0x45))
   {
     return false;
   }
-  _address = address;
-
-  if ((dataPin < 255) && (clockPin < 255))
-  {
-    _wire->begin(dataPin, clockPin);
-  } else {
-    _wire->begin();
-  }
   return reset();
 }
 
 
-bool SHT31::begin(const uint8_t dataPin, const uint8_t clockPin)
+bool SHT31::isConnected()
 {
-  return begin(SHT_DEFAULT_ADDRESS, dataPin, clockPin);
+  _wire->beginTransmission(_address);
+  int rv = _wire->endTransmission();
+  if (rv != 0) _error = SHT31_ERR_NOT_CONNECT;
+  return (rv == 0);
 }
-#endif
 
 
-bool SHT31::begin(const uint8_t address)
+uint8_t SHT31::getAddress()
 {
-  if ((address != 0x44) && (address != 0x45))
-  {
-    return false;
-  }
-  _address = address;
-  _wire->begin();
-  return reset();
+  return _address;
 }
 
 
@@ -90,14 +77,6 @@ bool SHT31::read(bool fast)
 }
 
 
-bool SHT31::isConnected()
-{
-  _wire->beginTransmission(_address);
-  int rv = _wire->endTransmission();
-  if (rv != 0) _error = SHT31_ERR_NOT_CONNECT;
-  return (rv == 0);
-}
-
 #ifdef doc
 //  bit - description
 //  ==================

SHT31.h

@@ -2,7 +2,7 @@
 //
 //    FILE: SHT31.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.4.0
+// VERSION: 0.5.0
 //    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.4.0"))
+#define SHT31_LIB_VERSION             (F("0.5.0"))
 
 #ifndef SHT_DEFAULT_ADDRESS
 #define SHT_DEFAULT_ADDRESS           0x44
@@ -44,21 +44,17 @@
 class SHT31
 {
 public:
-  SHT31(TwoWire *wire = &Wire);
+  SHT31(uint8_t address = SHT_DEFAULT_ADDRESS, TwoWire *wire = &Wire);
 
-#if defined(ESP8266) || defined(ESP32)
-  bool begin(const uint8_t address, uint8_t dataPin, uint8_t clockPin);
-  //  use SHT_DEFAULT_ADDRESS
-  bool begin(const uint8_t dataPin, const uint8_t clockPin);
-#endif
-  bool begin(const uint8_t address = SHT_DEFAULT_ADDRESS);
-
-  //  blocks 15 milliseconds + actual read + math
-  bool read(bool fast = true);
+  bool    begin();
+  uint8_t getAddress();
 
   //  check sensor is reachable over I2C
   virtual bool isConnected();
 
+  //  blocks 15 milliseconds + actual read + math
+  bool read(bool fast = true);
+
   //  details see datasheet; summary in SHT31.cpp file
   uint16_t readStatus();
 
@@ -92,18 +88,16 @@ class SHT31
   int getError();  //  clears error flag
 
 protected:
-  uint8_t   _address;
-  uint8_t   _heatTimeout;   //  seconds
-  uint32_t  _lastRead;
-  uint32_t  _lastRequest;   //  for async interface
-  uint32_t  _heaterStart;
-  uint32_t  _heaterStop;
-  bool      _heaterOn;
-
+  uint8_t  _address;
+  uint8_t  _heatTimeout;   //  seconds
+  uint32_t _lastRead;
+  uint32_t _lastRequest;   //  for async interface
+  uint32_t _heaterStart;
+  uint32_t _heaterStop;
+  bool     _heaterOn;
   uint16_t _rawHumidity;
   uint16_t _rawTemperature;
-
-  uint8_t _error;
+  uint8_t  _error;
 
 private:
   uint8_t crc8(const uint8_t *data, uint8_t len);

examples/SHT31_I2Cspeed/SHT31_I2Cspeed.ino

@@ -13,7 +13,7 @@
 uint32_t start;
 uint32_t stop;
 
-SHT31 sht;
+SHT31 sht(SHT31_ADDRESS);
 
 
 void setup()
@@ -24,8 +24,8 @@ void setup()
   Serial.println(SHT31_LIB_VERSION);
 
   Wire.begin();
-  sht.begin(SHT31_ADDRESS);
   Wire.setClock(100000);
+  sht.begin();
 
   uint16_t stat = sht.readStatus();
   Serial.print(stat, HEX);
@@ -41,23 +41,24 @@ void loop()
     Wire.setClock(I2Cfreq);
     test();
   }
+  Serial.println();
 }
 
 
 void test()
 {
   start = micros();
-  sht.read(true);         // default = true/fast       slow = false
+  sht.read(true);         //  default = true/fast       slow = false
   stop = micros();
   Serial.print("\t");
   Serial.print(stop - start);
   Serial.print("\t");
   Serial.print(sht.getTemperature(), 1);
   Serial.print("\t");
   Serial.println(sht.getHumidity(), 1);
-  delay(100);
+  delay(1000);
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/SHT31_async/SHT31_async.ino

@@ -14,7 +14,7 @@ uint32_t start;
 uint32_t stop;
 uint32_t cnt;
 
-SHT31 sht;
+SHT31 sht;  //  use default address and Wire
 
 
 void setup()
@@ -25,8 +25,8 @@ void setup()
   Serial.println(SHT31_LIB_VERSION);
 
   Wire.begin();
-  sht.begin(SHT31_ADDRESS);
   Wire.setClock(100000);
+  sht.begin();
 
   uint16_t stat = sht.readStatus();
   Serial.print(stat, HEX);
@@ -42,9 +42,9 @@ void loop()
   if (sht.dataReady())
   {
     start = micros();
-    bool success  = sht.readData();   // default = true = fast
+    bool success  = sht.readData();   //  default = true = fast
     stop = micros();
-    sht.requestData();                // request for next sample
+    sht.requestData();                //  request for next sample
 
     Serial.print("\t");
     Serial.print(stop - start);
@@ -63,9 +63,9 @@ void loop()
       cnt = 0;
     }
   }
-  cnt++; // simulate other activity
+  cnt++;  //  simulate other activity
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/SHT31_demo/SHT31_demo.ino

@@ -24,8 +24,8 @@ void setup()
   Serial.println(SHT31_LIB_VERSION);
 
   Wire.begin();
-  sht.begin(SHT31_ADDRESS);
   Wire.setClock(100000);
+  sht.begin();
 
   uint16_t stat = sht.readStatus();
   Serial.print(stat, HEX);
@@ -36,7 +36,7 @@ void setup()
 void loop()
 {
   start = micros();
-  sht.read();         // default = true/fast       slow = false
+  sht.read();         //  default = true/fast       slow = false
   stop = micros();
 
   Serial.print("\t");
@@ -49,5 +49,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/SHT31_heater/SHT31_heater.ino

@@ -10,7 +10,7 @@
 
 #define SHT31_ADDRESS   0x44
 
-SHT31 sht;
+SHT31 sht(SHT31_ADDRESS);
 uint16_t status;
 
 
@@ -22,10 +22,10 @@ void setup()
   Serial.println(SHT31_LIB_VERSION);
 
   Wire.begin();
-  sht.begin(SHT31_ADDRESS);
   Wire.setClock(100000);
+  sht.begin();
 
-  sht.setHeatTimeout(30);  // heater timeout 30 seconds, just for demo.
+  sht.setHeatTimeout(30);  //  heater timeout 30 seconds, just for demo.
 
   status = sht.readStatus();
   printHeaterStatus(status);
@@ -47,7 +47,7 @@ void setup()
 
 void loop()
 {
-  // forced switch off
+  //  forced switch off
   if (status & SHT31_STATUS_HEATER_ON) sht.heatOff();
 }
 
@@ -65,5 +65,5 @@ void printHeaterStatus(uint16_t status)
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --