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

#include <AccelStepper.h>

Public Types
enum	MotorInterfaceType { FUNCTION = 0, DRIVER = 1, FULL2WIRE = 2, FULL3WIRE = 3, FULL4WIRE = 4, HALF3WIRE = 6, HALF4WIRE = 8 }
	Symbolic names for number of pins. More...
Public Member Functions
	AccelStepper (uint8_t interface, PinName pin1=LED1, PinName pin2=LED2, PinName pin3=LED3, PinName pin4=LED4, bool enable=true)
	Constructor.
	AccelStepper (void(forward)(), void(backward)())
	Alternate Constructor which will call your own functions for forward and backward steps.
void	moveTo (long absolute)
	Set the target position.
void	move (long relative)
	Set the target position relative to the current position.
bool	run ()
	Poll the motor and step it if a step is due, implementing accelerations and decelerations to acheive the target position.
bool	runSpeed ()
	Poll the motor and step it if a step is due, implementing a constant speed as set by the most recent call to setSpeed().
void	setMaxSpeed (float speed)
	Sets the maximum permitted speed.
void	setAcceleration (float acceleration)
	Sets the acceleration/deceleration rate.
void	setSpeed (float speed)
	Sets the desired constant speed for use with runSpeed().
float	speed ()
	The most recently set speed.
long	distanceToGo ()
	The distance from the current position to the target position.
long	targetPosition ()
	The most recently set target position.
long	currentPosition ()
	The currently motor position.
void	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.
void	runToPosition ()
	Moves the motor (with acceleration/deceleration) to the target position and blocks until it is at position.
bool	runSpeedToPosition ()
	Runs at the currently selected speed until the target position is reached Does not implement accelerations.
void	runToNewPosition (long position)
	Moves the motor (with acceleration/deceleration) to the new target position and blocks until it is at position.
void	stop ()
	Sets a new target position that causes the stepper to stop as quickly as possible, using the current speed and acceleration parameters.
virtual void	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.
virtual void	enableOutputs ()
	Enable motor pin outputs by setting the motor pins to OUTPUT mode.
void	setMinPulseWidth (unsigned int minWidth)
	Sets the minimum pulse width allowed by the stepper driver.
void	setEnablePin (PinName enablePin)
	Sets the enable pin number for stepper drivers.
void	setPinsInverted (bool directionInvert=false, bool stepInvert=false, bool enableInvert=false)
	Sets the inversion for stepper driver pins.
void	setPinsInverted (bool pin1Invert, bool pin2Invert, bool pin3Invert, bool pin4Invert, bool enableInvert)
	Sets the inversion for 2, 3 and 4 wire stepper pins.
Protected Types
enum	Direction { DIRECTION_CCW = 0, DIRECTION_CW = 1 }
	Direction indicator Symbolic names for the direction the motor is turning. More...
Protected Member Functions
void	computeNewSpeed ()
	Forces the library to compute a new instantaneous speed and set that as the current speed.
virtual void	setOutputPins (uint8_t mask)
	Low level function to set the motor output pins bit 0 of the mask corresponds to _pin[0] bit 1 of the mask corresponds to _pin[1] You can override this to impment, for example serial chip output insted of using the output pins directly.
virtual void	step (long step)
	Called to execute a step.
virtual void	step0 (long step)
	Called to execute a step using stepper functions (pins = 0) Only called when a new step is required.
virtual void	step1 (long step)
	Called to execute a step on a stepper driver (ie where pins == 1).
virtual void	step2 (long step)
	Called to execute a step on a 2 pin motor.
virtual void	step3 (long step)
	Called to execute a step on a 3 pin motor, such as HDD spindle.
virtual void	step4 (long step)
	Called to execute a step on a 4 pin motor.
virtual void	step6 (long step)
	Called to execute a step on a 3 pin motor, such as HDD spindle.
virtual void	step8 (long step)
	Called to execute a step on a 4 pin half-steper motor.

Detailed Description

Support for stepper motors with acceleration etc.

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 once 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 current 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).

Performance: The fastest motor speed that can be reliably supported is about 4000 steps per second at a clock frequency of 16 MHz on Arduino such as Uno etc. Faster processors can support faster stepping speeds. 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. Calling setAcceleration() is expensive, since it requires a square root to be calculated.

Definition at line 264 of file AccelStepper.h.

Member Enumeration Documentation

enum Direction [protected]

Direction indicator Symbolic names for the direction the motor is turning.

Enumerator:

DIRECTION_CCW	Clockwise.
DIRECTION_CW	Counter-Clockwise.

Definition at line 470 of file AccelStepper.h.

enum MotorInterfaceType

Symbolic names for number of pins.

Use this in the pins argument the AccelStepper constructor to provide a symbolic name for the number of pins to use.

Enumerator:

FUNCTION	Use the functional interface, implementing your own driver functions (internal use only)
DRIVER	Stepper Driver, 2 driver pins required.
FULL2WIRE	2 wire stepper, 2 motor pins required
FULL3WIRE	3 wire stepper, such as HDD spindle, 3 motor pins required
FULL4WIRE	4 wire full stepper, 4 motor pins required
HALF3WIRE	3 wire half stepper, such as HDD spindle, 3 motor pins required
HALF4WIRE	4 wire half stepper, 4 motor pins required

Definition at line 271 of file AccelStepper.h.

Constructor & Destructor Documentation

AccelStepper	(	uint8_t	interface,
		PinName	pin1 = `LED1`,
		PinName	pin2 = `LED2`,
		PinName	pin3 = `LED3`,
		PinName	pin4 = `LED4`,
		bool	enable = `true`
	)

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]	interface	Number of pins to interface to. 1, 2, 4 or 8 are supported, but it is preferred to use the MotorInterfaceType symbolic names. AccelStepper::DRIVER (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(). AccelStepper::FULL2WIRE (2) means a 2 wire stepper (2 pins required). AccelStepper::FULL3WIRE (3) means a 3 wire stepper, such as HDD spindle (3 pins required). AccelStepper::FULL4WIRE (4) means a 4 wire stepper (4 pins required). AccelStepper::HALF3WIRE (6) means a 3 wire half stepper, such as HDD spindle (3 pins required) AccelStepper::HALF4WIRE (8) means a 4 wire half stepper (4 pins required) Defaults to AccelStepper::FULL4WIRE (4) pins.
[in]	pin1	Arduino digital pin number for motor pin 1. Defaults to pin 2. For a AccelStepper::DRIVER (interface==1), this is the Step input to the driver. Low to high transition means to step)
[in]	pin2	Arduino digital pin number for motor pin 2. Defaults to pin 3. For a AccelStepper::DRIVER (interface==1), this is the Direction input the driver. High means forward.
[in]	pin3	Arduino digital pin number for motor pin 3. Defaults to pin 4.
[in]	pin4	Arduino digital pin number for motor pin 4. Defaults to pin 5.
[in]	enable	If this is true (the default), enableOutputs() will be called to enable the output pins at construction time.

Definition at line 193 of file AccelStepper.cpp.

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]	forward	void-returning procedure that will make a forward step
[in]	backward	void-returning procedure that will make a backward step

Definition at line 230 of file AccelStepper.cpp.

Member Function Documentation

void computeNewSpeed ( ) [protected]

Forces the library to compute a new instantaneous speed and set that as the current speed.

It is called by the library:

after each step
after change to maxSpeed through setMaxSpeed()
after change to acceleration through setAcceleration()
after change to target position (relative or absolute) through move() or moveTo()

Definition at line 100 of file AccelStepper.cpp.

long currentPosition ( )

The currently motor position.

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

Definition at line 86 of file AccelStepper.cpp.

void disableOutputs ( ) [virtual]

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.

Definition at line 541 of file AccelStepper.cpp.

long 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.

Definition at line 76 of file AccelStepper.cpp.

void enableOutputs ( ) [virtual]

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

Called automatically by the constructor.

Definition at line 552 of file AccelStepper.cpp.

void move ( long relative )

Set the target position relative to the current position.

Parameters:

[in] relative The desired position relative to the current position. Negative is anticlockwise from the current position.

Definition at line 33 of file AccelStepper.cpp.

void moveTo ( long absolute )

Set the target position.

The run() function will try to move the motor (at most one step per call) from the current position to the target position set by the most recent call to this function. Caution: moveTo() also recalculates the speed for the next step. If you are trying to use constant speed movements, you should call setSpeed() after calling moveTo().

Parameters:

[in] absolute The desired absolute position. Negative is anticlockwise from the 0 position.

Definition at line 23 of file AccelStepper.cpp.

bool run ( )

Poll the motor and step it if a step is due, implementing accelerations and decelerations to acheive the target position.

You must call this as frequently as possible, but at least once per minimum step time interval, 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, based on the current speed and the time since the last step.

Returns:: true if the motor is still running to the target position.

Definition at line 186 of file AccelStepper.cpp.

bool runSpeed ( )

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

You must call this as frequently as possible, but at least once per step interval,

Returns:: true if the motor was stepped.

Definition at line 41 of file AccelStepper.cpp.

bool runSpeedToPosition ( )

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

Returns:: true if it stepped

Definition at line 622 of file AccelStepper.cpp.

void runToNewPosition ( long position )

Moves the motor (with acceleration/deceleration) to the new target position and blocks until it is at position.

Dont use this in event loops, since it blocks.

Parameters:

[in] position The new target position.

Definition at line 634 of file AccelStepper.cpp.

void runToPosition ( )

Moves the motor (with acceleration/deceleration) to the target position and blocks until it is at position.

Dont use this in event loops, since it blocks.

Definition at line 616 of file AccelStepper.cpp.

void setAcceleration ( float acceleration )

Sets the acceleration/deceleration rate.

Parameters:

[in] acceleration The desired acceleration in steps per second per second. Must be > 0.0. This is an expensive call since it requires a square root to be calculated. Dont call more ofthen than needed

Definition at line 274 of file AccelStepper.cpp.

void 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] position The position in steps of wherever the motor happens to be right now.

Definition at line 93 of file AccelStepper.cpp.

void setEnablePin ( PinName enablePin )

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] enablePin Arduino digital pin number for motor enable

See also:: setPinsInverted

Definition at line 584 of file AccelStepper.cpp.

void setMaxSpeed ( float speed )

Sets the maximum permitted speed.

The run() function will accelerate up to the speed set by this function. Caution: the maximum speed achievable depends on your processor and clock speed.

Parameters:

[in] speed The desired maximum speed in steps per second. Must be > 0. Caution: Speeds that exceed the maximum speed supported by the processor may Result in non-linear accelerations and decelerations.

Definition at line 259 of file AccelStepper.cpp.

void setMinPulseWidth ( unsigned int minWidth )

Sets the minimum pulse width allowed by the stepper driver.

The minimum practical pulse width is approximately 20 microseconds. Times less than 20 microseconds will usually result in 20 microseconds or so.

Parameters:

[in] minWidth The minimum pulse width in microseconds.

Definition at line 578 of file AccelStepper.cpp.

void setOutputPins ( uint8_t mask ) [protected, virtual]

Low level function to set the motor output pins bit 0 of the mask corresponds to _pin[0] bit 1 of the mask corresponds to _pin[1] You can override this to impment, for example serial chip output insted of using the output pins directly.

Definition at line 348 of file AccelStepper.cpp.

void setPinsInverted	(	bool	directionInvert = `false`,
		bool	stepInvert = `false`,
		bool	enableInvert = `false`
	)

Sets the inversion for stepper driver pins.

Parameters:

[in]	directionInvert	True for inverted direction pin, false for non-inverted
[in]	stepInvert	True for inverted step pin, false for non-inverted
[in]	enableInvert	True for inverted enable pin, false (default) for non-inverted

Definition at line 599 of file AccelStepper.cpp.

void setPinsInverted	(	bool	pin1Invert,
		bool	pin2Invert,
		bool	pin3Invert,
		bool	pin4Invert,
		bool	enableInvert
	)

Sets the inversion for 2, 3 and 4 wire stepper pins.

Parameters:

[in]	pin1Invert	True for inverted pin1, false for non-inverted
[in]	pin2Invert	True for inverted pin2, false for non-inverted
[in]	pin3Invert	True for inverted pin3, false for non-inverted
[in]	pin4Invert	True for inverted pin4, false for non-inverted
[in]	enableInvert	True for inverted enable pin, false (default) for non-inverted

Definition at line 606 of file AccelStepper.cpp.

void setSpeed ( float speed )

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

Parameters:

[in] speed The 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.

Definition at line 289 of file AccelStepper.cpp.

float speed ( )

The most recently set speed.

Returns:: the most recent speed in steps per second

Definition at line 304 of file AccelStepper.cpp.

void step ( long 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: