refactor begin()

ACD10.cpp

@@ -2,7 +2,7 @@
 //    FILE: ACD10.cpp
 //  AUTHOR: Rob Tillaart
 //    DATE: 2023-09-25
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 // PUPROSE: Arduino library for for I2C ACD10 CO2 sensor
 //     URL: https://github.com/RobTillaart/ACD10
 //          http://www.aosong.com/en/products-77.html
@@ -18,26 +18,17 @@ ACD10::ACD10(TwoWire *wire)
   _lastRead = 0;
   _concentration = 0;
   _temperature = 0;
-  _start = millis();
+  _preHeatStart = millis();
 }
 
 
-#if defined (ESP8266) || defined(ESP32)
-bool ACD10::begin(uint8_t sda, uint8_t scl)
-{
-  _wire->begin(sda, scl);
-  if (! isConnected())
-  {
-    return false;
-  }
-  return true;
-}
-#endif
-
-
 bool ACD10::begin()
 {
-  _wire->begin();
+  //  reset variables
+  _error = 0;
+  _lastRead = 0;
+  _concentration = 0;
+  _temperature = 0;
   if (! isConnected())
   {
     return false;
@@ -71,7 +62,7 @@ bool ACD10::preHeatDone()
 
 uint32_t ACD10::preHeatMillisLeft()
 {
-  uint32_t delta = millis() - _start;
+  uint32_t delta = millis() - _preHeatStart;
   if (delta >= 120000UL) return 0;
   return 120000UL - delta;
 }

ACD10.h

@@ -3,7 +3,7 @@
 //    FILE: ACD10.h
 //  AUTHOR: Rob Tillaart
 //    DATE: 2023-09-25
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 // PUPROSE: Arduino library for for I2C ACD10 CO2 sensor
 //     URL: https://github.com/RobTillaart/ACD10
 //          http://www.aosong.com/en/products-77.html
@@ -13,7 +13,7 @@
 #include "Wire.h"
 
 
-#define ACD10_LIB_VERSION         (F("0.1.0"))
+#define ACD10_LIB_VERSION         (F("0.1.1"))
 #define ACD10_DEFAULT_ADDRESS     0x2A
 
 //  ERROR CODES
@@ -29,9 +29,6 @@ class ACD10
 public:
   ACD10(TwoWire *wire = &Wire);
 
-#if defined (ESP8266) || defined(ESP32)
-  bool     begin(uint8_t sda, uint8_t scl);
-#endif
   bool     begin();
   bool     isConnected();
   uint8_t  getAddress();
@@ -52,15 +49,15 @@ class ACD10
   uint8_t  getRequestTime();
 
 
-  //  CALIBRATION
+  //  CALIBRATION  (! read datasheet)
   //       0 = manual  1 = auto
   bool     setCalibrationMode(uint8_t mode);
   uint8_t  readCallibrationMode();
   bool     setManualCalibration(uint16_t value);
   uint16_t readManualCalibration();
 
 
-  //  MISC
+  //  MISCELLANEOUS
   void     factoryReset();
   bool     readFactorySet();
   void     readFirmwareVersion(char * arr);  //  should have length 11++
@@ -70,6 +67,7 @@ class ACD10
   //  DEBUG
   int  getLastError();
 
+
 private:
   uint8_t  _address = 0x2A;
   TwoWire* _wire;
@@ -78,8 +76,8 @@ class ACD10
   int      _request(uint8_t * arr, uint8_t size);
   uint8_t  _crc8(uint8_t * arr, uint8_t size);
 
-  uint32_t _start = 0;
-  uint32_t _lastRead = 0;
+  uint32_t _preHeatStart  = 0;
+  uint32_t _lastRead      = 0;
   uint32_t _concentration = 0;    //  why datasheet states 32 bit as 400-5000 fit in 16 bit??
   uint16_t _temperature   = 0;
   uint8_t  _requestTime   = 80;

CHANGELOG.md

@@ -6,8 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
-## [0.1.0] - 2023-09-25
+## [0.1.1] - 2023-10-05
+- refactor **begin()**
+- add **ACD10_readSensor_wire1.ino** ESP32 et al.
+- update readme.md
+- minor edits
+
 
+## [0.1.0] - 2023-09-25
 - initial version
 
 

README.md

@@ -19,42 +19,56 @@ Arduino library for the ACD10 CO2 sensor (I2C).
 **Experimental**
 
 This library is to use the Aosong ACD10 CO2 sensor.
-Besides CO2 concentration it also provides a temperature reading.
-
-The sensor can be read over I2C and over Serial, however this library
-only support the I2C interface.
-The device has a fixed I2C address of 0x2A (42). 
+Besides CO2 concentration this sensor also provides a temperature reading.
 
 The CO2 concentration supported by the sensor has a range from 400 ~ 5000 ppm ±(50ppm + 5% reading).
 This makes the sensor applicable for outdoor and indoor measurements in
-a normal building setting. It is not suitable for CO2 heavy "industrial" environments.
+a normal building setting. 
+The sensor is not suitable for CO2 heavy "industrial" environments. 
+
+The temperature range the sensor can measure is: **TODO UNKNOWN YET**
+
+
+#### Pre-heat period
 
 When the sensor starts up it has a pre-heat period of 120 seconds.
-The library provides functions to check the time since the constructor is called,
-but note that this not necessarily implies the sensor is ON.
+The library provides functions to check the time since the constructor is called.
+Note that this not necessarily implies that the sensor is ON.
 During the preheat period one can make measurements but one should use those
 carefully as these are less accurate than after the preheat period.
 
+
+#### Calibration
+
 Also important is the calibration of the sensor, although done in the factory,
 a CO2 sensor needs regular calibration. See datasheet for details.
 
-The temperature range it can measure is: **TODO UNKNOWN YET**
 
-The sensor must be powered with 5V and usese about 225 mW.
-This implies it uses 50 mA and needs a separate power supply. (Do not forget to connect GND.)
+#### Power
+
+The sensor must be powered with 5V and uses about 225 mW.
+This implies the sensor uses 50 mA (@5V) and needs a separate power supply. 
+One must connect GND from the power supply to the GND of the MCU.
+
+
+#### I2C
+
+The sensor can be read over I2C and over Serial.
+This library only support the I2C interface (see hardware notes below).
+The device has a fixed I2C address of 0x2A (42). 
 The I2C communication supports 3-5V so any 3.3V MCU should be able to connect.
-(Do not forget pull up resistors).
+Do not forget appropriate pull up resistors on the I2C SDA and SCL lines.
 
 
 #### Datasheet warning
 
-Do not apply this product to safety protection devices or emergency stop equipment, and any other
-applications that may cause personal injury due to the product's failure.
+Do not apply this product to safety protection devices or emergency stop equipment, 
+and any other applications that may cause personal injury due to the product's failure.
 
 
 #### Operating conditions
 
-- temperature: 0°C~ +50°C ==> so keep away from freezing cold or direct sunlight.
+- temperature: 0°C~ +50°C ==> keep away from freezing cold or direct sunlight.
 - humidity: 0% ~ 95% RH ==> non-condensing conditions.
 - Data refresh frequency: 2 seconds
 
@@ -78,13 +92,13 @@ applications that may cause personal injury due to the product's failure.
 |   1   |  SDA/RX  |  I2C data         |  3-5V
 |   2   |  SCL/TX  |  I2C clock        |  3-5V
 |   3   |  GND     |  Ground           |
-|   4   |  VCC     |  Power +5V        |
-|   5   |  SET     |  select com mode  |  HIGH (or nc) => I2C, LOW => Serial
+|   4   |  VCC     |  Power +5V        |  separate power supply needed.
+|   5   |  SET     |  select com mode  |  HIGH (or n.c.) => I2C, LOW => Serial
 |   6   |   -      |  not connected    |
 
-If pin 5 is not connected, the default (HIGH) is to select I2C.
-If pin 5 is connected to GND, Serial / UART mode is selected.
-This latter mode is **NOT** supported by this library.
+If pin 5 is not connected or connected to HIGH, **I2C** is selected (default).
+If pin 5 is connected to GND (LOW), Serial / UART mode is selected.
+This latter serial mode is **NOT** supported by this library.
 
 
 #### Related
@@ -101,28 +115,29 @@ This latter mode is **NOT** supported by this library.
 
 #### Tested
 
-TODO: Test on Arduino UNO and ESP32 ?
-
+TODO: Test on Arduino UNO and ESP32
 
 
 ## I2C
 
 The device has a fixed I2C address of 0x2A (42). 
 The I2C communication supports 3-5V so any 3.3V - 5.0V MCU should be able to connect.
-Do not forget pull up resistors on SDA and SCL lines.
+Do not forget appropriate pull up resistors on the I2C SDA and SCL lines.
 
 
 #### Multiple sensors.
 
-The ACD10 sensor has a fixed I2C address 0x2A (42) so only
-one sensor per I2C bus can be used.
+The ACD10 sensor has a fixed I2C address 0x2A (42) so only one sensor per I2C bus can be used.
+
 If one needs more sensors there are some options.
 - One could use an I2C multiplexer - https://github.com/RobTillaart/TCA9548  (I2C 8 channel multiplexer)
 - One could use an MCU with multiple I2C buses.
-- One could use a Two-Wire compatible SW I2C (outside scope of this library).
+- One could use a (Two-Wire compatible) SW I2C (outside scope of this library).
 
 Using the VCC as a Chip Select is not advised as the ACD10
-has a preheat time of 2 minutes.
+has a preheat time of 2 minutes. 
+Every time the power is shut off the pre-heat would run again internally.
+It is unclear what effect this has on the lifetime and quality of the sensor.
 
 
 #### Performance I2C
@@ -151,10 +166,8 @@ TODO: run performance sketch.
 
 #### Constructor
 
-- **ACD10(uint8_t address = ACD10_DEFAULT_ADDRESS, TwoWire \*wire = &Wire)**
-- **bool begin(uint8_t sda, uint8_t scl)** (ESP32) initializes I2C, 
-and checks if device is visible on the I2C bus.
-- **bool begin()** initializes I2C, and checks if device is visible on the I2C bus.
+- **ACD10(TwoWire \*wire = &Wire)** optional select I2C bus.
+- **bool begin()** checks if device is visible on the I2C bus.
 - **bool isConnected()** Checks if device address can be found on I2C bus.
 - **uint8_t getAddress()** Returns address set in the constructor.
 
@@ -188,9 +201,10 @@ Multiple calls will give the same value until new measurement is made.
 - **uint32_t lastRead()** returns the moment of last **readSensor()** in milliseconds
 since start.
 Note the sensor can be read only once every two seconds, less often is better.
+The library does not guard this two seconds interval (yet).
 - **void setRequestTime(uint8_t milliseconds = 80)** set the time to make a measurement.
 Default = 80 milliseconds.
-This can be used to tweak / optimize performance a bit. 
+This can be used to tweak / optimize the performance, so use with care!
 Use 5~10 milliseconds above the minimal value the sensor still works.
 - **uint8_t getRequestTime()** returns the current request time in milliseconds.
 

examples/ACD10_readSensor/ACD10_readSensor.ino

@@ -8,7 +8,7 @@
 #include "ACD10.h"
 
 
-ACD10 mySensor;
+ACD10 mySensor(&Wire);  //  explicit default, not needed.
 
 
 void setup()

examples/ACD10_readSensor_wire1/.arduino-ci.yml

@@ -0,0 +1,30 @@
+platforms:
+  rpipico:
+    board: rp2040:rp2040:rpipico
+    package: rp2040:rp2040
+    gcc:
+      features:
+      defines:
+        - ARDUINO_ARCH_RP2040
+      warnings:
+      flags:
+
+packages:
+  rp2040:rp2040:
+    url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
+
+compile:
+  # Choosing to run compilation tests on 2 different Arduino platforms
+  platforms:
+    # - uno
+    # - due
+    # - zero
+    # - leonardo
+    # - m4
+    - esp32
+    # - esp8266
+    # - mega2560
+    # - rpipico
+
+  libraries:
+    - "printHelpers"

examples/ACD10_readSensor_wire1/ACD10_readSensor_wire1.ino

@@ -0,0 +1,50 @@
+//
+//    FILE: ACD10_readSensor.ino
+//  AUTHOR: Rob Tillaart
+// PUPROSE: test basic behaviour and performance
+
+
+#include "Wire.h"
+#include "ACD10.h"
+
+
+ACD10 mySensor(&Wire1);
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println();
+  Serial.println(__FILE__);
+  Serial.print("ACD10_LIB_VERSION: ");
+  Serial.println(ACD10_LIB_VERSION);
+
+  Wire1.begin();
+  mySensor.begin();
+}
+
+
+void loop()
+{
+  //  prepare a request every 5 seconds.
+  if (millis() - mySensor.lastRead() > 5000)  //  millis
+  {
+    mySensor.requestSensor();
+  }
+
+  //  if request has had enough time read the sensor.
+  if (mySensor.requestReady())
+  {
+    mySensor.readSensor();
+    Serial.print(mySensor.getCO2Concentration());
+    Serial.print("\t");
+    Serial.print(mySensor.getTemperature());
+    Serial.println();
+  }
+
+  //  do other things here.
+  delay(1000);
+}
+
+
+//  -- END OF FILE --

library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/ACD10.git"
   },
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "frameworks": "*",
   "platforms": "*",

library.properties

@@ -1,5 +1,5 @@
 name=ACD10
-version=0.1.0
+version=0.1.1
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for the ACD10 CO2 sensor.