Register dumping feature (#16)

* POC: register dumping
* Rename to RegisterData, early return on read/CRC error, return bool
* Clean up unused function
* Version bump
* Document readRegister in readme
* Make CRC check optional for readRegister method.

Author: Beanow

AGS02MA.cpp

@@ -2,7 +2,7 @@
 //    FILE: AGS02MA.cpp
 //  AUTHOR: Rob Tillaart, Viktor Balint, Beanow
 //    DATE: 2021-08-12
-// VERSION: 0.2.0
+// VERSION: 0.3.0
 // PURPOSE: Arduino library for AGS02MA TVOC
 //     URL: https://github.com/RobTillaart/AGS02MA
 
@@ -243,6 +243,22 @@ int AGS02MA::lastError()
   return e;
 }
 
+bool AGS02MA::readRegister(uint8_t address, AGS02MA::RegisterData &reg) {
+  if (!_readRegister(address))
+  {
+    return false;
+  }
+
+  _error = AGS02MA_OK;
+  // Don't pollute the struct given to us, until we've handled all error cases.
+  reg.data[0] = _buffer[0];
+  reg.data[1] = _buffer[1];
+  reg.data[2] = _buffer[2];
+  reg.data[3] = _buffer[3];
+  reg.crc = _buffer[4];
+  reg.crcValid = _CRC8(_buffer, 5) == 0;
+  return true;
+}
 
 /////////////////////////////////////////////////////////
 //

AGS02MA.h

@@ -3,7 +3,7 @@
 //    FILE: AGS02MA.h
 //  AUTHOR: Rob Tillaart, Viktor Balint, Beanow
 //    DATE: 2021-08-12
-// VERSION: 0.2.0
+// VERSION: 0.3.0
 // PURPOSE: Arduino library for AGS02MA TVOC
 //     URL: https://github.com/RobTillaart/AGS02MA
 //
@@ -13,7 +13,7 @@
 #include "Wire.h"
 
 
-#define AGS02MA_LIB_VERSION         (F("0.2.0"))
+#define AGS02MA_LIB_VERSION         (F("0.3.0"))
 
 #define AGS02MA_OK                  0
 #define AGS02MA_ERROR               -10
@@ -28,6 +28,13 @@
 class AGS02MA
 {
 public:
+  struct RegisterData
+  {
+    uint8_t data[4];
+    uint8_t crc;
+    bool    crcValid;
+  };
+
   struct ZeroCalibrationData
   {
     /**
@@ -104,6 +111,9 @@ class AGS02MA
   uint8_t  lastStatus() { return _status; };
   uint8_t  dataReady()  { return _status & 0x01; };
 
+  // Reading registers
+  bool     readRegister(uint8_t address, RegisterData &reg);
+
 
 private:
   uint32_t _readSensor();

README.md

@@ -174,8 +174,12 @@ See example sketch.
 To be called after at least 5 minutes in fresh air.
 For v117: 0-65535 = automatic calibration.
 For v118: 0 = automatic calibration, 1-65535 manual calibration.
-- **bool getZeroCalibrationData(ZeroCalibrationData &data);** fills a data struct with the current zero calibration status and value.
+- **bool getZeroCalibrationData(ZeroCalibrationData &data)** fills a data struct with the current zero calibration status and value.
 Returns true on success.
+- **bool readRegister(uint8_t address, RegisterData &reg)** fills a data struct with the chip's register data at that address.
+Primarily intended for troubleshooting and analysis of the sensor. Not recommended to build applications on top of this method's raw data.
+Returns true when the struct is filled, false when the data could not be read.
+Note: unlike other public methods, CRC errors don't return false or show up in `lastError()`, instead the CRC result is stored in `RegisterData.crcValid`.
 - **int lastError()** returns last error.
 - **uint8_t lastStatus()** returns status byte from last read.
 Read datasheet or table below for details. A new read is needed to update this.

examples/AGS02MA_readRegister/AGS02MA_readRegister.ino

@@ -0,0 +1,126 @@
+//
+//    FILE: AGS02MA_readRegister.ino
+//  AUTHOR: Rob Tillaart, Beanow
+// VERSION: 0.3.0
+// PURPOSE: test application
+//    DATE: 2022-04-22
+//     URL: https://github.com/RobTillaart/AGS02MA
+//
+
+
+#include "AGS02MA.h"
+
+
+const uint8_t addresses[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 0x11, 0x20, 0x21};
+
+
+AGS02MA::RegisterData reg;
+AGS02MA AGS(26);
+
+
+void setup()
+{
+  // ESP devices typically mis the first serial log lines after flashing.
+  // Delay somewhat to include all output.
+  delay(1000);
+
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+
+  Wire.begin();
+
+  Serial.print("AGS02MA_LIB_VERSION: ");
+  Serial.println(AGS02MA_LIB_VERSION);
+  Serial.println();
+
+  bool b = AGS.begin();
+  Serial.print("BEGIN:\t");
+  Serial.println(b);
+}
+
+
+void loop()
+{
+  delay(3000);
+  for (auto address : addresses)
+  {
+    bool b = AGS.readRegister(address, reg);
+    Serial.print("REG[0x");
+    Serial.print(address, HEX);
+    Serial.print("]");
+
+    if(b)
+    {
+      printRegister(address, reg);
+    }
+    else
+    {
+      Serial.print("\tError:\t");
+      Serial.println(AGS.lastError());
+    }
+    delay(50);
+  }
+  Serial.println();
+}
+
+
+void printRegister(uint8_t address, AGS02MA::RegisterData &reg) {
+  // Raw bytes first for any register.
+  for (auto b : reg.data)
+  {
+    Serial.print("\t");
+    Serial.print(b);
+  }
+
+  Serial.print("\tCRC: ");
+  Serial.print(reg.crcValid ? "OK  " : "ERR ");
+  Serial.print(reg.crc);
+
+  // Specific interpretations
+  switch (address)
+  {
+  case 0x00:
+    Serial.print("\tSensor data:\t");
+    Serial.print(reg.data[0]);
+    Serial.print("\t");
+    Serial.print(
+      (reg.data[1] << 16) +
+      (reg.data[2] << 8) +
+      reg.data[3]
+    );
+    break;
+  
+  case 0x01:
+  case 0x02:
+  case 0x03:
+  case 0x04:
+    Serial.print("\tCalibration:\t");
+    Serial.print(
+      (reg.data[0] << 8) +
+      reg.data[1]
+    );
+    Serial.print("\t");
+    Serial.print(
+      (reg.data[2] << 8) +
+      reg.data[3]
+    );
+    break;
+  
+  case 0x11:
+    Serial.print("\tVersion:\t");
+    Serial.print(reg.data[3]);
+    break;
+  
+  case 0x21:
+    Serial.print("\tI2C address:\t0x");
+    Serial.print(reg.data[0], HEX);
+    break;
+  
+  default:
+    break;
+  }
+  Serial.println();
+}
+
+
+// -- END OF FILE --

library.json

@@ -21,7 +21,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/AGS02MA.git"
   },
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

library.properties

@@ -1,5 +1,5 @@
 name=AGS02MA
-version=0.2.0
+version=0.3.0
 author=Rob Tillaart <[email protected]>
 maintainer=Rob Tillaart <[email protected]>
 sentence=Arduino library for AGS02MA - TVOC sensor