bertos/algo/ramp.h

   1
   2 /**
   3  * \file
   4  * <!--
   5  * Copyright 2004, 2008 Develer S.r.l. (http://www.develer.com/)
   6  * All Rights Reserved.
   7  * -->
   8  *
   9  * \brief Compute, save and load ramps for stepper motors (interace)
  10  *
  11  * \version $Id$
  12  *
  13  * \author Simone Zinanni <s.zinanni@develer.com>
  14  * \author Giovanni Bajo <rasky@develer.com>
  15  * \author Daniele Basile <asterix@develer.com>
  16  *
  17  * The acceleration ramp is used to properly accelerate a stepper motor. The main
  18  * entry point is the function ramp_evaluate(), which must be called at every step
  19  * of the motor: it gets as input the time elapsed since the stepper started
  20  * accelerating, and returns the time to wait before sending the next step. A pseudo
  21  * usage pattern is as follows:
  22  *
  23  * <pre>
  24  *  float time = 0;
  25  *  while (1)
  26  *  {
  27  *      float delta = ramp_evaluate(&my_ramp, time);
  28  *      sleep(delta);
  29  *      do_motor_step();
  30  *      time += delta;
  31  *  }
  32  * </pre>
  33  *
  34  * A similar pattern can be used to decelerate (it is sufficient to move the total
  35  * time backward, such as "time -= delta").
  36  *
  37  * The ramp can be configured with ramp_setup(), providing it with the minimum and
  38  * maximum operating frequency of the motor, and the total acceleration time in
  39  * milliseconds (that is, the time that will be needed to accelerate from the
  40  * minimum frequency to the maximum frequency).
  41  *
  42  * Both a very precise floating point and a very fast fixed point implementation
  43  * of the ramp evaluation are provided. The fixed point is hand-optimized assembly
  44  * for DSP56000 (but a portable C version of it can be easily written, see the
  45  * comments in the code).
  46  *
  47  */
  48
  49 #ifndef ALGO_RAMP_H
  50 #define ALGO_RAMP_H
  51
  52 #include <cfg/compiler.h>
  53 #include "hw_stepper.h"
  54
  55 /**
  56  * Define whether the ramp will use floating point calculation within ramp_evaluate().
  57  * Otherwise, a less precise fixed point version will be used, which is faster on
  58  * platforms which do no support floating point operations.
  59  *
  60  * \note Floating point operations will be always done within ramp_compute() to
  61  * precalculate values, so there has to be at least a floating point emulation support.
  62  */
  63 #define RAMP_USE_FLOATING_POINT   0
  64
  65
  66 #if !RAMP_USE_FLOATING_POINT
  67
  68         /**
  69          * Number of least-significant bits which are stripped away during ramp evaluation.
  70          * This setting allows to specify larger ramps at the price of less precision.
  71          *
  72          * The maximum ramp size allowed is 2^(24 + RAMP_CLOCK_SHIFT_PRECISION), in clocks.
  73          * For instance, using RAMP_CLOCK_SHIFT_PRECISION 1, and a 8x prescaler, the maximum
  74          * length of a ramp is about 6.7 secs. Raising RAMP_CLOCK_SHIFT_PRECISION to 2
  75          * brings the maximum length to 13.4 secs, at the price of less precision.
  76          *
  77          * ramp_compute() will check that the length is below the maximum allowed through
  78          * a runtime assertion.
  79          *
  80          * \note This macro is used only for the fixed-point version of the ramp.
  81          */
  82         #define RAMP_CLOCK_SHIFT_PRECISION 2
  83 #endif
  84
  85
  86 ///< Negative pulse width for ramp
  87 #define RAMP_PULSE_WIDTH    50
  88
  89 ///< Default ramp
  90 #define RAMP_DEF_TIME       6000000 ///< microsecs
  91 #define RAMP_DEF_MAXFREQ       5000 ///< Hz
  92 #define RAMP_DEF_MINFREQ        200 ///< Hz
  93 #define RAMP_DEF_POWERRUN        10 ///< 10 deciampere (1 ampere)
  94 #define RAMP_DEF_POWERIDLE        1 ///< 1 deciampere
  95
  96
  97 /**
  98  * Convert microseconds to timer clock ticks
  99  */
 100 #define TIME2CLOCKS(micros) ((uint32_t)(micros) * (STEPPER_CLOCK / 1000000))
 101
 102 /**
 103  * Convert timer clock ticks back to microseconds
 104  */
 105 #define CLOCKS2TIME(clocks) ((uint32_t)(clocks) / (STEPPER_CLOCK / 1000000))
 106
 107 /**
 108  * Convert microseconds to Hz
 109  */
 110 #define MICROS2FREQ(micros) (1000000UL / ((uint32_t)(micros)))
 111
 112 /**
 113  * Convert frequency (in Hz) to time (in microseconds)
 114  */
 115 #define FREQ2MICROS(hz) (1000000UL / ((uint32_t)(hz)))
 116
 117
 118
 119 /**
 120  * Structure holding pre-calculated data for speeding up real-time evaluation
 121  * of the ramp. This structure is totally different between the fixed and the
 122  * floating point version of the code.
 123  *
 124  * Consult the file-level documentation of ramp.c for more information about
 125  * the values of this structure.
 126  */
 127 struct RampPrecalc
 128 {
 129 #if RAMP_USE_FLOATING_POINT
 130         float beta;
 131         float alpha;
 132         float gamma;
 133 #else
 134         uint16_t max_div_min;
 135         uint32_t inv_total_time;
 136 #endif
 137 };
 138
 139
 140 /**
 141  * Ramp structure
 142  */
 143 struct Ramp
 144 {
 145         uint32_t clocksRamp;
 146         uint16_t clocksMinWL;
 147         uint16_t clocksMaxWL;
 148
 149         struct RampPrecalc precalc; ///< pre-calculated values for speed
 150 };
 151
 152
 153 /*
 154  * Function prototypes
 155  */
 156 void ramp_compute(
 157         struct Ramp * ramp,
 158         uint32_t clocksInRamp,
 159         uint16_t clocksInMinWavelength,
 160         uint16_t clocksInMaxWavelength);
 161
 162
 163 /** Setup an acceleration ramp for a stepper motor
 164  *
 165  *  \param ramp Ramp to fill
 166  *  \param length Length of the ramp (milliseconds)
 167  *  \param minFreq Minimum operating frequency of the motor (hertz)
 168  *  \param maxFreq Maximum operating frequency of the motor (hertz)
 169  *
 170  */
 171 void ramp_setup(struct Ramp* ramp, uint32_t length, uint32_t minFreq, uint32_t maxFreq);
 172
 173
 174 /**
 175  * Initialize a new ramp with default values
 176  */
 177 void ramp_default(struct Ramp *ramp);
 178
 179
 180 /**
 181  * Evaluate the ramp at the given point. Given a \a ramp, and the current \a clock since
 182  * the start of the acceleration, compute the next step, that is the interval at which
 183  * send the signal to the motor.
 184  *
 185  * \note The fixed point version does not work when curClock is zero. Anyway,
 186  * the first step is always clocksMaxWL, as stored within the ramp structure.
 187  */
 188 #if RAMP_USE_FLOATING_POINT
 189         float ramp_evaluate(const struct Ramp* ramp, float curClock);
 190 #else
 191         uint16_t ramp_evaluate(const struct Ramp* ramp, uint32_t curClock);
 192 #endif
 193
 194
 195 /** Self test */
 196 void ramp_test(void);
 197
 198 #endif /* ALGO_RAMP_H */
 199