update readme.md (#11)

- update keywords.txt - add defaults to offset functions. - update readme.md - update GitHub actions - update license 2023
RobTillaart · Feb 10, 2023 · 3f1510a · 3f1510a
1 parent f3b0cff
commit 3f1510a
Show file tree

Hide file tree

Showing 12 changed files with 432 additions and 53 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,14 +6,21 @@ 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-21
+- update keywords.txt
+- add defaults to offset functions.
+- update readme.md
+- update GitHub actions
+- update license 2023
+
+
 ## [0.2.1] - 2022-12-21
 - first part of the **readStatus()** not part of the protocol 
   - different interpretation of datasheet page 10 section 7.4
   - the state is sent after a read command as first byte
   - see https://github.com/RobTillaart/DHT20/issues/8 + page 11 datasheet
 - add **getAddress()** convenience function.
 
-
 ## [0.2.0] - 2022-10-30
 - add changelog.md
 - add rp2040 to build-CI

diff --git a/DHT20.cpp b/DHT20.cpp
@@ -1,7 +1,7 @@
 //
 //    FILE: DHT20.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 // PURPOSE: Arduino library for DHT20 I2C temperature and humidity sensor.
 
 
@@ -23,7 +23,7 @@ DHT20::DHT20(TwoWire *wire)
   _humidity    = 0;
   _humOffset   = 0;
   _tempOffset  = 0;
-  _status      = 0;
+  _status      = DHT20_OK;
   _lastRequest = 0;
   _lastRead    = 0;
 }
@@ -89,7 +89,7 @@ uint8_t DHT20::resetSensor()
 //
 int DHT20::read()
 {
-  //  do not read to fast
+  //  do not read to fast == more than once per second.
   if (millis() - _lastRead < 1000)
   {
     return DHT20_ERROR_LASTREAD;
@@ -115,7 +115,7 @@ int DHT20::requestData()
 {
   //  reset sensor if needed.
   resetSensor();
-  
+
   //  GET CONNECTION
   _wire->beginTransmission(DHT20_ADDRESS);
   _wire->write(0xAC);
@@ -201,7 +201,7 @@ float DHT20::getTemperature()
 
 void DHT20::setHumOffset(float offset)
 {
-  _humOffset  = offset;
+  _humOffset = offset;
 };
 
 
@@ -319,7 +319,7 @@ bool DHT20::_resetRegister(uint8_t reg)
   if (_wire->endTransmission() != 0) return false;
   delay(5);
 
-  int bytes = _wire->requestFrom(DHT20_ADDRESS, (uint8_t)3); 
+  int bytes = _wire->requestFrom(DHT20_ADDRESS, (uint8_t)3);
   for (int i = 0; i < bytes; i++)
   {
     value[i] = _wire->read();

diff --git a/DHT20.h b/DHT20.h
@@ -3,8 +3,7 @@
 //    FILE: DHT20.h
 //  AUTHOR: Rob Tillaart
 // PURPOSE: Arduino library for DHT20 I2C temperature and humidity sensor.
-// VERSION: 0.2.1
-// HISTORY: See DHT20.cpp
+// VERSION: 0.2.2
 //     URL: https://github.com/RobTillaart/DHT20
 //
 
@@ -21,7 +20,7 @@
 #include "Arduino.h"
 #include "Wire.h"
 
-#define DHT20_LIB_VERSION                    (F("0.2.1"))
+#define DHT20_LIB_VERSION                    (F("0.2.2"))
 
 #define DHT20_OK                             0
 #define DHT20_ERROR_CHECKSUM                -10
@@ -53,11 +52,11 @@ class DHT20
   int      requestData();
   //  read the raw data.
   int      readData();
-  //  converts raw databits to temperature and humidity.
+  //  converts raw data bits to temperature and humidity.
   int      convert();
 
 
-  //  SYNCHRONUOUS CALL
+  //  SYNCHRONOUS CALL
   //  blocking read call to read + convert data
   int      read();
   //  access the converted temperature & humidity
@@ -66,8 +65,8 @@ class DHT20
 
 
   //  OFFSET  1st order adjustments
-  void     setHumOffset(float offset);
-  void     setTempOffset(float offset);
+  void     setHumOffset(float offset = 0);
+  void     setTempOffset(float offset = 0);
   float    getHumOffset();
   float    getTempOffset();
 
@@ -88,13 +87,13 @@ class DHT20
 
 
   //  RESET  (new since 0.1.4)
-  //  use with care 
+  //  use with care
   //  returns number of registers reset => must be 3
   //  3     = OK
   //  0,1,2 = error.
   //  255   = no reset needed.
   //  See datasheet 7.4 Sensor Reading Process, point 1
-  //  use with care 
+  //  use with care
   uint8_t  resetSensor();
 
 
@@ -118,5 +117,5 @@ class DHT20
 };
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ Arduino library for I2C DHT20 temperature and humidity sensor.
 
 ## Description
 
-The DHT20 is a humidity an temperature sensor. 
+The DHT20 is a humidity and temperature sensor. 
 
 The sensor has a fixed address of **0x38**.
 It is not known if the address can be changed.
@@ -53,7 +53,21 @@ This keeps the API simple. The reads are 1-2 ms slower than 0.1.4. (< 50 ms).
 Still far below the 80 ms mentioned in the datasheet. 
 
 
-### Connection
+#### Tested
+
+Verified to work with Arduino UNO and ESP32 and ESP8266 (see #8)
+Please let me know if other platforms work (or not).
+
+
+## I2C
+
+#### Address
+
+The sensor has a fixed address of **0x38**.
+It is not known if the address can be changed.
+
+
+#### Connection
 
 Always check datasheet!
 
@@ -67,24 +81,71 @@ Front view
           +--------------+
 ```
 
-### Tested
+#### Performance
 
-Verified to work with Arduino UNO and ESP32 and ESP8266 (see #8)
-Please let me know if other platforms work (or not).
+The datasheet states 400 KHz as the maximum speed.
+Below the results of a small test that works well up to 800 KHz.
+
+ - Arduino UNO + 10 cm wires + no pull up + DHT20_I2C_speed.ino
+
+Speed in KHz, Time in microseconds. 
+
+
+**read()**
+
+|  Speed  |  Time   |  notes  |
+|:-------:|:-------:|:--------|
+|   100   |  44588  |  default I2C speed  |
+|   200   |  43988  |
+|   400   |  44040  |  datasheet maximum  |
+|   600   |  43224  |
+|   800   |  43988  |
+
+
+**ASYNC: requestData()**
+
+|  Speed  |  Time   |  notes  |
+|:-------:|:-------:|:--------|
+|   100   |  1676   |  default I2C speed  |
+|   200   |  1384   |
+|   400   |  1240   |  datasheet maximum  |
+|   600   |  1188   |
+|   800   |  1168   |
+
+
+**ASYNC: readData()**
+
+|  Speed  |  Time   |  notes  |
+|:-------:|:-------:|:--------|
+|   100   |   832   |  default I2C speed  |
+|   200   |   464   |
+|   400   |   284   |  datasheet maximum  |
+|   600   |   212   |
+|   800   |   188   |
+
+The numbers indicate that the conversion takes > 40 milliseconds.
+Requesting the measurement and fetching the data < 2.5 milliseconds.
+
+Using the asynchronous interface frees up a lot of clock cycles.
+Going beyond 400 KHz (datasheet max) does not save much extra time,
+and should only be used if you are in a need for speed.
 
 
 ## Interface
 
+```cpp
+#include "DHT20.h"
+```
 
-### Constructor
+#### Constructor
 
 - **DHT20(TwoWire \*wire = &Wire)** constructor, using a specific Wire (I2C bus).
 - **bool begin(uint8_t dataPin, uint8_t clockPin)** begin for ESP32 et al, to set I2C bus pins.
 - **bool begin()** initializer for non ESP32. Returns true if connected.
 - **bool isConnected()** returns true if the address of the DHT20 can be seen on the I2C bus.
 - **uint8_t getAddress()** returns the (fixed) address - convenience.
 
-### Core
+#### Core
 
 - **int8_t read()** read the sensor and store the values internally. 
 Returns the status of the read which should be 0 == **DHT20_OK**.
@@ -94,15 +155,17 @@ Multiple calls will return same value until a new **read()** is made.
 Multiple calls will return same value until a new **read()** is made.
 
 
-### Offset
+#### Offset
 
-- **void setHumOffset(float offset)** set an offset to calibrate the sensor (1st order).
+- **void setHumOffset(float offset = 0)** set an offset to calibrate the sensor (1st order).
+Default offset is 0.
 - **float getHumOffset()** return current humidity offset, default 0.
-- **void setTempOffset(float offset)** set an offset to calibrate the sensor (1st order).
+- **void setTempOffset(float offset = 0)** set an offset to calibrate the sensor (1st order).
+Default offset is 0.
 - **float getTempOffset()** return current temperature offset, default 0.
 
 
-### Asynchronous interface
+#### Asynchronous interface
 
 There are two timings that need to be considered (from datasheet):
 - time between requests = 1000 ms.
@@ -126,7 +189,7 @@ Note there must be at least 1000 milliseconds between requests!
 See the example **DHT20_async.ino**
 
 
-### Status
+#### Status
 
 - **uint8_t readStatus()** forced read of the status only.
 This function blocks a few milliseconds to optimize communication.
@@ -157,53 +220,52 @@ The call is needed to get the **read()** working well so it has been embedded in
 the read calls. (0.2.0)
 
 
-### Timing
+#### Timing
 
 - **uint32_t lastRead()** last time the sensor is read in milliseconds since start.
 - **uint32_t lastRequest()** last time a request is made to make a measurement.
 
 
-### Return codes
-
-| name                        |  value  |  notes  |
-|:----------------------------|:-------:|:--------|
-| DHT20_OK                    |    00   |  OK
-| DHT20_ERROR_CHECKSUM        |   -10   |  values might be OK if they are like recent previous ones.
-| DHT20_ERROR_CONNECT         |   -11   |  check connection
-| DHT20_MISSING_BYTES         |   -12   |  check connection
-| DHT20_ERROR_BYTES_ALL_ZERO  |   -13   |  check connection
-| DHT20_ERROR_READ_TIMEOUT    |   -14   |
-| DHT20_ERROR_LASTREAD        |   -15   |  wait 1 second between reads
-
+#### Return codes
 
-## Operation
-
-See examples
+|  name                        |  value  |  notes  |
+|:-----------------------------|:-------:|:--------|
+|  DHT20_OK                    |    00   |  OK
+|  DHT20_ERROR_CHECKSUM        |   -10   |  values might be OK if they are like recent previous ones.
+|  DHT20_ERROR_CONNECT         |   -11   |  check connection
+|  DHT20_MISSING_BYTES         |   -12   |  check connection
+|  DHT20_ERROR_BYTES_ALL_ZERO  |   -13   |  check connection
+|  DHT20_ERROR_READ_TIMEOUT    |   -14   |
+|  DHT20_ERROR_LASTREAD        |   -15   |  wait 1 second between reads
 
 
 ## Future
 
-#### must
+#### Must
+
 - improve documentation.
 - investigate the bug from #8 further
   (is done in 0.2.1 see issue #8)
 
-#### should
 
+#### Should
+
+
+#### Could
 
-#### could
 - improve unit tests.
 - investigate 
   - sensor calibration (website aosong?)
+  - can sensor address be changed?
 - investigate optimizing timing in readStatus()
   - delay(1) ==> microSeconds(???).
 - connected flag?
+- keep in sync DHT12 ?
 
 
-#### won't
+#### Wont
 
 - **void setIgnoreChecksum(bool = false)** ignore checksum flag speeds up communication a bit
 - **bool getIgnoreChecksum()** get checksum flag. for completeness.
--