0.2.2 CHT8305

libraries/CHT8305/CHANGELOG.md

@@ -6,12 +6,22 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.2.2] - 2024-09-16
+- Fix #15, improve error handling.
+- add return value **CHT8305_ERROR_BUFSIZE**
+- add return value **CHT8305_ERROR_GENERIC**
+- add return value **0xFFFF** for 2 functions.
+- set default values 0.0 for **offset** parameters.
+- fix missing names in keywords.txt
+- add plotter and performance example
+- update readme.md.
+
+
 ## [0.2.1] - 2024-01-30
 - add multiplexing section to readme.md
 - update examples (URL)
 - minor edits
 
-
 ## [0.2.0] - 2023-12-05
 - refactor API, constructor, begin()
 - update readme.md

libraries/CHT8305/CHT8305.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: CHT8305.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 // PURPOSE: Arduino library for CHT8305 temperature and humidity sensor
 //     URL: https://github.com/RobTillaart/CHT8305
 
@@ -17,14 +17,24 @@ CHT8305::CHT8305(const uint8_t address, TwoWire *wire)
 {
   _wire    = wire;
   _address = address;
+  _error   = CHT8305_OK;
 }
 
 
 int CHT8305::begin()
 {
-  if ((_address < 0x40) || (_address > 0x43)) return CHT8305_ERROR_ADDR;
+  if ((_address < 0x40) || (_address > 0x43))
-  if (! isConnected()) return CHT8305_ERROR_CONNECT;
+  {
-  return CHT8305_OK;
+    _error = CHT8305_ERROR_ADDR;
+    return _error;
+  }
+  if (! isConnected())
+  {
+    _error = CHT8305_ERROR_CONNECT;
+    return _error;
+  }
+  _error = CHT8305_OK;
+  return _error;
 }
 
 
@@ -50,27 +60,33 @@ int CHT8305::read()
   //  do not read too fast
   if (millis() - _lastRead < 1000)
   {
-    return CHT8305_ERROR_LASTREAD;
+    _error = CHT8305_ERROR_LASTREAD;
+    return _error;
   }
   _lastRead = millis();
 
   uint8_t data[4] = {0, 0, 0, 0 };
-  _readRegister(CHT8305_REG_TEMPERATURE, &data[0], 4);
+  if (_readRegister(CHT8305_REG_TEMPERATURE, &data[0], 4) != CHT8305_OK)
+  {
+    return _error;
+  }
 
-  uint16_t tmp = data[0] << 8 | data[1];
+  uint16_t tmp = (data[0] << 8) | data[1];
   _temperature = tmp * (165.0 / 65535.0) - 40.0;
-   tmp = data[2] << 8 | data[3];
+
+   tmp = (data[2] << 8) | data[3];
   _humidity    = tmp * (1.0 / 655.35);  //  == / 65535 * 100%
 
   if (_tempOffset != 0.0) _temperature += _tempOffset;
-  if (_humOffset  != 0.0) 
+  if (_humOffset  != 0.0)
   {
     _humidity += _humOffset;
     if (_humidity < 0.0)   _humidity = 0.0;
     if (_humidity > 100.0) _humidity = 100.0;
   }
 
-  return CHT8305_OK;
+  _error = CHT8305_OK;
+  return _error;
 }
 
 
@@ -79,14 +95,18 @@ int CHT8305::readTemperature()
   //  do not read too fast
   if (millis() - _lastRead < 1000)
   {
-    return CHT8305_ERROR_LASTREAD;
+    _error = CHT8305_ERROR_LASTREAD;
+    return _error;
   }
   _lastRead = millis();
 
   uint8_t data[2] = {0, 0};
-  _readRegister(CHT8305_REG_TEMPERATURE, &data[0], 2);
+  if (_readRegister(CHT8305_REG_TEMPERATURE, &data[0], 2) != CHT8305_OK)
+  {
+    return _error;
+  }
 
-  uint16_t tmp = data[0] << 8 | data[1];
+  uint16_t tmp = (data[0] << 8) | data[1];
   _temperature = tmp * (165.0 / 65535.0) - 40.0;
 
   if (_tempOffset != 0.0)
@@ -94,7 +114,8 @@ int CHT8305::readTemperature()
     _temperature += _tempOffset;
   }
 
-  return CHT8305_OK;
+  _error = CHT8305_OK;
+  return _error;
 }
 
 
@@ -103,14 +124,18 @@ int CHT8305::readHumidity()
   //  do not read too fast
   if (millis() - _lastRead < 1000)
   {
-    return CHT8305_ERROR_LASTREAD;
+    _error = CHT8305_ERROR_LASTREAD;
+    return _error;
   }
   _lastRead = millis();
 
   uint8_t data[2] = {0, 0};
-  _readRegister(CHT8305_REG_HUMIDITY, &data[0], 2);
+  if (_readRegister(CHT8305_REG_HUMIDITY, &data[0], 4) != CHT8305_OK)
+  {
+    return _error;
+  }
 
-  uint16_t tmp = data[0] << 8 | data[1];
+  uint16_t tmp = (data[0] << 8) | data[1];
   _humidity    = tmp * (1.0 / 655.35);  //  == / 65535 * 100%
 
   if (_humOffset  != 0.0)
@@ -120,7 +145,8 @@ int CHT8305::readHumidity()
     if (_humidity > 100.0) _humidity = 100.0;
   }
 
-  return CHT8305_OK;
+  _error = CHT8305_OK;
+  return _error;
 }
 
 
@@ -184,20 +210,27 @@ float CHT8305::getTemperatureOffset()
 //
 //  CONFIGURATION REGISTER
 //
-void CHT8305::setConfigRegister(uint16_t bitmask)
+bool CHT8305::setConfigRegister(uint16_t bitmask)
 {
   uint8_t data[2];
   data[0] = bitmask >> 8;
   data[1] = bitmask & 0xFF;
-  _writeRegister(2, &data[0], 2);
+  if (_writeRegister(2, &data[0], 2) != CHT8305_OK)
+  {
+    return false;
+  }
+  return true;
 }
 
 
 uint16_t CHT8305::getConfigRegister()
 {
   uint8_t data[2] = { 0, 0};
-  _readRegister(CHT8305_REG_CONFIG, &data[0], 2);
+  if (_readRegister(CHT8305_REG_CONFIG, &data[0], 2) != CHT8305_OK)
-  uint16_t tmp = data[0] << 8 | data[1];
+  {
+    return 0;
+  }
+  uint16_t tmp = (data[0] << 8) | data[1];
   return tmp;
 }
 
@@ -344,7 +377,10 @@ bool CHT8305::setAlertLevels(float temperature, float humidity)
 
   tmp = (temperature + 40.0) * (511.0 / 165.0);
   mask |= tmp;
-  _writeRegister(CHT8305_REG_ALERT, (uint8_t *)&mask, 2);
+  if (_writeRegister(CHT8305_REG_ALERT, (uint8_t *)&mask, 2) != CHT8305_OK)
+  {
+    return false;
+  }
   return true;
 }
 
@@ -352,7 +388,10 @@ bool CHT8305::setAlertLevels(float temperature, float humidity)
 float CHT8305::getAlertLevelTemperature()
 {
   uint16_t data = 0;
-  _readRegister(CHT8305_REG_ALERT, (uint8_t *)&data, 2);
+  if (_readRegister(CHT8305_REG_ALERT, (uint8_t *)&data, 2) != CHT8305_OK)
+  {
+    return CHT8305_ERROR_GENERIC;
+  }
   data &= 0x01FF;
   data <<= 7;
   return data * (165.0 / 65535.0) - 40.0;
@@ -362,7 +401,10 @@ float CHT8305::getAlertLevelTemperature()
 float CHT8305::getAlertLevelHumidity()
 {
   uint16_t data = 0;
-  _readRegister(CHT8305_REG_ALERT, (uint8_t *)&data, 2);
+  if (_readRegister(CHT8305_REG_ALERT, (uint8_t *)&data, 2) != CHT8305_OK)
+  {
+    return CHT8305_ERROR_GENERIC;
+  }
   data &= 0xFE00;
   return data * (100.0 / 65535.0);
 }
@@ -375,8 +417,11 @@ float CHT8305::getAlertLevelHumidity()
 float CHT8305::getVoltage()
 {
   uint8_t data[2] = { 0, 0};
-  _readRegister(CHT8305_REG_VOLTAGE, &data[0], 2);
+  if (_readRegister(CHT8305_REG_VOLTAGE, &data[0], 2) != CHT8305_OK)
-  uint16_t tmp = data[0] << 8 | data[1];
+  {
+    return CHT8305_ERROR_GENERIC;
+  }
+  uint16_t tmp = (data[0] << 8) | data[1];
   return tmp * (5.0 / 32768.0);   //  best guess
 }
 
@@ -388,8 +433,11 @@ float CHT8305::getVoltage()
 uint16_t CHT8305::getManufacturer()
 {
   uint8_t data[2] = { 0, 0};
-  _readRegister(CHT8305_REG_MANUFACTURER, &data[0], 2);
+  if (_readRegister(CHT8305_REG_MANUFACTURER, &data[0], 2) != CHT8305_OK)
-  uint16_t tmp = data[0] << 8 | data[1];
+  {
+    return 0xFFFF;
+  }
+  uint16_t tmp = (data[0] << 8) | data[1];
   return tmp;
 }
 
@@ -397,12 +445,23 @@ uint16_t CHT8305::getManufacturer()
 uint16_t CHT8305::getVersionID()
 {
   uint8_t data[2] = { 0, 0};
-  _readRegister(CHT8305_REG_VERSION, &data[0], 2);
+  if (_readRegister(CHT8305_REG_VERSION, &data[0], 2) != CHT8305_OK)
-  uint16_t tmp = data[0] << 8 | data[1];
+  {
+    return 0xFFFF;
+  }
+  uint16_t tmp = (data[0] << 8) | data[1];
   return tmp;
 }
 
 
+int CHT8305::getLastError()
+{
+  int e = _error;
+  _error = CHT8305_OK;
+  return e;
+}
+
+
 ////////////////////////////////////////////////
 //
 //  PRIVATE
@@ -412,7 +471,11 @@ int CHT8305::_readRegister(uint8_t reg, uint8_t * buf, uint8_t size)
   _wire->beginTransmission(_address);
   _wire->write(reg);
   int n = _wire->endTransmission();
-  if (n != 0) return CHT8305_ERROR_I2C;
+  if (n != 0)
+  {
+    _error = CHT8305_ERROR_I2C;
+    return _error;
+  }
 
   if (reg == CHT8305_REG_TEMPERATURE)  //  wait for conversion...
   {
@@ -420,14 +483,17 @@ int CHT8305::_readRegister(uint8_t reg, uint8_t * buf, uint8_t size)
   }
 
   n = _wire->requestFrom(_address, size);
-  if (n == size)
+  if (n != size)
   {
-    for (uint8_t i = 0; i < size; i++)
+    _error = CHT8305_ERROR_BUFSIZE;
-    {
+    return _error;
-      buf[i] = _wire->read();
-    }
   }
-  return CHT8305_OK;
+  for (uint8_t i = 0; i < size; i++)
+  {
+    buf[i] = _wire->read();
+  }
+  _error = CHT8305_OK;
+  return _error;
 }
 
 
@@ -440,8 +506,13 @@ int CHT8305::_writeRegister(uint8_t reg, uint8_t * buf, uint8_t size)
     _wire->write(buf[i]);
   }
   int n = _wire->endTransmission();
-  if (n != 0) return CHT8305_ERROR_I2C;
+  if (n != 0)
-  return CHT8305_OK;
+  {
+    _error = CHT8305_ERROR_I2C;
+    return _error;
+  }
+  _error = CHT8305_OK;
+  return _error;
 }
 
 

libraries/CHT8305/CHT8305.h

@@ -2,7 +2,7 @@
 //
 //    FILE: CHT8305.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 // PURPOSE: Arduino library for CHT8305 temperature and humidity sensor
 //     URL: https://github.com/RobTillaart/CHT8305
 //
@@ -12,30 +12,34 @@
 #include "Wire.h"
 
 
-#define CHT8305_LIB_VERSION              (F("0.2.1"))
+#define CHT8305_LIB_VERSION              (F("0.2.2"))
 
 //  DEFAULT ADDRESS
 #ifndef CHT8305_DEFAULT_ADDRESS
 #define CHT8305_DEFAULT_ADDRESS          0x40
 #endif
 
+
 //  ERRORS
 #define CHT8305_OK                       0
 #define CHT8305_ERROR_ADDR               -10
 #define CHT8305_ERROR_I2C                -11
 #define CHT8305_ERROR_CONNECT            -12
+#define CHT8305_ERROR_BUFSIZE            -13
 #define CHT8305_ERROR_LASTREAD           -20
+#define CHT8305_ERROR_GENERIC            -999
 
-//  REGISTERS
-#define CHT8305_REG_TEMPERATURE          0x00
-#define CHT8305_REG_HUMIDITY             0x01
-#define CHT8305_REG_CONFIG               0x02
-#define CHT8305_REG_ALERT                0x03
-#define CHT8305_REG_VOLTAGE              0x04
-#define CHT8305_REG_MANUFACTURER         0xFE
-#define CHT8305_REG_VERSION              0xFF
 
-//  REGISTER MASKS
+//  REGISTERS (in .h for build-CI test)
+#define CHT8305_REG_TEMPERATURE         0x00
+#define CHT8305_REG_HUMIDITY            0x01
+#define CHT8305_REG_CONFIG              0x02
+#define CHT8305_REG_ALERT               0x03
+#define CHT8305_REG_VOLTAGE             0x04
+#define CHT8305_REG_MANUFACTURER        0xFE
+#define CHT8305_REG_VERSION             0xFF
+
+//  REGISTER MASKS (in .h for build-CI test)
 #define CHT8305_CFG_SOFT_RESET          0x8000
 #define CHT8305_CFG_CLOCK_STRETCH       0x4000
 #define CHT8305_CFG_HEATER              0x2000
@@ -78,15 +82,16 @@ public:
 
 
   //  adding offsets works well in normal range
-  void     setHumidityOffset(float offset);
+  void     setHumidityOffset(float offset = 0.0);
   //  might introduce under- or overflow at the ends of the sensor range
-  void     setTemperatureOffset(float offset);
+  void     setTemperatureOffset(float offset = 0.0);
   float    getHumidityOffset();
   float    getTemperatureOffset();
 
 
   //  CONFIGURATION REGISTER
-  void     setConfigRegister(uint16_t bitmask);
+  //  default configRegister = 0x1004 (explicit no default parameter)
+  bool     setConfigRegister(uint16_t bitmask);
   uint16_t getConfigRegister();
   //
   //  |  bit  |  mask  |  name           |  description  |
@@ -132,13 +137,12 @@ public:
   void     setVCCenable(bool enable = true);
   bool     getVCCenable();
 
-
+  //       ALERT  FUNCTIONS
-  //  ALERT FUNCTIONS
+  //       mode    trigger
-  //  mode   trigger
+  //         0       T or H     (default)
-  //    0      T or H     (default)
+  //         1       T
-  //    1      T
+  //         2       H
-  //    2      H
+  //         3       T and H
-  //    3      T and H
   bool     setAlertTriggerMode(uint8_t mode = 0);
   uint8_t  getAlertTriggerMode();
   bool     getAlertPendingStatus();
@@ -153,6 +157,8 @@ public:
 
 
   //  VOLTAGE
+  //       one need to call setVCCenable(true) first.
+  //       meaning of this function is unclear.
   float    getVoltage();
 
 
@@ -161,6 +167,9 @@ public:
   uint16_t getVersionID();        //  may vary
 
 
+  //  ERROR HANDLING
+  int      getLastError();
+
 private:
   float    _humOffset       = 0.0;
   float    _tempOffset      = 0.0;
@@ -177,6 +186,8 @@ private:
 
   void     _setConfigMask(uint16_t mask);
   void     _clrConfigMask(uint16_t mask);
+
+  int      _error = CHT8305_OK;
 };
 
 

libraries/CHT8305/README.md

@@ -15,7 +15,8 @@ Arduino library for CHT8305 temperature and humidity sensor.
 
 **EXPERIMENTAL** minimal tested.
 
-If you are able to test this library, please let me know your experiences.
+If you are able to test this library, please let me know
+your experiences.
 
 
 ## Description
@@ -34,25 +35,25 @@ One of the interesting functions is the support of an ALERT function.
 This prevents the need for continuous polling of the sensor.
 
 
-#### 0.2.0 Breaking change
+### 0.2.0 Breaking change
 
 Version 0.2.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 
+The user has to call **Wire.begin()** and can optionally set the Wire pins
 before calling **begin()**.
 
 Moved the address parameter from **begin()** to constructor.
 
 
-#### Tests
+### Tests
 
 - Temperature and humidity functions works on AVR.
   - default about 14 milliseconds at 14 bit resolution.
 - offset functions work.
 - getVoltage() function works on AVR but meaning unclear.
 - getManufacturer(), getVersionID() works on AVR.
-- 
+-
 
 The ALERT functions are not tested.
 The reason is that the sensor I have does not expose the ALERT pin.
@@ -86,20 +87,43 @@ Always check datasheet for connections.
 Pull ups are needed on SDA, SCL and optional to ALERT.
 
 
-#### Alert
+### Alert
 
 The CHT8305 has an ALERT logic output pin with an open drain structure.
 This output is active low. (if the breakout supports this.)
 
 
-## I2C 
+## I2C
 
-#### performance
+### performance
 
-I2C bus speeds is supported up to 400 KHz.
+I2C bus speeds is supported up to 400 kHz.
+In practice the sensor seems to work even at 800 kHz.
+However not clear if the higher speed brings extra wear?
+
+As the sensor / library blocks on reading the temperature
+using high I2C speeds does not make a difference, except
+for reading Humidity.
+
+So a higher I2C speed does not help to read this sensor.
+
+See - HT8305_performance.ino
 
 
-#### Addresses
+|  SPEED   |  READ   |  READ_T  |  READ_H  |
+|:--------:|:-------:|:--------:|:--------:|
+|  100000  |  14824  |   14604  |    376   |
+|  200000  |  14476  |   14360  |    224   |
+|  300000  |  14368  |   14276  |    172   |
+|  400000  |  14324  |   14244  |    148   |
+|  500000  |  14300  |   14224  |    140   |
+|  600000  |  14276  |   14212  |    132   |
+|  700000  |  14272  |   14204  |    124   |
+|  800000  |  14268  |   14196  |    120   |
+
+
+
+### Addresses
 
 |  AD0  |   Address  |  Notes  |
 |:-----:|:----------:|:--------|
@@ -111,19 +135,19 @@ I2C bus speeds is supported up to 400 KHz.
 Pull ups are needed on SDA, SCL and optional to ALERT.
 
 
-#### I2C multiplexing
+### 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 
+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 
+to eight channels (think of it as I2C subnets) which can use the complete
-address range of the device. 
+address range of the device.
 
-Drawback of using a multiplexer is that it takes more administration in 
+Drawback of using a multiplexer is that it takes more administration in
-your code e.g. which device is on which channel. 
+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 
+Also note that switching between channels will slow down other devices
 too if they are behind the multiplexer.
 
 - https://github.com/RobTillaart/TCA9548
@@ -135,16 +159,16 @@ too if they are behind the multiplexer.
 #include "CHT8305.h"
 ```
 
-#### Constructor
+### Constructor
 
-- **CHT8305(const uint8_t address = CHT8305_DEFAULT_ADDRESS, TwoWire \*wire = &Wire)** Constructor 
+- **CHT8305(const uint8_t address = CHT8305_DEFAULT_ADDRESS, TwoWire \*wire = &Wire)**
-with default address (0x40) and I2C bus.
+Constructor with default address (0x40) and I2C bus.
 - **int begin()** initializes internals.
 Returns error status.
 - **bool isConnected()** checks if address (default 0x40) can be seen on the I2C bus.
 
 
-#### Core
+### Core
 
 - **int read()** reads both the temperature and humidity.
 Can be called once per second.
@@ -153,49 +177,63 @@ Can be called once per second.
 - **uint32_t lastRead()** returns lastRead in MilliSeconds since start sketch.
 Useful to check when it is time to call **read()** again, or for logging.
 - **float getHumidity()** returns last humidity read.
-Will return the same value until **read()** or **readTemperature()** is called again.
-- **float getTemperature()** returns last temperature read.
 Will return the same value until **read()** or **readHumidity()** is called again.
+- **float getTemperature()** returns last temperature read.
+Will return the same value until **read()** or **readTemperature()** is called again.
 
-Note: read(), readTemperature() and readHumidity() blocks each other,
+Note: **read()**, **readTemperature()** and **readHumidity()** block each other,
 so you can call only one of them every second.
 
 
-#### Conversion delay
+### Conversion delay
 
-- **void setConversionDelay(uint8_t cd = 14)** default is 14 milliseconds (datasheet).
+- **void setConversionDelay(uint8_t cd = 14)** default is 14 milliseconds
-7 ms failed. 8 ms worked, so values below 8 are mapped to 8 in the library.
+(from the datasheet). 7 milliseconds failed and 8 milliseconds worked.
-Expect 10 ms is pretty save. Use at own risk.
+So values below 8 milliseconds are mapped to 8 in the library.
+Expect that 10 milliseconds is a pretty save value to work with.
+Adjust this setting at your own risk.
 It might be that lower resolutions allow shorter delays. This is not tested.
-- **uint8_t getConversionDelay()** returns set value.
+- **uint8_t getConversionDelay()** returns the default (14) or last set value.
 
 
-#### Offset
+### Offset
 
-Adding offsets works well in the "normal range" but might introduce 
+Adding offsets works well in the "normal range" but might introduce
 under- or overflow at the ends of the sensor range.
 These are not handled for temperature by the library (humidity since 0.1.7).
-  
+
-- **void setHumidityOffset(float offset)** idem.
+- **void setHumidityOffset(float offset = 0.0)** idem. Default is set to
-- **void setTemperatureOffset(float offset)** idem.
+zero, for an easy reset off the offset.
+There is no range check in this function, however, **read()** will
+keep the value between 0 and 100%.
+- **void setTemperatureOffset(float offset = 0.0)** idem. Default is set to
+zero, for an easy reset off the offset.
+There is no range check in this function.
 - **float getHumidityOffset()** idem.
 - **float getTemperatureOffset()** idem.
 
-If the offset is not the same over the operational range, 
+If the offset is not the same over the operational range,
 consider a mapping function for temperature and humidity.
 e.g. https://github.com/RobTillaart/MultiMap
 
 
-#### Configuration register
+### Configuration register
 
 Check the datasheet for details of the register bits.
 
-- **void setConfigRegister(uint16_t bitmask)** idem. Default value 0x1004.
+- **bool setConfigRegister(uint16_t bitmask)** See table below.
-- **uint16_t getConfigRegister()** idem. 
+Default value 0x1004.
+Returns false if write to the config register fails.
+Check **getLastError()** for possible cause.
+- **uint16_t getConfigRegister()** idem.
+If 0x0000 is returned it may indicate an error.
+Check **getLastError()** for possible cause.
+
+Bits of configRegister, check datasheet for details.
 
 |  bit  |  mask  |  name           |  description  |
 |:-----:|:------:|:----------------|:--------------|
-|  15   | 0x8000 |  soft reset     |  1 = reboot the sensor to default 
+|  15   | 0x8000 |  soft reset     |  1 = reboot the sensor to default
 |  14   | 0x4000 |  clock stretch  |  1 = ON, 0 = OFF (default)
 |  13   | 0x2000 |  heater         |  1 = ON, 0 = OFF (default)
 |  12   | 0x1000 |  mode           |  1 = read both (default), 0 = read T or RH
@@ -207,39 +245,40 @@ Check the datasheet for details of the register bits.
 |  4    | 0x0010 |  H-ALT          |  Humidity Alert status
 |  3    | 0x0008 |  T-ALT          |  Temperature Alert status
 |  2    | 0x0004 |  VCC enable     |  1 = enable VCC measurement (default), 0 = disable
-|  1-0  | 0x0003 |  reserved.      |  do not change. 
+|  1-0  | 0x0003 |  reserved.      |  do not change.
 
 
-#### Getters / setters configuration register
+### Getters / setters configuration register
 
 Note: setting **setConfigRegister(bitmask)** can be faster.
 
-Wrapper functions for easy configuration.
+Wrapper functions for easy configuration. Read the datasheet for the details.
 
-- **void softReset()** sets the soft reset bit in the configuration, causing the sensor to reset.
+- **void softReset()** sets the soft reset bit in the configuration,
+causing the sensor to reset.
 - **void setI2CClockStretch(bool on = false)** check datasheet.
 - **bool getI2CClockStretch()** check datasheet.
-- **void setHeaterOn(bool on = false)** switch on internal heater. 
+- **void setHeaterOn(bool on = false)** switch on internal heater.
 Can improve humidity readings.
 See datasheet for (limited) details.
   - **WARNING** User is responsible for timing as library does not support timing.
 - **bool getHeater()** Returns status of the heater.
 - **void setMeasurementMode(bool both = true)** both T and H or single value.
-- **bool getMeasurementMode()** returns mode set above. 
+- **bool getMeasurementMode()** returns mode set above.
 - **bool getVCCstatus()** 1 ==  > 2.8V  0 == < 2.8V  Useful when battery operated?
 - **void setTemperatureResolution(uint8_t res = 0)** 1 = 11 bit, 0 = 14 bit (default).
 - **uint8_t getTemperatureResolution()** idem.
 - **void setHumidityResolution(uint8_t res = 0)** 2 = 8 bit, 1 = 11 bit, 0 = 14 bit (default).
 - **uint8_t getHumidityResolution()** idem.
-- **void setVCCenable(bool enable = false)** idem.
+- **void setVCCenable(bool enable = false)** enable VCC measurement of the power supply.
-- **bool getVCCenable()** idem.
+- **bool getVCCenable()** return current status of enable bit.
 
 
-#### Alert
+### Alert
 
 See register 3 datasheet page 12 for details.
 
-- **void setAlertTriggerMode(uint8_t mode)** see table below.
+- **void setAlertTriggerMode(uint8_t mode = 0)** see table below.
 - **uint8_t getAlertTriggerMode()** returns 0, 1, 2 or 3.
 
 |  mode  |  trigger  |  notes    |
@@ -252,7 +291,7 @@ See register 3 datasheet page 12 for details.
 - **bool getAlertPendingStatus()** idem.
 - **bool getAlertHumidityStatus()** idem.
 - **bool getAlertTemperatureStatus()** idem.
-- **bool setAlertLevels(float temperature, float humidity)** 
+- **bool setAlertLevels(float temperature, float humidity)**
   - the values will be truncated to the nearest value possible.
   - the ALERT supports HIGH limit only ==> there is no LOW limit ALERT.
   - note: the datasheet is ambiguous with respect to the formula used.
@@ -263,27 +302,53 @@ See register 3 datasheet page 12 for details.
 The ALERT pin triggers with a falling edge (from HIGH to LOW).
 
 
-#### Voltage
+### Supply voltage
 
-VCC measurement should be enabled by means of **void setVCCenable(true)**
+(datasheet 1.1.5)
-or by **setConfigRegister(0x0004)**.
+The chip has a feature to measure supply voltage (VCC) with 16bit output data.
+VCC measurement should be enabled by means of **void setVCCenable(true)**.
 
 - **float getVoltage()** unclear what unit is used.
 
-Best guess for now: 16 bit data implies ```voltage = 5.0V * value / 32768.0;``` 
+Best guess for now: 16 bit data implies ```voltage = 5.0V * value / 32767.0;```
 Varied slightly 5.000 - 4.999 also for 3V3 power supply.
 
-Conclusion: it is unclear how to interpret this register.
+Conclusion: it is not 100 % clear how to interpret this register.
 
 
-#### Meta data
+### Meta data
 
 - **uint16_t getManufacturer()** returns 0x5959.
-- **uint16_t getVersionID()** return value may differ. 
+- **uint16_t getVersionID()** return value may differ.
 Test returned 0x8305.
 
 
-#### Register map 
+### Error handling
+
+Since 0.2.2 some error handling has been added.
+This need to be improved in the future.
+
+- **getLastError()** returns 0 if all is OK.
+If it doesn't return 0 an error occurred during **read()** et al.
+The table gives some information where the problem occurred.
+A call to **getLastError()** resets the internal error flag.
+
+Note: in case of e.g. an I2C error, the last values of Temperature
+and Humidity do not change.
+
+|  Error constant          |   value  |  Notes  |
+|:-------------------------|:--------:|:--------|
+|  CHT8305_OK              |      0   |
+|  CHT8305_ERROR_ADDR      |    -10   |
+|  CHT8305_ERROR_I2C       |    -11   |
+|  CHT8305_ERROR_CONNECT   |    -12   |
+|  CHT8305_ERROR_BUFSIZE   |    -13   |
+|  CHT8305_ERROR_LASTREAD  |    -20   |
+|  CHT8305_ERROR_GENERIC   |    -999  |
+|                          |  0xFFFF  |  patch  |
+
+
+### Register map
 
 See datasheet page 10 for details
 
@@ -303,25 +368,26 @@ See datasheet page 10 for details
 #### Must
 
 - elaborate documentation.
-- more testing (platforms)
-
 
 #### Should
 
-- test ESP32, other platforms?
+- test other platforms
-- test performance.
+  - ESP32,
 - test resolution bits.
   - delay ?
 - test configuration functions.
 - test ALERT functions.
 - test write / readRegister with a single uint16_t to simplify code.
-
+- test error handling.
 
 #### Could
 
 - parameter testing
 - parameter defaults?
-
+- investigate asynchronous reading
+  - request, ready (after 15 millis), fetch
+  - needs lastRequest timestamp
+- configRegister => force bit 0 and 1 to 0
 
 #### Wont
 

libraries/CHT8305/examples/CHT8305_performance/CHT8305_performance.ino

@@ -0,0 +1,83 @@
+//
+//    FILE: CHT8305_performance.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: I2C performance for CHT8305 I2C humidity & temperature sensor
+//     URL: https://github.com/RobTillaart/CHT8305
+
+//  Always check datasheet - front view
+//
+//          +---------------+
+//  VCC ----| VCC           |
+//  SDA ----| SDA  CHT8305  |   CHECK DATASHEET.
+//  GND ----| GND           |
+//  SCL ----| SCL           |
+//   ?  ----| AD0           |   ? depends on address to select
+//          |               |
+//  IRQ ----| ALERT         |   only if enabled.
+//          +---------------+
+//
+//  check datasheet
+//  VCC     RED
+//  GND     BLACK
+//  SDA     YELLOW
+//  SCL     WHITE
+
+
+#include "CHT8305.h"
+
+CHT8305 CHT(0x40);   //  CHT8305_DEFAULT_ADDRESS = 0x40
+
+uint32_t start, stop;
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("CHT8305_LIB_VERSION: ");
+  Serial.println(CHT8305_LIB_VERSION);
+  Serial.println();
+  delay(100);
+
+  Wire.begin();
+  CHT.begin();
+  delay(1000);
+
+  Serial.println("Note: reading temperature is blocking!\n");
+
+  Serial.println("SPEED\tREAD\tREAD_T\tREAD_H");
+  for (uint32_t speed = 100000; speed <= 800000; speed += 50000)
+  {
+    Wire.setClock(speed);
+
+    start = micros();
+    CHT.read();
+    stop = micros();
+    Serial.print(speed);
+    Serial.print("\t");
+    Serial.print(stop - start);
+    delay(1000);
+
+    start = micros();
+    CHT.readTemperature();
+    stop = micros();
+    Serial.print("\t");
+    Serial.print(stop - start);
+    delay(1000);
+
+    start = micros();
+    CHT.readHumidity();
+    stop = micros();
+    Serial.print("\t");
+    Serial.print(stop - start);
+    Serial.print("\n");
+    delay(1000);
+  }
+}
+
+
+void loop()
+{
+}
+
+
+//  -- END OF FILE --

libraries/CHT8305/examples/CHT8305_performance/performance_0.2.2.txt

@@ -0,0 +1,24 @@
+IDE:    1.8.19
+Board:  Arduino
+
+CHT8305_LIB_VERSION: 0.2.2
+
+Note: reading temperature is blocking!
+
+SPEED	READ	READ_T	READ_H
+100000	14824	14604	384
+150000	14596	14440	276
+200000	14480	14360	224
+250000	14416	14312	192
+300000	14368	14276	168
+350000	14340	14252	156
+400000	14332	14244	152
+450000	14308	14236	144
+500000	14300	14232	140
+550000	14284	14212	132
+600000	14280	14220	132
+650000	14272	14208	128
+700000	14268	14204	124
+750000	14260	14196	120
+800000	14264	14200	120
+

libraries/CHT8305/examples/CHT8305_plotter/CHT8305_plotter.ino

@@ -0,0 +1,65 @@
+//
+//    FILE: CHT8305_plotter.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: Demo for CHT8305 I2C humidity & temperature sensor
+//     URL: https://github.com/RobTillaart/CHT8305
+//
+//  to be used with Arduino plotter.
+//
+//  Always check datasheet - front view
+//
+//          +---------------+
+//  VCC ----| VCC           |
+//  SDA ----| SDA  CHT8305  |   CHECK DATASHEET.
+//  GND ----| GND           |
+//  SCL ----| SCL           |
+//   ?  ----| AD0           |   ? depends on address to select
+//          |               |
+//  IRQ ----| ALERT         |   only if enabled.
+//          +---------------+
+//
+//  check datasheet
+//  VCC     RED
+//  GND     BLACK
+//  SDA     YELLOW
+//  SCL     WHITE
+
+
+#include "CHT8305.h"
+
+CHT8305 CHT(0x40);   //  CHT8305_DEFAULT_ADDRESS = 0x40
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("CHT8305_LIB_VERSION: ");
+  Serial.println(CHT8305_LIB_VERSION);
+  Serial.println();
+
+  Wire.begin();
+  Wire.setClock(400000);
+  CHT.begin();
+
+  delay(1000);
+}
+
+
+void loop()
+{
+  if (millis() - CHT.lastRead() >= 1000)
+  {
+    //  READ DATA
+    CHT.read();
+
+    Serial.print(CHT.getLastError());
+    Serial.print('\t');
+    Serial.print(CHT.getHumidity());
+    Serial.print('\t');
+    Serial.println(CHT.getTemperature());
+  }
+}
+
+
+//  -- END OF FILE --

libraries/CHT8305/keywords.txt

@@ -7,11 +7,15 @@ CHT8305	KEYWORD1
 # Methods and Functions (KEYWORD2)
 begin	KEYWORD2
 isConnected	KEYWORD2
+getAddress	KEYWORD2
 
 read	KEYWORD2
+readTemperature	KEYWORD2
+readHumidity	KEYWORD2
+
 lastRead	KEYWORD2
-getTemperature	KEYWORD2
 getHumidity	KEYWORD2
+getTemperature	KEYWORD2
 setConversionDelay	KEYWORD2
 getConversionDelay	KEYWORD2
 
@@ -50,8 +54,20 @@ setAlertLevels	KEYWORD2
 getAlertLevelTemperature	KEYWORD2
 getAlertLevelHumidity	KEYWORD2
 
+getVoltage	KEYWORD2
+
+getManufacturer	KEYWORD2
+getVersionID	KEYWORD2
+
 
 # Constants (LITERAL1)
 CHT8305_LIB_VERSION	LITERAL1
 CHT8305_DEFAULT_ADDRESS	LITERAL1
 
+
+CHT8305_OK	LITERAL1
+CHT8305_ERROR_ADDR	LITERAL1
+CHT8305_ERROR_I2C	LITERAL1
+CHT8305_ERROR_CONNECT	LITERAL1
+CHT8305_ERROR_LASTREAD	LITERAL1
+

libraries/CHT8305/library.json

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

libraries/CHT8305/library.properties

@@ -1,5 +1,5 @@
 name=CHT8305
-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 CHT8305 temperature and humidity sensor.