update readme.md + minor edits

Author: RobTillaart

AGS02MA.cpp

@@ -2,7 +2,7 @@
 //    FILE: AGS02MA.cpp
 //  AUTHOR: Rob Tillaart, Viktor Balint, Beanow
 //    DATE: 2021-08-12
-// VERSION: 0.4.2
+// VERSION: 0.4.3
 // PURPOSE: Arduino library for AGS02MA TVOC sensor
 //     URL: https://github.com/RobTillaart/AGS02MA
 

AGS02MA.h

@@ -3,17 +3,16 @@
 //    FILE: AGS02MA.h
 //  AUTHOR: Rob Tillaart, Viktor Balint, Beanow
 //    DATE: 2021-08-12
-// VERSION: 0.4.2
+// VERSION: 0.4.3
 // PURPOSE: Arduino library for AGS02MA TVOC sensor
 //     URL: https://github.com/RobTillaart/AGS02MA
-//
 
 
 #include "Arduino.h"
 #include "Wire.h"
 
 
-#define AGS02MA_LIB_VERSION         (F("0.4.2"))
+#define AGS02MA_LIB_VERSION         (F("0.4.3"))
 
 #define AGS02MA_OK                  0
 #define AGS02MA_ERROR               -10

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+
+## [0.4.3] - 2025-08-15
+- update readme.md
+- update license
+- minor edits
+
 ## [0.4.2] - 2024-02-03
 - update readme.md 
   - added multiplexer section
@@ -18,7 +24,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   - redo **readRegister()**
 - minor edits
 
-
 ## [0.4.1] - 2023-12-10
 - fix #26, error in readme.
 

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-2024 Rob Tillaart
+Copyright (c) 2021-2025 Rob Tillaart
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -14,9 +14,11 @@
 Arduino library for AGS02MA TVOC sensor.
 
 
-#### Description
+### Description
 
-This library is still experimental, so please use with care.
+**Experimental**
+
+This library is experimental, so please use with care.
 
 The AGS02MA is a sensor that measures the TVOC = Total Volatile Organic Compounds
 in the air. It does not measure a specific gas, but several.
@@ -25,36 +27,55 @@ in the air. It does not measure a specific gas, but several.
 Note the warning about the I2C low speed, the device works at max 30 KHz.
 Since 0.3.1 this library uses 25 KHz.
 
-Note this library is not meant to replace professional monitoring systems.
+Feedback as always, is welcome. Please open an issue.
+
+Note this library is **not** meant to replace professional monitoring systems.
 
 
-#### 0.4.0 Breaking change
+### 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 
+The user has to call **Wire.begin()** and can optionally set the Wire pins
 before calling **begin()**.
 
 
-#### Related
+### Related
 
+- https://github.com/RobTillaart/AGS02MA TVOC sensor
+- https://github.com/RobTillaart/AGS2616 H2 sensor
+- https://github.com/RobTillaart/AGS3870 CH4 sensor
+- https://github.com/RobTillaart/AGS3871 CO sensor
 - https://www.renesas.com/us/en/document/whp/overview-tvoc-and-indoor-air-quality
-
+- https://github.com/RobTillaart/map2colour
+- https://github.com/RobTillaart/SGP30 (experimental)
 
 ## I2C
 
 ### PIN layout from left to right
 
 |  Front L->R  |  Description  |
 |:------------:|:--------------|
-|   pin 1      |   VDD +       |
+|   pin 1      |   VDD +5V     |
 |   pin 2      |   SDA data    |
 |   pin 3      |   GND         |
 |   pin 4      |   SCL clock   |
 
 
-#### WARNING - LOW SPEED
+### Address
+
+The device has a fixed address of 26 or 0x1A.
+
+The device works at 100 kHz I2C bus speed (datasheet).
+
+Note: several AGS devices use the same I2C address 0x1A.
+Known are the AGS2616 (H2), AGS3870 (CH4), AGS3871 (CO), AGS02MA (TVOC).
+If you want to use them on one I2C bus, you need multiplexing.
+See section below.
+
+
+### WARNING - LOW SPEED
 
 The sensor uses I2C at very low speed <= 30 KHz.
 For an Arduino UNO the lowest speed supported is about 30.4KHz (TWBR = 255) which works.
@@ -69,7 +90,7 @@ This is done to minimize interference with the communication of other devices.
 The reset clock speed can be changed with **setI2CResetSpeed(speed)** e.g. to 200 or 400 KHz.
 
 
-#### 0.3.1 fix.
+### 0.3.1 fix.
 
 Version 0.3.1 sets the **I2C prescaler TWSR** register of the Arduino UNO to 4 so the lowest
 speed possible is reduced to about 8 KHz.
@@ -78,19 +99,19 @@ So the communication speed will be set to 25 KHz, also for other boards, for sta
 After communication the clock (+ prescaler) is reset again as before.
 
 
-#### I2C multiplexing
+### I2C multiplexing
 
 Sometimes you need to control more devices than possible with the default
 address range the device provides.
-This is possible with an I2C multiplexer e.g. TCA9548 which creates up 
-to eight channels (think of it as I2C subnets) which can use the complete 
-address range of the device. 
+This is possible with an I2C multiplexer e.g. TCA9548 which creates up
+to eight channels (think of it as I2C subnets) which can use the complete
+address range of the device.
 
-Drawback of using a multiplexer is that it takes more administration in 
-your code e.g. which device is on which channel. 
+Drawback of using a multiplexer is that it takes more administration in
+your code e.g. which device is on which channel.
 This will slow down the access, which must be taken into account when
 deciding which devices are on which channel.
-Also note that switching between channels will slow down other devices 
+Also note that switching between channels will slow down other devices
 too if they are behind the multiplexer.
 
 - https://github.com/RobTillaart/TCA9548
@@ -103,7 +124,7 @@ My devices all report version 117 and this version is used to develop / test thi
 There are devices reported with version 118 which behave differently.
 
 
-#### ugM3 not supported
+### ugM3 not supported
 
 See  - https://github.com/RobTillaart/AGS02MA/issues/11
 
@@ -114,7 +135,7 @@ If you encounter similar problems with setting the mode (any version), please le
 That will help indicating if this is a "structural change" or incident.
 
 
-#### Calibrate problem!
+### Calibrate problem!
 
 See - https://github.com/RobTillaart/AGS02MA/issues/13
 
@@ -130,7 +151,7 @@ Note: the version 0.2.0 determines the version in the calibration function so
 it won't calibrate any non 117 version.
 
 
-#### Please report your experiences.
+### Please report your experiences.
 
 If you have a AGS20MA device, version 117 or 118 or other,
 please let me know your experiences
@@ -143,43 +164,49 @@ with the sensor and this (or other) library.
 #include "AGS02MA.h"
 ```
 
-#### Constructor
+### Constructor
 
-- **AGS02MA(uint8_t deviceAddress = 26, TwoWire \*wire = &Wire)** constructor, 
+- **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.
+- **bool begin()** initialize the library. 
+Returns false if deviceAddress cannot be seen on the I2C bus.
+- **bool isConnected()** returns true if deviceAddress can be seen on I2C, false otherwise.
+- **void reset()** resets the internal variables.
 
 
-#### Timing
+### Heating
 
-- **bool isHeated()** returns true if 2 minutes have passed after startup (call of **begin()** ).
+- **bool isHeated()** returns true if 2 minutes have passed after 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.
+According to the datasheet, preheating will improve the quality of the measurements.
+Note: if begin() is not called, isHeated() might be incorrect.
+- **uint32_t lastRead()** returns the 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 at least 1.5 seconds but preferred 3 seconds apart according to the datasheet.
+One must keep reads / measurements at least 1.5 seconds but preferred 3 seconds 
+apart according to the datasheet.
 
 
-#### Administration
+### Administration
 
 - **bool setAddress(const uint8_t deviceAddress)** sets a new address 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.
+- **uint8_t getSensorVersion()** reads sensor version from the device.
 If the version cannot be read the function will return 255.
-(My test sensors all return version 117, version 118 is reported)
-- **uint32_t getSensorDate()** (experimental) reads bytes from the sensor that seem to indicate the production date(?). This date is encoded in an uint32_t to minimize footprint as it is a debug function.
+My test sensors all return version 117, version 118 is reported to exist too.
+- **uint32_t getSensorDate()** (experimental) reads bytes from the sensor that seem 
+to indicate the production date(?). 
+This date is encoded in an uint32_t to minimize footprint as it is a debug function.
 
 ```cpp
 uint32_t dd = sensor.getSensorDate();
 Serial.println(dd, HEX);   //  prints YYYYMMDD e.g. 20210203
 ```
 
 
-#### I2C clock speed
+### I2C clock speed
 
 The library sets the clock speed to 25 KHz during operation
 and resets it to 100 KHz after operation.
@@ -190,7 +217,7 @@ The following function can change the I2C reset speed to e.g. 200 or 400 KHz.
 - **uint32_t getI2CResetSpeed()** returns the value set. Default is 100 KHz.
 
 
-#### setMode
+### setMode
 
 The default mode at startup of the sensor is PPB = parts per billion.
 
@@ -199,7 +226,7 @@ The default mode at startup of the sensor is PPB = parts per billion.
 - **uint8_t getMode()** returns mode set. 0 = PPB, 1 = UGm3, 255 = not set.
 
 
-#### Air quality classification
+### Air quality classification
 
 Indicative
 
@@ -220,7 +247,7 @@ Indicative
   - https://github.com/RobTillaart/map2colour for continuous scale.
 
 
-#### PPB versus UGM3
+### 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.
@@ -252,7 +279,7 @@ Some known gasses
 - https://github.com/RobTillaart/AtomicWeight  (determine M from chemical formula)
 
 
-#### Read the sensor
+### Read the sensor
 
 WARNING: The datasheet advises to take 3 seconds between reads.
 Tests gave stable results at 1.5 second intervals.
@@ -273,7 +300,7 @@ Typical value should be between 0.01 .. 999.99
 - **float readUGF3()** returns microgram per cubic feet.
 
 
-#### Error Codes
+### Error Codes
 
 |  ERROR_CODES                |  value  |
 |:----------------------------|:-------:|
@@ -284,40 +311,40 @@ Typical value should be between 0.01 .. 999.99
 |  AGS02MA_ERROR_NOT_READY    |   -13   |
 
 
-#### Cached values
+### Cached values
 
 - **float lastPPM()** returns last readPPM (parts per million) value (cached).
 - **uint32_t lastPPB()** returns last read PPB (parts per billion) value (cached). Should be between 1..999999.
 - **uint32_t lastUGM3()** returns last read UGM3 (microgram per cubic meter) value (cached).
 
 
-#### Calibration
+### Calibration
 
 - **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. 
+- **bool getZeroCalibrationData(ZeroCalibrationData &data)** fills a data struct with the
+current zero calibration status and value.
 Returns true on success.
 
 
-#### Other
+### Other
 
 - **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 **RegisterData** 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()`, 
+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.
 - **uint8_t dataReady()** returns RDY bit from last read.
 
 
-#### Status bits.
+### Status bits.
 
 |  bit  |  description                        |  notes  |
 |:-----:|:------------------------------------|:--------|
@@ -340,6 +367,7 @@ Read datasheet or table below for details. A new read is needed to update this.
 - test with hardware
   - different gasses ? indoor / outdoor?
 - test with different processors
+- isHeated() bugs if begin() is not called before...
 
 #### Could
 

examples/AGS02MA_PPB/AGS02MA_PPB.ino

@@ -18,6 +18,7 @@ void setup()
   delay(1000);
 
   Serial.begin(115200);
+  Serial.println();
   Serial.println(__FILE__);
   Serial.print("AGS02MA_LIB_VERSION: ");
   Serial.println(AGS02MA_LIB_VERSION);

examples/AGS02MA_PPB_TIMING/AGS02MA_PPB_TIMING.ino

@@ -18,6 +18,7 @@ void setup()
   delay(1000);
 
   Serial.begin(115200);
+  Serial.println();
   Serial.println(__FILE__);
   Serial.print("AGS02MA_LIB_VERSION: ");
   Serial.println(AGS02MA_LIB_VERSION);

examples/AGS02MA_PPM/AGS02MA_PPM.ino

@@ -18,6 +18,7 @@ void setup()
   delay(1000);
 
   Serial.begin(115200);
+  Serial.println();
   Serial.println(__FILE__);
   Serial.print("AGS02MA_LIB_VERSION: ");
   Serial.println(AGS02MA_LIB_VERSION);