AccelStepper
Public Member Functions | Protected Member Functions
AccelStepper Class Reference

Support for stepper motors with acceleration etc. More...

#include <AccelStepper.h>

List of all members.

Public Member Functions

 AccelStepper (uint8_t pins=4, uint8_t pin1=2, uint8_t pin2=3, uint8_t pin3=4, uint8_t pin4=5)
 AccelStepper (void(*forward)(), void(*backward)())
void moveTo (long absolute)
void move (long relative)
boolean run ()
boolean runSpeed ()
void setMaxSpeed (float speed)
void setAcceleration (float acceleration)
void setSpeed (float speed)
float speed ()
long distanceToGo ()
long targetPosition ()
long currentPosition ()
void setCurrentPosition (long position)
void runToPosition ()
boolean runSpeedToPosition ()
void runToNewPosition (long position)
void disableOutputs ()
void enableOutputs ()
void setMinPulseWidth (unsigned int minWidth)
void setEnablePin (uint8_t enablePin=0xff)
void setPinsInverted (bool direction, bool step, bool enable=false)

Protected Member Functions

void computeNewSpeed ()
virtual void step (uint8_t step)
virtual void step0 (void)
virtual void step1 (uint8_t step)
virtual void step2 (uint8_t step)
virtual void step4 (uint8_t step)
virtual void step8 (uint8_t step)
virtual float desiredSpeed ()

Detailed Description

Support for stepper motors with acceleration etc.

Tested on Arduino Diecimila and Mega with arduino-0018 & arduino-0021 on OpenSuSE 11.1 and avr-libc-1.6.1-1.15, cross-avr-binutils-2.19-9.1, cross-avr-gcc-4.1.3_20080612-26.5.

Installation
Install in the usual way: unzip the distribution zip file to the libraries sub-folder of your sketchbook.

This software is Copyright (C) 2010 Mike McCauley. Use is subject to license conditions. The main licensing options available are GPL V2 or Commercial:

Open Source Licensing GPL V2
This is the appropriate option if you want to share the source code of your application with everyone you distribute it to, and you also want to give them the right to share who uses it. If you wish to use this software under Open Source Licensing, you must contribute all your source code to the open source community in accordance with the GPL Version 2 when your application is distributed. See http://www.gnu.org/copyleft/gpl.html
Commercial Licensing
This is the appropriate option if you are creating proprietary applications and you are not prepared to distribute and share the source code of your application. Contact info@open.com.au for details.
Revision History
Version:
1.0 Initial release
1.1 Added speed() function to get the current speed.
1.2 Added runSpeedToPosition() submitted by Gunnar Arndt.
1.3 Added support for stepper drivers (ie with Step and Direction inputs) with _pins == 1
1.4 Added functional contructor to support AFMotor, contributed by Limor, with example sketches.
1.5 Improvements contributed by Peter Mousley: Use of microsecond steps and other speed improvements to increase max stepping speed to about 4kHz. New option for user to set the min allowed pulse width. Added checks for already running at max speed and skip further calcs if so.
1.6 Fixed a problem with wrapping of microsecond stepping that could cause stepping to hang. Reported by Sandy Noble. Removed redundant _lastRunTime member.
1.7 Fixed a bug where setCurrentPosition() did always work as expected. Reported by Peter Linhart. Reported by Sandy Noble. Removed redundant _lastRunTime member.
1.8 Added support for 4 pin half-steppers, requested by Harvey Moon
1.9 setCurrentPosition() now also sets motor speed to 0.
1.10 Builds on Arduino 1.0
1.11 Improvments from Michael Ellison: Added optional enable line support for stepper drivers Added inversion for step/direction/enable lines for stepper drivers
1.12 Announce Google Group
1.13 Improvements to speed calculation. Cost of calculation is now less in the worst case, and more or less constant in all cases. This should result in slightly beter high speed performance, and reduce anomalous speed glitches when other steppers are accelerating. However, its hard to see how to replace the sqrt() required at the very first step from 0 speed.
1.14 Fixed a problem with compiling under arduino 0021 reported by EmbeddedMan
1.15 Fixed a problem with runSpeedToPosition which did not correctly handle running backwards to a smaller target position. Added examples
Author:
Mike McCauley (mikem@open.com.au)

This defines a single 2 or 4 pin stepper motor, or stepper moter with fdriver chip, with optional acceleration, deceleration, absolute positioning commands etc. Multiple simultaneous steppers are supported, all moving at different speeds and accelerations.

Operation
This module operates by computing a step time in microseconds. The step time is recomputed after each step and after speed and acceleration parameters are changed by the caller. The time of each step is recorded in microseconds. The run() function steps the motor if a new step is due. The run() function must be called frequently until the motor is in the desired position, after which time run() will do nothing.
Positioning
Positions are specified by a signed long integer. At construction time, the current position of the motor is consider to be 0. Positive positions are clockwise from the initial position; negative positions are anticlockwise. The curent position can be altered for instance after initialization positioning.
Caveats
This is an open loop controller: If the motor stalls or is oversped, AccelStepper will not have a correct idea of where the motor really is (since there is no feedback of the motor's real position. We only know where we _think_ it is, relative to the initial starting point).

The fastest motor speed that can be reliably supported is 4000 steps per second (4 kHz) at a clock frequency of 16 MHz. However, any speed less than that down to very slow speeds (much less than one per second) are also supported, provided the run() function is called frequently enough to step the motor whenever required for the speed set.

Examples:

AFMotor_ConstantSpeed.pde, AFMotor_MultiStepper.pde, Blocking.pde, ConstantSpeed.pde, MultiStepper.pde, Overshoot.pde, and Random.pde.


Constructor & Destructor Documentation

AccelStepper::AccelStepper ( uint8_t  pins = 4,
uint8_t  pin1 = 2,
uint8_t  pin2 = 3,
uint8_t  pin3 = 4,
uint8_t  pin4 = 5 
)

Constructor. You can have multiple simultaneous steppers, all moving at different speeds and accelerations, provided you call their run() functions at frequent enough intervals. Current Position is set to 0, target position is set to 0. MaxSpeed and Acceleration default to 1.0. The motor pins will be initialised to OUTPUT mode during the constructor by a call to enableOutputs().

Parameters:
[in]pinsNumber of pins to interface to. 1, 2 or 4 are supported. 1 means a stepper driver (with Step and Direction pins). If an enable line is also needed, call setEnablePin() after construction. You may also invert the pins using setPinsInverted(). 2 means a 2 wire stepper. 4 means a 4 wire stepper. 8 means a 4 wire half stepper Defaults to 4 pins.
[in]pin1Arduino digital pin number for motor pin 1. Defaults to pin 2. For a driver (pins==1), this is the Step input to the driver. Low to high transition means to step)
[in]pin2Arduino digital pin number for motor pin 2. Defaults to pin 3. For a driver (pins==1), this is the Direction input the driver. High means forward.
[in]pin3Arduino digital pin number for motor pin 3. Defaults to pin 4.
[in]pin4Arduino digital pin number for motor pin 4. Defaults to pin 5.

References enableOutputs().

AccelStepper::AccelStepper ( void(*)()  forward,
void(*)()  backward 
)

Alternate Constructor which will call your own functions for forward and backward steps. You can have multiple simultaneous steppers, all moving at different speeds and accelerations, provided you call their run() functions at frequent enough intervals. Current Position is set to 0, target position is set to 0. MaxSpeed and Acceleration default to 1.0. Any motor initialization should happen before hand, no pins are used or initialized.

Parameters:
[in]forwardvoid-returning procedure that will make a forward step
[in]backwardvoid-returning procedure that will make a backward step

Member Function Documentation

void AccelStepper::computeNewSpeed ( ) [protected]

Forces the library to compute a new instantaneous speed and set that as the current speed. Calls desiredSpeed(), which can be overridden by subclasses. It is called by the library:

References desiredSpeed(), and setSpeed().

Referenced by moveTo(), run(), setAcceleration(), setCurrentPosition(), and setMaxSpeed().

long AccelStepper::currentPosition ( )

The currently motor position.

Returns:
the current motor position in steps. Positive is clockwise from the 0 position.
Examples:
MultiStepper.pde, and Overshoot.pde.
float AccelStepper::desiredSpeed ( ) [protected, virtual]

Compute and return the desired speed. The default algorithm uses maxSpeed, acceleration and the current speed to set a new speed to move the motor from teh current position to the target position. Subclasses may override this to provide an alternate algorithm (but do not block). Called by computeNewSpeed whenever a new speed neds to be computed.

References distanceToGo().

Referenced by computeNewSpeed().

void AccelStepper::disableOutputs ( )

Disable motor pin outputs by setting them all LOW Depending on the design of your electronics this may turn off the power to the motor coils, saving power. This is useful to support Arduino low power modes: disable the outputs during sleep and then reenable with enableOutputs() before stepping again.

long AccelStepper::distanceToGo ( )

The distance from the current position to the target position.

Returns:
the distance from the current position to the target position in steps. Positive is clockwise from the current position.
Examples:
MultiStepper.pde, and Random.pde.

Referenced by desiredSpeed().

void AccelStepper::enableOutputs ( )

Enable motor pin outputs by setting the motor pins to OUTPUT mode. Called automatically by the constructor.

Referenced by AccelStepper().

void AccelStepper::move ( long  relative)

Set the target position relative to the current position

Parameters:
[in]relativeThe desired position relative to the current position. Negative is anticlockwise from the current position.

References moveTo().

void AccelStepper::moveTo ( long  absolute)

Set the target position. The run() function will try to move the motor from the current position to the target position set by the most recent call to this function.

Parameters:
[in]absoluteThe desired absolute position. Negative is anticlockwise from the 0 position.
Examples:
MultiStepper.pde, Overshoot.pde, and Random.pde.

References computeNewSpeed().

Referenced by move(), and runToNewPosition().

boolean AccelStepper::run ( )

Poll the motor and step it if a step is due, implementing accelerations and decelerations to achive the ratget position. You must call this as fequently as possible, but at least once per minimum step interval, preferably in your main loop.

Returns:
true if the motor is at the target position.
Examples:
MultiStepper.pde, Overshoot.pde, and Random.pde.

References computeNewSpeed(), and runSpeed().

Referenced by runToPosition().

boolean AccelStepper::runSpeed ( )

Poll the motor and step it if a step is due, implmenting a constant speed as set by the most recent call to setSpeed().

Returns:
true if the motor was stepped.
Examples:
ConstantSpeed.pde.

References step().

Referenced by run(), and runSpeedToPosition().

boolean AccelStepper::runSpeedToPosition ( )

Runs at the currently selected speed until the target position is reached Does not implement accelerations.

Returns:
true if it stepped

References runSpeed().

void AccelStepper::runToNewPosition ( long  position)

Moves the motor to the new target position and blocks until it is at position. Dont use this in event loops, since it blocks.

Parameters:
[in]positionThe new target position.
Examples:
Blocking.pde, and Overshoot.pde.

References moveTo(), and runToPosition().

void AccelStepper::runToPosition ( )

Moves the motor at the currently selected constant speed (forward or reverse) to the target position and blocks until it is at position. Dont use this in event loops, since it blocks.

References run().

Referenced by runToNewPosition().

void AccelStepper::setAcceleration ( float  acceleration)

Sets the acceleration and deceleration parameter.

Parameters:
[in]accelerationThe desired acceleration in steps per second per second. Must be > 0.
Examples:
Blocking.pde, MultiStepper.pde, Overshoot.pde, and Random.pde.

References computeNewSpeed().

void AccelStepper::setCurrentPosition ( long  position)

Resets the current position of the motor, so that wherever the motor happens to be right now is considered to be the new 0 position. Useful for setting a zero position on a stepper after an initial hardware positioning move. Has the side effect of setting the current motor speed to 0.

Parameters:
[in]positionThe position in steps of wherever the motor happens to be right now.
Examples:
Overshoot.pde.

References computeNewSpeed().

void AccelStepper::setEnablePin ( uint8_t  enablePin = 0xff)

Sets the enable pin number for stepper drivers. 0xFF indicates unused (default). Otherwise, if a pin is set, the pin will be turned on when enableOutputs() is called and switched off when disableOutputs() is called.

Parameters:
[in]enablePinArduino digital pin number for motor enable
See also:
setPinsInverted
void AccelStepper::setMaxSpeed ( float  speed)

Sets the maximum permitted speed. the run() function will accelerate up to the speed set by this function.

Parameters:
[in]speedThe desired maximum speed in steps per second. Must be > 0. Speeds of more than 1000 steps per second are unreliable.
Examples:
Blocking.pde, ConstantSpeed.pde, MultiStepper.pde, Overshoot.pde, and Random.pde.

References computeNewSpeed(), and speed().

void AccelStepper::setMinPulseWidth ( unsigned int  minWidth)

Sets the minimum pulse width allowed by the stepper driver.

Parameters:
[in]minWidthThe minimum pulse width in microseconds.
void AccelStepper::setPinsInverted ( bool  direction,
bool  step,
bool  enable = false 
)

Sets the inversion for stepper driver pins

Parameters:
[in]directionTrue for inverted direction pin, false for non-inverted
[in]stepTrue for inverted step pin, false for non-inverted
[in]enableTrue for inverted enable pin, false (default) for non-inverted

References step().

void AccelStepper::setSpeed ( float  speed)

Sets the desired constant speed for use with runSpeed().

Parameters:
[in]speedThe desired constant speed in steps per second. Positive is clockwise. Speeds of more than 1000 steps per second are unreliable. Very slow speeds may be set (eg 0.00027777 for once per hour, approximately. Speed accuracy depends on the Arduino crystal. Jitter depends on how frequently you call the runSpeed() function.
Examples:
ConstantSpeed.pde.

References speed().

Referenced by computeNewSpeed().

float AccelStepper::speed ( )

The most recently set speed

Returns:
the most recent speed in steps per second

Referenced by setMaxSpeed(), and setSpeed().

void AccelStepper::step ( uint8_t  step) [protected, virtual]

Called to execute a step. Only called when a new step is required. Subclasses may override to implement new stepping interfaces. The default calls step1(), step2(), step4() or step8() depending on the number of pins defined for the stepper.

Parameters:
[in]stepThe current step phase number (0 to 7)

References step0(), step1(), step2(), step4(), and step8().

Referenced by runSpeed(), and setPinsInverted().

void AccelStepper::step0 ( void  ) [protected, virtual]

Called to execute a step using stepper functions (pins = 0) Only called when a new step is required. Calls _forward() or _backward() to perform the step

Referenced by step().

void AccelStepper::step1 ( uint8_t  step) [protected, virtual]

Called to execute a step on a stepper drover (ie where pins == 1). Only called when a new step is required. Subclasses may override to implement new stepping interfaces. The default sets or clears the outputs of Step pin1 to step, and sets the output of _pin2 to the desired direction. The Step pin (_pin1) is pulsed for 1 microsecond which is the minimum STEP pulse width for the 3967 driver.

Parameters:
[in]stepThe current step phase number (0 to 7)

Referenced by step().

void AccelStepper::step2 ( uint8_t  step) [protected, virtual]

Called to execute a step on a 2 pin motor. Only called when a new step is required. Subclasses may override to implement new stepping interfaces. The default sets or clears the outputs of pin1 and pin2

Parameters:
[in]stepThe current step phase number (0 to 7)

Referenced by step().

void AccelStepper::step4 ( uint8_t  step) [protected, virtual]

Called to execute a step on a 4 pin motor. Only called when a new step is required. Subclasses may override to implement new stepping interfaces. The default sets or clears the outputs of pin1, pin2, pin3, pin4.

Parameters:
[in]stepThe current step phase number (0 to 7)

Referenced by step().

void AccelStepper::step8 ( uint8_t  step) [protected, virtual]

Called to execute a step on a 4 pin half-steper motor. Only called when a new step is required. Subclasses may override to implement new stepping interfaces. The default sets or clears the outputs of pin1, pin2, pin3, pin4.

Parameters:
[in]stepThe current step phase number (0 to 7)

Referenced by step().

long AccelStepper::targetPosition ( )

The most recently set target position.

Returns:
the target position in steps. Positive is clockwise from the 0 position.

The documentation for this class was generated from the following files: