Diff: PID.h

Revision:

2:d6f14bb935da

Parent:

1:24c444f3716b

Child:

3:93fb84c4e9bc

--- a/PID.h	Mon May 21 16:16:13 2018 +0000
+++ b/PID.h	Tue May 22 17:15:51 2018 +0000
@@ -31,41 +31,30 @@
  *  a correct performance until you have tuned all 3 parameters Kp, Ki and Kd.
  *
  * @note :
- *      You must provide a 16 bits Timer definition that allow the use of a
- *      quadrature encoder (pins A & B must be connected respectively to
- *      pin 1 and 2 of the timer.
+ *      You must provide a 16 bits Timer definition that allow the use of a quadrature encoder (pins A & B must be connected respectively to pin 1 and 2 of the timer.
  *
  *      Typicaly on Nucleo F446RE TIM3 and TIM4 are perfect to do this job.
  *      In this case simply use TIM3 or TIM4 as timer parameter 
  *
- *      You must also provide the number of pulses generated by the QE for a
- *      1mm displacement of the wheel.       
+ *      You must also provide the number of pulses generated by the QE for a 1mm displacement of the wheel.       
  *
  *      You may also add 2 or 3 outputs to drive a PWM full bridge :
  *          - 2 outputs for DIR/PWM full bridge
  *          - 3 outputs for IN+/IN-/PWM full bridge.
  *      Or you may not define any outputs.
  *
- *      In this case the PID controler must use a specific function that will
- *      output a PWM value that user must transform to match the full bridge.
+ *      In this case the PID controler must use a specific function that will output a PWM value that user must transform to match the full bridge.
  *      Value evolve from 1 (full PWM fortward) to -1 (full PWM backward).
  *      This value can also be found in the global variable : _PwmValue
  * 
  * @note :
- *      As this motion control system is implemented in a microcontroler it is
- *      important to understand that there is a loop time for the motion control
- *      system and that this loop time MUST be constant. Kp, Ki and Kd are
- *      dependent of the loop time. changing loop time mean changing the
- *      corrector's coefficients.
- *
+ *      As this motion control system is implemented in a microcontroler it is important to understand that there is a loop time for the motion control system and that this loop time MUST be constant.
+ *      Kp, Ki and Kd are dependent of the loop time. changing loop time mean changing the corrector's coefficients.
  *      We use a Ticker to control loop time.
  *
- *      The looptime can be set by software as long as it remain constant during
- *      the whole use of PID controler. Loop time is set to 1ms by default.
+ *      The looptime can be set by software as long as it remain constant during the whole use of PID controler. Loop time is set to 1ms by default.
  *
- *      Take care not to increase too mutch this time (or you will fail to 
- *      to control the motion) and to always keep enought time for computation
- *      to take place during this loop.
+ *      Take care not to increase too mutch this time (or you will fail to to control the motion) and to always keep enought time for computation to take place during this loop.
  *
  * @note :
  *      The PID is initialized with Ki = 0, Kd = 0 and Kp = 1
@@ -85,61 +74,64 @@
 #define PID_H
 
 /**
- * Includes
+ * Includes : Mbed Library + Nucleo_Encoder_16_bits library
  */
 #include "mbed.h"
 #include "Nucleo_Encoder_16_bits.h"
 
 /**
- * PID Motion control system
+ * PID Motion control system (speed control).
+ *  refere to wikipedia for more explainations : https://en.wikipedia.org/wiki/PID_controller
  */
 class PID {
 
 public :
 
     /**
-     * Constructor (standard) without full bridge control
+     * Constructor (standard) with full bridge control
      *
-     * @param _TIM is the Mbed 16 bits timer used to connect the A&B output of QE
-     * @param scale is the number of pulses on the QE for 1mm displacement of the wheel
-     * @param outPWM is the Mbed pin used to send PWM on the full bridge
-     * @param outDir is the Mbed pin used to send direction to the full bridge
-     * @param invDir is the Mbed pin used to send direction (in case of 3 pins full bridge)
+     * @param _TIM : the Mbed 16 bits timer used to connect the A&B output of QE
+     * @param outPWM : the Mbed pin used to send PWM on the full bridge
+     * @param outA : the Mbed pin used to send direction to the full bridge
+     * @param outB : the Mbed pin used to send direction (in case of 3 pins full bridge)
+     * @param scale : the number of pulses on the QE for 1mm displacement of the wheel
+     * @param loopTime : the time between 2 computations
      */
     PID(TIM_TypeDef * TIM, PinName outPWM, PinName outA, PinName outB, double scale = 31.8309886184, double loopTime = 0.001);
 
     /**
      * Set the Kp value
      *
-     * @param : Kp value
-     * @return : the value of Kp
-     * @note : can also be accessed using the global variable _Kp
+     * @param  Kp value
+     * @return  the value of Kp
+     * @note  can also be accessed using the global variable _Kp
      */
     float setProportionnalValue (float KpValue);
     
     /**
      * Set the Ki value
      *
-     * @param : Ki value
-     * @return : the value of Ki
-     * @note : can also be accessed using the global variable _Ki
+     * @param  Ki value
+     * @return  the value of Ki
+     * @note  can also be accessed using the global variable _Ki
      */
     float setintegralValue (float KiValue);
     
     /**
      * Set the Kd value
      *
-     * @param : Kd value
-     * @return : the value of Kd
-     * @note : can also be accessed using the global variable _Kd
+     * @param  Kd value
+     * @return  the value of Kd
+     * @note  can also be accessed using the global variable _Kd
      */
     float setDerivativeValue (float KdValue);
     
     /**
      * compute the PWM value of a motion controled system
      *
-     * @param : Set point value (in mm/s)
-     * @return : PWM value (between -1 and 1)
+     * @param  Set point value (in mm/s)
+     * @return  PWM value (between -1 and 1)
+     * @note    this function is provided for users that don't use a 3 wires full bridge
      */
     float computePWM (float setPoint); 
     
@@ -151,9 +143,20 @@
     void setSpeed (float setPoint);
     
     /**
-     * Global Variable
+     * Get position of the wheel (in step of the Quadrature Encoder)
+     *
+     * @note One step is a fouth of a period of A or B signal
+     * @note position is updated each time a motion computation take place
+     * @return the number of step from beggining
      */
+    long getPosition (void);
+    
     float   _Kp, _Ki, _Kd, _PwmValue;
+    long    _Position;
+    /**
+     * Global Variable to indicate that required speed is unreachable (=1 if speed is unreachable)
+     * @note    must be cleared by user
+     */
     int     RobotIsStuck;  
 
 protected :