0.1.1 AGS02MA

Author: RobTillaart

libraries/AGS02MA/AGS02MA.cpp

@@ -1,8 +1,8 @@
 //
 //    FILE: AGS02MA.cpp
-//  AUTHOR: Rob Tillaart
+//  AUTHOR: Rob Tillaart, Viktor Balint
 //    DATE: 2021-08-12
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 // PURPOSE: Arduino library for AGS02MA TVOC
 //     URL: https://github.com/RobTillaart/AGS02MA
 
@@ -18,12 +18,17 @@
 
 
 
-
 AGS02MA::AGS02MA(const uint8_t deviceAddress, TwoWire *wire)
 {
-  _address    = deviceAddress;
-  _wire       = wire;
-  _error      = AGS02MA_OK;
+  _address       = deviceAddress;
+  _wire          = wire;
+
+  _I2CResetSpeed = 100000;
+  _startTime     = 0;
+  _lastRead      = 0;
+  _mode          = 255;
+  _status        = AGS02MA_OK;
+  _error         = AGS02MA_OK;
 }
 
 
@@ -54,13 +59,13 @@ bool AGS02MA::begin()
 bool AGS02MA::isConnected()
 {
 #if defined (__AVR__)
-  TWBR = 255; 
+  TWBR = 255;
 #else
   _wire->setClock(AGS02MA_I2C_CLOCK);
 #endif
   _wire->beginTransmission(_address);
-  bool rv =  ( _wire->endTransmission() == 0);
-  _wire->setClock(_I2CReseSpeed);
+  bool rv = ( _wire->endTransmission(true) == 0);
+  _wire->setClock(_I2CResetSpeed);
   return rv;
 }
 
@@ -84,6 +89,7 @@ uint8_t AGS02MA::getSensorVersion()
   uint8_t version = 0xFF;
   if (_readRegister(AGS02MA_VERSION))
   {
+    // unclear what the other bytes have for information. (if there is any)
     version = _buffer[3];
     if (_CRC8(_buffer, 5) != 0)
     {
@@ -147,6 +153,7 @@ uint32_t AGS02MA::readPPB()
 
 uint32_t AGS02MA::readUGM3()
 {
+  // TODO identical code wise to PPB, can be merged into one.
   uint32_t val = 0xFFFFFFFF;
   _lastRead = millis();
   if (_readRegister(AGS02MA_DATA))
@@ -183,41 +190,41 @@ int AGS02MA::lastError()
 }
 
 
-
 /////////////////////////////////////////////////////////
 //
 // PRIVATE
 //
 bool AGS02MA::_readRegister(uint8_t reg)
 {
 #if defined (__AVR__)
-  TWBR = 255; 
+  TWBR = 255;
 #else
   _wire->setClock(AGS02MA_I2C_CLOCK);
 #endif
   _wire->beginTransmission(_address);
   _wire->write(reg);
-  _error = _wire->endTransmission();
-
+  _error = _wire->endTransmission(true);
+  delay(30);
   if (_wire->requestFrom(_address, (uint8_t)5) != 5)
   {
     _error = AGS02MA_ERROR;
-    _wire->setClock(_I2CReseSpeed);
+    _wire->setClock(_I2CResetSpeed);
     return false;
   }
   for (int i = 0; i < 5; i++)
   {
     _buffer[i] = _wire->read();
   }
-  _wire->setClock(_I2CReseSpeed);
+  delay(30);
+  _wire->setClock(_I2CResetSpeed);
   return true;
 }
 
 
 bool AGS02MA::_writeRegister(uint8_t reg)
 {
 #if defined (__AVR__)
-  TWBR = 255; 
+  TWBR = 255;
 #else
   _wire->setClock(AGS02MA_I2C_CLOCK);
 #endif
@@ -227,8 +234,9 @@ bool AGS02MA::_writeRegister(uint8_t reg)
   {
     _wire->write(_buffer[i]);
   }
-  _error = _wire->endTransmission();
-  _wire->setClock(_I2CReseSpeed);
+  _error = _wire->endTransmission(true);
+  delay(30);
+  _wire->setClock(_I2CResetSpeed);
   return (_error == 0);
 }
 

libraries/AGS02MA/AGS02MA.h

@@ -1,9 +1,9 @@
 #pragma once
 //
 //    FILE: AGS02MA.h
-//  AUTHOR: Rob Tillaart
+//  AUTHOR: Rob Tillaart, Viktor Balint
 //    DATE: 2021-08-12
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 // PURPOSE: Arduino library for AGS02MA TVOC
 //     URL: https://github.com/RobTillaart/AGS02MA
 //
@@ -13,66 +13,72 @@
 #include "Wire.h"
 
 
-#define AGS02MA_LIB_VERSION         (F("0.1.0"))
+#define AGS02MA_LIB_VERSION         (F("0.1.1"))
 
 #define AGS02MA_OK                  0
 #define AGS02MA_ERROR               -10
 #define AGS02MA_CRC_ERROR           -11
 
 
-#define AGS02MA_I2C_CLOCK           25000
-#define AGS02MA_I2C_RESET           400000
+#define AGS02MA_I2C_CLOCK           30000
 
 
 class AGS02MA
 {
 public:
+  // address 26 = 0x1A
   explicit AGS02MA(const uint8_t deviceAddress = 26, TwoWire *wire = &Wire);
 
-#if defined (ESP8266) || defined(ESP32) 
+#if defined (ESP8266) || defined(ESP32)
   bool     begin(uint8_t sda, uint8_t scl);
 #endif
   bool     begin();
   bool     isConnected();
 
   bool     isHeated() { return (millis() - _startTime) > 120000UL; };
-  uint32_t lastRead() { return _lastRead; };
 
+
+  // CONFIGURATION
   bool     setAddress(const uint8_t deviceAddress);
   uint8_t  getAddress() { return _address; };
-
   uint8_t  getSensorVersion();
-  void     setI2CResetSpeed(uint32_t s) { _I2CReseSpeed = s; };
-  uint32_t getI2CResetSpeed() { return _I2CReseSpeed; };
 
+  // to set the speed the I2C bus should return to
+  // as the device operates at very low bus speed.
+  void     setI2CResetSpeed(uint32_t s) { _I2CResetSpeed = s; };
+  uint32_t getI2CResetSpeed() { return _I2CResetSpeed; };
+
+  // to be called after at least 5 minutes in fresh air.
+  bool     zeroCalibration();
 
+
+  // CORE
   bool     setPPBMode();
   bool     setUGM3Mode();
   uint8_t  getMode() { return _mode; };
 
   uint32_t readPPB();
   uint32_t readUGM3();
 
-  // to be called after at least 5 minutes in fresh air.
-  bool     zeroCalibration();
-
+  uint32_t lastRead() { return _lastRead; };
   int      lastError();
   uint8_t  lastStatus() { return _status; };
 
+
 private:
   bool     _readRegister(uint8_t reg);
   bool     _writeRegister(uint8_t reg);
-  uint8_t  _CRC8(uint8_t * buf, uint8_t size);
 
-  uint32_t _I2CReseSpeed  = 100000;
+  uint32_t _I2CResetSpeed = 100000;
   uint32_t _startTime     = 0;
   uint32_t _lastRead      = 0;
   uint8_t  _address       = 0;
   uint8_t  _mode          = 255;
   uint8_t  _status        = 0;
-
   uint8_t  _buffer[5];
 
+  uint8_t  _CRC8(uint8_t * buf, uint8_t size);
+
   int      _error = AGS02MA_OK;
 
   TwoWire*  _wire;

libraries/AGS02MA/README.md

@@ -4,22 +4,28 @@
 
 # AGS02MA
 
-Arduino library for AGS02MA TVOC sensor. 
+Arduino library for AGS02MA TVOC sensor.
 
-This library is experimental, so please use with care. 
-Please note the warning about the I2C speed.
+This library is experimental, so please use with care.
+Note the warning about the I2C speed, the device works at 30 KHz.
 
 
 ## I2C - warning low speed
 
-The sensor uses I2C at very low speed < 30KHz. For an Arduino UNO the lowest speed is about 30.4KHz (TWBR = 255) which works sometimes. During tests roughly 1 in 20 reads of the sensor was successful.
-Tests with ESP32, which can go as low as ~5 KHZ are underway and expected to work.
+The sensor uses I2C at very low speed <= 30 KHz.
+For an Arduino UNO the lowest speed possible is about 30.4KHz (TWBR = 255) which works.
+Tests with ESP32 / ESP8266 at 30 KHz look good, tests with lower clock speeds are to be done but expected to work.
+First runs indicate 2 failed reads in > 500 Reads, so less than 1%
+
+The library sets the clock speed to 30 KHz (for non AVR) during operation and resets it to 100 KHz after operation.
+This is done to minimize interference with the communication of other devices. The reset clock speed can be changed with **setI2CResetSpeed()** e.g. to 200 or 400 KHz.
 
-The library sets the clock speed to 25KHz (for non AVR) during operation and resets it to 100 KHz
-after operation. This is done to minimize interference with the communication with other devices.
 
 ## Interface
 
+
+### Constructor
+
 - **AGS02MA(uint8_t deviceAddress = 26, TwoWire \*wire = &Wire)** constructor, with default address and default I2C interface.
 - **bool begin(uint8_t sda, uint8_t scl)** begin for ESP32 and ESP8266.
 - **bool begin()** initializer for Arduino UNO a.o.
@@ -28,58 +34,91 @@ after operation. This is done to minimize interference with the communication wi
 
 ### Timing
 
-- **bool isHeated()** returns true if 2 minutes have passed after startup. 
-Otherwise the device is not ready.
-- **uint32_t lastRead()** last time the device is read, timestamp in milliseconds since start.
+- **bool isHeated()** returns true if 2 minutes have passed after startup (call of **begin()** ).
+Otherwise the device is not optimal ready.
+According to the datasheet the preheating will improve the quality
+of the measurements.
+- **uint32_t lastRead()** last time the device is read, timestamp is in milliseconds since start.
+Returns 0 if **readPPB()** or **readUGM3()** is not called yet.
+This function allows to implement sort of asynchronous wait.
+One must keep reads ~3 seconds apart according to the datasheet.
 
 
 ### Administration
 
-- **bool setAddress(const uint8_t deviceAddress)** Not implemented yet.
-- **uint8_t getAddress()** returns set address.
+- **bool setAddress(const uint8_t deviceAddress)** sets a new addres for the sensor. If function succeeds the address changes immediately and will be persistent over a reboot.
+- **uint8_t getAddress()** returns the set address. Default the function will return 26 or 0x1A.
 - **uint8_t getSensorVersion()** reads sensor version from device.
+If the version cannot be read the function will return 255.
 
-The library sets the clock speed to 25KHz (for non AVR) during operation and resets it to 100 KHz
-after operation. This is done to minimize interference with the communication with other devices.
-The following function can change this reset speed.
+The library sets the clock speed to 30 KHz (for non AVR) during operation and resets it to 100 KHz after operation.
+This is done to minimize interference with the communication of other devices.
+The following function can change the I2C reset speed to e.g. 200 or 400 KHz.
 
 - **setI2CResetSpeed(uint32_t s)** sets the I2C speed the library need to reset the I2C speed to.
-- **getI2CResetSpeed()** returns the set value above. Default is 100KHz.
+- **getI2CResetSpeed()** returns the set value above. Default is 100 KHz.
 
 
 ### setMode
 
+The default mode at startup of the sensor is PPB = parts per billion.
+
 - **bool setPPBMode()** sets device in PartPerBillion mode. Returns true on success.
 - **bool setUGM3Mode()** sets device in micro gram per cubic meter mode. Returns true on success.
 - **uint8_t getMode()** returns mode set. 0 = PPB, 1 = UGm3, 255 = not set.
 
 
+#### PPB versus UGM3
+
+There is no 1 to 1 relation between the PPB and the uG/m3 readings as this relation depends on the weight of the individual molecules.
+PPB is therefore an more an absolute indicator where uG/m3 is sort of relative indicator.
+If the gas is unknown, PPB is imho the preferred measurement.
+
+
 ### Reading
 
-WARNING: Take at least 2 seconds between reads.
+WARNING: Datasheet advises to take 3 seconds between reads.
+You might be able to squeeze time down to 1.5 second at your own risk.
 
-- **uint32_t readPPB()** reads PPB from device. returns 0xFFFFFFFF if failed. 
-Check lastStatus() to get more info
+- **uint32_t readPPB()** reads PPB from device.
+Returns 0xFFFFFFFF if failed.
+Typical value should be between 1..999999.
+Check lastStatus() to get more info about success.
 - **uint32_t readUGM3()** reads current value from device. 
+Returns 0xFFFFFFFF if failed.
 
 
 ### Other
 
-- **bool zeroCalibration()** to be called after at least 5 minutes in fresh air. 
-See example sketch. 
+- **bool zeroCalibration()** to be called after at least 5 minutes in fresh air.
+See example sketch.
 - **int lastError()** returns last error.
-- **uint8_t lastStatus()** returns status byte from last read. Read datasheet.
+- **uint8_t lastStatus()** returns status byte from last read.
+Read datasheet for details. 
 
 
 ## Future
 
-- improve documentation
 - test test test ...
-- add examples
-- optimize code 
-- buy a sensor
-- elaborate error handling.
-- elaborate unit test.
+- buy a few sensors
+
+### Documentation
 
+- improve
+- add table for molecular weights
+- add indicative table for PPB health zone
+
+### Code
+
+- add examples 
+- add **float readPPM()**
+- add **float readmGM3()**
+- add **bool RDYbit()** split the RDY bit of the status byte
+- check the mode bits of the status byte with internal \_mode.
+- optimize code where possible
+- optimize timing 30ms between low level I2C reads and writes.
+- elaborate error handling.
+- improve unit testing?
+- investigate max frequency of reads (now 3 seconds apart)