fix #56, make breaking change more explicit (#57)

- fix #56, update readme.md
- add parameter default for **fastProcessor**
- add **last_time_read()** to replace **last_read()** in future.
- minor edits

Author: RobTillaart

CHANGELOG..md

@@ -5,6 +5,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.5.2] - 2024-11-18
+- fix #56, update readme.md
+- add parameter default for **fastProcessor**
+- add **last_time_read()** to replace **last_read()** in future.
+- minor edits
+
+
 ## [0.5.1] - 2024-11-08
 - fix #54, calibration sketch should output int32_t for offset.
 - update examples

HX711.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: HX711.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.1
+// VERSION: 0.5.2
 // PURPOSE: Library for load cells for UNO
 //     URL: https://github.com/RobTillaart/HX711_MP
 //     URL: https://github.com/RobTillaart/HX711
@@ -15,7 +15,7 @@ HX711::HX711()
   _gain     = HX711_CHANNEL_A_GAIN_128;
   _offset   = 0;
   _scale    = 1;
-  _lastRead = 0;
+  _lastTimeRead = 0;
   _price    = 0;
   _mode     = HX711_AVERAGE_MODE;
   _fastProcessor = false;
@@ -48,7 +48,7 @@ void HX711::reset()
   _gain     = HX711_CHANNEL_A_GAIN_128;
   _offset   = 0;
   _scale    = 1;
-  _lastRead = 0;
+  _lastTimeRead = 0;
   _price    = 0;
   _mode     = HX711_AVERAGE_MODE;
 }
@@ -141,13 +141,13 @@ float HX711::read()
 
   while (m > 0)
   {
-    //  delayMicroSeconds(1) needed for fast processors?
+    //  delayMicroSeconds(1) is needed for fast processors
+    //  T2  >= 0.2 us
     digitalWrite(_clockPin, HIGH);
-    if (_fastProcessor)
-        delayMicroseconds(1);
+    if (_fastProcessor) delayMicroseconds(1);
     digitalWrite(_clockPin, LOW);
-    if (_fastProcessor)
-        delayMicroseconds(1);
+    //  keep duty cycle ~50%
+    if (_fastProcessor) delayMicroseconds(1);
     m--;
   }
 
@@ -157,7 +157,7 @@ float HX711::read()
   //  SIGN extend
   if (v.data[2] & 0x80) v.data[3] = 0xFF;
 
-  _lastRead = millis();
+  _lastTimeRead = millis();
   return 1.0 * v.value;
 }
 
@@ -416,9 +416,15 @@ void HX711::power_up()
 //
 //  MISC
 //
+uint32_t HX711::last_time_read()
+{
+  return _lastTimeRead;
+}
+
+//  obsolete future
 uint32_t HX711::last_read()
 {
-  return _lastRead;
+  return _lastTimeRead;
 }
 
 
@@ -458,15 +464,15 @@ uint8_t HX711::_shiftIn()
   while (mask > 0)
   {
     digitalWrite(clk, HIGH);
-    if(_fastProcessor)       //  T2  >= 0.2 us
-      delayMicroseconds(1);
+    //  T2  >= 0.2 us
+    if(_fastProcessor) delayMicroseconds(1);
     if (digitalRead(data) == HIGH)
     {
       value |= mask;
     }
     digitalWrite(clk, LOW);
-    if(_fastProcessor)
-      delayMicroseconds(1);   //  keep duty cycle ~50%
+    //  keep duty cycle ~50%
+    if(_fastProcessor) delayMicroseconds(1);
     mask >>= 1;
   }
   return value;

HX711.h

@@ -2,7 +2,7 @@
 //
 //    FILE: HX711.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.1
+// VERSION: 0.5.2
 // PURPOSE: Library for load cells for Arduino
 //     URL: https://github.com/RobTillaart/HX711_MP
 //     URL: https://github.com/RobTillaart/HX711
@@ -15,7 +15,7 @@
 
 #include "Arduino.h"
 
-#define HX711_LIB_VERSION               (F("0.5.1"))
+#define HX711_LIB_VERSION               (F("0.5.2"))
 
 
 const uint8_t HX711_AVERAGE_MODE = 0x00;
@@ -163,7 +163,8 @@ class HX711
 
 
   //  TIME OF LAST READ
-  uint32_t last_read();
+  uint32_t last_time_read();
+  uint32_t last_read();  //  obsolete in the future
 
 
   //  PRICING
@@ -179,7 +180,7 @@ class HX711
   uint8_t  _gain;
   int32_t  _offset;
   float    _scale;
-  uint32_t _lastRead;
+  uint32_t _lastTimeRead;
   float    _price;
   uint8_t  _mode;
   bool     _fastProcessor;

README.md

@@ -29,6 +29,15 @@ This translates roughly to 4 or max 5 significant digits in a single measurement
 That's why multiple measurements are advised to average and reduce the noise.
 
 
+### Breaking change 0.4.0
+
+The **begin()** function has a new parameter **bool fastProcessor** which is default false.
+It is used to slow down the internal **shiftIn()** to keep clock pulses within the 
+specification. For most processors the internal code is "slow enough".
+If the processor can set an IO pin faster than 0.4 us (spec datasheet == 0.2 us), 
+the parameter **fastProcessor** must be set to true.
+
+
 ### Breaking change 0.3.0
 
 In issue #11 it became clear that the timing of the default **shiftIn()** function to 
@@ -79,9 +88,13 @@ For now one can add an IOpin for this and use **digitalWrite()**.
 
 - https://github.com/bogde/HX711
 - https://github.com/RobTillaart/weight  (conversions kg <> stone etc.)
+- https://github.com/RobTillaart/HX710
 - https://github.com/RobTillaart/HX711
 - https://github.com/RobTillaart/HX711_MP  multipoint calibration version.
 
+Discussion about resolution of the ADC
+- https://forum.arduino.cc/t/scale-from-50-kg-to-5000kg-what-adc/1139710
+
 
 ### Faulty boards
 
@@ -116,7 +129,7 @@ Steps to take for calibration
 
 - **HX711()** constructor.
 - **~HX711()**
-- **void begin(uint8_t dataPin, uint8_t clockPin, bool fastProcessor)** sets a fixed gain 128 for now.
+- **void begin(uint8_t dataPin, uint8_t clockPin, bool fastProcessor = false)** sets a fixed gain 128 for now.
 The fastProcessor option adds a 1 uS delay for each clock half-cycle to keep the time greater than 200 nS.
 - **void reset()** set internal state to start condition.
 Since 0.3.4 reset also does a power down / up cycle.
@@ -294,8 +307,8 @@ For weight conversion functions see https://github.com/RobTillaart/weight
 
 To be verified in a test setup.
 
-In issue #53, a question was asked to convert the input of the HX711 to milivolts.
-Thinking about this question resulted in a simple and imho an elegant idea:
+In issue #53, a question was asked to convert the input of the HX711 to millivolts.
+Thinking about this question resulted in a simple and elegant idea:
 
 - Apply 0.000 mV to the system.
 - Call **tare(times)** to calibrate the zero point. 
@@ -306,7 +319,7 @@ Assuming the scale is linear, the HX711 now works like a millivolt meter.
 And the **float get_units(uint8_t times = 1)** will return microvolts.
 
 In fact, one could map any linear unit this way, e.g. if the voltage applied 
-is linear with temperature, humidity or windspeed one can map this directly.
+is linear with temperature, humidity or wind speed one can map this directly.
 
 
 ## Notes
@@ -400,6 +413,7 @@ See https://github.com/RobTillaart/HX711/issues/40
 
 #### Should
 
+- replace last_read() with last_time_read()
 - test B channel explicitly.
 - test reset and reboot behaviours.
 - investigate read()
@@ -408,6 +422,9 @@ See https://github.com/RobTillaart/HX711/issues/40
 
 #### Could
 
+- optimize fastProcessor code (possible better performance)
+  - injecting 2 microdelays is not always needed.
+  - int flag instead of bool.
 - test different load cells
 - make enum of the MODE's
 - add examples

library.json

@@ -1,7 +1,7 @@
 {
   "name": "HX711",
   "keywords": "loadcell,weight,kilo,pound,gram,price,lbs,ounce,pound",
-  "description": "Arduino library for HX711 load cell amplifier",
+  "description": "Arduino library for HX711 load cell amplifier, includes calibrate functions, reading median and median_average.",
   "authors":
   [
     {
@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/HX711"
   },
-  "version": "0.5.1",
+  "version": "0.5.2",
   "license": "MIT",
   "frameworks": "*",
   "platforms": "*",

library.properties

@@ -1,9 +1,9 @@
 name=HX711
-version=0.5.1
+version=0.5.2
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
-sentence=Arduino library for HX711 load cell amplifier
-paragraph=includes calibrate functions.
+sentence=Arduino library for HX711 load cell amplifier.
+paragraph=includes calibrate functions, reading median and median_average.
 category=Signal Input/Output
 url=https://github.com/RobTillaart/HX711
 architectures=*

test/unit_test_001.cpp

@@ -64,7 +64,7 @@ unittest(test_constructor)
   //  pins are default LOW apparently.
   assertTrue(scale.is_ready()); 
   //  default not read
-  assertEqual(0, scale.last_read());
+  assertEqual(0, scale.last_time_read());
 }