refactor API, begin() (#25)

- refactor API, begin()
- update readme.md

Author: RobTillaart

AGS02MA.cpp

@@ -2,7 +2,7 @@
 //    FILE: AGS02MA.cpp
 //  AUTHOR: Rob Tillaart, Viktor Balint, Beanow
 //    DATE: 2021-08-12
-// VERSION: 0.3.4
+// VERSION: 0.4.0
 // PURPOSE: Arduino library for AGS02MA TVOC sensor
 //     URL: https://github.com/RobTillaart/AGS02MA
 
@@ -26,25 +26,9 @@ AGS02MA::AGS02MA(const uint8_t deviceAddress, TwoWire *wire)
 }
 
 
-#if defined (ESP8266) || defined(ESP32)
-bool AGS02MA::begin(uint8_t dataPin, uint8_t clockPin)
-{
-  _startTime = millis();  //  PREHEAT
-  if ((dataPin < 255) && (clockPin < 255))
-  {
-    _wire->begin(dataPin, clockPin);
-  } else {
-    _wire->begin();
-  }
-  return isConnected();
-}
-#endif
-
-
 bool AGS02MA::begin()
 {
   _startTime = millis();  //  PREHEAT TIMING
-  _wire->begin();
   return isConnected();
 }
 

AGS02MA.h

@@ -3,7 +3,7 @@
 //    FILE: AGS02MA.h
 //  AUTHOR: Rob Tillaart, Viktor Balint, Beanow
 //    DATE: 2021-08-12
-// VERSION: 0.3.4
+// VERSION: 0.4.0
 // PURPOSE: Arduino library for AGS02MA TVOC sensor
 //     URL: https://github.com/RobTillaart/AGS02MA
 //
@@ -13,7 +13,7 @@
 #include "Wire.h"
 
 
-#define AGS02MA_LIB_VERSION         (F("0.3.4"))
+#define AGS02MA_LIB_VERSION         (F("0.4.0"))
 
 #define AGS02MA_OK                  0
 #define AGS02MA_ERROR               -10
@@ -51,9 +51,6 @@ class AGS02MA
   //  address 26 = 0x1A
   explicit AGS02MA(const uint8_t deviceAddress = 26, TwoWire *wire = &Wire);
 
-#if defined (ESP8266) || defined(ESP32)
-  bool     begin(uint8_t sda, uint8_t scl);
-#endif
   bool     begin();
   bool     isConnected();
   void     reset();
@@ -102,7 +99,7 @@ class AGS02MA
 
   float    lastPPM()    { return _lastPPB   * 0.001; };
   uint32_t lastPPB()    { return _lastPPB;  };    //  fetch last PPB measurement
-  uint32_t lastUGM3()   { return _lastUGM3; };    // fetch last UGM3 measurement
+  uint32_t lastUGM3()   { return _lastUGM3; };    //  fetch last UGM3 measurement
 
 
   //  STATUS

CHANGELOG.md

@@ -6,12 +6,17 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.0] - 2023-12-06
+- refactor API, begin()
+- update readme.md
+
+----
+
 ## [0.3.4] - 2023-09-25
 - add Wire1 support for ESP32
 - update readme.md
 - minor edits
 
-
 ## [0.3.3] - 2023-01-21
 - update GitHub actions
 - update license 2023

README.md

@@ -13,11 +13,23 @@
 
 Arduino library for AGS02MA TVOC sensor.
 
+
+#### Description
+
 This library is still experimental, so please use with care.
 Note the warning about the I2C low speed, the device works at max 30 KHz.
 Since 0.3.1 this library uses 25 KHz.
 
 
+#### 0.4.0 Breaking change
+
+Version 0.4.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 
+before calling **begin()**.
+
+
 ## I2C
 
 ### PIN layout from left to right
@@ -101,12 +113,11 @@ with the sensor and this (or other) library.
 #include "AGS02MA.h"
 ```
 
-
 #### 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.
+- **AGS02MA(uint8_t deviceAddress = 26, TwoWire \*wire = &Wire)** constructor, 
+with default address and default I2C interface.
+- **bool begin()** initialize the library.
 - **bool isConnected()** returns true if device address can be seen on I2C.
 - **void reset()** reset internal variables.
 
@@ -157,6 +168,7 @@ The default mode at startup of the sensor is PPB = parts per billion.
 - **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.
 
+
 #### Air quality classification
 
 | ppm     | Class               |
@@ -171,6 +183,7 @@ The default mode at startup of the sensor is PPB = parts per billion.
 
 [Source](https://learn.kaiterra.com/en/resources/understanding-tvoc-volatile-organic-compounds)
 
+
 #### PPB versus UGM3
 
 There is no 1 to 1 relation between the PPB and the uG/m3 readings as this relation depends

examples/AGS02MA_PPB/AGS02MA_PPB.ino

@@ -1,11 +1,8 @@
 //
 //    FILE: AGS02MA_PPB.ino
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
 // PURPOSE: test application
-//    DATE: 2021-08-12
 //     URL: https://github.com/RobTillaart/AGS02MA
-//
 
 
 #include "AGS02MA.h"
@@ -16,24 +13,27 @@ AGS02MA AGS(26);
 
 void setup()
 {
+  //  ESP devices typically miss 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();
 
+  Wire.begin();
+
   bool b = AGS.begin();
   Serial.print("BEGIN:\t");
   Serial.println(b);
 
   Serial.print("VERSION:\t");
   Serial.println(AGS.getSensorVersion());
 
-  // pre-heating improves measurement quality
-  // can be skipped
+  //  pre-heating improves measurement quality
+  //  can be skipped
   Serial.println("\nWarming up (120 seconds = 24 dots)");
   while (AGS.isHeated() == false)
   {
@@ -70,4 +70,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/AGS02MA_PPB_TIMING/AGS02MA_PPB_TIMING.ino

@@ -15,24 +15,27 @@ AGS02MA AGS(26);
 
 void setup()
 {
+  //  ESP devices typically miss 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();
 
+  Wire.begin();
+
   bool b = AGS.begin();
   Serial.print("BEGIN:\t");
   Serial.println(b);
 
   Serial.print("VERS:\t");
   Serial.println(AGS.getSensorVersion());
 
-  // pre-heating improves measurement quality
-  // can be skipped
+  //  pre-heating improves measurement quality
+  //  can be skipped
   Serial.println("\nWarming up (120 seconds = 24 dots)");
   while (AGS.isHeated() == false)
   {
@@ -69,5 +72,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/AGS02MA_PPM/AGS02MA_PPM.ino

@@ -15,24 +15,27 @@ AGS02MA AGS(26);
 
 void setup()
 {
+  //  ESP devices typically miss 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();
 
+  Wire.begin();
+
   bool b = AGS.begin();
   Serial.print("BEGIN:\t");
   Serial.println(b);
 
   Serial.print("VERSION:\t");
   Serial.println(AGS.getSensorVersion());
 
-  // pre-heating improves measurement quality
-  // can be skipped
+  //  pre-heating improves measurement quality
+  //  can be skipped
   Serial.println("\nWarming up (120 seconds = 24 dots)");
   while (AGS.isHeated() == false)
   {
@@ -65,5 +68,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/AGS02MA_UGM3/AGS02MA_UGM3.ino

@@ -1,11 +1,8 @@
 //
 //    FILE: AGS02MA_UGM3.ino
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
 // PURPOSE: test application
-//    DATE: 2021-08-12
 //     URL: https://github.com/RobTillaart/AGS02MA
-//
 
 
 #include "AGS02MA.h"
@@ -16,21 +13,24 @@ AGS02MA AGS(26);
 
 void setup()
 {
+  //  ESP devices typically miss 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();
 
+  Wire.begin();
+
   bool b = AGS.begin();
   Serial.print("BEGIN:\t");
   Serial.println(b);
 
-  // pre-heating improves measurement quality 
-  // can be skipped
+  //  pre-heating improves measurement quality 
+  //  can be skipped
   Serial.println("\nWarming up (120 seconds = 24 dots)");
   while (AGS.isHeated() == false)
   {
@@ -67,4 +67,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/AGS02MA_calibrate/AGS02MA_calibrate.ino

@@ -1,15 +1,13 @@
 //
 //    FILE: AGS02MA_calibrate.ino
 //  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.
+//  You can decrease/disable warmup when you're certain the chip already warmed up.
 #define WARMUP_MINUTES 6
 #define READ_INTERVAL 3000
 
@@ -22,13 +20,12 @@ AGS02MA AGS(26);
 
 void setup()
 {
-  // ESP devices typically mis the first serial log lines after flashing.
-  // Delay somewhat to include all output.
+  //  ESP devices typically miss 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();
@@ -49,7 +46,7 @@ void setup()
   Serial.println(version);
   int err = AGS.lastError();
 
-  // Reading version correctly matters, as we display additional comments based on it.
+  //  Reading version correctly matters, as we display additional comments based on it.
   if(err != AGS02MA_OK)
   {
     Serial.print("Error reading version:\t");
@@ -101,7 +98,7 @@ void setup()
 
   delay(1000);
 
-  // returns 1 if successful written
+  //  returns 1 if successful written
   b = AGS.zeroCalibration();
   Serial.println();
   Serial.print("CALIB:\t");
@@ -123,8 +120,8 @@ void setup()
 
   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.
+  //  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!");
@@ -162,4 +159,5 @@ void printPPB()
   Serial.println();
 }
 
-// -- END OF FILE --
+
+//  -- END OF FILE --