Manual zero calibration (#15)

* Helper, interpret buffered data as two uint16
* Add manualZeroCalibration, using 0 for automatic. This should fix automatic zero calibration on v118 sensors and be compatible with v117.
* Add getZeroCalibration. Returns a struct to only read the register once, as a typical application needs both values.
* Version bump, add Beanow as author
* Update calibration example
* Include manual zero calibration example
* Readme update
* Base power-off notice on initial status or version + in manual calibration example
* Implement error handling for getZeroCalibrationData
* Include full manualZeroCalibration explanation in readme
* Add ZeroCalibrationData.status warning
* Version & author bump in library.json and library.properties

Author: Beanow

AGS02MA.cpp

@@ -1,8 +1,8 @@
 //
 //    FILE: AGS02MA.cpp
-//  AUTHOR: Rob Tillaart, Viktor Balint
+//  AUTHOR: Rob Tillaart, Viktor Balint, Beanow
 //    DATE: 2021-08-12
-// VERSION: 0.1.4
+// VERSION: 0.2.0
 // PURPOSE: Arduino library for AGS02MA TVOC
 //     URL: https://github.com/RobTillaart/AGS02MA
 
@@ -205,17 +205,37 @@ uint32_t AGS02MA::readUGM3()
 }
 
 
-bool AGS02MA::zeroCalibration()
+bool AGS02MA::manualZeroCalibration(uint16_t value)
 {
   _buffer[0] = 0x00;
   _buffer[1] = 0x0C;
-  _buffer[2] = 0xFF;
-  _buffer[3] = 0xF3;
-  _buffer[4] = 0xFC;
+  _buffer[2] = (uint8_t) (value >> 8);
+  _buffer[3] = (uint8_t) (value & 0x00FF);
+  _buffer[4] = _CRC8(_buffer, 4);
   return _writeRegister(AGS02MA_CALIBRATION);
 }
 
 
+bool AGS02MA::getZeroCalibrationData(AGS02MA::ZeroCalibrationData &data) {
+  if (!_readRegister(AGS02MA_CALIBRATION))
+  {
+    return false;
+  }
+
+  if (_CRC8(_buffer, 5) != 0)
+  {
+    _error = AGS02MA_ERROR_CRC;
+    return false;
+  }
+
+  _error = AGS02MA_OK;
+  // Don't pollute the struct given to us, until we've handled all error cases.
+  data.status = _getDataMSB();
+  data.value = _getDataLSB();
+  return true;
+}
+
+
 int AGS02MA::lastError()
 {
   int e = _error;
@@ -250,7 +270,7 @@ uint32_t AGS02MA::_readSensor()
   }
   return value;
 }
- 
+
 
 bool AGS02MA::_readRegister(uint8_t reg)
 {
@@ -301,6 +321,15 @@ bool AGS02MA::_writeRegister(uint8_t reg)
   return (_error == 0);
 }
 
+uint16_t AGS02MA::_getDataMSB()
+{
+  return (_buffer[0] << 8) + _buffer[1];
+}
+
+uint16_t AGS02MA::_getDataLSB()
+{
+  return (_buffer[2] << 8) + _buffer[3];
+}
 
 uint8_t AGS02MA::_CRC8(uint8_t * buf, uint8_t size)
 {

AGS02MA.h

@@ -1,9 +1,9 @@
 #pragma once
 //
 //    FILE: AGS02MA.h
-//  AUTHOR: Rob Tillaart, Viktor Balint
+//  AUTHOR: Rob Tillaart, Viktor Balint, Beanow
 //    DATE: 2021-08-12
-// VERSION: 0.1.4
+// VERSION: 0.2.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.1.4"))
+#define AGS02MA_LIB_VERSION         (F("0.2.0"))
 
 #define AGS02MA_OK                  0
 #define AGS02MA_ERROR               -10
@@ -28,6 +28,19 @@
 class AGS02MA
 {
 public:
+  struct ZeroCalibrationData
+  {
+    /**
+     * Warning, the exact meaning of this status is not fully documented.
+     * It seems like it's a bitmask:
+     * 0000 1100 | 0x0C | 12  | Typical value
+     * 0000 1101 | 0x0D | 13  | Sometimes seen on v117
+     * 0111 1101 | 0x7D | 125 | Seen on v118, after power-off (gives different data than 12!)
+     */
+    uint16_t status;
+    uint16_t value;
+  };
+
   // address 26 = 0x1A
   explicit AGS02MA(const uint8_t deviceAddress = 26, TwoWire *wire = &Wire);
 
@@ -53,7 +66,16 @@ class AGS02MA
   uint32_t getI2CResetSpeed() { return _I2CResetSpeed; };
 
   // to be called after at least 5 minutes in fresh air.
-  bool     zeroCalibration();
+  bool     zeroCalibration() { return manualZeroCalibration(0); };
+
+  /**
+   * Set the zero calibration value manually.
+   * 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     manualZeroCalibration(uint16_t value = 0);
+  bool     getZeroCalibrationData(ZeroCalibrationData &data);
 
 
   // MODE
@@ -99,6 +121,8 @@ class AGS02MA
   uint8_t  _status        = 0;
   uint8_t  _buffer[5];
 
+  uint16_t _getDataMSB();
+  uint16_t _getDataLSB();
   uint8_t  _CRC8(uint8_t * buf, uint8_t size);
   uint8_t  _bin2bcd(uint8_t val);
 

README.md

@@ -170,6 +170,12 @@ Typical value should be between 0.01 .. 999.99
 
 - **bool zeroCalibration()** to be called after at least 5 minutes in fresh air.
 See example sketch.
+- **bool manualZeroCalibration(uint16_t value = 0)** Set the zero calibration value manually.
+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.
+Returns true on success.
 - **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_calibrate/AGS02MA_calibrate.ino

@@ -1,59 +1,165 @@
 //
 //    FILE: AGS02MA_calibrate.ino
-//  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
+//  AUTHOR: Rob Tillaart, Beanow
+// VERSION: 0.2.0
 // PURPOSE: test application
 //    DATE: 2021-08-12
 //     URL: https://github.com/RobTillaart/AGS02MA
 //
 
 #include "AGS02MA.h"
 
+// You can decrease/disable warmup when you're certain the chip already warmed up.
+#define WARMUP_MINUTES 6
+#define READ_INTERVAL 3000
 
-uint32_t start, stop;
 
+uint32_t start, stop;
+uint8_t version;
 
 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__);
 
   Serial.print("AGS02MA_LIB_VERSION: ");
   Serial.println(AGS02MA_LIB_VERSION);
   Serial.println();
 
+  Serial.print("WARMUP:\t\t");
+  Serial.println(WARMUP_MINUTES);
+  Serial.print("INTERVAL:\t");
+  Serial.println(READ_INTERVAL);
+
   Wire.begin();
 
   bool b = AGS.begin();
-  Serial.print("BEGIN:\t");
+  Serial.print("BEGIN:\t\t");
   Serial.println(b);
 
-  Serial.println("Place the device outside in open air for 6 minutes");
-  Serial.println("Take a drink and relax ;)");
+  Serial.print("VERSION:\t");
+  version = AGS.getSensorVersion();
+  Serial.println(version);
+  int err = AGS.lastError();
+
+  // Reading version correctly matters, as we display additional comments based on it.
+  if(err != AGS02MA_OK)
+  {
+    Serial.print("Error reading version:\t");
+    Serial.println(err);
+    Serial.println("Won't attempt to calibrate. Reset when connection with the sensor is stable.");
+    Serial.println();
+    return;
+  }
+
+  b = AGS.setPPBMode();
+  uint8_t m = AGS.getMode();
+  Serial.print("MODE:\t\t");
+  Serial.print(b);
+  Serial.print("\t");
+  Serial.println(m);
+
+  Serial.println();
+  Serial.print("Place the device outside in open air for ");
+  Serial.print(WARMUP_MINUTES);
+  Serial.println(" minute(s).");
+  Serial.println("Make sure your device has warmed up sufficiently for the best results.");
+  Serial.println("The PPB values should be stable (may include noise) not constantly decreasing.");
   Serial.println();
 
   start = millis();
-  while(millis() - start < 360000UL)
+  stop = WARMUP_MINUTES * 60000UL;
+  while(millis() - start < stop)
+  {
+    Serial.print("[PRE ]\t");
+    printPPB();
+    delay(READ_INTERVAL);
+  }
+
+  Serial.println();
+  Serial.println("About to perform calibration now.");
+
+  AGS02MA::ZeroCalibrationData initialValue;
+  if (!AGS.getZeroCalibrationData(initialValue))
   {
-    delay(15000);
-    Serial.println(millis() - start);
+    Serial.print("Error reading zero calibration data:\t");
+    Serial.println(AGS.lastError());
+    Serial.println("Won't attempt to calibrate. Reset when connection with the sensor is stable.");
+    Serial.println();
+    return;
   }
 
+  Serial.println("Your previous calibration data was:");
+  printZeroCalibrationData(initialValue);
+
+  delay(1000);
+
   // returns 1 if successful written
   b = AGS.zeroCalibration();
+  Serial.println();
   Serial.print("CALIB:\t");
   Serial.println(b);
+  Serial.println();
+  Serial.println("Calibration done.");
+
+  AGS02MA::ZeroCalibrationData zc;
+  while (!AGS.getZeroCalibrationData(zc))
+  {
+    Serial.print("Error:\t");
+    Serial.print(AGS.lastError());
+    Serial.println("\tretrying...");
+    delay(READ_INTERVAL);
+  }
 
-  Serial.println("Calibration done");
+  Serial.println("Your new calibration data is:");
+  printZeroCalibrationData(zc);
+
+  Serial.println();
+  Serial.println("Showing what PPB values look like post calibration.");
+  // A 125 status is typically shown on v118's after they've been powered off.
+  // Either having this version at all, or seeing this status, we'll display a notice.
+  if (version == 118 || initialValue.status == 125)
+  {
+    Serial.println("NOTICE: v118 sensors are known to give different results after powering off!");
+    Serial.println("You may need to manually set your calibration value every time power was lost.");
+  }
+  Serial.println();
 }
 
 
 void loop()
 {
+  Serial.print("[POST]\t");
+  printPPB();
+  delay(READ_INTERVAL);
+}
+
+
+void printZeroCalibrationData(AGS02MA::ZeroCalibrationData &zc) {
+  Serial.print("Status:\t");
+  Serial.println(zc.status);
+  Serial.print("Value:\t");
+  Serial.println(zc.value);
 }
 
 
+void printPPB()
+{
+  uint32_t value = AGS.readPPB();
+  Serial.print("PPB:\t");
+  Serial.print(value);
+  Serial.print("\t");
+  Serial.print(AGS.lastStatus(), HEX);
+  Serial.print("\t");
+  Serial.print(AGS.lastError(), HEX);
+  Serial.println();
+}
+
 // -- END OF FILE --