Added support of power fit functions

Author: DrGFreeman

README.md

@@ -1,57 +1,67 @@
 # SharpDistSensor
 A library for the Arduino IDE that helps interface with Sharp analog distance sensors.  
 
-Version 1.0.0  
+Version 1.1.0  
 [![Build Status](https://travis-ci.org/DrGFreeman/SharpDistSensor.svg?branch=master)](https://travis-ci.org/DrGFreeman/SharpDistSensor)  
 By Julien de la Bruère-Terreault (drgfreeman@tuta.io)
 
 ## Summary
-The analog value from the sensor is converted to distance using a polynomial fit curve up to fifth order.
+The analog value from the sensor is converted to distance using either a
+polynomial fit function up to fifth order or a power fit function.
 
-The default polynomial coefficients in this library are calibrated for the Sharp GP2Y0A60SZLF Analog Distance Sensor 10-150cm 5V, over a range of 50-1500 mm (analog values 30-875). The returned distance is in millimeters (mm) units.  
+By default, this library is set to use polynomial coefficients calibrated for the Sharp GP2Y0A60SZLF Analog Distance Sensor 10-150cm 5V, over a range of 50-1500 mm (analog values 30-875). The returned distance is in millimeters (mm) units.  
 
 For different accuracy, range, sensor model or units, different coefficients may be required.  
 
 The distance output is filtered using real-time median filtering (sliding window of ajustable size). The MedianFilter class from the following library is used: https://github.com/daPhoosa/MedianFilter.
 
 ## Examples
-Three example sketches are provided with the library:
+Four example sketches are provided with the library:
 * _SharpDistSensorBasic.ino_  
-This example shows how to use the library with the default calibration curve for the Sharp GP2Y0A60SZLF 5V sensor.
+This example shows how to use the library with the default calibration function for the Sharp GP2Y0A60SZLF 5V sensor.
 
 * _SharpDistSensorByModel.ino_  
 This example shows how to use the library by selecting a pre-defined sensor
 model calibration.
 
-* _SharpDistSensorCustom.ino_  
-This example shows how to use the library with a custom, user defined calibration curve.
+* _SharpDistSensorCustomPoly.ino_  
+This example shows how to use the library with a custom, user defined polynomial calibration function.
+
+* _SharpDistSensorCustomPower.ino_  
+This example shows how to use the library with a custom, user defined power calibration function.
 
 ## Library Reference
 * `SharpDistSensor(const byte pin, const byte size = 1)`  
 Constructor: `pin` is the analog pin to which the sensor is connected, `size` is the size of the median filter window and should be an odd positive integer (default = 1 = no filtering).  
 
 * `uint16_t getDist()`  
-Returns the measured distance. Distance units are in millimeters (mm) if using the library default settings. If using custom calibration, units depend on the calibration used.  
+Returns the measured distance. Distance units are in millimeters (mm) if using the library default settings or pre-defined sensor models. If using custom calibration, units depend on the calibration used.  
 
 * `void setModel(const byte model)`
-Sets the calibration based on pre-defined sensor model polynomial fit curves.
+Sets the calibration based on pre-defined sensor model fit functions.  
 
 * `void setPolyFitCoeffs(const byte nbCoeffs, const float* coeffs, const uint16_t valMin, const uint16_t valMax)`  
-Sets the polynomial fit curve coefficients _C0_ to _C5_ in the relation:  
+Sets the polynomial fit function coefficients _C0_ to _C5_ in the relation:  
 _Distance = C0 + C1 * A + C2 * A^2 + ... + C5 * A^5_  
 where _A_ is the analog value read from the sensor. At least one coefficient must be provided and up to six maximum (5th order polynomial). `nbCoeffs` is the number of coefficients passed and `coeffs` a vector containing the coefficients (C0 to C5). `valMin` and `valMax` define the range of analog values for which the polynomial fit is valid. Analog values outside this range will be set to the respective min or max values.  
 
+* `void setPowerFitCoeffs(const float C, const float P, const uint16_t valMin, const uint16_t valMax)`  
+Sets the power fit function coefficients _C_ and _P_ in the relation:  
+_Distance = C * A^P_  
+where _A_ is the analog value read from the sensor. `valMin` and `valMax` define the range of analog values for which the power fit is valid. Analog values outside this range will be set to the respective min or max values.  
+
 * `void setValMinMax(const uint16_t valMin, const uint16_t valMax)`  
-Sets the range of analog values for which the polynomial fit is valid (`valMin` and `valMax`). Analog values outside this range will be set to the respective min or max values.
+Sets the range of analog values for which the polynomial or power fit is valid (`valMin` and `valMax`). Analog values outside this range will be set to the respective min or max values.
 
 ## Pre-defined sensor models
 * `GP2Y0A60SZLF_5V` - GP2Y0A60SZLF Analog Distance Sensor 10-150cm, 5V  
 
-Model | C0 | C1 | C2 | C3 | C4 | C5 | valMin | valMax
-------|----|----|----|----|----|----|--------|--------
-**GP2Y0A60SZLF_5V** | 1734 | -9.005 | 2.032E-2 | -2.251E-5 | 1.167E-8 | -2.037E-12 | 30 | 875
+Model | Units | C0 | C1 | C2 | C3 | C4 | C5 | valMin | valMax
+------|-------|----|----|----|----|----|----|--------|--------
+**GP2Y0A60SZLF_5V** | mm | 1734 | -9.005 | 2.032E-2 | -2.251E-5 | 1.167E-8 | -2.037E-12 | 30 | 875
 
 ## Version history
+* 1.1.0 (2017-04-05): Added support of power fit functions.
 * 1.0.0 (2017-03-29): Initial major release for Arduino Library Manager (no change rel. to 0.3.2)
 * 0.3.2 (2017-03-29): Modified models enum and related type in setModel method arguments.
 * 0.3.1 (2017-03-28): Improved README and fixed comments in SharpDistSensorByModel example.

SharpDistSensor.cpp

@@ -53,14 +53,23 @@ uint16_t SharpDistSensor::getDist()
   // Constrain sensor values to remain within set min-max range
   sensVal = constrain(sensVal, _valMin, _valMax);
 
-  // Calculate distance from polynomial fit curve
   uint16_t dist = 0;
-  dist += _coeffs[5] * pow(sensVal, 5);
-  dist += _coeffs[4] * pow(sensVal, 4);
-  dist += _coeffs[3] * pow(sensVal, 3);
-  dist += _coeffs[2] * pow(sensVal, 2);
-  dist += _coeffs[1] * sensVal;
-  dist += _coeffs[0];
+
+  if (_fitType == FIT_POLY)
+  {
+    // Calculate distance from polynomial fit function
+    dist += _polyCoeffs[5] * pow(sensVal, 5);
+    dist += _polyCoeffs[4] * pow(sensVal, 4);
+    dist += _polyCoeffs[3] * pow(sensVal, 3);
+    dist += _polyCoeffs[2] * pow(sensVal, 2);
+    dist += _polyCoeffs[1] * sensVal;
+    dist += _polyCoeffs[0];
+  }
+  else if (_fitType == FIT_POWER)
+  {
+    // Calculate distance from power fit function
+    dist = _powerCoeffC * pow(sensVal, _powerCoeffP);
+  }
 
   if (_mfSize > 1)
   {
@@ -86,29 +95,47 @@ void SharpDistSensor::setModel(const models model)
   }
 }
 
-// Set the polynomial fit curve coefficients and range
+// Set the polynomial fit function coefficients and range
 void SharpDistSensor::setPolyFitCoeffs(const byte nbCoeffs,
   const float* coeffs, const uint16_t valMin, const uint16_t valMax)
 {
+  // Set fit type to FIT_POLY
+  _fitType = FIT_POLY;
+
   // Set coefficients
   for (byte i = 0; i < 6; i++)
   {
     if (i < nbCoeffs)
     {
       // Coefficient is provided
-      _coeffs[i] = coeffs[i];
+      _polyCoeffs[i] = coeffs[i];
     }
     else
     {
       // Coefficient is not provided, set to zero
-      _coeffs[i] = 0;
+      _polyCoeffs[i] = 0;
     }
   }
 
   // Set analog value range
   setValMinMax(valMin, valMax);
 }
 
+// Set the power fit function coefficients and range
+void SharpDistSensor::setPowerFitCoeffs(const float C, const float P,
+  const uint16_t valMin, const uint16_t valMax)
+{
+  // Set fit type to FIT_POWER
+  _fitType = FIT_POWER;
+
+  // Set power fit function coefficients
+  _powerCoeffC = C;
+  _powerCoeffP = P;
+
+  // Set analog value range
+  setValMinMax(valMin, valMax);
+}
+
 // Set the analog value range for which to return a distance
 void SharpDistSensor::setValMinMax(const uint16_t valMin, const uint16_t valMax)
 {

SharpDistSensor.h

@@ -31,19 +31,22 @@ SharpDistSensor; Sharp analog distance sensor library
 This is a library for the Arduino IDE that helps interface with Sharp IR analog
 distance sensors.
 
-The analog value from the sensor is converted to distance using a fifth order
-polynomial fit curve.
+The analog value from the sensor is converted to distance using either a fifth
+order polynomial fit function or a power fit function.
 
-The default polynomial coefficients in this lilbrary are calibrated for the
-Sharp GP2Y0A60SZLF Analog Distance Sensor 10-150cm, 5V over a range of 50-1500
-mm (analog values 30-875). Distance units are millimeters (mm). For different
-accuracy, range, sensor model or units, different coefficients may be required.
+By default, this library is set to use polynomial coefficients calibrated for
+the Sharp GP2Y0A60SZLF Analog Distance Sensor 10-150cm 5V, over a range of
+50-1500 mm (analog values 30-875). The returned distance is in millimeters (mm)
+units.  For different accuracy, range, sensor model or units, different
+coefficients may be required.
 
 Use the setModel method to change the sensor model calibration. The following
 models are currently supported:
 -GP2Y0A60SZLF_5V (GP2Y0A60SZLF Analog Distance Sensor 10-150cm, 5V)
 
-Use the setPolyFitCoeffs method to define custom coefficients.
+Use the setPolyFitCoeffs method to define custom polynomial coefficients.
+
+Use the setPowerFitCoeffs method to define custom power coefficients.
 
 Use the setValMinMax method to define different analog values range.
 
@@ -79,7 +82,7 @@ class SharpDistSensor
   // Set the sensor model
   void setModel(const models model);
 
-  /* Set the polynomial fit curve coefficients and range
+  /* Set the polynomial fit function coefficients and range
     nbCoeffs: Number of coefficients (1 min, 6 max)
     coeffs:   Coefficients (x^0 to x^5)
     valMin: Minimal analog value for which to return a distance
@@ -88,6 +91,14 @@ class SharpDistSensor
   void setPolyFitCoeffs(const byte nbCoeffs, const float* coeffs,
     const uint16_t valMin, const uint16_t valMax);
 
+  /* Set the power fit function coefficients and range
+    C and P: Coefficients in Distance = C*x^P relation
+    valMin: Minimal analog value for which to return a distance
+    valMax: Maximal analog value for which to return a distance
+  */
+  void setPowerFitCoeffs(const float C, const float P,
+    const uint16_t valMin, const uint16_t valMax);
+
   // Set the analog value range for which to return a distance
   void setValMinMax(const uint16_t valMin, const uint16_t valMax);
 
@@ -104,8 +115,22 @@ class SharpDistSensor
   // Maximal analog value for which to return a distance
   uint16_t _valMax;
 
-  // Polynomial curve coefficients to convert analog signal to distance
-  float _coeffs[6];
+  // Polynomial function coefficients to convert analog signal to distance
+  float _polyCoeffs[6];
+
+  // Power function coefficients to convert analog signal to distance
+  float _powerCoeffC;
+  float _powerCoeffP;
+
+  // Possible types of fit functions
+  enum fitTypes
+  {
+    FIT_POLY,
+    FIT_POWER
+  };
+
+  // Fit function type used
+  fitTypes _fitType;
 
   // Median filter object instance
   MedianFilter medFilt;

…stSensorCustom/SharpDistSensorCustom.ino …CustomPoly/SharpDistSensorCustomPoly.inoexamples/SharpDistSensorCustom/SharpDistSensorCustom.ino renamed to examples/SharpDistSensorCustomPoly/SharpDistSensorCustomPoly.ino examples/SharpDistSensorCustom/SharpDistSensorCustom.ino renamed to examples/SharpDistSensorCustomPoly/SharpDistSensorCustomPoly.ino

@@ -1,5 +1,5 @@
 /*
-SharpDistSensorCustom.ino
+SharpDistSensorCustomPoly.ino
 Source: https://github.com/DrGFreeman/SharpDistSensor
 
 MIT License
@@ -60,8 +60,8 @@ const byte nbCoefficients = 6;  // Number of coefficients
  * These should represent a range of analog values within which the
  * polynomial fit curve is valid.
  */
-const uint16_t minVal = 134; // ~800 mm
-const uint16_t maxVal = 875; // ~50mm
+const unsigned int minVal = 134; // ~800 mm
+const unsigned int maxVal = 875; // ~50mm
 
 void setup() {
   Serial.begin(9600);

examples/SharpDistSensorCustomPower/SharpDistSensorCustomPower.ino

@@ -0,0 +1,83 @@
+/*
+SharpDistSensorCustomPower.ino
+Source: https://github.com/DrGFreeman/SharpDistSensor
+
+MIT License
+
+Copyright (c) 2017 Julien de la Bruere-Terreault <drgfreeman@tuta.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+/*
+This example shows how to use the SharpDistSensor library to continuously
+read the sensor and display the analog value and the corrseponding distance
+using custom power fit curve and range.
+*/
+
+#include <SharpDistSensor.h>
+
+// Analog pin to which the sensor is connected
+const byte sensorPin = A0;
+
+// Window size of the median filter (odd number, 1 = no filtering)
+const byte mediumFilterWindowSize = 5;
+
+// Create an object instance of the SharpDistSensor class
+SharpDistSensor sensor(sensorPin, mediumFilterWindowSize);
+
+/* Set the power fit curve coefficients and range
+ * C and P: Coefficients in Distance = C*A^P relation
+ * where A is the analog value read from the sensor.
+ */
+const float C = 90373.;
+const float P = -1.027;
+
+/*
+ * Minimum and maximum analog values for which to return a distance
+ * These should represent a range of analog values within which the
+ * power fit curve is valid.
+ */
+const unsigned int minVal = 134; // ~800 mm
+const unsigned int maxVal = 875; // ~50mm
+
+void setup() {
+  Serial.begin(9600);
+
+  // Set custom power fit curve coefficients and range
+  sensor.setPowerFitCoeffs(C, P, minVal, maxVal);
+}
+
+void loop() {
+  /* Print raw analog value. This step is not required to read the sensor,
+     it is included here to show the relation between the raw analog value
+     and the returned distance. */
+  Serial.print(analogRead(sensorPin));
+
+  Serial.print(", ");
+
+  // Get distance from sensor
+  unsigned int distance = sensor.getDist();
+
+  // Print distance to Serial
+  Serial.println(distance);
+
+  // Wait some time
+  delay(50);
+}

keywords.txt

@@ -2,6 +2,7 @@ SharpDistSensor	KEYWORD1
 getDist	KEYWORD2
 setModel	KEYWORD2
 setPolyFitCoeffs	KEYWORD2
+setPowerFitCoeffs	KEYWORD2
 setValMinMax	KEYWORD2
 GP2Y0A60SZLF_5V	LITERAL1
 GP2Y0A60SZLF_3V	LITERAL1

library.properties

@@ -1,9 +1,9 @@
 name=SharpDistSensor
-version=1.0.0
-author=Julien de la Bruere-Terreault
-maintainer=Julien de la Bruere-Terreault <drgfreeman@tuta.io>
+version=1.1.0
+author=Julien de la Bruere-Terreault (drgfreeman@tuta.io)
+maintainer=Julien de la Bruere-Terreault (drgfreeman@tuta.io)
 sentence=Sharp analog distance sensor library
-paragraph=This is a library for the Arduino IDE that helps interface with Sharp IR analog distance sensors.
+paragraph=This is a library for the Arduino IDE that helps interface with Sharp IR analog distance sensors. It supports polynomial and power fit functions as well as real-time median filtering (sliding window of ajustable size).
 category=Sensors
 url=https://github.com/DrGFreeman/SharpDistSensor
 architectures=*