Merge branch 'master' into codex/resolver-issues-del-repositorio

Add MQ303A voltage resolution unit test

.github/pull_request_template.md

@@ -12,6 +12,8 @@ Please delete options that are not relevant.
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
 - [ ] This change requires a documentation update
+- [ ] I have updated the version in `library.properties` to reflect my changes (advance by 0.01 for minor changes, or a whole number for new features)
+- [ ] I have submitted the pull request
 
 # How Has This Been Tested?
 

CONTRIBUTING.md

@@ -20,3 +20,7 @@ Pull request will be check by three main authors who are linked in
 [REAMDE.md](https://github.com/miguel5612/MQSensorsLib/README.md) and they determine to merge to
 master branch. Later than assessment and debbuging procedures was completed, the contribution 
 will be released.
+
+## Versioning
+
+When making a pull request, please remember to update the `library.properties` file to reflect the changes you've made. If your change is minor, consider advancing the version by 0.01. If you're adding a new feature, you may want to advance the version by a whole number.

README.md

@@ -68,6 +68,7 @@ float ppmCH4 = MQ4.readSensor();
 * AO -> Analog Output of the sensor
 ##### Data of board that you should have
 * RL Value in KOhms
+* If the sensor uses a different supply voltage than the ADC reference, call `yourSensor.setVCC(<voltage>);`
 ##### Graph
 ![Wiring_MQSensor](https://raw.githubusercontent.com/miguel5612/MQSensorsLib_Docs/master/static/img/Points_explanation.jpeg)
 #### RS/R0 value (From datasheet of your sensor)
@@ -121,15 +122,15 @@ You'll need Arduino desktop app 1.8.9 or later.
 ### Sensor manufacturers:
 | Sensor | Manufacture | URL Datasheet |
 |----------|----------|----------|
-| MQ-2 | Pololulu| [datasheet](https://www.pololu.com/file/0J309/MQ2.pdf) |
+| MQ-2 | HANWEI Electronics| [datasheet](https://www.pololu.com/file/0J309/MQ2.pdf) |
-| MQ-3 | Sparkfun | [datasheet](https://www.sparkfun.com/datasheets/Sensors/MQ-3.pdf) |
+| MQ-3 | HANWEI Electronics | [datasheet](https://www.sparkfun.com/datasheets/Sensors/MQ-3.pdf) |
-| MQ-4 | Sparkfun | [datasheet](https://www.sparkfun.com/datasheets/Sensors/Biometric/MQ-4.pdf) |
+| MQ-4 | HANWEI Electronics | [datasheet](https://www.sparkfun.com/datasheets/Sensors/Biometric/MQ-4.pdf) |
-| MQ-5 | parallax | [datasheet](https://www.parallax.com/sites/default/files/downloads/605-00009-MQ-5-Datasheet.pdf) |
+| MQ-5 | HANWEI Electronics | [datasheet](https://www.parallax.com/sites/default/files/downloads/605-00009-MQ-5-Datasheet.pdf) |
-| MQ-6 | Sparkfun | [datasheet](https://www.sparkfun.com/datasheets/Sensors/Biometric/MQ-6.pdf) |
+| MQ-6 | HANWEI Electronics | [datasheet](https://www.sparkfun.com/datasheets/Sensors/Biometric/MQ-6.pdf) |
-| MQ-7 | Sparkfun | [datasheet](https://www.sparkfun.com/datasheets/Sensors/Biometric/MQ-7.pdf) |
+| MQ-7 | HANWEI Electronics | [datasheet](https://www.sparkfun.com/datasheets/Sensors/Biometric/MQ-7.pdf) |
-| MQ-8 | Sparkfun | [datasheet](https://dlnmh9ip6v2uc.cloudfront.net/datasheets/Sensors/Biometric/MQ-8.pdf) |
+| MQ-8 | HANWEI Electronics | [datasheet](https://dlnmh9ip6v2uc.cloudfront.net/datasheets/Sensors/Biometric/MQ-8.pdf) |
-| MQ-9 | Haoyuelectronics | [datasheet](http://www.haoyuelectronics.com/Attachment/MQ-9/MQ9.pdf) |
+| MQ-9 | HANWEI Electronics | [datasheet](http://www.haoyuelectronics.com/Attachment/MQ-9/MQ9.pdf) |
-| MQ-131 | Sensorsportal | [datasheet](http://www.sensorsportal.com/DOWNLOADS/MQ131.pdf) |
+| MQ-131 | HANWEI Electronics | [datasheet](http://www.sensorsportal.com/DOWNLOADS/MQ131.pdf) |
 | MQ-135 | HANWEI Electronics | [datasheet](https://www.electronicoscaldas.com/datasheet/MQ-135_Hanwei.pdf) |
 | MQ-136 | HANWEI Electronics | [datasheet](https://github.com/miguel5612/MQSensorsLib_Docs/blob/master/Datasheets/MQ136%20-%20Hanwei.pdf) |
 | MQ-303A | HANWEI Electronics | [datasheet](http://www.kosmodrom.com.ua/pdf/MQ303A.pdf) |
@@ -173,6 +174,10 @@ Examples/MQ-board.ino
 * [Data sheets](https://github.com/miguel5612/MQSensorsLib_Docs/tree/master/Datasheets) - Curves and behavior for each sensor, using logarithmic graphs.
 * [Main purpose](https://github.com/miguel5612/MQSensorsLib_Docs/blob/master/static/img/bg.jpg) - Every sensor has high sensibility for a specific gas or material.
 
+## Issues
+
+Consulte [docs/issues.md](docs/issues.md) para un resumen de los problemas abiertos y sus soluciones.
+
 ## Contributing
 
 Please read [CONTRIBUTING.md](https://github.com/miguel5612/MQSensorsLib/blob/master/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

docs/issues.md

@@ -0,0 +1,31 @@
+# Issues y soluciones
+
+Este documento resume los problemas reportados en el repositorio y las soluciones propuestas o implementadas.
+
+## Abiertos
+
+### #75 MQ-3 sensor and CH4 gas reading 'ovf' failure
+**Estado:** abierto
+
+El usuario reporta desbordamiento ("ovf") al utilizar valores muy altos en `setA` y `setB` para leer CH4 con un sensor MQ-3. La solución propuesta es revisar los valores utilizados en `setA` y `setB`, ya que `2*10^31` en C++ no corresponde a `2e31`. Se recomienda usar notación exponencial (`2e31`) o `pow(10,31)` y comprobar que los parámetros no excedan el rango de `float`.
+
+### #74 possible error in the calculation formula for `_RS_Calc`
+**Estado:** resuelto en la rama `work`
+
+Se detectó que la resistencia del sensor se calculaba con `_VOLT_RESOLUTION` en lugar del voltaje de alimentación real. Se añadieron los métodos `setVCC` y `getVCC` y se modificaron las ecuaciones para usar `VCC`. Esta corrección se refleja en la versión 3.0.1 de la biblioteca.
+
+### #70 Parameters to model temperature and humidity dependence
+**Estado:** abierto
+
+Los usuarios solicitan factores de corrección para temperatura y humedad aplicables a otros sensores (MQ-4 y MQ-8) además del MQ-135. Aún no se han añadido estos parámetros. Se anima a la comunidad a contribuir con implementaciones y ejemplos.
+
+### #67 Sensor won't finish the Calibration process if done in clean air
+**Estado:** abierto
+
+Se reporta que la calibración se detiene mostrando un mensaje de "Conection issue" cuando se intenta calibrar el sensor MQ-135 en aire limpio. La recomendación del mantenedor es revisar la conexión física y probar el sensor con un programa básico para asegurar su correcto funcionamiento antes de usar la librería. Aún no se ha implementado un cambio en el código.
+
+
+## Cerrados destacados
+
+Para obtener más información sobre todos los issues cerrados, consulte la página de [Issues en GitHub](https://github.com/miguel5612/MQSensorsLib/issues?q=is%3Aissue+is%3Aclosed).
+

examples/UnitTesting/UnitTesting.ino

@@ -246,6 +246,15 @@ test(MQ303A_Ethanol)
   assertEqual(PPM,ppmExp);
 }
 
+test(MQ303A_VoltResolution)
+{
+  float vRes = 4.7;
+  MQ303A.setVoltResolution(vRes);
+  MQ303A.setADC(100);            // provide dummy ADC value
+  MQ303A.readSensor(true);       // dummy read for MQ303A
+  assertEqualFloat(MQ303A.getVoltResolution(), vRes);
+}
+
 test(MQ309A_CO)
 {
   MQ309A.setRegressionMethod(1); //_PPM =  a*ratio^b

library.properties

@@ -1,5 +1,5 @@
 name=MQUnifiedsensor
-version=3.0.0
+version=3.0.1
 author= Miguel Califa <miguelangel5612@gmail.com>, Yersson Carrillo<miguelangel5612@gmail.com>, Ghiordy Contreras<miguelangel5612@gmail.com>
 maintainer= Miguel Califa <miguelangel5612@gmail.com>
 sentence= This library allows you to read the MQ sensors very easily.

src/MQUnifiedsensor.cpp

@@ -1,17 +1,21 @@
 #include "MQUnifiedsensor.h"
 
+#define retries 2
+#define retry_interval 20
+
 MQUnifiedsensor::MQUnifiedsensor(String Placa, float Voltage_Resolution, int ADC_Bit_Resolution, int pin, String type) {
   this->_pin = pin;
   Placa.toCharArray(this->_placa, 20);
-  type.toCharArray(this->_type, 6);
+  type.toCharArray(this->_type, 7);
   //this->_type = type; //MQ-2, MQ-3 ... MQ-309A
   //this->_placa = Placa;
   this-> _VOLT_RESOLUTION = Voltage_Resolution;
+  this-> _VCC = Voltage_Resolution;
   this-> _ADC_Bit_Resolution = ADC_Bit_Resolution;
 }
 MQUnifiedsensor::MQUnifiedsensor(String Placa, String type) {
   Placa.toCharArray(this->_placa, 20);
-  type.toCharArray(this->_type, 6);
+  type.toCharArray(this->_type, 7);
 }
 void MQUnifiedsensor::init()
 {
@@ -38,6 +42,13 @@ void MQUnifiedsensor::setVoltResolution(float voltage_resolution)
 {
   _VOLT_RESOLUTION = voltage_resolution;
 }
+void MQUnifiedsensor::setVCC(float vcc)
+{
+  _VCC = vcc;
+}
+void MQUnifiedsensor::setPin(int pin) {
+  this->_pin = pin;
+}
 void MQUnifiedsensor::setRegressionMethod(int regressionMethod)
 {
   //this->_regressionMethod = regressionMethod;
@@ -53,6 +64,10 @@ float MQUnifiedsensor::getVoltResolution()
 {
   return _VOLT_RESOLUTION;
 }
+float MQUnifiedsensor::getVCC()
+{
+  return _VCC;
+}
 String MQUnifiedsensor::getRegressionMethod()
 {
   if(_regressionMethod == 1) return "Exponential";
@@ -79,7 +94,8 @@ void MQUnifiedsensor::serialDebug(bool onSetup)
     Serial.println("Contributors: Andres A. Martinez - Juan A. Rodríguez - Mario A. Rodríguez O ");
 
     Serial.print("Sensor: "); Serial.println(_type);
-    Serial.print("Supply voltage: "); Serial.print(_VOLT_RESOLUTION); Serial.println(" VDC");
+    Serial.print("ADC voltage: "); Serial.print(_VOLT_RESOLUTION); Serial.println(" VDC");
+    Serial.print("Sensor supply (VCC): "); Serial.print(_VCC); Serial.println(" VDC");
     Serial.print("ADC Resolution: "); Serial.print(_ADC_Bit_Resolution); Serial.println(" Bits");
     Serial.print("R0: "); Serial.print(_R0); Serial.println(" KΩ");
     Serial.print("RL: "); Serial.print(_RL); Serial.println(" KΩ");
@@ -100,7 +116,7 @@ void MQUnifiedsensor::serialDebug(bool onSetup)
     else
     {
       Serial.print("|"); Serial.print(_adc);  Serial.print("| v = ADC*"); Serial.print(_VOLT_RESOLUTION); Serial.print("/"); Serial.print((pow(2, _ADC_Bit_Resolution)) - 1); Serial.print("  |    "); Serial.print(_sensor_volt);
-      Serial.print("     | RS = ((" ); Serial.print(_VOLT_RESOLUTION ); Serial.print("*RL)/Voltage) - RL|      "); Serial.print(_RS_Calc); Serial.print("     | Ratio = RS/R0|    ");
+      Serial.print("     | RS = ((" ); Serial.print(_VCC ); Serial.print("*RL)/Voltage) - RL|      "); Serial.print(_RS_Calc); Serial.print("     | Ratio = RS/R0|    ");
       Serial.print(_ratio);  Serial.print( "       |   ");
       if(_regressionMethod == 1) Serial.print("ratio*a + b");
       else Serial.print("pow(10, (log10(ratio)-b)/a)");
@@ -136,10 +152,12 @@ float MQUnifiedsensor::validateEcuation(float ratioInput)
 float MQUnifiedsensor::readSensor(bool isMQ303A, float correctionFactor, bool injected)
 {
   //More explained in: https://jayconsystems.com/blog/understanding-a-gas-sensor
+
+  float voltRes = _VOLT_RESOLUTION; // preserve global resolution
   if(isMQ303A) {
-    _VOLT_RESOLUTION = _VOLT_RESOLUTION - 0.45; //Calculations for RS using mq303a sensor look wrong #42
+    voltRes = voltRes - 0.45; //Calculations for RS using mq303a sensor look wrong #42
   }
-  _RS_Calc = ((_VOLT_RESOLUTION*_RL)/_sensor_volt)-_RL; //Get value of RS in a gas
+  _RS_Calc = ((_VCC*_RL)/_sensor_volt)-_RL; //Get value of RS in a gas
   if(_RS_Calc < 0)  _RS_Calc = 0; //No negative values accepted.
   if(!injected) _ratio = _RS_Calc / this->_R0;   // Get ratio RS_gas/RS_air
   _ratio += correctionFactor;
@@ -158,7 +176,7 @@ float MQUnifiedsensor::readSensor(bool isMQ303A, float correctionFactor, bool in
 float MQUnifiedsensor::readSensorR0Rs()
 {
   //More explained in: https://jayconsystems.com/blog/understanding-a-gas-sensor
-  _RS_Calc = ((_VOLT_RESOLUTION*_RL)/_sensor_volt)-_RL; //Get value of RS in a gas
+  _RS_Calc = ((_VCC*_RL)/_sensor_volt)-_RL; //Get value of RS in a gas
   if(_RS_Calc < 0)  _RS_Calc = 0; //No negative values accepted.
   _ratio = this->_R0/_RS_Calc;   // Get ratio RS_air/RS_gas <- INVERTED for MQ-131 issue 28 https://github.com/miguel5612/MQSensorsLib/issues/28
   if(_ratio <= 0)  _ratio = 0; //No negative values accepted or upper datasheet recomendation.
@@ -188,7 +206,7 @@ float MQUnifiedsensor::calibrate(float ratioInCleanAir) {
   */
   float RS_air; //Define variable for sensor resistance
   float R0; //Define variable for R0
-  RS_air = ((_VOLT_RESOLUTION*_RL)/_sensor_volt)-_RL; //Calculate RS in fresh air
+  RS_air = ((_VCC*_RL)/_sensor_volt)-_RL; //Calculate RS in fresh air
   if(RS_air < 0)  RS_air = 0; //No negative values accepted.
   R0 = RS_air/ratioInCleanAir; //Calculate R0 
   if(R0 < 0)  R0 = 0; //No negative values accepted.
@@ -225,7 +243,7 @@ float MQUnifiedsensor:: setRsR0RatioGetPPM(float value)
 float MQUnifiedsensor::getRS()
 {
   //More explained in: https://jayconsystems.com/blog/understanding-a-gas-sensor
-  _RS_Calc = ((_VOLT_RESOLUTION*_RL)/_sensor_volt)-_RL; //Get value of RS in a gas
+  _RS_Calc = ((_VCC*_RL)/_sensor_volt)-_RL; //Get value of RS in a gas
   if(_RS_Calc < 0)  _RS_Calc = 0; //No negative values accepted.
   return _RS_Calc;
 }

src/MQUnifiedsensor.h

@@ -6,10 +6,6 @@
 
 /***********************Software Related Macros************************************/
 
-#define ADC_RESOLUTION 10 // for 10bit analog to digital converter.
-#define retries 2
-#define retry_interval 20
-
 class MQUnifiedsensor
 {
   public:
@@ -26,6 +22,8 @@ class MQUnifiedsensor
     void setB(float b);
     void setRegressionMethod(int regressionMethod);
     void setVoltResolution(float voltage_resolution =  5);
+    void setVCC(float vcc = 5);
+    void setPin(int pin = 1);
     void serialDebug(bool onSetup = false); //Show on serial port information about sensor
     void setADC(int value); //For external ADC Usage
     
@@ -41,6 +39,7 @@ class MQUnifiedsensor
     float getR0();
     float getRL();
     float getVoltResolution();
+    float getVCC();
     String getRegressionMethod();
     float getVoltage(bool read = true, bool injected = false, int value = 0);
     float stringTofloat(String & str);
@@ -51,9 +50,10 @@ class MQUnifiedsensor
 
   private:
     /************************Private vars************************************/
-    byte _pin;
+    byte _pin = 1;
     byte _firstFlag = false;
     float _VOLT_RESOLUTION  = 5.0; // if 3.3v use 3.3
+    float _VCC = 5.0; // Sensor supply voltage
     float _RL = 10; //Value in KiloOhms
     byte _ADC_Bit_Resolution = 10;
     byte _regressionMethod = 1; // 1 -> Exponential || 2 -> Linear
@@ -61,7 +61,7 @@ class MQUnifiedsensor
     float _adc, _a, _b, _sensor_volt;
     float  _R0, RS_air, _ratio, _PPM, _RS_Calc;  
     
-    char _type[6];
+    char _type[7];
     char _placa[20]; 
 };