develop (#2)

* initial release
* refactor + examples

CHANGELOG.md

@@ -6,11 +6,24 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.1.1] - 2022-10-14
+
+- add parameter to begin(float percentage)
+- refactored stop()
+- refactored setPercentage()
+- remapped the 0-100% to 2000-2500 microseconds of servo as
+  the full 1600-2500 range was only active above 50~60%
+  depending on the voltage used.
+- add forward(), backward() + example.
+- add setInvert(flag = false)
+- updated readme.md
+
+
 ## [0.1.0] - 2022-10-13
 
 - initial version
-- add stop(), get- and setpercentage()
+- add stop(), get- and setPercentage()
 - add getSeconds(), resetSeconds() for simple duration management.
-- low percentages < 50% do not work.
+- **low percentages < 50% do not work.**
 
 

PERIPUMP.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: PERIPUMP.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 //    DATE: 2022-10-13
 // PURPOSE: Arduino library for peristaltic pump
 
@@ -18,54 +18,63 @@ PERIPUMP::PERIPUMP(uint8_t pumpPin)
 }
 
 
-void PERIPUMP::begin()
+void PERIPUMP::begin(float percentage)
 {
   _myServo.attach(_pin);
-  stop();
   resetRunTime();
+  setPercentage(percentage);
 }
 
 
 void PERIPUMP::stop()
 {
-  _myServo.writeMicroseconds(1500);
-  if (_start != 0)
-  {
-    _sumTime += (millis() - _start);
-    _start = 0;
-  }
+  setPercentage(0);
+}
+
+
+void PERIPUMP::forward()
+{
+  setPercentage(100);
+}
+
+
+void PERIPUMP::backward()
+{
+  setPercentage(-100);
 }
 
 
+//  the worker.
 void PERIPUMP::setPercentage(float percentage)
 {
   //  weighted runtime ?
   //  _sumTime += (millis() - _start) * abs(_percentage);
-  _percentage = constrain(percentage, -100, 100);
+
+  _percentage = constrain(percentage, -100.0, 100.0);
+
+  uint32_t now = millis();
 
   uint16_t ms = 0;
   if (_percentage == 0)
   {
-    ms = 1500;
-    if (_start != 0)
-    {
-      _sumTime += (millis() - _start);
-      _start = 0;
-    }
+    if (_start != 0) _sumTime += (now - _start);
+    //  middle position is stop
+    ms = 0;
+    _start = 0;
   }
   else if (_percentage > 0)
   {
-    //  1600 - 2500
-    ms = 1600 + 9 * _percentage;         //  9 ==  900 / 100%
-    if (_start == 0) _start = millis();
+    ms = 500 + 5 * _percentage;
+    if (_start == 0) _start = now;
   }
   else if (_percentage < 0)
   {
-    //  500 - 1400
-    ms = 1400 + 9 * _percentage;
-    if (_start == 0) _start = millis();
+    ms = -500 + 5 * _percentage;
+    if (_start == 0) _start = now;
   }
-  _myServo.writeMicroseconds(ms);
+
+  if (_invert) _myServo.writeMicroseconds(1500 - ms);
+  else _myServo.writeMicroseconds(1500 + ms);
 }
 
 
@@ -75,6 +84,19 @@ float PERIPUMP::getPercentage()
 }
 
 
+void PERIPUMP::setInvert(bool flag)
+{
+  _invert = flag;
+}
+
+
+bool PERIPUMP::getInvert()
+{
+  return _invert;
+}
+
+
+
 //////////////////////////////////////////////////////
 //
 //  DURATION

PERIPUMP.h

@@ -2,7 +2,7 @@
 //
 //    FILE: PERIPUMP.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 //    DATE: 2022-10-13
 // PURPOSE: Arduino library for peristaltic pump
 //
@@ -13,24 +13,34 @@
 #include "Arduino.h"
 #include "Servo.h"
 
-#define PERIPUMP_LIB_VERSION        (F("0.1.0"))
+#define PERIPUMP_LIB_VERSION                  (F("0.1.1"))
 
 
 class PERIPUMP
 {
 public:
   PERIPUMP(uint8_t pumpPin);
 
-  void     begin();
+  void     begin(float percentage = 0);
 
   //////////////////////////////////////////////////////
   //
   //  RUNNING
   //
   void     stop();
+  //  For 100% speed
+  void     forward();
+  void     backward();
+  //  Fine tuning speed
   void     setPercentage(float percentage);
   float    getPercentage();
 
+  //  EXPERIMENTAL / TEST
+  //  flag to swap forward and backward in software if needed.
+  //       easier than doing it hardware way
+  void     setInvert(bool flag = false);
+  bool     getInvert();
+
   //////////////////////////////////////////////////////
   //
   //  DURATION
@@ -45,6 +55,7 @@ class PERIPUMP
   Servo    _myServo;
   uint32_t _sumTime = 0;
   uint32_t _start   = 0;
+  bool     _invert = false;
 };
 
 

README.md

@@ -21,13 +21,20 @@ To hide the details of the Servo library and provide an easy to use interface,
 this PERIPUMP library gives control by setting the speed of the pump as a percentage
 ranging from -100.0% .. 100.0%. 
 
-The Servo library allows 900 steps for 0..100% so in theory the precision is 
+The Servo library allows 900 steps for 0..100% so **in theory** the precision is 
 approximately around 1 decimal.
-In my first tests however with a 5Volt lab power supply, the pump only started 
-to run around 60% at 5 volt and around 50% at 6 volt. 
-Not measured if the behaviour was linear for the remaining 50%.
+In my first tests however with a 5 volt lab power supply, the pump only started 
+to run around 60% at 5 volt and around 50% at 6 volt.
+Since 0.1.1 the mapping from 0..100% is done on the upper 500 steps of the servo,
+to get the pump moving at lower percentages. This gives a practical precision of
+around 0.2 % which is still very nice. 
+Although there might still be low percentages that does not work on 5V, they might 
+work on 6V, or when one goes from full speed to lower speed. (momentum differs).
+At least there will be a larger "active range" for the percentages.
 
-This implies that the actual flow depends on BOTH the voltage used and the percentage set.
+Not measured if the behaviour is linear.
+
+The actual flow depends on BOTH the voltage used and the percentage set.
 
 The library provides also a minimalistic time registration. 
 It measures how long the pump has been running since the start of the sketch or 
@@ -43,7 +50,7 @@ Feedback on the library is welcome.
 
 ## Hardware schema
 
-In my first tests the DFR0523 pump drew a current between 330 -360 mA at full speed.
+In my first tests the DFR0523 pump drew a current between 330 -360 mA (5V) at full speed.
 This implies an external power supply of 5 (or 6) volts is mandatory.
 
 ```
@@ -62,17 +69,28 @@ This implies an external power supply of 5 (or 6) volts is mandatory.
 ### Base
 
 - **PERIPUMP(uint8_t pumpPin)** constructor. pumpPin should be a PWM supporting pin.
-- **void begin()** initialize the internal variables.
+- **void begin(float percentage = 0)** initialize the internal variables.
+Default percentage = 0% == stop.
 - **void stop()** set speed percentage to zero, effectively stop the pump.
 Also stops the run time measurement counter.
+- **void forward()** 100% forward.
+- **void backward()** 100% backward.
 - **void setPercentage(float percentage)** sets speed as a percentage of the full speed.
-The range goes from -100.0 % .. +100.0 %.
+  - The percentage goes from -100.0 % .. +100.0 %.
   - If percentage == 0, the pump stops. 
   - Negative values set the pump in reverse.
   - Positive values set the pump in forward mode.
+  - low values might not work.
 - **float getPercentage()** returns set speed: -100.0 % .. +100.0 %.
 
 
+### Invert (experimental / test)
+
+- **void setInvert(bool flag = false)** inverts forward and backward to
+easy swap direction without rebuilding hardware setup.
+Default = false.
+- **bool getInvert()** returns value invert flag.
+
 ### RunTime
 
 - **float getRunTime()** returns total seconds running since last reset / start.
@@ -85,19 +103,15 @@ Resets the internal time counter to zero again.
 The examples show the basic working of the functions.
 
 
-#### 0.1.0 release
-
-- low percentages < 50% do not work.
-
-
 ## Future
 
 #### Must (next release)
 
-- investigate a possible solution for the **lower 50% problem**.
-  - map the range 1-100% only on the top 500 steps of the underlying Servo lib.
-- initial speed as parameter for **begin()**
-  - default percentage == 0 ?
+- investigate calibration process
+  - function to set the ranges for percentage.
+  - four values needed  500-VAR1    VAR2-2500
+  - defaults for these variables.
+  - could that be command line #defines?
 
 
 #### Should
@@ -115,9 +129,6 @@ The examples show the basic working of the functions.
   - add **void setVolumePerSecond(float flow)** indication cm^3 / sec
   - at full speed only?
   - linear / non linear interpolatable (multiMap).
-- investigate calibration process.
-- add **void forward()** **void reverse()**
-- add **void setInvert(bool true)** (if pump is connected reverse it would be easy to fix in software.
 
 
 #### Won't (for now lowest prio)
@@ -127,7 +138,8 @@ The examples show the basic working of the functions.
   - compilation of examples works for UNO and RP2040 pico.
 - add **void pump_ml(int ml)**  auto stop after X ml? possible?
 - investigate difference per pump (one pump behaves different enough)
+  - calibration might solve this.
 - investigate flow-accounting?
   - sum += time x speed - is that better?
   - two counters needed, one per direction
-
+- **incr()** and **decr()** as they are direction dependant.

examples/peripump_forward_backward/peripump_forward_backward.ino

@@ -0,0 +1,65 @@
+//
+//    FILE: peripump_forward_backward.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo
+//     URL: https://github.com/RobTillaart/PERIPUMP.git
+//
+
+
+#include "PERIPUMP.h"
+
+PERIPUMP pump(5);
+
+
+//  add switches between pin and GND.
+const int STOP_PIN     = 2;
+const int FORWARD_PIN  = 3;
+const int BACKWARD_PIN = 4;
+
+//  prevent sudden reversal.
+int mode = 0; // 0 == stop,  1 == forward,  -1 == backward
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("PERIPUMP_LIB_VERSION: ");
+  Serial.println(PERIPUMP_LIB_VERSION);
+
+  pinMode(STOP_PIN, INPUT_PULLUP);
+  pinMode(FORWARD_PIN, INPUT_PULLUP);
+  pinMode(BACKWARD_PIN, INPUT_PULLUP);
+
+  pump.begin();
+}
+
+
+void loop()
+{
+  if (digitalRead(STOP_PIN) == LOW)
+  {
+    pump.stop();
+    mode = 0;
+  }
+  if (digitalRead(FORWARD_PIN) == LOW)
+  {
+    // prevent sudden reversal
+    if (mode == 1) pump.forward();
+    else pump.stop();
+    mode = 1;
+  }
+  if (digitalRead(BACKWARD_PIN) == LOW)
+  {
+    // prevent sudden reversal
+    if (mode == -1) pump.backward();
+    else pump.stop();
+    mode = -1;
+  }
+
+  //  debounce etc
+  delay(100);
+}
+
+
+//  -- END OF FILE --