add read_median() and more

Author: RobTillaart

libraries/HX711/HX711.cpp

@@ -1,7 +1,7 @@
 //
 // FILE: HX711.cpp
 // AUTHOR: Rob Tillaart
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 // PURPOSE: Library for Loadcells for UNO
 // URL: https://github.com/RobTillaart/HX711
 //
@@ -10,7 +10,7 @@
 // 0.1.1 2019-09-09 change long to float (reduce footprint)
 // 0.2.0 2020-06-15 refactor; add price functions;
 // 0.2.1 2020-12-28 add arduino-ci + unit test
-
+// 0.2.2 2021-05-10 add read_median(), fix typo, add mode operandi
 
 #include "HX711.h"
 
@@ -21,6 +21,7 @@ HX711::HX711()
 
 HX711::~HX711() {}
 
+
 void HX711::begin(uint8_t dataPin, uint8_t clockPin)
 {
  _dataPin = dataPin;
@@ -33,18 +34,23 @@ void HX711::begin(uint8_t dataPin, uint8_t clockPin)
  reset();
 }
 
+
 void HX711::reset()
 {
- _offset = 0;
- _scale = 1;
- _gain = 128;
+ _offset = 0;
+ _scale = 1;
+ _gain = 128;
+ _lastRead = 0;
+ _mode = HX711_AVERAGE_MODE;
 }
 
+
 bool HX711::is_ready()
 {
  return digitalRead(_dataPin) == LOW;
 }
 
+
 float HX711::read() 
 {
  // this waiting takes most time...
@@ -85,12 +91,21 @@ float HX711::read()
  return 1.0 * v.value;
 }
 
+
 // assumes tare() has been set.
-void HX711::callibrate_scale(uint16_t weight, uint8_t times)
+void HX711::calibrate_scale(uint16_t weight, uint8_t times)
 {
  _scale = (1.0 * weight) / (read_average(times) - _offset);
 }
 
+// will be obsolete
+void HX711::callibrate_scale(uint16_t weight, uint8_t times)
+{
+ calibrate_scale(weight, times); 
+};
+ 
+
+
 void HX711::wait_ready(uint32_t ms) 
 {
  while (!is_ready())
@@ -99,6 +114,7 @@ void HX711::wait_ready(uint32_t ms)
  }
 }
 
+
 bool HX711::wait_ready_retry(uint8_t retries, uint32_t ms) 
 {
  while (retries--)
@@ -120,8 +136,10 @@ bool HX711::wait_ready_timeout(uint32_t timeout, uint32_t ms)
  return false;
 }
 
+
 float HX711::read_average(uint8_t times) 
 {
+ if (times < 1) times = 1;
  float sum = 0;
  for (uint8_t i = 0; i < times; i++) 
  {
@@ -131,18 +149,101 @@ float HX711::read_average(uint8_t times)
  return sum / times;
 }
 
+
+float HX711::read_median(uint8_t times) 
+{
+ if (times > 15) times = 15;
+ if (times < 3) times = 3;
+ float s[15];
+ for (uint8_t i = 0; i < times; i++) 
+ {
+ s[i] = read();
+ yield();
+ }
+ _insertSort(s, times);
+ if (times & 0x01) return s[times/2];
+ return (s[times/2] + s[times/2+1])/2;
+}
+
+
+float HX711::read_medavg(uint8_t times) 
+{
+ if (times > 15) times = 15;
+ if (times < 3) times = 3;
+ float s[15];
+ for (uint8_t i = 0; i < times; i++) 
+ {
+ s[i] = read();
+ yield();
+ }
+ _insertSort(s, times);
+ float sum = 0;
+ // iterate over 1/4 to 3/4 of the array
+ uint8_t cnt = 0;
+ uint8_t first = (times + 2) / 4;
+ uint8_t last = times - first - 1;
+ for (uint8_t i = first; i <= last; i++) // !! include last too
+ {
+ sum += s[i];
+ cnt++;
+ }
+ return sum/cnt;
+}
+
+
+void HX711::_insertSort(float * array, uint8_t size)
+{
+ uint8_t t, z;
+ float temp;
+ for (t = 1; t < size; t++) 
+ {
+ z = t;
+ temp = array[z];
+ while( (z > 0) && (temp < array[z - 1] )) 
+ {
+ array[z] = array[z - 1];
+ z--;
+ }
+ array[z] = temp;
+ yield();
+ }
+}
+
+
+float HX711::get_value(uint8_t times) 
+{
+ float raw;
+ switch(_mode)
+ {
+ case HX711_MEDAVG_MODE:
+ raw = read_medavg(times);
+ break;
+ case HX711_MEDIAN_MODE:
+ raw = read_median(times);
+ break;
+ case HX711_AVERAGE_MODE:
+ default:
+ raw = read_average(times);
+ break;
+ }
+ return raw - _offset;
+};
+
+
 float HX711::get_units(uint8_t times)
 {
  float units = get_value(times) * _scale;
  return units;
 };
 
+
 void HX711::power_down() 
 {
  digitalWrite(_clockPin, LOW);
  digitalWrite(_clockPin, HIGH);
 }
 
+
 void HX711::power_up() 
 {
  digitalWrite(_clockPin, LOW);

libraries/HX711/HX711.h

@@ -2,7 +2,7 @@
 //
 // FILE: HX711.h
 // AUTHOR: Rob Tillaart
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 // PURPOSE: Library for Loadcells for UNO
 // URL: https://github.com/RobTillaart/HX711
 //
@@ -15,7 +15,16 @@
 
 #include "Arduino.h"
 
-#define HX711_LIB_VERSION (F("0.2.1"))
+#define HX711_LIB_VERSION (F("0.2.2"))
+
+
+const uint8_t HX711_AVERAGE_MODE = 0x00;
+// in median mode only between 3 and 15 samples are allowed.
+const uint8_t HX711_MEDIAN_MODE = 0x01;
+// medavg = average of the middle "half" of sorted elements
+// in medavg mode only between 3 and 15 samples are allowed.
+const uint8_t HX711_MEDAVG_MODE = 0x02;
+
 
 class HX711
 {
@@ -41,49 +50,75 @@ class HX711
 
  // raw read
  float read();
- // multiple raw reads
+ // get average of multiple raw reads
  float read_average(uint8_t times = 10);
+
+ // get median of multiple raw reads 
+ // times = 3..15 - odd numbers preferred
+ float read_median(uint8_t times = 7); 
+
+ // get average of "middle half" of multiple raw reads.
+ // times = 3..15 - odd numbers preferred
+ float read_medavg(uint8_t times = 7); 
+
+
+ // get set mode for get_value() and indirect get_units().
+ // in median and medavg mode only 3..15 samples are allowed.
+ void set_average_mode() { _mode = HX711_AVERAGE_MODE; };
+ void set_median_mode() { _mode = HX711_MEDIAN_MODE; };
+ void set_medavg_mode() { _mode = HX711_MEDAVG_MODE; };
+ uint8_t get_mode() { return _mode; };
+ 
  // corrected for offset
- float get_value(uint8_t times = 1) { return read_average(times) - _offset; };
+ float get_value(uint8_t times = 1);
  // converted to proper units.
  float get_units(uint8_t times = 1);
 
+
  // TARE
  // call tare to calibrate zero
  void tare(uint8_t times = 10) { _offset = read_average(times); };
  float get_tare() { return -_offset * _scale; };
  bool tare_set() { return _offset != 0; };
 
+
  // CORE "CONSTANTS" -> read datasheet
  // GAIN values: 128, 64 32 [only 128 tested & verified]
  void set_gain(uint8_t gain = 128) { _gain = gain; };
  uint8_t get_gain() { return _gain; };
  // SCALE > 0
- void set_scale(float scale = 1.0) { _scale = 1 / scale; };
- float get_scale() { return 1 / _scale; };
+ void set_scale(float scale = 1.0) { _scale = 1.0 / scale; };
+ float get_scale() { return 1.0 / _scale; };
  // OFFSET > 0
  void set_offset(long offset = 0) { _offset = offset; };
  long get_offset() { return _offset; };
 
+
  // CALIBRATION
  // clear the scale
  // call tare() to set the zero offset
  // put a known weight on the scale 
- // call callibrate_scale(weight) 
+ // call calibrate_scale(weight) 
  // scale is calculated.
- void callibrate_scale(uint16_t weight, uint8_t times = 10);
+ void calibrate_scale(uint16_t weight, uint8_t times = 10);
+ // obsolete typo but just do not want to break interface yet
+ void callibrate_scale(uint16_t weight, uint8_t times = 10); 
+
 
  // POWER MANAGEMENT
  void power_down();
  void power_up();
 
+
  // TIME OF LAST READ
  uint32_t last_read() { return _lastRead; };
 
+
  // PRICING (idem calories?)
  float get_price(uint8_t times = 1) { return get_units(times) * _price; };
- void set_unit_price(float price) { _price = price; };
- float get_unit_price() { return _price; };
+ void set_unit_price(float price = 1.0) { _price = price; };
+ float get_unit_price() { return _price; };
+
 
 private:
  uint8_t _dataPin;
@@ -94,6 +129,9 @@ class HX711
  float _scale = 1;
  uint32_t _lastRead = 0;
  float _price = 0;
+ uint8_t _mode = 0;
+
+ void _insertSort(float * array, uint8_t size);
 };
 
 // -- END OF FILE --

libraries/HX711/README.md

@@ -23,16 +23,16 @@ footprint.
 
 First action is to call **begin(dataPin, clockPin)** to make connection to the **HX711**.
 
-Second step is callibration for which a number of functions exist.
+Second step is calibration for which a number of functions exist.
 - **tare()** measures zero point
 - **set_scale(factor)** set a known conversion factor e.g. from EEPROM.
-- **callibrate_scale(WEIGHT, TIMES)** determines the scale factor based upon a known weight e.g. 1 Kg.
+- **calibrate_scale(WEIGHT, TIMES)** determines the scale factor based upon a known weight e.g. 1 Kg.
 
-Steps to take for callibration
+Steps to take for calibration
 1. clear the scale
 1. call tare() to set the zero offset
 1. put a known weight on the scale 
-1. call callibrate_scale(weight) 
+1. call calibrate_scale(weight) 
 1. scale is calculated.
 1. save the offset and scale for later use e.g. EEPROM.
 
@@ -53,7 +53,7 @@ For weight conversion functions see https://github.com/RobTillaart/weight
 ### Scale values for loadcells
 
 These scale values worked pretty well with a set of loadcells, 
-Use callibrate to find your values.
+Use calibrate to find your values.
 
 - 5 KG loadcell scale.set_scale(420.52); 
 - 20 KG loadcell scale.set_scale(127.15); 

libraries/HX711/examples/HX_grocery_scale/HX_grocery_scale.ino

@@ -43,11 +43,11 @@ void setup()
  while(!Serial.available());
  while(Serial.available()) Serial.read();
 
- scale.callibrate_scale(1000, 5);
+ scale.calibrate_scale(1000, 5);
  Serial.print("UNITS: ");
  Serial.println(scale.get_units(10));
 
- Serial.println("\nScale is callibrated, press a key to continue");
+ Serial.println("\nScale is calibrated, press a key to continue");
  while(!Serial.available());
  while(Serial.available()) Serial.read();
 

libraries/HX711/examples/HX_kitchen_scale/HX_kitchen_scale.ino

@@ -39,15 +39,15 @@ void setup()
  Serial.println(scale.get_units(10));
 
 
- Serial.println("\nPut a 1 kg in the scale, press a key to continue");
+ Serial.println("\nPut 1000 gram in the scale, press a key to continue");
  while(!Serial.available());
  while(Serial.available()) Serial.read();
 
- scale.callibrate_scale(1000, 5);
+ scale.calibrate_scale(1000, 5);
  Serial.print("UNITS: ");
  Serial.println(scale.get_units(10));
 
- Serial.println("\nScale is callibrated, press a key to continue");
+ Serial.println("\nScale is calibrated, press a key to continue");
  while(!Serial.available());
  while(Serial.available()) Serial.read();