00001 // AccelStepper.h 00002 // 00003 /// \mainpage AccelStepper library for Arduino 00004 /// 00005 /// This is the Arduino AccelStepper library. 00006 /// It provides an object-oriented interface for 2 or 4 pin stepper motors. 00007 /// 00008 /// The standard Arduino IDE includes the Stepper library 00009 /// (http://arduino.cc/en/Reference/Stepper) for stepper motors. It is 00010 /// perfectly adequate for simple, single motor applications. 00011 /// 00012 /// AccelStepper significantly improves on the standard Arduino Stepper library in several ways: 00013 /// \li Supports acceleration and deceleration 00014 /// \li Supports multiple simultaneous steppers, with independent concurrent stepping on each stepper 00015 /// \li API functions never delay() or block 00016 /// \li Supports 2 and 4 wire steppers 00017 /// \li Supports alternate stepping functions to enable support of AFMotor (https://github.com/adafruit/Adafruit-Motor-Shield-library) 00018 /// \li Supports stepper drivers such as the Sparkfun EasyDriver (based on 3967 driver chip) 00019 /// \li Very slow speeds are supported 00020 /// \li Extensive API 00021 /// \li Subclass support 00022 /// 00023 /// The latest version of this documentation can be downloaded from 00024 /// http://www.open.com.au/mikem/arduino/AccelStepper 00025 /// 00026 /// Example Arduino programs are included to show the main modes of use. 00027 /// 00028 /// The version of the package that this documentation refers to can be downloaded 00029 /// from http://www.open.com.au/mikem/arduino/AccelStepper/AccelStepper-1.5.zip 00030 /// You can find the latest version at http://www.open.com.au/mikem/arduino/AccelStepper 00031 /// 00032 /// Tested on Arduino Diecimila and Mega with arduino-0018 & arduino-0021 00033 /// on OpenSuSE 11.1 and avr-libc-1.6.1-1.15, 00034 /// cross-avr-binutils-2.19-9.1, cross-avr-gcc-4.1.3_20080612-26.5. 00035 /// 00036 /// \par Installation 00037 /// Install in the usual way: unzip the distribution zip file to the libraries 00038 /// sub-folder of your sketchbook. 00039 /// 00040 /// This software is Copyright (C) 2010 Mike McCauley. Use is subject to license 00041 /// conditions. The main licensing options available are GPL V2 or Commercial: 00042 /// 00043 /// \par Open Source Licensing GPL V2 00044 /// This is the appropriate option if you want to share the source code of your 00045 /// application with everyone you distribute it to, and you also want to give them 00046 /// the right to share who uses it. If you wish to use this software under Open 00047 /// Source Licensing, you must contribute all your source code to the open source 00048 /// community in accordance with the GPL Version 2 when your application is 00049 /// distributed. See http://www.gnu.org/copyleft/gpl.html 00050 /// 00051 /// \par Commercial Licensing 00052 /// This is the appropriate option if you are creating proprietary applications 00053 /// and you are not prepared to distribute and share the source code of your 00054 /// application. Contact info@open.com.au for details. 00055 /// 00056 /// \par Revision History 00057 /// \version 1.0 Initial release 00058 /// 00059 /// \version 1.1 Added speed() function to get the current speed. 00060 /// \version 1.2 Added runSpeedToPosition() submitted by Gunnar Arndt. 00061 /// \version 1.3 Added support for stepper drivers (ie with Step and Direction inputs) with _pins == 1 00062 /// \version 1.4 Added functional contructor to support AFMotor, contributed by Limor, with example sketches. 00063 /// \version 1.5 Improvements contributed by Peter Mousley: Use of microsecond steps and other speed improvements 00064 /// to increase max stepping speed to about 4kHz. New option for user to set the min allowed pulse width. 00065 /// Added checks for already running at max speed and skip further calcs if so. 00066 /// 00067 /// 00068 /// \author Mike McCauley (mikem@open.com.au) 00069 // Copyright (C) 2009 Mike McCauley 00070 // $Id: AccelStepper.h,v 1.5 2011/03/21 00:42:15 mikem Exp mikem $ 00071 00072 #ifndef AccelStepper_h 00073 #define AccelStepper_h 00074 00075 #include <stdlib.h> 00076 #include <wiring.h> 00077 00078 // These defs cause trouble on some versions of Arduino 00079 #undef round 00080 00081 ///////////////////////////////////////////////////////////////////// 00082 /// \class AccelStepper AccelStepper.h <AccelStepper.h> 00083 /// \brief Support for stepper motors with acceleration etc. 00084 /// 00085 /// This defines a single 2 or 4 pin stepper motor, or stepper moter with fdriver chip, with optional 00086 /// acceleration, deceleration, absolute positioning commands etc. Multiple 00087 /// simultaneous steppers are supported, all moving 00088 /// at different speeds and accelerations. 00089 /// 00090 /// \par Operation 00091 /// This module operates by computing a step time in microseconds. The step 00092 /// time is recomputed after each step and after speed and acceleration 00093 /// parameters are changed by the caller. The time of each step is recorded in 00094 /// microseconds. The run() function steps the motor if a new step is due. 00095 /// The run() function must be called frequently until the motor is in the 00096 /// desired position, after which time run() will do nothing. 00097 /// 00098 /// \par Positioning 00099 /// Positions are specified by a signed long integer. At 00100 /// construction time, the current position of the motor is consider to be 0. Positive 00101 /// positions are clockwise from the initial position; negative positions are 00102 /// anticlockwise. The curent position can be altered for instance after 00103 /// initialization positioning. 00104 /// 00105 /// \par Caveats 00106 /// This is an open loop controller: If the motor stalls or is oversped, 00107 /// AccelStepper will not have a correct 00108 /// idea of where the motor really is (since there is no feedback of the motor's 00109 /// real position. We only know where we _think_ it is, relative to the 00110 /// initial starting point). 00111 /// 00112 /// The fastest motor speed that can be reliably supported is 4000 steps per 00113 /// second (4 kHz) at a clock frequency of 16 MHz. However, any speed less than that 00114 /// down to very slow speeds (much less than one per second) are also supported, 00115 /// provided the run() function is called frequently enough to step the motor 00116 /// whenever required for the speed set. 00117 class AccelStepper 00118 { 00119 public: 00120 /// Constructor. You can have multiple simultaneous steppers, all moving 00121 /// at different speeds and accelerations, provided you call their run() 00122 /// functions at frequent enough intervals. Current Position is set to 0, target 00123 /// position is set to 0. MaxSpeed and Acceleration default to 1.0. 00124 /// The motor pins will be initialised to OUTPUT mode during the 00125 /// constructor by a call to enableOutputs(). 00126 /// \param[in] pins Number of pins to interface to. 1, 2 or 4 are 00127 /// supported. 1 means a stepper driver (with Step and Direction pins) 00128 /// 2 means a 2 wire stepper. 4 means a 4 wire stepper. 00129 /// Defaults to 4 pins. 00130 /// \param[in] pin1 Arduino digital pin number for motor pin 1. Defaults 00131 /// to pin 2. For a driver (pins==1), this is the Step input to the driver. Low to high transition means to step) 00132 /// \param[in] pin2 Arduino digital pin number for motor pin 2. Defaults 00133 /// to pin 3. For a driver (pins==1), this is the Direction input the driver. High means forward. 00134 /// \param[in] pin3 Arduino digital pin number for motor pin 3. Defaults 00135 /// to pin 4. 00136 /// \param[in] pin4 Arduino digital pin number for motor pin 4. Defaults 00137 /// to pin 5. 00138 AccelStepper(uint8_t pins = 4, uint8_t pin1 = 2, uint8_t pin2 = 3, uint8_t pin3 = 4, uint8_t pin4 = 5); 00139 00140 /// Alternate Constructor which will call your own functions for forward and backward steps. 00141 /// You can have multiple simultaneous steppers, all moving 00142 /// at different speeds and accelerations, provided you call their run() 00143 /// functions at frequent enough intervals. Current Position is set to 0, target 00144 /// position is set to 0. MaxSpeed and Acceleration default to 1.0. 00145 /// Any motor initialization should happen before hand, no pins are used or initialized. 00146 /// \param[in] forward void-returning procedure that will make a forward step 00147 /// \param[in] backward void-returning procedure that will make a backward step 00148 AccelStepper(void (*forward)(), void (*backward)()); 00149 00150 /// Set the target position. The run() function will try to move the motor 00151 /// from the current position to the target position set by the most 00152 /// recent call to this function. 00153 /// \param[in] absolute The desired absolute position. Negative is 00154 /// anticlockwise from the 0 position. 00155 void moveTo(long absolute); 00156 00157 /// Set the target position relative to the current position 00158 /// \param[in] relative The desired position relative to the current position. Negative is 00159 /// anticlockwise from the current position. 00160 void move(long relative); 00161 00162 /// Poll the motor and step it if a step is due, implementing 00163 /// accelerations and decelerations to achive the ratget position. You must call this as 00164 /// fequently as possible, but at least once per minimum step interval, 00165 /// preferably in your main loop. 00166 /// \return true if the motor is at the target position. 00167 boolean run(); 00168 00169 /// Poll the motor and step it if a step is due, implmenting a constant 00170 /// speed as set by the most recent call to setSpeed(). 00171 /// \return true if the motor was stepped. 00172 boolean runSpeed(); 00173 00174 /// Sets the maximum permitted speed. the run() function will accelerate 00175 /// up to the speed set by this function. 00176 /// \param[in] speed The desired maximum speed in steps per second. Must 00177 /// be > 0. Speeds of more than 1000 steps per second are unreliable. 00178 void setMaxSpeed(float speed); 00179 00180 /// Sets the acceleration and deceleration parameter. 00181 /// \param[in] acceleration The desired acceleration in steps per second 00182 /// per second. Must be > 0. 00183 void setAcceleration(float acceleration); 00184 00185 /// Sets the desired constant speed for use with runSpeed(). 00186 /// \param[in] speed The desired constant speed in steps per 00187 /// second. Positive is clockwise. Speeds of more than 1000 steps per 00188 /// second are unreliable. Very slow speeds may be set (eg 0.00027777 for 00189 /// once per hour, approximately. Speed accuracy depends on the Arduino 00190 /// crystal. Jitter depends on how frequently you call the runSpeed() function. 00191 void setSpeed(float speed); 00192 00193 /// The most recently set speed 00194 /// \return the most recent speed in steps per second 00195 float speed(); 00196 00197 /// The distance from the current position to the target position. 00198 /// \return the distance from the current position to the target position 00199 /// in steps. Positive is clockwise from the current position. 00200 long distanceToGo(); 00201 00202 /// The most recently set target position. 00203 /// \return the target position 00204 /// in steps. Positive is clockwise from the 0 position. 00205 long targetPosition(); 00206 00207 00208 /// The currently motor position. 00209 /// \return the current motor position 00210 /// in steps. Positive is clockwise from the 0 position. 00211 long currentPosition(); 00212 00213 /// Resets the current position of the motor, so that wherever the mottor 00214 /// happens to be right now is considered to be the new position. Useful 00215 /// for setting a zero position on a stepper after an initial hardware 00216 /// positioning move. 00217 /// \param[in] position The position in steps of wherever the motor 00218 /// happens to be right now. 00219 void setCurrentPosition(long position); 00220 00221 /// Moves the motor to the target position and blocks until it is at 00222 /// position. Dont use this in event loops, since it blocks. 00223 void runToPosition(); 00224 00225 /// Runs at the currently selected speed until the target position is reached 00226 /// Does not implement accelerations. 00227 boolean runSpeedToPosition(); 00228 00229 /// Moves the motor to the new target position and blocks until it is at 00230 /// position. Dont use this in event loops, since it blocks. 00231 /// \param[in] position The new target position. 00232 void runToNewPosition(long position); 00233 00234 /// Disable motor pin outputs by setting them all LOW 00235 /// Depending on the design of your electronics this may turn off 00236 /// the power to the motor coils, saving power. 00237 /// This is useful to support Arduino low power modes: disable the outputs 00238 /// during sleep and then reenable with enableOutputs() before stepping 00239 /// again. 00240 void disableOutputs(); 00241 00242 /// Enable motor pin outputs by setting the motor pins to OUTPUT 00243 /// mode. Called automatically by the constructor. 00244 void enableOutputs(); 00245 00246 /// Sets the minimum pulse width allowed by the stepper driver. 00247 /// \param[in] minWidth The minimum pulse width in microseconds. 00248 void setMinPulseWidth(unsigned int minWidth); 00249 00250 protected: 00251 00252 /// Forces the library to compute a new instantaneous speed and set that as 00253 /// the current speed. Calls 00254 /// desiredSpeed(), which can be overridden by subclasses. It is called by 00255 /// the library: 00256 /// \li after each step 00257 /// \li after change to maxSpeed through setMaxSpeed() 00258 /// \li after change to acceleration through setAcceleration() 00259 /// \li after change to target position (relative or absolute) through 00260 /// move() or moveTo() 00261 void computeNewSpeed(); 00262 00263 /// Called to execute a step. Only called when a new step is 00264 /// required. Subclasses may override to implement new stepping 00265 /// interfaces. The default calls step1(), step2() or step4() depending on the 00266 /// number of pins defined for the stepper. 00267 /// \param[in] step The current step phase number (0 to 3) 00268 virtual void step(uint8_t step); 00269 00270 /// Called to execute a step using stepper functions (pins = 0) Only called when a new step is 00271 /// required. Calls _forward() or _backward() to perform the step 00272 virtual void step0(void); 00273 00274 /// Called to execute a step on a stepper drover (ie where pins == 1). Only called when a new step is 00275 /// required. Subclasses may override to implement new stepping 00276 /// interfaces. The default sets or clears the outputs of Step pin1 to step, 00277 /// and sets the output of _pin2 to the desired direction. The Step pin (_pin1) is pulsed for 1 microsecond 00278 /// which is the minimum STEP pulse width for the 3967 driver. 00279 /// \param[in] step The current step phase number (0 to 3) 00280 virtual void step1(uint8_t step); 00281 00282 /// Called to execute a step on a 2 pin motor. Only called when a new step is 00283 /// required. Subclasses may override to implement new stepping 00284 /// interfaces. The default sets or clears the outputs of pin1 and pin2 00285 /// \param[in] step The current step phase number (0 to 3) 00286 virtual void step2(uint8_t step); 00287 00288 /// Called to execute a step on a 4 pin motor. Only called when a new step is 00289 /// required. Subclasses may override to implement new stepping 00290 /// interfaces. The default sets or clears the outputs of pin1, pin2, 00291 /// pin3, pin4. 00292 /// \param[in] step The current step phase number (0 to 3) 00293 virtual void step4(uint8_t step); 00294 00295 /// Compute and return the desired speed. The default algorithm uses 00296 /// maxSpeed, acceleration and the current speed to set a new speed to 00297 /// move the motor from teh current position to the target 00298 /// position. Subclasses may override this to provide an alternate 00299 /// algorithm (but do not block). Called by computeNewSpeed whenever a new speed neds to be 00300 /// computed. 00301 virtual float desiredSpeed(); 00302 00303 private: 00304 /// Number of pins on the stepper motor. Permits 2 or 4. 2 pins is a 00305 /// bipolar, and 4 pins is a unipolar. 00306 uint8_t _pins; // 2 or 4 00307 00308 /// Arduino pin number for the 2 or 4 pins required to interface to the 00309 /// stepper motor. 00310 uint8_t _pin1, _pin2, _pin3, _pin4; 00311 00312 /// The current absolution position in steps. 00313 long _currentPos; // Steps 00314 00315 /// The target position in steps. The AccelStepper library will move the 00316 /// motor from teh _currentPos to the _targetPos, taking into account the 00317 /// max speed, acceleration and deceleration 00318 long _targetPos; // Steps 00319 00320 /// The current motos speed in steps per second 00321 /// Positive is clockwise 00322 float _speed; // Steps per second 00323 00324 /// The maximum permitted speed in steps per second. Must be > 0. 00325 float _maxSpeed; 00326 00327 /// The acceleration to use to accelerate or decelerate the motor in steps 00328 /// per second per second. Must be > 0 00329 float _acceleration; 00330 00331 /// The current interval between steps in microseconds 00332 unsigned long _stepInterval; 00333 00334 /// The last run time (when runSpeed() was last called) in microseconds 00335 unsigned long _lastRunTime; 00336 00337 /// The last step time in microseconds 00338 unsigned long _lastStepTime; 00339 00340 /// The minimum allowed pulse width in microseconds 00341 unsigned int _minPulseWidth; 00342 00343 // The pointer to a forward-step procedure 00344 void (*_forward)(); 00345 00346 // The pointer to a backward-step procedure 00347 void (*_backward)(); 00348 }; 00349 00350 #endif