0.4.3 RunningAverage

2024-09-19 16:46:11 -04:00 · 2022-11-23 19:22:02 +01:00 · 2022-11-23 19:22:02 +01:00 · 47196dbab8
commit 47196dbab8
parent cd10217a62
11 changed files with 385 additions and 91 deletions
--- a/libraries/RunningAverage/.arduino-ci.yml
+++ b/libraries/RunningAverage/.arduino-ci.yml
@ -1,5 +1,21 @@
+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
+  #  selected only those that work
  platforms:
    - uno
    # - due
@ -7,5 +23,7 @@ compile:
    # - leonardo
    - m4
    - esp32
-    # - esp8266
+    - esp8266
    # - mega2560
+    - rpipico
+
--- a/libraries/RunningAverage/CHANGELOG.md
+++ b/libraries/RunningAverage/CHANGELOG.md
@ -0,0 +1,111 @@
+# Change Log runningAverage
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+
+## [0.4.3] - 2022-11-23
+- add changelog.md
+- add RP2040 to build-CI
+- add examples
+- add getAverageSubset(start, count) - experimental
+- update readme.md
+
+
+## [0.4.2] - 2021-12-28
+- update license
+- minor edits
+
+## [0.4.1] - 2021-11-22
+- updated buil-CI, readme, badges
+- add getAverageLast() functions.
+
+## [0.4.0] - 2021-05-18
+- increase size above 256 elements (16 bit version)
+
+----
+
+## [0.3.2] - 2021-01-15
+- add add()
+- license
+- refactor
+
+## [0.3.1] - 2020-06-19
+- fix library.json
+- minor refactor
+
+## [0.3.0] - 2020-04-16
+- main refactor
+
+----
+
+## [0.2.16] - 2020-04-16
+- improve \_sum - see issue #149 (bourkemcrobbo)
+
+## [0.2.15] - 2020-01-17
+- fix overflow in getValue - see issue #139
+
+
+## [0.2.14] - 2020-01-15
+- added getValue(n) to retrieve elements in order of addition - see issue #132
+
+## [0.2.13] - 2017-07-26
+- revert double to float - issue #33;
+- refactored a bit; marked some TODO's
+- all function names to camelCase
+
+## [0.2.12] - 2016-12-01
+- add GetStandardDeviation()
+- add GetStandardError()
+- add BufferIsFull()  (V0v1kkk)
+
+## [0.2.11] - 2015-09-04
+- add getMaxInBuffer() getMinInBuffer() request (Antoon)
+
+## [0.2.10] - 2015-09-01
+- added getFastAverage()
+- refactored getAverage()
+- http://forum.arduino.cc/index.php?topic=50473
+
+## [0.2.09] - 2015-07-12
+- refactor const
+- refactor constructor
+
+## [0.2.08] - 2015-04-10
+- refactor getMin() and getMax() implementation
+
+## [0.2.07] - 2015-03-16
+- added getMin() and getMax() functions (Eric Mulder)
+
+## [0.2.06] - 2015-03-07
+- all size uint8_t
+
+## [0.2.05] - 2014-12-16
+- changed float -> double
+
+## [0.2.04] - 2014-07-03
+- added memory protection
+
+## [0.2.03] - 2013-11-31
+- add getElement()
+
+## [0.2.02] - 2012-12-30
+- refactored trimValue -> fillValue
+
+## [0.2.01] - 2012-11-21
+- refactored
+
+## [0.2.00] - 2012-??-??  
+- Yuval Naveh added trimValue (found on web)
+- http://stromputer.googlecode.com/svn-history/r74/trunk/Arduino/Libraries/RunningAverage/RunningAverage.cpp
+
+----
+
+## [0.1.01] - 2011-02-28
+- fixed missing destructor in .h
+
+## [0.1.00] - 2011-01-30
+- initial version
+
--- a/libraries/RunningAverage/README.md
+++ b/libraries/RunningAverage/README.md
@ -96,6 +96,10 @@ Note: if called with a value larger or equal to **getCount()**  (incl **getSize(
 parameter, the functions will return the statistics of the whole buffer. 


+## Subset (experimental)
+
+- **float getAverageSubset(uint16_t start, uint16_t count)** 
+Get the average of subset - count elements from start.


 ## Operation
@ -105,11 +109,15 @@ See examples

 ## Future 

- add error handling  (important?)
- default size for constructor
- update documentation, explain better.
- create a double based derived class? Template class?
- check for optimizations.
- clear(bool zero = true)  to suppress setting all to 0. ??
- separate releaseNotes.md
+#### must
+- update documentation, explain better
+
+#### should
+- add error handling  (important?)
+- check for optimizations.
+- clear(bool zero = true) to suppress setting all to 0. ?
+
+#### could
+- default size for constructor
+- create a double based derived class? Template class?

--- a/libraries/RunningAverage/RunningAverage.cpp
+++ b/libraries/RunningAverage/RunningAverage.cpp
@ -1,44 +1,13 @@
 //
 //    FILE: RunningAverage.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.4.2
+// VERSION: 0.4.3
 //    DATE: 2015-July-10
 // PURPOSE: Arduino library to calculate the running average by means of a circular buffer
 //     URL: https://github.com/RobTillaart/RunningAverage
 //
-// The library stores N individual values in a circular buffer,
-// to calculate the running average.
-//
-//  HISTORY:
-//  0.1.00  2011-01-30  initial version
-//  0.1.01  2011-02-28  fixed missing destructor in .h
-//  0.2.00  2012-??-??  Yuval Naveh added trimValue (found on web)
-//          http://stromputer.googlecode.com/svn-history/r74/trunk/Arduino/Libraries/RunningAverage/RunningAverage.cpp
-//  0.2.01  2012-11-21  refactored
-//  0.2.02  2012-12-30  refactored trimValue -> fillValue
-//  0.2.03  2013-11-31  getElement
-//  0.2.04  2014-07-03  added memory protection
-//  0.2.05  2014-12-16  changed float -> double
-//  0.2.06  2015-03-07  all size uint8_t
-//  0.2.07  2015-03-16  added getMin() and getMax() functions (Eric Mulder)
-//  0.2.08  2015-04-10  refactored getMin() and getMax() implementation
-//  0.2.09  2015-07-12  refactor const + constructor
-//  0.2.10  2015-09-01  added getFastAverage() and refactored getAverage()
-//                      http://forum.arduino.cc/index.php?topic=50473
-//  0.2.11  2015-09-04  added getMaxInBuffer() getMinInBuffer() request (Antoon)
-//  0.2.12  2016-12-01  added GetStandardDeviation() GetStandardError() BufferIsFull()  (V0v1kkk)
-//  0.2.13  2017-07-26  revert double to float - issue #33;
-//                      refactored a bit; marked some TODO's; all function names to camelCase
-//  0.2.14  2020-01-15  added getValue(n) to retrieve elements in order of addition - see issue #132
-//  0.2.15  2020-01-17  fix overflow in getValue - see issue #139
-//  0.2.16  2020-04-16  improve _sum - see issue #149 (bourkemcrobbo)
-//  0.3.0   2020-04-16  main refactor
-//  0.3.1   2020-06-19  fix library.json; minor refactor
-//  0.3.2   2021-01-15  add add() + license + refactor
-//  0.4.0   2021-05-18  increase size above 256 elements (16 bit version)
-//  0.4.1   2021-11-22  updated buil-CI, readme, badges
-//                      add getAverageLast() functions.
-//  0.4.2   2021-12-28  license, minor edits
+//  The library stores N individual values in a circular buffer,
+//  to calculate the running average.


 #include "RunningAverage.h"
@ -60,7 +29,7 @@ RunningAverage::~RunningAverage()
 }


-// resets all counters
+//  resets all counters
 void RunningAverage::clear()
 {
  _count = 0;
@ -75,7 +44,7 @@ void RunningAverage::clear()
 }


-// adds a new value to the data-set
+//  adds a new value to the data-set
 void RunningAverage::addValue(const float value)
 {
  if (_array == NULL)
@ -90,24 +59,24 @@ void RunningAverage::addValue(const float value)

  if (_index == _partial) _index = 0;  // faster than %

-  // handle min max
+  //  handle min max
  if (_count == 0) _min = _max = value;
  else if (value < _min) _min = value;
  else if (value > _max) _max = value;

-  // update count as last otherwise if ( _count == 0) above will fail
+  //  update count as last otherwise if ( _count == 0) above will fail
  if (_count < _partial) _count++;
 }


-// returns the average of the data-set added so far, NAN if no elements.
+//  returns the average of the data-set added so far, NAN if no elements.
 float RunningAverage::getAverage()
 {
  if (_count == 0)
  {
    return NAN;
  }
-
+  //  OPTIMIZE local variable for sum.
  _sum = 0;
  for (uint16_t i = 0; i < _count; i++)
  {
@ -117,7 +86,8 @@ float RunningAverage::getAverage()
 }


-// the larger the size of the internal buffer the greater the gain wrt getAverage()
+//  the larger the size of the internal buffer 
+//  the greater the gain wrt getAverage()
 float RunningAverage::getFastAverage() const
 {
  if (_count == 0)
@ -125,11 +95,11 @@ float RunningAverage::getFastAverage() const
    return NAN;
  }

-  return _sum / _count;   // multiplication is faster ==> extra admin
+  return _sum / _count;   //  multiplication is faster ==> extra admin
 }


-// returns the minimum value in the buffer
+//  returns the minimum value in the buffer
 float RunningAverage::getMinInBuffer() const
 {
  if (_count == 0)
@ -146,7 +116,7 @@ float RunningAverage::getMinInBuffer() const
 }


-// returns the maximum value in the buffer
+//  returns the maximum value in the buffer
 float RunningAverage::getMaxInBuffer() const
 {
  if (_count == 0)
@ -163,7 +133,7 @@ float RunningAverage::getMaxInBuffer() const
 }


-// returns the value of an element if exist, NAN otherwise
+//  returns the value of an element if exist, NAN otherwise
 float RunningAverage::getElement(uint16_t index) const
 {
  if (_count == 0)
@ -175,14 +145,14 @@ float RunningAverage::getElement(uint16_t index) const
 }


-// Return standard deviation of running average.
-// If buffer is empty or has only one element, return NAN.
+//  Return standard deviation of running average.
+//  If buffer is empty or has only one element, return NAN.
 float RunningAverage::getStandardDeviation() const
 {
-  // see issue #13
-  // need float _stddev = -1;
-  //    + patch add() and clear() to reset _stddev to -1;
-  // if (_stddev != -1) return _stddev;
+  //  see issue #13
+  //  need float _stddev = -1;
+  //     + patch add() and clear() to reset _stddev to -1;
+  //  if (_stddev != -1) return _stddev;
  if (_count <= 1) return NAN;

  float temp = 0;
@ -193,14 +163,14 @@ float RunningAverage::getStandardDeviation() const
  }
  temp = sqrt(temp/(_count - 1));
  return temp;
-  // see issue #13
-  // _stddev = temp;  // cache the calculate value
-  // return _stddev;
+  //  see issue #13
+  //  _stddev = temp;  // cache the calculate value
+  //  return _stddev;
 }


-// Return standard error of running average.
-// If buffer is empty or has only one element, return NAN.
+//  Return standard error of running average.
+//  If buffer is empty or has only one element, return NAN.
 float RunningAverage::getStandardError() const
 {
  float temp = getStandardDeviation();
@ -215,37 +185,39 @@ float RunningAverage::getStandardError() const
 }


-// fill the average with the same value number times. (weight)
-// This is maximized to size times.
-// no need to fill the internal buffer over 100%
+//  fill the average with the same value number times. (weight)
+//  This is maximized to size times.
+//  no need to fill the internal buffer over 100%
 void RunningAverage::fillValue(const float value, const uint16_t number)
 {
  clear();
  uint16_t s = number;
-  if (s > _size) s = _size;
+  if (s > _partial) s = _partial;
+
  for (uint16_t i = s; i > 0; i--)
  {
    addValue(value);
  }
 }

+
 // https://github.com/RobTillaart/RunningAverage/issues/13
 // - substantially faster version off fillValue()
 // - adds to program size
 // void RunningAverage::fillValue(const float value, const uint16_t number)
 // {
  // uint16_t s = number;
-  // if (s > _size) s = _size;
-  // for (uint16_t idx = 0; idx < s; idx++)
+  // if (s > _partial) s = _partial;
+  // for (uint16_t i = 0; i < s; i++)
  // {
-    // _array[idx] = value;
+    // _array[i] = value;
  // }
-  // _index = s;
-  // if (_index == _partial) _index = 0;  // faster than %
  // _min = value;
  // _max = value;
+  // _sum = value * s;
  // _count = s;
-  // _sum = s * value;
+  // _index = s;
+  // if (_index == _partial) _index = 0;
 // }


@ -276,7 +248,7 @@ void RunningAverage::setPartial(const uint16_t partial)

 ////////////////////////////////////////////////////////////////
 //
-// 0.4.1 added.
+//  0.4.1 added.
 //
 float RunningAverage::getAverageLast(uint16_t count)
 {
@ -336,5 +308,31 @@ float RunningAverage::getMaxInBufferLast(uint16_t count)
 }


+
+////////////////////////////////////////////////////////////////
+//
+//  Experimental 0.4.3
+//
+float RunningAverage::getAverageSubset(uint16_t start, uint16_t count)
+{
+  if (_count == 0)
+  {
+    return NAN;
+  }
+
+  uint16_t cnt = _count;
+  if (cnt > count) cnt = count;
+
+  float sum = 0;   //  do not disrupt global _sum
+  for (uint16_t i = 0; i < cnt; i++)
+  {
+    uint16_t idx = _index + start + i;
+    while (idx >= _partial) idx -= _partial;
+    sum += _array[idx];
+  }
+  return sum / cnt;
+}
+
+
 // -- END OF FILE --

--- a/libraries/RunningAverage/RunningAverage.h
+++ b/libraries/RunningAverage/RunningAverage.h
@ -2,18 +2,16 @@
 //
 //    FILE: RunningAverage.h
 //  AUTHOR: Rob.Tillaart@gmail.com
-// VERSION: 0.4.2
+// VERSION: 0.4.3
 //    DATE: 2016-dec-01
 // PURPOSE: Arduino library to calculate the running average by means of a circular buffer
 //     URL: https://github.com/RobTillaart/RunningAverage
-//
-// HISTORY: See RunningAverage.cpp


 #include "Arduino.h"


-#define RUNNINGAVERAGE_LIB_VERSION    (F("0.4.2"))
+#define RUNNINGAVERAGE_LIB_VERSION    (F("0.4.3"))


 class RunningAverage
@ -28,22 +26,22 @@ public:
  void     fillValue(const float value, const uint16_t number);
  float    getValue(const uint16_t position);

-  float    getAverage();      // iterates over all elements.
-  float    getFastAverage() const;  // reuses previous calculated values.
+  float    getAverage();      //  iterates over all elements.
+  float    getFastAverage() const;  //  reuses previous calculated values.

-  // return statistical characteristics of the running average
+  //  return statistical characteristics of the running average
  float    getStandardDeviation() const;
  float    getStandardError() const;

-  // returns min/max added to the data-set since last clear
+  //  returns min/max added to the data-set since last clear
  float    getMin() const { return _min; };
  float    getMax() const { return _max; };

-  // returns min/max from the values in the internal buffer
+  //  returns min/max from the values in the internal buffer
  float    getMinInBuffer() const;
  float    getMaxInBuffer() const;

-  // return true if buffer is full
+  //  return true if buffer is full
  bool     bufferIsFull() const { return _count == _size; };

  float    getElement(uint16_t index) const;
@ -51,17 +49,20 @@ public:
  uint16_t getSize() const { return _size; }
  uint16_t getCount() const { return _count; }

-  // use not all elements just a part from 0..partial-1
-  // (re)setting partial will clear the internal buffer.
+  //  use not all elements just a part from 0..partial-1
+  //  (re)setting partial will clear the internal buffer.
  void     setPartial(const uint16_t partial = 0);  // 0 ==> use all
  uint16_t getPartial()   { return _partial; };


-  // get some stats from the last count additions.
+  //  get some stats from the last count additions.
  float    getAverageLast(uint16_t count);
  float    getMinInBufferLast(uint16_t count);
  float    getMaxInBufferLast(uint16_t count);

+  //       Experimental 0.4.3
+  float    getAverageSubset(uint16_t start, uint16_t count);
+

 protected:
  uint16_t _size;
--- a/libraries/RunningAverage/examples/ra_fillValue_test/ra_fillValue_test.ino
+++ b/libraries/RunningAverage/examples/ra_fillValue_test/ra_fillValue_test.ino
@ -0,0 +1,71 @@
+//
+//    FILE: ra_fillValue_test.ino
+//  AUTHOR: Rob Tillaart
+//    DATE: 2012-12-30
+// PUPROSE: demo + timing of fillValue
+
+
+#include "RunningAverage.h"
+
+RunningAverage myRA(10);
+int samples = 0;
+
+uint32_t start, stop;
+
+
+void setup(void)
+{
+  Serial.begin(115200);
+  Serial.print("Demo RunningAverage lib - fillValue ");
+  Serial.print("Version: ");
+  Serial.println(RUNNINGAVERAGE_LIB_VERSION);
+  delay(10);
+
+  for (int i = 0; i < 15; i++)
+  {
+    measure_duration(i);
+    check_statistics();
+  }
+
+  Serial.println();
+}
+
+
+void loop(void)
+{
+}
+
+
+void measure_duration(int n)
+{
+  start = micros();
+  myRA.fillValue(100, n);
+  stop = micros();
+  Serial.print("fillValue(100, ");
+  Serial.print(n);
+  Serial.print("): ");
+  Serial.println(stop - start);
+  delay(100);
+}
+
+
+void check_statistics()
+{
+  Serial.print(myRA.getAverage());
+  Serial.print("\t");
+  Serial.print(myRA.getFastAverage());
+  Serial.print("\t");
+  Serial.print(myRA.getSize());
+  Serial.print("\t");
+  Serial.print(myRA.getCount());
+  Serial.print("\t");
+  Serial.print(myRA.getMinInBuffer());
+  Serial.print("\t");
+  Serial.print(myRA.getMaxInBuffer());
+  Serial.print("\t");
+  Serial.print(myRA.getStandardDeviation());
+  Serial.print("\n");
+}
+
+
+// -- END OF FILE --
--- a/libraries/RunningAverage/examples/ra_getAverageSubset/ra_getAverageSubset.ino
+++ b/libraries/RunningAverage/examples/ra_getAverageSubset/ra_getAverageSubset.ino
@ -0,0 +1,62 @@
+//
+//    FILE: ra_getAverageSubset.ino
+//  AUTHOR: Rob Tillaart
+//    DATE: 2012-12-30
+// PUPROSE: show working of runningAverage
+
+
+#include "RunningAverage.h"
+
+RunningAverage myRA(10);
+int samples = 0;
+
+
+void setup(void)
+{
+  Serial.begin(115200);
+  Serial.println("Demo RunningAverage lib");
+  Serial.print("Version: ");
+  Serial.println(RUNNINGAVERAGE_LIB_VERSION);
+  myRA.clear(); // explicitly start clean
+
+  for (int i = 0; i < 20; i++)
+  {
+    myRA.addValue(i);
+  }
+  Serial.println();
+  Serial.print(myRA.getAverage(), 3);
+  Serial.print("\t");
+  Serial.print(myRA.getAverageSubset(0, 5), 3);
+  Serial.print("\t");
+  Serial.print(myRA.getAverageSubset(3, 5), 3);
+  Serial.print("\t");
+  Serial.println(myRA.getAverageSubset(5, 5), 3);
+  Serial.println();
+  delay(10000);
+
+  myRA.clear(); // explicitly start clean
+}
+
+
+void loop(void)
+{
+  long rn = random(0, 1000);
+  myRA.addValue(rn * 0.001);
+  samples++;
+  Serial.print(samples);
+  Serial.print("\t");
+  Serial.print(100 * myRA.getAverage(), 3);
+  Serial.print("\t");
+  Serial.println(100 * myRA.getAverageSubset(5, 5), 3);
+
+  if (samples == 300)
+  {
+    samples = 0;
+    myRA.clear();
+    Serial.println();
+  }
+  delay(10);
+}
+
+
+// -- END OF FILE --
--- a/libraries/RunningAverage/examples/ra_performance/performance_0.4.3.txt
+++ b/libraries/RunningAverage/examples/ra_performance/performance_0.4.3.txt
@ -0,0 +1,24 @@
+
+UNO    IDE 1.8.19
+
+Performance RunningAverage lib: 0.4.3
+
+	clear 		: 64
+	addValue 	: 24
+	fillValue 	: 1512
+	getValue 	: 8
+	getAverage 	: 516
+	getFastAverage 	: 40
+	getStandardDeviation 	: 1848
+	getStandardError 	: 1912
+	getMin 		: 4
+	getMax 		: 4
+	getMinInBuffer 	: 220
+	getMaxInBuffer 	: 208
+	bufferIsFull 	: 12
+	getElement 	: 4
+	getSize 	: 4
+	getCount 	: 8
+
+done...
+
--- a/libraries/RunningAverage/library.json
+++ b/libraries/RunningAverage/library.json
@ -15,7 +15,7 @@
    "type": "git",
    "url": "https://github.com/RobTillaart/RunningAverage.git"
  },
-  "version": "0.4.2",
+  "version": "0.4.3",
  "license": "MIT",
  "frameworks": "arduino",
  "platforms": "*",
--- a/libraries/RunningAverage/library.properties
+++ b/libraries/RunningAverage/library.properties
@ -1,5 +1,5 @@
 name=RunningAverage
-version=0.4.2
+version=0.4.3
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=The library stores the last N individual values in a circular buffer to calculate the running average. 
--- a/libraries/RunningAverage/test/unit_test_001.cpp
+++ b/libraries/RunningAverage/test/unit_test_001.cpp
@ -41,6 +41,7 @@ unittest_setup()
  fprintf(stderr, "RUNNINGAVERAGE_LIB_VERSION: %s\n", (char *) RUNNINGAVERAGE_LIB_VERSION);
 }

+
 unittest_teardown()
 {
 }
@ -140,7 +141,6 @@ unittest(test_partial)
 }


-
 unittest(test_last)
 {
  RunningAverage myRA(300);
@ -175,4 +175,5 @@ unittest(test_last)

 unittest_main()

+
 // --------