Changeset 789 for firmware/trunk/libraries/stepper/stepper.c

Timestamp:

08/06/08 14:03:57 (5 months ago)

Author:

liamstask

Message:

- add examples to stepper doc
- remove Stepper_GetStep() which was unimplemented and unused

Files:

• firmware/trunk/libraries/stepper/stepper.c (modified) (18 diffs)

firmware/trunk/libraries/stepper/stepper.c

@@ -98 +98 @@
   - bipolar or unipolar
   - normal of half-stepping
-
+  
+  \section Positioning
   You can generally use the stepper motor in 2 modes - \b absolute positioning or \b relative positioning.
 
@@ -106 +107 @@
 
   For relative positioning, use Stepper_Step( ) to simply move a number of steps from the current position.
+  
+  See the <a href="http://www.makingthings.com/documentation/how-to/stepper-motor">Stepper Motor how-to</a>
+  for more detailed info on hooking up a stepper motor to the Make Controller.
 * \ingroup Libraries
 * @{
@@ -111 +115 @@
 
 /**
-  Attempt to set the specified 
   Sets whether the specified Stepper is active.
   @param index An integer specifying which stepper (0 or 1).
   @param state An integer specifying the active state - 1 (active) or 0 (inactive).
   @return Zero on success.
+  
+  \b Example
+  \code
+  // enable stepper 1
+  Stepper_SetActive(1, 1);
+  \endcode
 */
 int Stepper_SetActive( int index, int state )
@@ -152 +161 @@
   @param index An integer specifying which stepper (0-1).
   @return State - 1 (active) or 0 (inactive).
+  
+  \b Example
+  \code
+  if( Stepper_GetActive(1) )
+  {
+    // Stepper 1 is active
+  }
+  else
+  {
+    // Stepper 1 is inactive
+  }
+  \endcode
 */
 int Stepper_GetActive( int index )
@@ -166 +187 @@
 /** 
   Set the position of the specified stepper motor.
+  Note that this will not ask the stepper to move.  It will simply update
+  the position that the stepper thinks its at.  To move the stepper, see
+  Stepper_SetPositionRequested() or Stepper_Step().
   @param index An integer specifying which stepper (0 or 1).
   @param position An integer specifying the stepper position.
   @return status (0 = OK).
+  
+  \b Example
+  \code
+  // reset stepper 1 to call its current position 0
+  Stepper_SetPosition(1, 0);
+  \endcode
 */
 int Stepper_SetPosition( int index, int position )
@@ -192 +222 @@
 /** 
   Set the destination position for a stepper motor.
+  This will start the stepper moving the given number of
+  steps at the current speed, as set by Stepper_SetSpeed().
+  
+  While it's moving, you can call Stepper_GetPosition() to read
+  its current position.
   @param index An integer specifying which stepper (0 or 1).
   @param positionRequested An integer specifying the desired stepper position.
   @return status (0 = OK).
+  
+  \b Example
+  \code
+  // start moving stepper 0 1500 steps
+  Stepper_SetPositionRequested(0, 1500);
+  \endcode
 */
 int Stepper_SetPositionRequested( int index, int positionRequested )
@@ -216 +257 @@
 /** 
   Set the speed at which a stepper will move.
-  This is a number of ms per step,
-  rather than the more common steps per second.  Arranging it this way makes 
-  it easier to express as an integer.  Fastest speed is 1ms / step (1000 steps
-  per second) and slowest is many seconds.
+  This is a number of ms per step, rather than the more common steps per second.  
+  Arranging it this way makes it easier to express as an integer.  
+  Fastest speed is 1ms / step (1000 steps per second) and slowest is many seconds.
   @param index An integer specifying which stepper (0 or 1).
   @param speed An integer specifying the stepper speed in ms per step
   @return status (0 = OK).
+  
+  \b Example
+  \code
+  // set the speed to 1ms / step (1000 steps per second)
+  Stepper_SetSpeed(0, 1);
+  \endcode
 */
 int Stepper_SetSpeed( int index, int speed )
@@ -250 +296 @@
   @param index An integer specifying which stepper (0 or 1).
   @return The speed (0 - 1023), or 0 on error.
+  
+  \b Example
+  \code
+  int step0_speed = Stepper_GetSpeed(0);
+  // now step0_speed has the speed of stepper 0
+  \endcode
 */
 int Stepper_GetSpeed( int index )
@@ -264 +316 @@
 /** 
   Read the current position of a stepper motor.
-  @param index An integer specifying which stepper (0 - 3).
+  @param index An integer specifying which stepper (0 or 1).
   @return The position, 0 on error.
+  
+  \b Example
+  \code
+  int step0_pos = Stepper_GetPosition(0);
+  // now step0_pos has the current position of stepper 0
+  \endcode
 */
 int Stepper_GetPosition( int index )
@@ -280 +338 @@
 /** 
   Read the destination position of a stepper motor.
+  This indicates where the stepper is ultimately headed.  To see
+  where it actually is, see Stepper_GetPosition().
   @param index An integer specifying which stepper (0 or 1).
   @return The position and 0 on error
+  
+  \b Example
+  \code
+  int step1_destination = Stepper_GetPositionRequested(1);
+  // step1_destination has the requested position for stepper 1
+  \endcode
 */
 int Stepper_GetPositionRequested( int index )
@@ -300 +366 @@
   @param steps An integer specifying the number of steps.  Can be negative to go in reverse.
   @return status (0 = OK).
+  
+  \b Example
+  \code
+  // take 1200 steps forward from our current position
+  Stepper_Step(0, 1200);
+  \endcode
 */
 int Stepper_Step( int index, int steps )
@@ -319 +391 @@
 
 /** 
-  Not implemented - returns 0.
-  @param index An integer specifying which stepper (0 or 1).
-*/
-int Stepper_GetStep( int index )
-{
-  if ( index < 0 || index >= STEPPER_COUNT )
-    return CONTROLLER_ERROR_ILLEGAL_INDEX;
-
-  return 0; // write-only
-}
-
-/** 
   Set the duty - from 0 to 1023.  The default is for 100% power (1023).
   @param index An integer specifying which stepper (0 or 1).
   @param duty An integer specifying the stepper duty (0 - 1023).
   @return status (0 = OK).
+  
+  \b Example
+  \code
+  // set stepper 0 to half power
+  Stepper_SetDuty(0, 512);
+  \endcode
 */
 int Stepper_SetDuty( int index, int duty )
@@ -358 +424 @@
   Get the duty 
   Read the value previously set for the duty.
-  @param index An integer specifying which stepper (0 - 3).
+  @param index An integer specifying which stepper (0 or 1).
   @return The duty (0 - 1023), or 0 on error.
+  
+  \b Example
+  \code
+  int step1_duty = Stepper_GetDuty(1);
+  // step1_duty has the current duty for stepper 1
+  \endcode
 */
 int Stepper_GetDuty( int index )
@@ -373 +445 @@
 
 /** 
-  Declare whether the stepper is bipolar or not.  Default is bipolar.
+  Declare whether the stepper is bipolar or not.  
+  Default is bipolar.
   @param index An integer specifying which stepper (0 or 1).
   @param bipolar An integer 1 for bipolar, 0 for unipolar
   @return status (0 = OK).
+  
+  \b Example
+  \code
+  // set stepper 1 to unipolar
+  Stepper_SetBipolar(1, 0);
+  \endcode
 */
 int Stepper_SetBipolar( int index, int bipolar )
@@ -395 +474 @@
   Get the bipolar setting
   Read the value previously set for bipolar.
-  @param index An integer specifying which stepper (0 - 3).
+  @param index An integer specifying which stepper (0 or 1).
   @return 1 for bipolar or 0 for unipolar.
+  
+  \b Example
+  \code
+  if( Stepper_GetBipolar(1) )
+  {
+    // stepper 1 is bipolar
+  }
+  else
+  {
+    // stepper 1 is unipolar
+  }
+  \endcode
 */
 int Stepper_GetBipolar( int index )
@@ -410 +501 @@
 
 /** 
-  Declare whether the stepper is in half stepping mode or not.  Default is not - i.e. in full step mode.
+  Declare whether the stepper is in half stepping mode or not.  
+  Default is not - i.e. in full step mode.
   @param index An integer specifying which stepper (0 or 1).
   @param halfStep An integer specifying 1 for half step, 0 for full step
   @return status (0 = OK).
+  
+  \b Example
+  \code
+  // set stepper 1 to half step mode
+  Stepper_SetHalfStep(1, 1);
+  \endcode
 */
 int Stepper_SetHalfStep( int index, int halfStep )
@@ -433 +531 @@
   @param index An integer specifying which stepper (0 or 1).
   @return the HalfStep setting.
+  
+  \b Example
+  \code
+  if( Stepper_GetHalfStep(1) )
+  {
+    // stepper 1 is in half step mode
+  }
+  else
+  {
+    // stepper 1 is in full step mode
+  }
+  \endcode
 */
 int Stepper_GetHalfStep( int index )
@@ -1151 +1261 @@
       value = Stepper_GetBipolar( index );
       break;
-    case 7: // step
-      value = Stepper_GetStep( index );
-      break;
   }
   return value;