update to v.0.2.0: non-blocking moves

CheapStepper.h

@@ -58,7 +58,7 @@ class CheapStepper
 
 
 	// non-blocking versions of move()
-	// call update() in loop to keep moving
+	// call run() in loop to keep moving
 
 	void newMove (bool clockwise, int numSteps);
 	void newMoveTo (bool clockwise, int toStep);
@@ -91,7 +91,8 @@ class CheapStepper
 	int getPin(int p) { 
 		if (p<4) return pins[p]; // returns pin #
 		return 0; // default 0
-	} 
+	}
+	int getStepsLeft() { return stepsLeft; } // returns steps left in current move
 
 private:
 

examples/cheapStepper_move/cheapStepper_move.ino

@@ -1,70 +1,126 @@
-#include <CheapStepper.h>
+/*
+ * cheapStepper_move.ino
+ * ///////////////////////////////////////////
+ * using CheapStepper Arduino library v.0.2.0
+ * created by Tyler Henry, 7/2016
+ * ///////////////////////////////////////////
+ * 
+ * This sketch illustrates the library's
+ * "blocking" move functions -
+ * i.e. the move will "pause" the arduino sketch
+ * -- for non-blocking moves, see cheapStepper_newMoveTo.ino example
+ * 
+ * This sketch also shows how to set the RPM
+ * and shows a few different types of move functions
+ * - by steps or by degrees.
+ * 
+ * Blocking moves are useful if you need a specific RPM
+ * but don't need your arduino to perform other functions
+ * while the stepper is moving.
+ * 
+ * //////////////////////////////////////////////////////
+ */
+
+// first, include the library :)
 
-// this sketch shows how to set rpm
-// and shows a few different types of move functions - by steps or by degrees
+#include <CheapStepper.h>
 
+// next, declare the stepper
+// and connect pins 8,9,10,11 to IN1,IN2,IN3,IN4 on ULN2003 board
 
 CheapStepper stepper (8,9,10,11); 
-// declare your 28YBJ-48 stepper motor with ULN2003 driver board
-// on pins 8,9,10,11 -> IN1,IN2,IN3,IN4 on board
 
+ // let's create a boolean variable to save the direction of our rotation
+
+boolean moveClockwise = true;
 
-boolean moveClockwise;
 
 void setup() {
+
+  // let's set a custom speed of 20rpm (the default is ~16.25rpm)
 
   stepper.setRpm(20); 
-  // let's set a custom speed of 20rpm (the default is ~16.25rpm)
-  // accepted range: 6rpm (may overheat) - 24rpm (may skip)
-  // best range: 10rpm (safe, high torque) - 22rpm (fast, low torque)
+  /* Note: CheapStepper library assumes you are powering your 28BYJ-48 stepper
+   * using an external 5V power supply (>100mA) for RPM calculations
+   * -- don't try to power the stepper directly from the Arduino
+   * 
+   * accepted RPM range: 6RPM (may overheat) - 24RPM (may skip)
+   * ideal range: 10RPM (safe, high torque) - 22RPM (fast, low torque)
+   */
+
+  // now let's set up a serial connection and print some stepper info to the console
 
   Serial.begin(9600); Serial.println();
-  Serial.print("20 rpm = delay of ");
-  Serial.print(stepper.getDelay()); // get delay between steps for set rpm
+  Serial.print(stepper.getRpm()); // get the RPM of the stepper
+  Serial.print(" rpm = delay of ");
+  Serial.print(stepper.getDelay()); // get delay between steps for set RPM
   Serial.print(" microseconds between steps");
   Serial.println();
 
-  // void setTotalSteps(4076); // you can try this if you think your motor
-                               // is geared 63.68395:1 rather than 64:1
-                               // which would make the total steps 4076 (rather than default 4096)
-                               // see: http://forum.arduino.cc/index.php?topic=71964.15 for more info
+  // stepper.setTotalSteps(4076);
+  /* you can uncomment the above line if you think your motor
+   * is geared 63.68395:1 (measured) rather than 64:1 (advertised)
+   * which would make the total steps 4076 (rather than default 4096)
+   * for more info see: http://forum.arduino.cc/index.php?topic=71964.15
+   */
 }
 
 void loop() {
+
+    // let's do a clockwise move first
+
     moveClockwise = true;
+
+    // let's move the stepper clockwise to position 2048
+    // which is 180 degrees, a half-turn (if using default of 4096 total steps)
 
     stepper.moveTo (moveClockwise, 2048);
-    // move the stepper clockwise to position 2048 
-    // which is 180 degrees, a half-turn (if using default of 4096 total steps)
+
+    // now let's print the stepper position to the console
 
     Serial.print("step position: ");  
-    Serial.print(stepper.getStep()); // print the current step position to the console
+    Serial.print(stepper.getStep()); // get the current step position
     Serial.print(" / 4096");
     Serial.println();
-    delay(1000); // wait a sec
+
+    // now let's wait one second
 
+    delay(1000); // wait a sec
+
+    // and now let's move another 90 degrees (a quarter-turn) clockwise
 
     stepper.moveDegrees (moveClockwise, 90);
-    // move the stepper 90 degrees clockwise, a quarter-turn
-    // stepper.moveDegreesCW (90); <--- also works
+    // stepper.moveDegreesCW (90); <--- another way to do a clockwise 90 degree turn
+
+    // let's print the stepper position to the console again
 
     Serial.print("step position: ");
     Serial.print(stepper.getStep());
     Serial.print(" / 4096");
     Serial.println();
+
+    // and wait another second
+
     delay(1000);
+
+    // ok, now let's reverse directions (to counter-clockwise)
 
+    moveClockwise = false;
 
-    moveClockwise = false; // let's change directions
+    // and move back to the start position (0 degree)
 
-    stepper.moveToDegree (moveClockwise, 0); 
-    // moveClockwise is now false, so go counter-clockwise back to start (degree 0)
+    stepper.moveToDegree (moveClockwise, 0);
+    // moveClockwise is now false, so move counter-clockwise back to start
+
+    // let's print the position to the console once again
 
     Serial.print("step position: ");
     Serial.print(stepper.getStep());
     Serial.print(" / 4096");
     Serial.println();
-    delay(1000);
+
+    // and wait another second before starting loop() over
 
+    delay(1000);  
 }
 

examples/cheapStepper_simple/cheapStepper_simple.ino

@@ -1,42 +1,90 @@
+/*
+ * cheapStepper_simple.ino
+ * ///////////////////////////////////////////
+ * using CheapStepper Arduino library v.0.2.0
+ * created by Tyler Henry, 7/2016
+ * ///////////////////////////////////////////
+ * 
+ * this sketch illustrates basic step() functionality of the library:
+ * the stepper performs a full rotation, pauses 1 second,
+ * then does a full rotation in the other direction, and so on
+ * 
+ * //////////////////////////////////////////////////////
+ */
+
+// first, include the library :)
+
 #include <CheapStepper.h>
 
-// this sketch performs a full rotation, pauses 1 second, then does a full rotation in the other direction, and so on
 
 CheapStepper stepper;
-// declare your stepper using default pins:
+// here we declare our stepper using default pins:
 // arduino pin <--> pins on ULN2003 board:
 // 8 <--> IN1
 // 9 <--> IN2
 // 10 <--> IN3
 // 11 <--> IN4
 
+ // let's create a boolean variable to save the direction of our rotation
+
 boolean moveClockwise = true;
 
+
 void setup() {
+
+  // let's just set up a serial connection and test print to the console
+
   Serial.begin(9600);
+  Serial.println("Ready to start moving!");
 }
 
 void loop() {
+
+  // let's move a full rotation (4096 mini-steps)
+  // we'll go step-by-step using the step() function
 
   for (int s=0; s<4096; s++){
-    // loop 4096 times
-    // 4096 steps = full rotation (maybe 4076... depends on your exact gear ratio: http://forum.arduino.cc/index.php?topic=71964.15)
+    // this will loop 4096 times
+    // 4096 steps = full rotation using default values
+    /* Note:
+     * you could alternatively use 4076 steps... 
+     * if you think your 28BYJ-48 stepper's internal gear ratio is 63.68395:1 (measured) rather than 64:1 (advertised)
+     * for more info, see: http://forum.arduino.cc/index.php?topic=71964.15)
+     */
+
+    // let's move one "step" (of the 4096 per full rotation)
 
     stepper.step(moveClockwise);
-    // step once (direction based on moveClockwise boolean)
-    // note: you can also say stepper.stepCW(); or stepper.stepCCW();
+    /* the direction is based on moveClockwise boolean:
+     * true for clockwise, false for counter-clockwise
+     * -- you could also say stepper.stepCW(); or stepper.stepCCW();
+     */
+
+    // now let's get the current step position of motor
 
-    int nStep = stepper.getStep(); // get current step position of motor
+    int nStep = stepper.getStep();
+
+    // and if it's divisible by 64...
 
-    if (nStep%64==0){ // if it's divisible by 64...
-      Serial.print("step: ");
-      Serial.print(nStep); //... print to console
+    if (nStep%64==0){ 
+
+      // let's print the position to the console
+
+      Serial.print("current step position: "); Serial.print(nStep);
       Serial.println();
+
     }
   }
-  delay(1000); // wait a sec
+
+  // now we've moved 4096 steps
+
+  // let's wait one second
+
+  delay(1000);
+
+  // and switch directions before starting loop() again
 
-  moveClockwise = !moveClockwise; // switch directions
+  moveClockwise = !moveClockwise;
 }
 
 

keywords.txt

@@ -27,11 +27,28 @@ moveDegreesCW	KEYWORD2
 moveDegreesCCW	KEYWORD2
 moveToDegreeCW	KEYWORD2
 moveToDegreeCCW	KEYWORD2
+newMove			KEYWORD2
+newMoveTo		KEYWORD2
+newMoveDegrees	KEYWORD2
+newMoveToDegree	KEYWORD2
+run				KEYWORD2
+stop 			KEYWORD2
+newMoveCW		KEYWORD2
+newMoveCCW		KEYWORD2
+newMoveToCW		KEYWORD2
+newMoveToCCW	KEYWORD2
+newMoveDegreesCW	KEYWORD2
+newMoveDegreesCCW	KEYWORD2
+newMoveToDegreeCW	KEYWORD2
+newMoveToDegreeCCW	KEYWORD2
 step 			KEYWORD2
 stepCW			KEYWORD2
 stepCCW			KEYWORD2
 getStep			KEYWORD2
 getDelay		KEYWORD2
+getRpm			KEYWORD2
+getPin			KEYWORD2
+getStepsLeft	KEYWORD2
 
 #######################################
 # Constants (LITERAL1)

library.properties

@@ -1,9 +1,9 @@
 name=CheapStepper
-version=0.1
+version=0.2
 author=Tyler Henry
 maintainer=Tyler Henry <tyler@tylerhenry.com>
-sentence=A library for the cheap but decent 28BYJ-48 5v stepper motor with ULN2003 driver board
-paragraph=Early version currently only supports blocking motor control (e.g. uses delays & blocks loop)
+sentence=A library for the cheap but useful 28BYJ-48 5v stepper motor with ULN2003 driver board
+paragraph=Library uses half-stepping for fine control (default: 4096 mini-steps per rotation), and supports blocking and non-blocking moves. The total number of steps is also adjustable (e.g. 4076 steps for 63.68395:1 measured gear ratio).
 category=Device Control
 url=https://github.com/tyhenry/CheapStepper
 architectures=*