RPR/02_Software/01_Arduino/libraries/AccelStepper/doc/index.html

218 lines
20 KiB
HTML
Raw Permalink Normal View History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>AccelStepper: AccelStepper library for Arduino</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">AccelStepper
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title"><a class="el" href="classAccelStepper.html" title="Support for stepper motors with acceleration etc. ">AccelStepper</a> library for Arduino </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This is the Arduino <a class="el" href="classAccelStepper.html" title="Support for stepper motors with acceleration etc. ">AccelStepper</a> library. It provides an object-oriented interface for 2, 3 or 4 pin stepper motors and motor drivers.</p>
<p>The standard Arduino IDE includes the Stepper library (<a href="http://arduino.cc/en/Reference/Stepper">http://arduino.cc/en/Reference/Stepper</a>) for stepper motors. It is perfectly adequate for simple, single motor applications.</p>
<p><a class="el" href="classAccelStepper.html" title="Support for stepper motors with acceleration etc. ">AccelStepper</a> significantly improves on the standard Arduino Stepper library in several ways: </p><ul>
<li>Supports acceleration and deceleration </li>
<li>Supports multiple simultaneous steppers, with independent concurrent stepping on each stepper </li>
<li>API functions never delay() or block </li>
<li>Supports 2, 3 and 4 wire steppers, plus 3 and 4 wire half steppers. </li>
<li>Supports alternate stepping functions to enable support of AFMotor (<a href="https://github.com/adafruit/Adafruit-Motor-Shield-library">https://github.com/adafruit/Adafruit-Motor-Shield-library</a>) </li>
<li>Supports stepper drivers such as the Sparkfun EasyDriver (based on 3967 driver chip) </li>
<li>Very slow speeds are supported </li>
<li>Extensive API </li>
<li>Subclass support</li>
</ul>
<p>The latest version of this documentation can be downloaded from <a href="http://www.airspayce.com/mikem/arduino/AccelStepper">http://www.airspayce.com/mikem/arduino/AccelStepper</a> The version of the package that this documentation refers to can be downloaded from <a href="http://www.airspayce.com/mikem/arduino/AccelStepper/AccelStepper-1.57.zip">http://www.airspayce.com/mikem/arduino/AccelStepper/AccelStepper-1.57.zip</a></p>
<p>Example Arduino programs are included to show the main modes of use.</p>
<p>You can also find online help and discussion at <a href="http://groups.google.com/group/accelstepper">http://groups.google.com/group/accelstepper</a> Please use that group for all questions and discussions on this topic. Do not contact the author directly, unless it is to discuss commercial licensing. Before asking a question or reporting a bug, please read</p><ul>
<li><a href="http://en.wikipedia.org/wiki/Wikipedia:Reference_desk/How_to_ask_a_software_question">http://en.wikipedia.org/wiki/Wikipedia:Reference_desk/How_to_ask_a_software_question</a></li>
<li><a href="http://www.catb.org/esr/faqs/smart-questions.html">http://www.catb.org/esr/faqs/smart-questions.html</a></li>
<li><a href="http://www.chiark.greenend.org.uk/~shgtatham/bugs.html">http://www.chiark.greenend.org.uk/~shgtatham/bugs.html</a></li>
</ul>
<p>Tested on Arduino Diecimila and Mega with arduino-0018 &amp; 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. Tested on Teensy <a href="http://www.pjrc.com/teensy">http://www.pjrc.com/teensy</a> including Teensy 3.1 built using Arduino IDE 1.0.5 with teensyduino addon 1.18 and later.</p>
<dl class="section user"><dt>Installation</dt><dd></dd></dl>
<p>Install in the usual way: unzip the distribution zip file to the libraries sub-folder of your sketchbook.</p>
<dl class="section user"><dt>Theory</dt><dd></dd></dl>
<p>This code uses speed calculations as described in "Generate stepper-motor speed profiles in real time" by David Austin <a href="http://fab.cba.mit.edu/classes/MIT/961.09/projects/i0/Stepper_Motor_Speed_Profile.pdf">http://fab.cba.mit.edu/classes/MIT/961.09/projects/i0/Stepper_Motor_Speed_Profile.pdf</a> or <a href="http://www.embedded.com/design/mcus-processors-and-socs/4006438/Generate-stepper-motor-speed-profiles-in-real-time">http://www.embedded.com/design/mcus-processors-and-socs/4006438/Generate-stepper-motor-speed-profiles-in-real-time</a> or <a href="http://web.archive.org/web/20140705143928/http://fab.cba.mit.edu/classes/MIT/961.09/projects/i0/Stepper_Motor_Speed_Profile.pdf">http://web.archive.org/web/20140705143928/http://fab.cba.mit.edu/classes/MIT/961.09/projects/i0/Stepper_Motor_Speed_Profile.pdf</a> with the exception that <a class="el" href="classAccelStepper.html" title="Support for stepper motors with acceleration etc. ">AccelStepper</a> uses steps per second rather than radians per second (because we dont know the step angle of the motor) An initial step interval is calculated for the first step, based on the desired acceleration On subsequent steps, shorter step intervals are calculated based on the previous step until max speed is achieved.</p>
<dl class="section user"><dt>Adafruit Motor Shield V2</dt><dd></dd></dl>
<p>The included examples AFMotor_* are for Adafruit Motor Shield V1 and do not work with Adafruit Motor Shield V2. See <a href="https://github.com/adafruit/Adafruit_Motor_Shield_V2_Library">https://github.com/adafruit/Adafruit_Motor_Shield_V2_Library</a> for examples that work with Adafruit Motor Shield V2.</p>
<dl class="section user"><dt>Donations</dt><dd></dd></dl>
<p>This library is offered under a free GPL license for those who want to use it that way. We try hard to keep it up to date, fix bugs and to provide free support. If this library has helped you save time or money, please consider donating at <a href="http://www.airspayce.com">http://www.airspayce.com</a> or here:</p>
<p> <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> </p>
<dl class="section user"><dt>Trademarks</dt><dd></dd></dl>
<p><a class="el" href="classAccelStepper.html" title="Support for stepper motors with acceleration etc. ">AccelStepper</a> is a trademark of AirSpayce Pty Ltd. The <a class="el" href="classAccelStepper.html" title="Support for stepper motors with acceleration etc. ">AccelStepper</a> mark was first used on April 26 2010 for international trade, and is used only in relation to motor control hardware and software. It is not to be confused with any other similar marks covering other goods and services.</p>
<dl class="section user"><dt>Copyright</dt><dd></dd></dl>
<p>This software is Copyright (C) 2010 Mike McCauley. Use is subject to license conditions. The main licensing options available are GPL V2 or Commercial:</p>
<dl class="section user"><dt>Open Source Licensing GPL V2</dt><dd>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 <a href="https://www.gnu.org/licenses/gpl-2.0.html">https://www.gnu.org/licenses/gpl-2.0.html</a></dd></dl>
<dl class="section user"><dt>Commercial Licensing</dt><dd>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. Purchase commercial licenses at <a href="http://airspayce.binpress.com/">http://airspayce.binpress.com/</a></dd></dl>
<dl class="section user"><dt>Revision History</dt><dd></dd></dl>
<dl class="section version"><dt>Version</dt><dd>1.0 Initial release</dd>
<dd>
1.1 Added speed() function to get the current speed. </dd>
<dd>
1.2 Added runSpeedToPosition() submitted by Gunnar Arndt. </dd>
<dd>
1.3 Added support for stepper drivers (ie with Step and Direction inputs) with _pins == 1 </dd>
<dd>
1.4 Added functional contructor to support AFMotor, contributed by Limor, with example sketches. </dd>
<dd>
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. </dd>
<dd>
1.6 Fixed a problem with wrapping of microsecond stepping that could cause stepping to hang. Reported by Sandy Noble. Removed redundant _lastRunTime member. </dd>
<dd>
1.7 Fixed a bug where setCurrentPosition() did not always work as expected. Reported by Peter Linhart. </dd>
<dd>
1.8 Added support for 4 pin half-steppers, requested by Harvey Moon </dd>
<dd>
1.9 setCurrentPosition() now also sets motor speed to 0. </dd>
<dd>
1.10 Builds on Arduino 1.0 </dd>
<dd>
1.11 Improvments from Michael Ellison: Added optional enable line support for stepper drivers Added inversion for step/direction/enable lines for stepper drivers </dd>
<dd>
1.12 Announce Google Group </dd>
<dd>
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. </dd>
<dd>
1.14 Fixed a problem with compiling under arduino 0021 reported by EmbeddedMan </dd>
<dd>
1.15 Fixed a problem with runSpeedToPosition which did not correctly handle running backwards to a smaller target position. Added examples </dd>
<dd>
1.16 Fixed some cases in the code where abs() was used instead of fabs(). </dd>
<dd>
1.17 Added example ProportionalControl </dd>
<dd>
1.18 Fixed a problem: If one calls the funcion runSpeed() when Speed is zero, it makes steps without counting. reported by Friedrich, Klappenbach. </dd>
<dd>
1.19 Added MotorInterfaceType and symbolic names for the number of pins to use for the motor interface. Updated examples to suit. Replaced individual pin assignment variables _pin1, _pin2 etc with array _pin[4]. _pins member changed to _interface. Added _pinInverted array to simplify pin inversion operations. Added new function setOutputPins() which sets the motor output pins. It can be overridden in order to provide, say, serial output instead of parallel output Some refactoring and code size reduction. </dd>
<dd>
1.20 Improved documentation and examples to show need for correctly specifying <a class="el" href="classAccelStepper.html#a73bdecf1273d98d8c5fbcb764cabeea5adedd394a375190a3df8d4519c0d4dc2f" title="4 wire full stepper, 4 motor pins required ">AccelStepper::FULL4WIRE</a> and friends. </dd>
<dd>
1.21 Fixed a problem where desiredSpeed could compute the wrong step acceleration when _speed was small but non-zero. Reported by Brian Schmalz. Precompute sqrt_twoa to improve performance and max possible stepping speed </dd>
<dd>
1.22 Added Bounce.pde example Fixed a problem where calling moveTo(), setMaxSpeed(), setAcceleration() more frequently than the step time, even with the same values, would interfere with speed calcs. Now a new speed is computed only if there was a change in the set value. Reported by Brian Schmalz. </dd>
<dd>
1.23 Rewrite of the speed algorithms in line with <a href="http://fab.cba.mit.edu/classes/MIT/961.09/projects/i0/Stepper_Motor_Speed_Profile.pdf">http://fab.cba.mit.edu/classes/MIT/961.09/projects/i0/Stepper_Motor_Speed_Profile.pdf</a> Now expect smoother and more linear accelerations and decelerations. The desiredSpeed() function was removed. </dd>
<dd>
1.24 Fixed a problem introduced in 1.23: with runToPosition, which did never returned </dd>
<dd>
1.25 Now ignore attempts to set acceleration to 0.0 </dd>
<dd>
1.26 Fixed a problem where certina combinations of speed and accelration could cause oscillation about the target position. </dd>
<dd>
1.27 Added stop() function to stop as fast as possible with current acceleration parameters. Also added new Quickstop example showing its use. </dd>
<dd>
1.28 Fixed another problem where certain combinations of speed and accelration could cause oscillation about the target position. Added support for 3 wire full and half steppers such as Hard Disk Drive spindle. Contributed by Yuri Ivatchkovitch. </dd>
<dd>
1.29 Fixed a problem that could cause a DRIVER stepper to continually step with some sketches. Reported by Vadim. </dd>
<dd>
1.30 Fixed a problem that could cause stepper to back up a few steps at the end of accelerated travel with certain speeds. Reported and patched by jolo. </dd>
<dd>
1.31 Updated author and distribution location details to airspayce.com </dd>
<dd>
1.32 Fixed a problem with enableOutputs() and setEnablePin on Arduino Due that prevented the enable pin changing stae correctly. Reported by Duane Bishop. </dd>
<dd>
1.33 Fixed an error in example AFMotor_ConstantSpeed.pde did not setMaxSpeed(); Fixed a problem that caused incorrect pin sequencing of FULL3WIRE and HALF3WIRE. Unfortunately this meant changing the signature for all step*() functions. Added example MotorShield, showing how to use AdaFruit Motor Shield to control a 3 phase motor such as a HDD spindle motor (and without using the AFMotor library. </dd>
<dd>
1.34 Added setPinsInverted(bool pin1Invert, bool pin2Invert, bool pin3Invert, bool pin4Invert, bool enableInvert) to allow inversion of 2, 3 and 4 wire stepper pins. Requested by Oleg. </dd>
<dd>
1.35 Removed default args from setPinsInverted(bool, bool, bool, bool, bool) to prevent ambiguity with setPinsInverted(bool, bool, bool). Reported by Mac Mac. </dd>
<dd>
1.36 Changed enableOutputs() and disableOutputs() to be virtual so can be overridden. Added new optional argument 'enable' to constructor, which allows you toi disable the automatic enabling of outputs at construction time. Suggested by Guido. </dd>
<dd>
1.37 Fixed a problem with step1 that could cause a rogue step in the wrong direction (or not, depending on the setup-time requirements of the connected hardware). Reported by Mark Tillotson. </dd>
<dd>
1.38 run() function incorrectly always returned true. Updated function and doc so it returns true if the motor is still running to the target position. </dd>
<dd>
1.39 Updated typos in keywords.txt, courtesey Jon Magill. </dd>
<dd>
1.40 Updated documentation, including testing on Teensy 3.1 </dd>
<dd>
1.41 Fixed an error in the acceleration calculations, resulting in acceleration of haldf the intended value </dd>
<dd>
1.42 Improved support for FULL3WIRE and HALF3WIRE output pins. These changes were in Yuri's original contribution but did not make it into production.<br />
</dd>
<dd>
1.43 Added DualMotorShield example. Shows how to use <a class="el" href="classAccelStepper.html" title="Support for stepper motors with acceleration etc. ">AccelStepper</a> to control 2 x 2 phase steppers using the Itead Studio Arduino Dual Stepper Motor Driver Shield model IM120417015.<br />
</dd>
<dd>
1.44 examples/DualMotorShield/DualMotorShield.ino examples/DualMotorShield/DualMotorShield.pde was missing from the distribution.<br />
</dd>
<dd>
1.45 Fixed a problem where if setAcceleration was not called, there was no default acceleration. Reported by Michael Newman.<br />
</dd>
<dd>
1.45 Fixed inaccuracy in acceleration rate by using Equation 15, suggested by Sebastian Gracki.<br />
Performance improvements in runSpeed suggested by Jaakko Fagerlund.<br />
</dd>
<dd>
1.46 Fixed error in documentation for runToPosition(). Reinstated time calculations in runSpeed() since new version is reported not to work correctly under some circumstances. Reported by Oleg V Gavva.<br />
</dd>
<dd>
1.48 2015-08-25 Added new class <a class="el" href="classMultiStepper.html" title="Operate multiple AccelSteppers in a co-ordinated fashion. ">MultiStepper</a> that can manage multiple AccelSteppers, and cause them all to move to selected positions at such a (constant) speed that they all arrive at their target position at the same time. Suitable for X-Y flatbeds etc.<br />
Added new method maxSpeed() to <a class="el" href="classAccelStepper.html" title="Support for stepper motors with acceleration etc. ">AccelStepper</a> to return the currently configured maxSpeed.<br />
</dd>
<dd>
1.49 2016-01-02 Testing with VID28 series instrument stepper motors and EasyDriver. OK, although with light pointers and slow speeds like 180 full steps per second the motor movement can be erratic, probably due to some mechanical resonance. Best to accelerate through this speed.<br />
Added isRunning().<br />
</dd>
<dd>
1.50 2016-02-25 <a class="el" href="classAccelStepper.html#a3591e29a236e2935afd7f64ff6c22006">AccelStepper::disableOutputs</a> now sets the enable pion to OUTPUT mode if the enable pin is defined. Patch from Piet De Jong.<br />
Added notes about the fact that AFMotor_* examples do not work with Adafruit Motor Shield V2.<br />
</dd>
<dd>
1.51 2016-03-24 Fixed a problem reported by gregor: when resetting the stepper motor position using setCurrentPosition() the stepper speed is reset by setting _stepInterval to 0, but _speed is not reset. this results in the stepper motor not starting again when calling setSpeed() with the same speed the stepper was set to before. </dd>
<dd>
1.52 2016-08-09 Added <a class="el" href="classMultiStepper.html" title="Operate multiple AccelSteppers in a co-ordinated fashion. ">MultiStepper</a> to keywords.txt. Improvements to efficiency of <a class="el" href="classAccelStepper.html#aa4a6bdf99f698284faaeb5542b0b7514">AccelStepper::runSpeed()</a> as suggested by David Grayson. Improvements to speed accuracy as suggested by David Grayson. </dd>
<dd>
1.53 2016-08-14 Backed out Improvements to speed accuracy from 1.52 as it did not work correctly. </dd>
<dd>
1.54 2017-01-24 Fixed some warnings about unused arguments. </dd>
<dd>
1.55 2017-01-25 Fixed another warning in MultiStepper.cpp </dd>
<dd>
1.56 2017-02-03 Fixed minor documentation error with DIRECTION_CCW and DIRECTION_CW. Reported by David Mutterer. Added link to Binpress commercial license purchasing. </dd>
<dd>
1.57 2017-03-28 _direction moved to protected at the request of Rudy Ercek. setMaxSpeed() and setAcceleration() now correct negative values to be positive.</dd></dl>
<dl class="section author"><dt>Author</dt><dd>Mike McCauley (<a href="#" onclick="location.href='mai'+'lto:'+'mik'+'em'+'@ai'+'rs'+'pay'+'ce'+'.co'+'m'; return false;">mikem<span style="display: none;">.nosp@m.</span>@air<span style="display: none;">.nosp@m.</span>spayc<span style="display: none;">.nosp@m.</span>e.co<span style="display: none;">.nosp@m.</span>m</a>) DO NOT CONTACT THE AUTHOR DIRECTLY: USE THE LISTS </dd></dl>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.11
</small></address>
</body>
</html>