AccelStepper.h

00001 // AccelStepper.h
00002 //
00003 /// \mainpage AccelStepper library for MBED
00004 ///
00005 /// This is the MBED AccelStepper library.
00006 /// It provides an object-oriented interface for 2, 3 or 4 pin stepper motors.
00007 /// Based on the Arduino AccelStepper library by Airspayce.com
00008 /// Translated for MBED by Jaap Vermaas <jaap@tuxic.nl>, 03-2015
00009 ///
00010 /// The standard Arduino IDE includes the Stepper library
00011 /// (http://arduino.cc/en/Reference/Stepper) for stepper motors. It is
00012 /// perfectly adequate for simple, single motor applications.
00013 ///
00014 /// AccelStepper significantly improves on the standard Arduino Stepper library in several ways:
00015 /// \li Supports acceleration and deceleration
00016 /// \li Supports multiple simultaneous steppers, with independent concurrent stepping on each stepper
00017 /// \li API functions never delay() or block
00018 /// \li Supports 2, 3 and 4 wire steppers, plus 3 and 4 wire half steppers.
00019 /// \li Supports alternate stepping functions to enable support of AFMotor (https://github.com/adafruit/Adafruit-Motor-Shield-library)
00020 /// \li Supports stepper drivers such as the Sparkfun EasyDriver (based on 3967 driver chip)
00021 /// \li Very slow speeds are supported
00022 /// \li Extensive API
00023 /// \li Subclass support
00024 ///
00025 /// The latest version of this documentation can be downloaded from 
00026 /// http://www.airspayce.com/mikem/arduino/AccelStepper
00027 /// The version of the package that this documentation refers to can be downloaded 
00028 /// from http://www.airspayce.com/mikem/arduino/AccelStepper/AccelStepper-1.47.zip
00029 ///
00030 /// Example Arduino programs are included to show the main modes of use.
00031 ///
00032 /// You can also find online help and discussion at http://groups.google.com/group/accelstepper
00033 /// Please use that group for all questions and discussions on this topic. 
00034 /// Do not contact the author directly, unless it is to discuss commercial licensing.
00035 /// Before asking a question or reporting a bug, please read http://www.catb.org/esr/faqs/smart-questions.html
00036 ///
00037 /// Tested on Arduino Diecimila and Mega with arduino-0018 & arduino-0021 
00038 /// on OpenSuSE 11.1 and avr-libc-1.6.1-1.15,
00039 /// cross-avr-binutils-2.19-9.1, cross-avr-gcc-4.1.3_20080612-26.5.
00040 /// Tested on Teensy http://www.pjrc.com/teensy including Teensy 3.1 built using Arduino IDE 1.0.5 with 
00041 /// teensyduino addon 1.18 and later.
00042 ///
00043 /// \par Installation
00044 ///
00045 /// Install in the usual way: unzip the distribution zip file to the libraries
00046 /// sub-folder of your sketchbook. 
00047 ///
00048 /// \par Theory
00049 ///
00050 /// This code uses speed calculations as described in 
00051 /// "Generate stepper-motor speed profiles in real time" by David Austin 
00052 /// http://fab.cba.mit.edu/classes/MIT/961.09/projects/i0/Stepper_Motor_Speed_Profile.pdf
00053 /// with the exception that AccelStepper uses steps per second rather than radians per second
00054 /// (because we dont know the step angle of the motor)
00055 /// An initial step interval is calculated for the first step, based on the desired acceleration
00056 /// On subsequent steps, shorter step intervals are calculated based 
00057 /// on the previous step until max speed is achieved.
00058 /// 
00059 /// \par Donations
00060 ///
00061 /// This library is offered under a free GPL license for those who want to use it that way. 
00062 /// We try hard to keep it up to date, fix bugs
00063 /// and to provide free support. If this library has helped you save time or money, please consider donating at
00064 /// http://www.airspayce.com or here:
00065 ///
00066 /// \htmlonly <form action="https://www.paypal.com/cgi-bin/webscr" method="post"><input type="hidden" name="cmd" value="_donations" /> <input type="hidden" name="business" value="mikem@airspayce.com" /> <input type="hidden" name="lc" value="AU" /> <input type="hidden" name="item_name" value="Airspayce" /> <input type="hidden" name="item_number" value="AccelStepper" /> <input type="hidden" name="currency_code" value="USD" /> <input type="hidden" name="bn" value="PP-DonationsBF:btn_donateCC_LG.gif:NonHosted" /> <input type="image" alt="PayPal — The safer, easier way to pay online." name="submit" src="https://www.paypalobjects.com/en_AU/i/btn/btn_donateCC_LG.gif" /> <img alt="" src="https://www.paypalobjects.com/en_AU/i/scr/pixel.gif" width="1" height="1" border="0" /></form> \endhtmlonly
00067 /// 
00068 /// \par Trademarks
00069 ///
00070 /// AccelStepper is a trademark of AirSpayce Pty Ltd. The AccelStepper mark was first used on April 26 2010 for
00071 /// international trade, and is used only in relation to motor control hardware and software.
00072 /// It is not to be confused with any other similar marks covering other goods and services.
00073 ///
00074 /// \par Copyright
00075 ///
00076 /// This software is Copyright (C) 2010 Mike McCauley. Use is subject to license
00077 /// conditions. The main licensing options available are GPL V2 or Commercial:
00078 ///
00079 /// \par Open Source Licensing GPL V2
00080 /// This is the appropriate option if you want to share the source code of your
00081 /// application with everyone you distribute it to, and you also want to give them
00082 /// the right to share who uses it. If you wish to use this software under Open
00083 /// Source Licensing, you must contribute all your source code to the open source
00084 /// community in accordance with the GPL Version 2 when your application is
00085 /// distributed. See http://www.gnu.org/copyleft/gpl.html
00086 /// 
00087 /// \par Commercial Licensing
00088 /// This is the appropriate option if you are creating proprietary applications
00089 /// and you are not prepared to distribute and share the source code of your
00090 /// application. Contact info@airspayce.com for details.
00091 ///
00092 /// \par Revision History
00093 /// \version 1.0 Initial release
00094 ///
00095 /// \version 1.1 Added speed() function to get the current speed.
00096 /// \version 1.2 Added runSpeedToPosition() submitted by Gunnar Arndt.
00097 /// \version 1.3 Added support for stepper drivers (ie with Step and Direction inputs) with _pins == 1
00098 /// \version 1.4 Added functional contructor to support AFMotor, contributed by Limor, with example sketches.
00099 /// \version 1.5 Improvements contributed by Peter Mousley: Use of microsecond steps and other speed improvements
00100 ///              to increase max stepping speed to about 4kHz. New option for user to set the min allowed pulse width.
00101 ///              Added checks for already running at max speed and skip further calcs if so. 
00102 /// \version 1.6 Fixed a problem with wrapping of microsecond stepping that could cause stepping to hang. 
00103 ///              Reported by Sandy Noble.
00104 ///              Removed redundant _lastRunTime member.
00105 /// \version 1.7 Fixed a bug where setCurrentPosition() did not always work as expected. 
00106 ///              Reported by Peter Linhart.
00107 /// \version 1.8 Added support for 4 pin half-steppers, requested by Harvey Moon
00108 /// \version 1.9 setCurrentPosition() now also sets motor speed to 0.
00109 /// \version 1.10 Builds on Arduino 1.0
00110 /// \version 1.11 Improvments from Michael Ellison:
00111 ///   Added optional enable line support for stepper drivers
00112 ///   Added inversion for step/direction/enable lines for stepper drivers
00113 /// \version 1.12 Announce Google Group
00114 /// \version 1.13 Improvements to speed calculation. Cost of calculation is now less in the worst case, 
00115 ///    and more or less constant in all cases. This should result in slightly beter high speed performance, and
00116 ///    reduce anomalous speed glitches when other steppers are accelerating. 
00117 ///    However, its hard to see how to replace the sqrt() required at the very first step from 0 speed.
00118 /// \version 1.14 Fixed a problem with compiling under arduino 0021 reported by EmbeddedMan
00119 /// \version 1.15 Fixed a problem with runSpeedToPosition which did not correctly handle
00120 ///    running backwards to a smaller target position. Added examples
00121 /// \version 1.16 Fixed some cases in the code where abs() was used instead of fabs().
00122 /// \version 1.17 Added example ProportionalControl
00123 /// \version 1.18 Fixed a problem: If one calls the funcion runSpeed() when Speed is zero, it makes steps 
00124 ///    without counting. reported by  Friedrich, Klappenbach.
00125 /// \version 1.19 Added MotorInterfaceType and symbolic names for the number of pins to use
00126 ///               for the motor interface. Updated examples to suit.
00127 ///               Replaced individual pin assignment variables _pin1, _pin2 etc with array _pin[4].
00128 ///               _pins member changed to _interface.
00129 ///               Added _pinInverted array to simplify pin inversion operations.
00130 ///               Added new function setOutputPins() which sets the motor output pins.
00131 ///               It can be overridden in order to provide, say, serial output instead of parallel output
00132 ///               Some refactoring and code size reduction.
00133 /// \version 1.20 Improved documentation and examples to show need for correctly
00134 ///               specifying AccelStepper::FULL4WIRE and friends.
00135 /// \version 1.21 Fixed a problem where desiredSpeed could compute the wrong step acceleration
00136 ///               when _speed was small but non-zero. Reported by Brian Schmalz.
00137 ///               Precompute sqrt_twoa to improve performance and max possible stepping speed
00138 /// \version 1.22 Added Bounce.pde example
00139 ///               Fixed a problem where calling moveTo(), setMaxSpeed(), setAcceleration() more 
00140 ///               frequently than the step time, even
00141 ///               with the same values, would interfere with speed calcs. Now a new speed is computed 
00142 ///               only if there was a change in the set value. Reported by Brian Schmalz.
00143 /// \version 1.23 Rewrite of the speed algorithms in line with 
00144 ///               http://fab.cba.mit.edu/classes/MIT/961.09/projects/i0/Stepper_Motor_Speed_Profile.pdf
00145 ///               Now expect smoother and more linear accelerations and decelerations. The desiredSpeed()
00146 ///               function was removed.
00147 /// \version 1.24  Fixed a problem introduced in 1.23: with runToPosition, which did never returned
00148 /// \version 1.25  Now ignore attempts to set acceleration to 0.0
00149 /// \version 1.26  Fixed a problem where certina combinations of speed and accelration could cause
00150 ///                oscillation about the target position.
00151 /// \version 1.27  Added stop() function to stop as fast as possible with current acceleration parameters.
00152 ///                Also added new Quickstop example showing its use.
00153 /// \version 1.28  Fixed another problem where certain combinations of speed and accelration could cause
00154 ///                oscillation about the target position.
00155 ///                Added support for 3 wire full and half steppers such as Hard Disk Drive spindle.
00156 ///                Contributed by Yuri Ivatchkovitch.
00157 /// \version 1.29  Fixed a problem that could cause a DRIVER stepper to continually step
00158 ///                with some sketches. Reported by Vadim.
00159 /// \version 1.30  Fixed a problem that could cause stepper to back up a few steps at the end of
00160 ///                accelerated travel with certain speeds. Reported and patched by jolo.
00161 /// \version 1.31  Updated author and distribution location details to airspayce.com
00162 /// \version 1.32  Fixed a problem with enableOutputs() and setEnablePin on Arduino Due that
00163 ///                prevented the enable pin changing stae correctly. Reported by Duane Bishop.
00164 /// \version 1.33  Fixed an error in example AFMotor_ConstantSpeed.pde did not setMaxSpeed();
00165 ///                Fixed a problem that caused incorrect pin sequencing of FULL3WIRE and HALF3WIRE.
00166 ///                Unfortunately this meant changing the signature for all step*() functions.
00167 ///                Added example MotorShield, showing how to use AdaFruit Motor Shield to control
00168 ///                a 3 phase motor such as a HDD spindle motor (and without using the AFMotor library.
00169 /// \version 1.34  Added setPinsInverted(bool pin1Invert, bool pin2Invert, bool pin3Invert, bool pin4Invert, bool enableInvert) 
00170 ///                to allow inversion of 2, 3 and 4 wire stepper pins. Requested by Oleg.
00171 /// \version 1.35  Removed default args from setPinsInverted(bool, bool, bool, bool, bool) to prevent ambiguity with 
00172 ///                setPinsInverted(bool, bool, bool). Reported by Mac Mac.
00173 /// \version 1.36  Changed enableOutputs() and disableOutputs() to be virtual so can be overridden.
00174 ///                Added new optional argument 'enable' to constructor, which allows you toi disable the 
00175 ///                automatic enabling of outputs at construction time. Suggested by Guido.
00176 /// \version 1.37  Fixed a problem with step1 that could cause a rogue step in the 
00177 ///                wrong direction (or not,
00178 ///                depending on the setup-time requirements of the connected hardware). 
00179 ///                Reported by Mark Tillotson.
00180 /// \version 1.38  run() function incorrectly always returned true. Updated function and doc so it returns true 
00181 ///                if the motor is still running to the target position.
00182 /// \version 1.39  Updated typos in keywords.txt, courtesey Jon Magill.
00183 /// \version 1.40  Updated documentation, including testing on Teensy 3.1
00184 /// \version 1.41  Fixed an error in the acceleration calculations, resulting in acceleration of haldf the intended value
00185 /// \version 1.42  Improved support for FULL3WIRE and HALF3WIRE output pins. These changes were in Yuri's original
00186 ///                contribution but did not make it into production.<br>
00187 /// \version 1.43  Added DualMotorShield example. Shows how to use AccelStepper to control 2 x 2 phase steppers using the 
00188 ///                Itead Studio Arduino Dual Stepper Motor Driver Shield model IM120417015.<br>
00189 /// \version 1.44  examples/DualMotorShield/DualMotorShield.ino examples/DualMotorShield/DualMotorShield.pde
00190 ///                was missing from the distribution.<br>
00191 /// \version 1.45  Fixed a problem where if setAcceleration was not called, there was no default
00192 ///                acceleration. Reported by Michael Newman.<br>
00193 /// \version 1.45  Fixed inaccuracy in acceleration rate by using Equation 15, suggested by Sebastian Gracki.<br>
00194 ///                Performance improvements in runSpeed suggested by Jaakko Fagerlund.<br>
00195 /// \version 1.46  Fixed error in documentation for runToPosition().
00196 ///                Reinstated time calculations in runSpeed() since new version is reported 
00197 ///                not to work correctly under some circumstances. Reported by Oleg V Gavva.<br>
00198 
00199 ///
00200 /// \author  Mike McCauley (mikem@airspayce.com) DO NOT CONTACT THE AUTHOR DIRECTLY: USE THE LISTS
00201 // Copyright (C) 2009-2013 Mike McCauley
00202 // $Id: AccelStepper.h,v 1.21 2014/10/31 06:05:30 mikem Exp mikem $
00203 
00204 #ifndef AccelStepper_h
00205 #define AccelStepper_h
00206 
00207 #include <stdlib.h>
00208 #include <mbed.h>
00209 #define max(a,b) (((a) > (b)) ? (a) : (b))
00210 #define constrain(amt,low,high) ((amt)<(low)?(low):((amt)>(high)?(high):(amt)))
00211 #define LOW false
00212 #define HIGH true
00213 //#if ARDUINO >= 100
00214 //#include <Arduino.h>
00215 //#else
00216 //#include <WProgram.h>
00217 //#include <wiring.h>
00218 //#endif
00219 
00220 // These defs cause trouble on some versions of Arduino
00221 #undef round
00222 
00223 /////////////////////////////////////////////////////////////////////
00224 /// \class AccelStepper AccelStepper.h <AccelStepper.h>
00225 /// \brief Support for stepper motors with acceleration etc.
00226 ///
00227 /// This defines a single 2 or 4 pin stepper motor, or stepper moter with fdriver chip, with optional
00228 /// acceleration, deceleration, absolute positioning commands etc. Multiple
00229 /// simultaneous steppers are supported, all moving 
00230 /// at different speeds and accelerations. 
00231 ///
00232 /// \par Operation
00233 /// This module operates by computing a step time in microseconds. The step
00234 /// time is recomputed after each step and after speed and acceleration
00235 /// parameters are changed by the caller. The time of each step is recorded in
00236 /// microseconds. The run() function steps the motor once if a new step is due.
00237 /// The run() function must be called frequently until the motor is in the
00238 /// desired position, after which time run() will do nothing.
00239 ///
00240 /// \par Positioning
00241 /// Positions are specified by a signed long integer. At
00242 /// construction time, the current position of the motor is consider to be 0. Positive
00243 /// positions are clockwise from the initial position; negative positions are
00244 /// anticlockwise. The current position can be altered for instance after
00245 /// initialization positioning.
00246 ///
00247 /// \par Caveats
00248 /// This is an open loop controller: If the motor stalls or is oversped,
00249 /// AccelStepper will not have a correct 
00250 /// idea of where the motor really is (since there is no feedback of the motor's
00251 /// real position. We only know where we _think_ it is, relative to the
00252 /// initial starting point).
00253 ///
00254 /// \par Performance
00255 /// The fastest motor speed that can be reliably supported is about 4000 steps per
00256 /// second at a clock frequency of 16 MHz on Arduino such as Uno etc. 
00257 /// Faster processors can support faster stepping speeds. 
00258 /// However, any speed less than that
00259 /// down to very slow speeds (much less than one per second) are also supported,
00260 /// provided the run() function is called frequently enough to step the motor
00261 /// whenever required for the speed set.
00262 /// Calling setAcceleration() is expensive,
00263 /// since it requires a square root to be calculated.
00264 class AccelStepper
00265 {
00266 public:
00267     /// \brief Symbolic names for number of pins.
00268     /// Use this in the pins argument the AccelStepper constructor to 
00269     /// provide a symbolic name for the number of pins
00270     /// to use.
00271     typedef enum
00272     {
00273     FUNCTION  = 0, ///< Use the functional interface, implementing your own driver functions (internal use only)
00274     DRIVER    = 1, ///< Stepper Driver, 2 driver pins required
00275     FULL2WIRE = 2, ///< 2 wire stepper, 2 motor pins required
00276     FULL3WIRE = 3, ///< 3 wire stepper, such as HDD spindle, 3 motor pins required
00277         FULL4WIRE = 4, ///< 4 wire full stepper, 4 motor pins required
00278     HALF3WIRE = 6, ///< 3 wire half stepper, such as HDD spindle, 3 motor pins required
00279     HALF4WIRE = 8  ///< 4 wire half stepper, 4 motor pins required
00280     } MotorInterfaceType;
00281 
00282     /// Constructor. You can have multiple simultaneous steppers, all moving
00283     /// at different speeds and accelerations, provided you call their run()
00284     /// functions at frequent enough intervals. Current Position is set to 0, target
00285     /// position is set to 0. MaxSpeed and Acceleration default to 1.0.
00286     /// The motor pins will be initialised to OUTPUT mode during the
00287     /// constructor by a call to enableOutputs().
00288     /// \param[in] interface Number of pins to interface to. 1, 2, 4 or 8 are
00289     /// supported, but it is preferred to use the \ref MotorInterfaceType symbolic names. 
00290     /// AccelStepper::DRIVER (1) means a stepper driver (with Step and Direction pins).
00291     /// If an enable line is also needed, call setEnablePin() after construction.
00292     /// You may also invert the pins using setPinsInverted().
00293     /// AccelStepper::FULL2WIRE (2) means a 2 wire stepper (2 pins required). 
00294     /// AccelStepper::FULL3WIRE (3) means a 3 wire stepper, such as HDD spindle (3 pins required). 
00295     /// AccelStepper::FULL4WIRE (4) means a 4 wire stepper (4 pins required). 
00296     /// AccelStepper::HALF3WIRE (6) means a 3 wire half stepper, such as HDD spindle (3 pins required)
00297     /// AccelStepper::HALF4WIRE (8) means a 4 wire half stepper (4 pins required)
00298     /// Defaults to AccelStepper::FULL4WIRE (4) pins.
00299     /// \param[in] pin1 Arduino digital pin number for motor pin 1. Defaults
00300     /// to pin 2. For a AccelStepper::DRIVER (interface==1), 
00301     /// this is the Step input to the driver. Low to high transition means to step)
00302     /// \param[in] pin2 Arduino digital pin number for motor pin 2. Defaults
00303     /// to pin 3. For a AccelStepper::DRIVER (interface==1), 
00304     /// this is the Direction input the driver. High means forward.
00305     /// \param[in] pin3 Arduino digital pin number for motor pin 3. Defaults
00306     /// to pin 4.
00307     /// \param[in] pin4 Arduino digital pin number for motor pin 4. Defaults
00308     /// to pin 5.
00309     /// \param[in] enable If this is true (the default), enableOutputs() will be called to enable
00310     /// the output pins at construction time.
00311     // AccelStepper(uint8_t interface = AccelStepper::FULL4WIRE, uint8_t pin1 = 2, uint8_t pin2 = 3, uint8_t pin3 = 4, uint8_t pin4 = 5, bool enable = true);
00312     AccelStepper(uint8_t interface, PinName pin1 = LED1, PinName pin2 = LED2, PinName pin3 = LED3, PinName pin4 = LED4, bool enable = true);
00313 
00314     /// Alternate Constructor which will call your own functions for forward and backward steps. 
00315     /// You can have multiple simultaneous steppers, all moving
00316     /// at different speeds and accelerations, provided you call their run()
00317     /// functions at frequent enough intervals. Current Position is set to 0, target
00318     /// position is set to 0. MaxSpeed and Acceleration default to 1.0.
00319     /// Any motor initialization should happen before hand, no pins are used or initialized.
00320     /// \param[in] forward void-returning procedure that will make a forward step
00321     /// \param[in] backward void-returning procedure that will make a backward step
00322     AccelStepper(void (*forward)(), void (*backward)());
00323     
00324     /// Set the target position. The run() function will try to move the motor (at most one step per call)
00325     /// from the current position to the target position set by the most
00326     /// recent call to this function. Caution: moveTo() also recalculates the speed for the next step. 
00327     /// If you are trying to use constant speed movements, you should call setSpeed() after calling moveTo().
00328     /// \param[in] absolute The desired absolute position. Negative is
00329     /// anticlockwise from the 0 position.
00330     void    moveTo(long absolute); 
00331 
00332     /// Set the target position relative to the current position
00333     /// \param[in] relative The desired position relative to the current position. Negative is
00334     /// anticlockwise from the current position.
00335     void    move(long relative);
00336 
00337     /// Poll the motor and step it if a step is due, implementing
00338     /// accelerations and decelerations to acheive the target position. You must call this as
00339     /// frequently as possible, but at least once per minimum step time interval,
00340     /// preferably in your main loop. Note that each call to run() will make at most one step, and then only when a step is due,
00341     /// based on the current speed and the time since the last step.
00342     /// \return true if the motor is still running to the target position.
00343     bool run();
00344 
00345     /// Poll the motor and step it if a step is due, implementing a constant
00346     /// speed as set by the most recent call to setSpeed(). You must call this as
00347     /// frequently as possible, but at least once per step interval,
00348     /// \return true if the motor was stepped.
00349     bool runSpeed();
00350 
00351     /// Sets the maximum permitted speed. The run() function will accelerate
00352     /// up to the speed set by this function.
00353     /// Caution: the maximum speed achievable depends on your processor and clock speed.
00354     /// \param[in] speed The desired maximum speed in steps per second. Must
00355     /// be > 0. Caution: Speeds that exceed the maximum speed supported by the processor may
00356     /// Result in non-linear accelerations and decelerations.
00357     void    setMaxSpeed(float speed);
00358 
00359     /// Sets the acceleration/deceleration rate.
00360     /// \param[in] acceleration The desired acceleration in steps per second
00361     /// per second. Must be > 0.0. This is an expensive call since it requires a square 
00362     /// root to be calculated. Dont call more ofthen than needed
00363     void    setAcceleration(float acceleration);
00364 
00365     /// Sets the desired constant speed for use with runSpeed().
00366     /// \param[in] speed The desired constant speed in steps per
00367     /// second. Positive is clockwise. Speeds of more than 1000 steps per
00368     /// second are unreliable. Very slow speeds may be set (eg 0.00027777 for
00369     /// once per hour, approximately. Speed accuracy depends on the Arduino
00370     /// crystal. Jitter depends on how frequently you call the runSpeed() function.
00371     void    setSpeed(float speed);
00372 
00373     /// The most recently set speed
00374     /// \return the most recent speed in steps per second
00375     float   speed();
00376 
00377     /// The distance from the current position to the target position.
00378     /// \return the distance from the current position to the target position
00379     /// in steps. Positive is clockwise from the current position.
00380     long    distanceToGo();
00381 
00382     /// The most recently set target position.
00383     /// \return the target position
00384     /// in steps. Positive is clockwise from the 0 position.
00385     long    targetPosition();
00386 
00387     /// The currently motor position.
00388     /// \return the current motor position
00389     /// in steps. Positive is clockwise from the 0 position.
00390     long    currentPosition();  
00391 
00392     /// Resets the current position of the motor, so that wherever the motor
00393     /// happens to be right now is considered to be the new 0 position. Useful
00394     /// for setting a zero position on a stepper after an initial hardware
00395     /// positioning move.
00396     /// Has the side effect of setting the current motor speed to 0.
00397     /// \param[in] position The position in steps of wherever the motor
00398     /// happens to be right now.
00399     void    setCurrentPosition(long position);  
00400     
00401     /// Moves the motor (with acceleration/deceleration) 
00402     /// to the target position and blocks until it is at
00403     /// position. Dont use this in event loops, since it blocks.
00404     void    runToPosition();
00405 
00406     /// Runs at the currently selected speed until the target position is reached
00407     /// Does not implement accelerations.
00408     /// \return true if it stepped
00409     bool runSpeedToPosition();
00410 
00411     /// Moves the motor (with acceleration/deceleration)
00412     /// to the new target position and blocks until it is at
00413     /// position. Dont use this in event loops, since it blocks.
00414     /// \param[in] position The new target position.
00415     void    runToNewPosition(long position);
00416 
00417     /// Sets a new target position that causes the stepper
00418     /// to stop as quickly as possible, using the current speed and acceleration parameters.
00419     void stop();
00420 
00421     /// Disable motor pin outputs by setting them all LOW
00422     /// Depending on the design of your electronics this may turn off
00423     /// the power to the motor coils, saving power.
00424     /// This is useful to support Arduino low power modes: disable the outputs
00425     /// during sleep and then reenable with enableOutputs() before stepping
00426     /// again.
00427     virtual void    disableOutputs();
00428 
00429     /// Enable motor pin outputs by setting the motor pins to OUTPUT
00430     /// mode. Called automatically by the constructor.
00431     virtual void    enableOutputs();
00432 
00433     /// Sets the minimum pulse width allowed by the stepper driver. The minimum practical pulse width is 
00434     /// approximately 20 microseconds. Times less than 20 microseconds
00435     /// will usually result in 20 microseconds or so.
00436     /// \param[in] minWidth The minimum pulse width in microseconds. 
00437     void    setMinPulseWidth(unsigned int minWidth);
00438 
00439     /// Sets the enable pin number for stepper drivers.
00440     /// 0xFF indicates unused (default).
00441     /// Otherwise, if a pin is set, the pin will be turned on when 
00442     /// enableOutputs() is called and switched off when disableOutputs() 
00443     /// is called.
00444     /// \param[in] enablePin Arduino digital pin number for motor enable
00445     /// \sa setPinsInverted
00446     void    setEnablePin(PinName enablePin);
00447 
00448     /// Sets the inversion for stepper driver pins
00449     /// \param[in] directionInvert True for inverted direction pin, false for non-inverted
00450     /// \param[in] stepInvert      True for inverted step pin, false for non-inverted
00451     /// \param[in] enableInvert    True for inverted enable pin, false (default) for non-inverted
00452     void    setPinsInverted(bool directionInvert = false, bool stepInvert = false, bool enableInvert = false);
00453 
00454     /// Sets the inversion for 2, 3 and 4 wire stepper pins
00455     /// \param[in] pin1Invert True for inverted pin1, false for non-inverted
00456     /// \param[in] pin2Invert True for inverted pin2, false for non-inverted
00457     /// \param[in] pin3Invert True for inverted pin3, false for non-inverted
00458     /// \param[in] pin4Invert True for inverted pin4, false for non-inverted
00459     /// \param[in] enableInvert    True for inverted enable pin, false (default) for non-inverted
00460     void    setPinsInverted(bool pin1Invert, bool pin2Invert, bool pin3Invert, bool pin4Invert, bool enableInvert);
00461 
00462 protected:
00463     DigitalOut *_pin0;
00464     DigitalOut *_pin1;
00465     DigitalOut *_pin2;
00466     DigitalOut *_pin3;
00467 
00468     /// \brief Direction indicator
00469     /// Symbolic names for the direction the motor is turning
00470     typedef enum
00471     {
00472     DIRECTION_CCW = 0,  ///< Clockwise
00473         DIRECTION_CW  = 1   ///< Counter-Clockwise
00474     } Direction;
00475 
00476     /// Forces the library to compute a new instantaneous speed and set that as
00477     /// the current speed. It is called by
00478     /// the library:
00479     /// \li  after each step
00480     /// \li  after change to maxSpeed through setMaxSpeed()
00481     /// \li  after change to acceleration through setAcceleration()
00482     /// \li  after change to target position (relative or absolute) through
00483     /// move() or moveTo()
00484     void           computeNewSpeed();
00485 
00486     /// Low level function to set the motor output pins
00487     /// bit 0 of the mask corresponds to _pin[0]
00488     /// bit 1 of the mask corresponds to _pin[1]
00489     /// You can override this to impment, for example serial chip output insted of using the
00490     /// output pins directly
00491     virtual void   setOutputPins(uint8_t mask);
00492 
00493     /// Called to execute a step. Only called when a new step is
00494     /// required. Subclasses may override to implement new stepping
00495     /// interfaces. The default calls step1(), step2(), step4() or step8() depending on the
00496     /// number of pins defined for the stepper.
00497     /// \param[in] step The current step phase number (0 to 7)
00498     virtual void   step(long step);
00499 
00500     /// Called to execute a step using stepper functions (pins = 0) Only called when a new step is
00501     /// required. Calls _forward() or _backward() to perform the step
00502     /// \param[in] step The current step phase number (0 to 7)
00503     virtual void   step0(long step);
00504 
00505     /// Called to execute a step on a stepper driver (ie where pins == 1). Only called when a new step is
00506     /// required. Subclasses may override to implement new stepping
00507     /// interfaces. The default sets or clears the outputs of Step pin1 to step, 
00508     /// and sets the output of _pin2 to the desired direction. The Step pin (_pin1) is pulsed for 1 microsecond
00509     /// which is the minimum STEP pulse width for the 3967 driver.
00510     /// \param[in] step The current step phase number (0 to 7)
00511     virtual void   step1(long step);
00512 
00513     /// Called to execute a step on a 2 pin motor. Only called when a new step is
00514     /// required. Subclasses may override to implement new stepping
00515     /// interfaces. The default sets or clears the outputs of pin1 and pin2
00516     /// \param[in] step The current step phase number (0 to 7)
00517     virtual void   step2(long step);
00518 
00519     /// Called to execute a step on a 3 pin motor, such as HDD spindle. Only called when a new step is
00520     /// required. Subclasses may override to implement new stepping
00521     /// interfaces. The default sets or clears the outputs of pin1, pin2,
00522     /// pin3
00523     /// \param[in] step The current step phase number (0 to 7)
00524     virtual void   step3(long step);
00525 
00526     /// Called to execute a step on a 4 pin motor. Only called when a new step is
00527     /// required. Subclasses may override to implement new stepping
00528     /// interfaces. The default sets or clears the outputs of pin1, pin2,
00529     /// pin3, pin4.
00530     /// \param[in] step The current step phase number (0 to 7)
00531     virtual void   step4(long step);
00532 
00533     /// Called to execute a step on a 3 pin motor, such as HDD spindle. Only called when a new step is
00534     /// required. Subclasses may override to implement new stepping
00535     /// interfaces. The default sets or clears the outputs of pin1, pin2,
00536     /// pin3
00537     /// \param[in] step The current step phase number (0 to 7)
00538     virtual void   step6(long step);
00539 
00540     /// Called to execute a step on a 4 pin half-steper motor. Only called when a new step is
00541     /// required. Subclasses may override to implement new stepping
00542     /// interfaces. The default sets or clears the outputs of pin1, pin2,
00543     /// pin3, pin4.
00544     /// \param[in] step The current step phase number (0 to 7)
00545     virtual void   step8(long step);
00546 
00547 private:
00548     /// Number of pins on the stepper motor. Permits 2 or 4. 2 pins is a
00549     /// bipolar, and 4 pins is a unipolar.
00550     uint8_t        _interface;          // 0, 1, 2, 4, 8, See MotorInterfaceType
00551 
00552     /// Arduino pin number assignments for the 2 or 4 pins required to interface to the
00553     /// stepper motor or driver
00554     uint8_t        _pin[4];
00555 
00556     /// Whether the _pins is inverted or not
00557     uint8_t        _pinInverted[4];
00558 
00559     /// The current absolution position in steps.
00560     long           _currentPos;    // Steps
00561 
00562     /// The target position in steps. The AccelStepper library will move the
00563     /// motor from the _currentPos to the _targetPos, taking into account the
00564     /// max speed, acceleration and deceleration
00565     long           _targetPos;     // Steps
00566 
00567     /// The current motos speed in steps per second
00568     /// Positive is clockwise
00569     float          _speed;         // Steps per second
00570 
00571     /// The maximum permitted speed in steps per second. Must be > 0.
00572     float          _maxSpeed;
00573 
00574     /// The acceleration to use to accelerate or decelerate the motor in steps
00575     /// per second per second. Must be > 0
00576     float          _acceleration;
00577     float          _sqrt_twoa; // Precomputed sqrt(2*_acceleration)
00578 
00579     /// The current interval between steps in microseconds.
00580     /// 0 means the motor is currently stopped with _speed == 0
00581     unsigned long  _stepInterval;
00582 
00583     /// The last step time in microseconds
00584     unsigned long  _lastStepTime;
00585 
00586     /// The minimum allowed pulse width in microseconds
00587     unsigned int   _minPulseWidth;
00588 
00589     /// Is the direction pin inverted?
00590     ///bool           _dirInverted; /// Moved to _pinInverted[1]
00591 
00592     /// Is the step pin inverted?
00593     ///bool           _stepInverted; /// Moved to _pinInverted[0]
00594 
00595     /// Is the enable pin inverted?
00596     bool           _enableInverted;
00597 
00598     /// Enable pin for stepper driver, or 0xFF if unused.
00599     //uint8_t        _enablePin;
00600     DigitalOut *_enablePin;
00601 
00602     /// The pointer to a forward-step procedure
00603     void (*_forward)();
00604 
00605     /// The pointer to a backward-step procedure
00606     void (*_backward)();
00607 
00608     /// The step counter for speed calculations
00609     long _n;
00610 
00611     /// Initial step size in microseconds
00612     float _c0;
00613 
00614     /// Last step size in microseconds
00615     float _cn;
00616 
00617     /// Min step size in microseconds based on maxSpeed
00618     float _cmin; // at max speed
00619 
00620     /// Current direction motor is spinning in
00621     bool _direction; // 1 == CW
00622 
00623 };
00624 
00625 /// @example Random.pde
00626 /// Make a single stepper perform random changes in speed, position and acceleration
00627 
00628 /// @example Overshoot.pde
00629 ///  Check overshoot handling
00630 /// which sets a new target position and then waits until the stepper has 
00631 /// achieved it. This is used for testing the handling of overshoots
00632 
00633 /// @example MultiStepper.pde
00634 /// Shows how to multiple simultaneous steppers
00635 /// Runs one stepper forwards and backwards, accelerating and decelerating
00636 /// at the limits. Runs other steppers at the same time
00637 
00638 /// @example ConstantSpeed.pde
00639 /// Shows how to run AccelStepper in the simplest,
00640 /// fixed speed mode with no accelerations
00641 
00642 /// @example Blocking.pde 
00643 /// Shows how to use the blocking call runToNewPosition
00644 /// Which sets a new target position and then waits until the stepper has 
00645 /// achieved it.
00646 
00647 /// @example AFMotor_MultiStepper.pde
00648 /// Control both Stepper motors at the same time with different speeds
00649 /// and accelerations. 
00650 
00651 /// @example AFMotor_ConstantSpeed.pde
00652 /// Shows how to run AccelStepper in the simplest,
00653 /// fixed speed mode with no accelerations
00654 
00655 /// @example ProportionalControl.pde
00656 /// Make a single stepper follow the analog value read from a pot or whatever
00657 /// The stepper will move at a constant speed to each newly set posiiton, 
00658 /// depending on the value of the pot.
00659 
00660 /// @example Bounce.pde
00661 /// Make a single stepper bounce from one limit to another, observing
00662 /// accelrations at each end of travel
00663 
00664 /// @example Quickstop.pde
00665 /// Check stop handling.
00666 /// Calls stop() while the stepper is travelling at full speed, causing
00667 /// the stepper to stop as quickly as possible, within the constraints of the
00668 /// current acceleration.
00669 
00670 /// @example MotorShield.pde
00671 /// Shows how to use AccelStepper to control a 3-phase motor, such as a HDD spindle motor
00672 /// using the Adafruit Motor Shield http://www.ladyada.net/make/mshield/index.html.
00673 
00674 /// @example DualMotorShield.pde
00675 /// Shows how to use AccelStepper to control 2 x 2 phase steppers using the 
00676 /// Itead Studio Arduino Dual Stepper Motor Driver Shield
00677 /// model IM120417015
00678 
00679 #endif 
00680