Add delay_time param to move

Allow for optional delay before the start of a move. Especially useful for sequences of moves where pauses  with no movement are desired between moves. Corresponding and general fixes to examples.

Author: pvanallen

README.md

@@ -3,7 +3,9 @@
 ## Description
 This Python library is descended from the VarspeedServo library (https://github.com/netlabtoolkit/VarSpeedServo), originally written for the Arduino in C++ (which was itself built on an early Arduino servo library). Unlike the old Arduino library, VarSpeedPython is not tied to servos, and can be used more generally for timed moves from one value to another. It is also **not** bound to any processor architecture with hardware interrupts etc.
 
-The library is designed for projects that need to control values over time. For example: setting the new angle of a servo in 1.5 seconds; setting the brightness of an LED by fading up; or moving a graphic on a screen. You can set the amount of time for a change in value, and apply easing to each move. It also provides a function for running sequences of moves (that can be looped or repeated if desired), where each move in the sequence has a new position and speed. More than one move or sequence can be run at the same time.
+The library is designed for projects that need to control values over time. For example: setting the new angle of a servo in 3.0 seconds; setting the brightness of an LED by fading up in 2.5 seconds; or moving a graphic on a screen. You can set the amount of time for a change in value, and apply easing to each move to make it seem more natural. 
+
+It also provides a function for running **sequences** of moves (that can be looped or repeated if desired), where each move in the sequence has a new position and speed. More than one move or sequence can be run at the same time.
 
 VarSpeedPython objects are designed to be called repeatedly from within an event loop and do not block execution.
 
@@ -25,11 +27,11 @@ VarSpeedPython objects are designed to be called repeatedly from within an event
 
 ## Circuit Python Setup
 
-To set up on CircuitPython:
+To set up on a CircuitPython hardware device:
 
-* Put varspeed.py in the lib directory on CIRCUITPY
-* Put easing_functions.py in the lib directory on CIRCUITPY
-* Copy the python from any of the examples into code.py at the top of CIRCUITPY
+* Put varspeed/varspeed.py in the **lib** directory on CIRCUITPY
+* Put varspeed/easing_functions.py in the **lib** directory on CIRCUITPY
+* Copy the python code from any of the examples/ into code.py or main.py at the top of CIRCUITPY
 
 ## Code Examples - non-CircuitPython
 
@@ -46,10 +48,10 @@ To set up on CircuitPython:
 
 ## Easing Types
 
-For any move (even within a sequence), you can set an easing function using the following classic Robert Penner easing types. For an animated and graphed visualization of each easing type, see https://easings.net. For an explanation of the use of easing, see this article: [Animation Principles in UI Design: Understanding Easing](https://medium.com/motion-in-interaction/animation-principles-in-ui-design-understanding-easing-bea05243fe3)
+For any move (even within a sequence), you can set an easing function using the following classic Robert Penner easing types. For an animated and graphed visualization of each easing type, see [https://easings.net](https://easings.net). For an explanation of the use of easing, see this article: [Animation Principles in UI Design: Understanding Easing](https://medium.com/motion-in-interaction/animation-principles-in-ui-design-understanding-easing-bea05243fe3)
 
 > [!WARNING]  
-> The names on https://easings.net do not reflect the names used in the `easing_functions.py` file. The names used in this project start with the type of easing used by the function (e.g Linear, Quad, Circular) followed by the word _Ease_ and finally whether it's "In", "Out" or "InOut". For example: the function listed on the website as _easeInOutCubic_  is called _CubicEaseInOut_ in this library. The reason behind this naming scheme is to be consistent with python classes naming conventions. The list with all easing functions with the correct names is listed here below.
+> The names on https://easings.net do not reflect the names used in the `easing_functions.py` file. The names used in this project start with the type of easing used by the function (e.g Linear, Quad, Circular) followed by the word _Ease_ and finally whether it's "In", "Out" or "InOut". For example: the function listed on the website as _easeInOutCubic_  is called _CubicEaseInOut_ in this library. The reason behind this naming scheme is to be consistent with python classes naming conventions. The list with all this library's easing functions with the correct names are listed below. Note also that the new gamma functions are not listed on the easings.net page
 
 * LinearInOut (essentially no easing)
 * QuadEaseInOut, QuadEaseIn, QuadEaseOut
@@ -62,6 +64,11 @@ For any move (even within a sequence), you can set an easing function using the
 * ElasticEaseIn, ElasticEaseOut, ElasticEaseInOut
 * BackEaseIn, BackEaseOut, BackEaseInOut
 * BounceEaseIn, BounceEaseOut, BounceEaseInOut
+* GammaEaseIn, GammaEaseOut, GammaEaseInOut
+
+
+* **NEW: GAMMA EASING** - provides gamma correction of 2.8 for dimming LEDs and other lighting to match human vision characteristics. **EXPLANATION** of gamma correction: https://www.advateklighting.com/blog/guides/dithering-and-gamma-correction
+
 
 ## CLASS: Vspeed
 ```python
@@ -92,7 +99,7 @@ Creates and initializes a Vspeed object.
 
 ## move
 ```python
-def move(self, new_position = 0, time_secs = 2.0, steps = 20, easing = "LinearInOut"):
+def move(self, new_position = 0, time_secs = 2.0, steps = 20, easing = "LinearInOut", delay_start = 0.0):
 ```
 
 ---
@@ -104,6 +111,7 @@ Generates a series of values that transition from the current position to a new_
 * **time_secs** (int) : time for the transition to the new_position
 * **steps** (int) : number of steps to change from the start position to the new_position
 * **easing** (string) : the easing function to use for the transition
+* **delay_start** (float) : the number of seconds to delay the start of the move - this helps when putting several moves together in a sequence so there can be pauses between moves
 
 ### Returns
 * **position** (int or float) : each new position, marked by changed being True
@@ -120,7 +128,7 @@ def sequence(self, sequence, loop_max = 1):
 Creates a series of values in a sequence of moves as specified in the sequence array.
 
 ### Args
-* **sequence** (array of tuples) : perform a sequence of moves (position,time,steps,easing) in the array.
+* **sequence** (array of tuples) : perform a sequence of moves (position,time,steps,easing,delay_start[optiona]) in the array.
 * **loop_max** (int) : how many times to loop the sequence, zero means loop forever.
 
 ### Returns

examples/move_simple.py

@@ -1,10 +1,8 @@
 # move_simple.py
 #
 # a non-hardware dependent example of using the VarSpeedPython class
-# to ramp a value from one value to another
+# to ramp a value from one level to another
 #
-import time
-
 from varspeed import Vspeed
 
 MIN = 0
@@ -15,6 +13,7 @@
 # init_position = initial start position
 # result = float, int
 # debug = False, True # set if varspeed will output debug info
+
 vs = Vspeed(init_position=MIN, result="int", debug=False)
 
 running = True

examples/move_simple_servo.py

@@ -1,8 +1,7 @@
 # move_simple_servo.py
 #
 # changes the position of a servo over time
-#
-import time
+
 import board
 import pwmio
 from adafruit_motor import servo
@@ -20,26 +19,35 @@
 # make the output of the function be within the MIN MAX bounds set
 vs.set_bounds(lower_bound=MIN, upper_bound=MAX)
 
-# create a PWMOut object on Pin D4
+# create a PWMOut object on Pin D13
 pwm = pwmio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=50)
 
 # Create a servo object
 my_servo = servo.Servo(pwm)
-
-print(f'Paused for 5 seconds at {MIN}...')
 # set the servo to a known starting point
 my_servo.angle = MIN
-time.sleep(5)
+print(f'Starting at position {MIN}, in 3 seconds starting move to {MAX}...')
 
-print(f'Moving to {MAX}...')
 running = True
 while running:
-    # move(new_position,time_secs of move,steps in move,easing function)
+    # move(new_position,time_secs of move,steps in move,easing function, delay_start in seconds)
     # for more into on easing, see: https://github.com/semitable/easing-functions
-    # for a visual repesentation of the easing options see: http://www.emix8.org/forum/viewtopic.php?t=1063
+    # for a visual repesentation of the easing options see: https://easings.net
     #
-    # move from the current position
+    # move from the current MIN position    
     position, running, changed = vs.move(
-        new_position=MAX, time_secs=2, steps=180, easing="CubicEaseInOut")
+        new_position=MAX, time_secs=2, steps=180, easing="ExponentialEaseInOut", delay_start=3.0)
     if changed:  # only act if the output changed
         my_servo.angle = position
+
+running = True
+while running:
+    # move(new_position,time_secs of move,steps in move,easing function, delay_start in seconds)
+    # for more into on easing, see: https://github.com/semitable/easing-functions
+    # for a visual repesentation of the easing options see: https://easings.net
+    #
+    # move from the current MIN position    
+    position, running, changed = vs.move(
+        new_position=MIN, time_secs=2, steps=180, easing="ExponentialEaseInOut", delay_start=3.0)
+    if changed:  # only act if the output changed
+        my_servo.angle = position

examples/sequence_simple.py

@@ -3,8 +3,6 @@
 # a non-hardware dependent example of using the VarSpeedPython class
 # to have a series of moves in a sequence
 #
-import time
-
 from varspeed import Vspeed
 
 MIN = 0.0

examples/sequence_simple_servo.py

@@ -29,9 +29,11 @@
 # set the servo to a known starting point
 my_servo.angle = MIN
 
-my_sequence = [(MAX / 2, 2.0, 100, "QuadEaseIn"),
-               (MIN, 2.0, 100, "QuadEaseOut"),
-               (MAX, 2.0, 100, "SineEaseInOut")]
+# note that these sequence moves may include a last delay_start parameter 
+my_sequence = [(MAX, 2.0, 100, "QuadEaseIn"), # missing delay_start parameter defaults to 0.0
+               (MIN, 2.0, 100, "QuadEaseOut",3), # waits 3 seconds to start
+               (MAX, 2.0, 100, "SineEaseInOut",2), # waits 2 seconds to start
+               ] 
 
 running = True
 while running:
@@ -44,10 +46,7 @@
     #         if 1, play once
     #         if >1, loop sequence that many times
     #
-    position, running, changed = vs.sequence(sequence=my_sequence, loop_max=2)
+    position, running, changed = vs.sequence(sequence=my_sequence, loop_max=1)
 
-    #print(position, running, changed)
     if changed:
-        # print(
-            # f'Sequence Num: {vs.seq_pos}, Step: {vs.step}, Position: {position}')
         my_servo.angle = position

examples/two_sequences_at_once.py

@@ -22,7 +22,7 @@
                 (MAX, 1.0, 10, "QuadEaseOut")]
 
 my_sequence2 = [(MAX, 1.0, 10, "QuadEaseOut"),
-                (MIN, 1.0, 10, "SineEaseInOut")]
+                (MIN, 1.0, 10, "QuadEaseIn")]
 
 running1 = True
 running2 = True
@@ -41,10 +41,10 @@
         sequence=my_sequence1, loop_max=2)
     if changed1:
         print(
-            f'Sequence 1 Num: {vs1.seq_pos}, Step: {vs1.step}, Position: {position1}')
+            f'Sequence 1 Move: {vs1.seq_pos}, Step: {vs1.step}, Position: {position1}')
 
     position2, running2, changed2 = vs2.sequence(
         sequence=my_sequence2, loop_max=2)
     if changed2:
         print(
-            f'Sequence 2 Num: {vs2.seq_pos}, Step: {vs2.step}, Position: {position2}')
+            f'Sequence 2 Move: {vs2.seq_pos}, Step: {vs2.step}, Position: {position2}')

examples/two_sequences_at_once_servo.py

@@ -2,14 +2,13 @@
 #
 # an example of how to use two sequences at the same time without blocking either one
 #
-import time
 import board
 import pwmio
 from adafruit_motor import servo
 from varspeed import Vspeed
 
-MIN = 20
-MAX = 180
+MIN = 15
+MAX = 165
 
 # create a PWMOut object on Pin D13
 pwm1 = pwmio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=50)
@@ -33,36 +32,37 @@
 
 # set the servo to a known starting point
 my_servo1.angle = vs1.position
+my_servo2.angle = vs2.position
 
-my_sequence1 = [(MIN, 1, 100, "QuadEaseIn"),
-                (MAX, 1, 100, "QuadEaseOut")]
+my_sequence1 = [(MIN, 1, 100, "QuadEaseIn",2),
+                (MAX, 1, 100, "QuadEaseIn",2)]
 
-my_sequence2 = [(MAX, 1, 100, "QuadEaseIn"),
-                (MIN, 1, 100, "QuadEaseOut")]
+my_sequence2 = [(MAX, 1, 100, "QuadEaseIn",2),
+                (MIN, 1, 100, "QuadEaseIn",2)]
 
 running1 = True
 running2 = True
 #print("starting  position",vs.position)
 while running1 and running2:
   # run a sequence of moves
   # sequence(sequence,loop,loop_max)
-  # sequence = moves in this format: (next-position,secs-to-move,number-of-steps,easing function)
-  #     example: [(90,5,10,LinearInOut),(0,8,10,QuadEaseInOut),(180,5,10,CubicEaseIn)]
+  # sequence = moves in this format: (next-position,secs-to-move,number-of-steps,easing function,delay_start)
+  #     example: [(90,5,10,LinearInOut,2),(0,8,10,QuadEaseInOut,2),(180,5,10,CubicEaseIn,2)]
   # loop_max = number of times to run the sequence in a loop
   #     if zero, loop forever
   #     if 1, play once
   #     if >1, loop sequence that many times
   #
     position1, running1, changed1 = vs1.sequence(
-        sequence=my_sequence1, loop_max=5)
+        sequence=my_sequence1, loop_max=3)
     if changed1:
-        print(
-            f'Sequence Num: {vs1.seq_pos}, Step: {vs1.step}, Position: {position1}')
+        #print(
+        #    f'Sequence Num: {vs1.seq_pos}, Step: {vs1.step}, Position: {position1}')
         my_servo1.angle = position1
 
     position2, running2, changed2 = vs2.sequence(
-        sequence=my_sequence2, loop_max=5)
+        sequence=my_sequence2, loop_max=3)
     if changed2:
-        print(
-            f'Sequence Num: {vs2.seq_pos}, Step: {vs2.step}, Position: {position2}')
+        #print(
+        #    f'Sequence Num: {vs2.seq_pos}, Step: {vs2.step}, Position: {position2}')
         my_servo2.angle = position2

varspeed/varspeed.py

@@ -11,6 +11,7 @@ def __init__(self, init_position = 0, result = "int", debug=False):
     Args:
         init_position (int/float): sets the initial position of the object.
         result (string = "int" or "float"): sets the type of the returned position.
+        # debug (boolean False or True # set if varspeed will output debug info
 
     Returns:
         object: returns a varspeed object
@@ -30,7 +31,6 @@ def __init__(self, init_position = 0, result = "int", debug=False):
     self.upper_bound = 1000
     self.lower_bound = 0
     self.last_reported_position = init_position
-    self.easing_correction = 1
     self.result = result
     self.step = 0
     self.increment_seq_num = True
@@ -41,14 +41,16 @@ def __init__(self, init_position = 0, result = "int", debug=False):
     self.seq_loop_count = 0
     self.debug = debug
 
-  def move(self, new_position = 0, time_secs = 2.0, steps = 20, easing = "LinearInOut"):
-    """Generates a series of values that transition from the current position to a new_position
+  def move(self, new_position = 0, time_secs = 2.0, steps = 20, easing = "LinearInOut", delay_start=0.0):
+    """MOVE: Generates a series of values that transition from the current position to a new_position,
+          with a delay at the start of the move
 
     Args:
         new_position (float): new position output will change to over time_secs
         time_secs (int): time for the transition to the new_position
         steps (int): number of steps to change from the start position to the new_position
         easing (string): the easing function to use for the transition
+        delay_start (float): the number of seconds to delay the start of the move
 
     Returns:
         position (int or float): each new position, marked by changed being True
@@ -57,9 +59,8 @@ def move(self, new_position = 0, time_secs = 2.0, steps = 20, easing = "LinearIn
 
     """
     if not self.started or new_position != self.new_position:
-      if (self.debug): ("new move")
+      if self.debug: print("new move")
       self.new_position = new_position
-      #self.last_position = self.position
       self.start_time = time.monotonic()
       self.end_time = self.start_time + time_secs
       self.step_delay = time_secs / steps
@@ -70,17 +71,22 @@ def move(self, new_position = 0, time_secs = 2.0, steps = 20, easing = "LinearIn
       self.easing = easing
       self.easing_method = getattr(ease, self.easing)
       self.ease = self.easing_method(start=self.position, end=self.new_position, duration=steps)
+      self.delay_start = delay_start
+      self.delay_start_complete = False
+      if self.debug: print("Delaying move by",self.delay_start,"secs")
 
     changed = False
     running = True
     self.started = True
 
-    #if self.new_position != self.position or self.end_time < time.monotonic():
     diff_time = time.monotonic() - self.start_time
-    if diff_time > self.step_delay:
+    if diff_time >= self.delay_start and self.delay_start_complete == False:
+      self.delay_start_complete = True
+    diff_time = time.monotonic() - self.start_time
+    if diff_time > self.step_delay and self.delay_start_complete:
       # time to change
       self.step += 1
-      # if (self.debug): print("new step " ,self.step,diff_time,self.step_delay)
+      # if self.debug: print("new step " ,self.step,diff_time,self.step_delay)
       self.start_time = time.monotonic()
       self.position = self.ease(self.step)
       # are we there yet?
@@ -93,7 +99,7 @@ def move(self, new_position = 0, time_secs = 2.0, steps = 20, easing = "LinearIn
     else:
       changed = True
 
-    # restrict the output to integer if needed
+    # restrict the output to integer if needed (e.g. for a servo)
     if self.result == "int":
       position = round(self.position)
 
@@ -112,10 +118,10 @@ def move(self, new_position = 0, time_secs = 2.0, steps = 20, easing = "LinearIn
     return self.position, running, changed
 
   def sequence(self, sequence, loop_max = 1):
-    """Creates a series of values in a sequence of moves as specified in the sequence array
+    """SEQUENCE: Creates a series of values in a sequence of moves as specified in the sequence array
 
     Args:
-        sequence (array of tuples): perform a sequence of moves (position,time,steps,easing) in the array
+        sequence (array of tuples): perform a sequence of moves (position,time,steps,easing,delay_start) in the array
         loop_max (int): how many time to loop the sequence, zero means loop forever
 
     Returns:
@@ -154,11 +160,17 @@ def sequence(self, sequence, loop_max = 1):
         if self.debug: print("START sequence move",self.seq_pos,sequence[self.seq_pos])
         self.increment_seq_num = False
 
+      # if this sequence does not include a delay_start value (5th element), append it to the tupple
+      if len(sequence[self.seq_pos]) < 5:
+        sequence[self.seq_pos] = sequence[self.seq_pos] + (0.0,)
+      # initiate the move
       position, running, changed = self.move(
         new_position=sequence[self.seq_pos][0],
         time_secs=sequence[self.seq_pos][1],
         steps=sequence[self.seq_pos][2],
-        easing=sequence[self.seq_pos][3])
+        easing=sequence[self.seq_pos][3],
+        delay_start=sequence[self.seq_pos][4],
+        )
 
       if not running: # finished with move
         self.increment_seq_num = True