Diff: CreaBot.h

Revision:

6:4d8938b686a6

Parent:

5:efe80c5db389

Child:

7:3a793ddc3490

--- a/CreaBot.h	Wed Oct 31 14:36:07 2018 +0000
+++ b/CreaBot.h	Wed Nov 28 09:46:41 2018 +0000
@@ -1,62 +1,145 @@
-
+/**
+ * @file CreaBot.h
+ * @brief File contains Creabot Library.
+ 
+ * CreaBot.h contains the class Motor, and related enums and structs.
+ * Includes "mbed.h" and "motor.h"
+ 
+ * Refactorings:
+ * All variables with suffixes "_cm_sec" = speeds in centimeters per second
+ * MotCommand -> BotCommand
+ * cmdbot_t -> BotCmdVerb
+ * cm -> dist_cm
+ 
+ * @author Tarek Lule, Francois Druilhe, et al.
+ * @date 21. Nov. 2018.
+ * @see https://os.mbed.com/users/sepp_nepp/code/CreaBotLib/  */
+ 
+ // -------------------- Motor ---------------------------
+ 
 #ifndef CREABOT_H
 #define CREABOT_H
 
 #include "mbed.h"
 #include "motor.h"
 
-#define MAX_SPEED 30 //cm per second
-#define DEFAULT_SPEED 2 //cm per second
+#define MAX_SPEED_CM_SEC 30.0f /**< Clamp maximum advancement speed = 30cm/sec, was MAX_SPEED */
+#define DEFAULT_SPEED_CM_SEC 2.0f /**< Default advancement speed = 2.0cm/sec, was DEFAULT_SPEED */
 #define PI 3.141592f
-#define DEPTH_FIFO 256
+#define DEPTH_FIFO 256  /**< Initialize the depth of the command FIFO to 256 */
 
-typedef enum {FORWARD, BACKWARD, ROTATE, LEFT, RIGHT, IDLE} cmdbot_t;
+/** \enum BotCmdVerb 
+* \brief Robot Commands Verbs, gives the movement direction
+*  */
+typedef enum {
+    IDLE = 0,   /**< Command to do nothing */  
+    FORWARD,    /**< Advance the robot straight forward */  
+    BACKWARD,   /**< Advance the robot straight backwards. */  
+    ROTATE,     /**< Rotate around its own axis */  
+    LEFT,       /**< Advance in a left curve */
+    RIGHT,      /**< Advance in a right curve */
+    REVLEFT,    /**< Reverse in a left curve */
+    REVRIGHT    /**< Reverse in a right curve */
+} BotCmdVerb;
+
 
-/** Command structure as put into command FIFO, or treated by the FIFO-Handler */
-class MotCommand{
-  public:
-    cmdbot_t command;
-    float angle;
-    float cm;
-    /** Assigns the parameters to the class members, depending on command type */
-    void assign(cmdbot_t cmd, float p1, float p2);
-};
+/** \enum BotStatus 
+* \brief Possible states of two motors of Bot
+*  */
+typedef enum {
+    AlLSTOP = 0,/**< All Motors have stopped */  
+    LMOT_RUNS,  /**< Left Motor still runs */  
+    RMOT_RUNS,  /**< Right Motor still runs */  
+    MOTORS_RUN  /**< Both Motors still run */  
+} BotStatus;
+
+/** \struct BotCommand
+* \brief Structure of a Motor Command.
 
-/** Command FIFO, 256 elements deep, puts MotCommands in a queue, 
- *  handles the MotCommands one by one using ticker and callback. 
- *  Internally stores all commands in a static 256 array
- *  Only passes pointers forward and backward.
+* The command structure is put into command FIFO, and treated by the FIFO-Handler */
+typedef struct {
+    BotCmdVerb command; /**< General Command to give movement direction.*/
+    float dist_cm;      /**< Distance in dist_cm for translational movements .*/
+    float angle_deg;    /**< Angle in degree for rotational movement .*/
+    void set(BotCmdVerb Acommand, float Adist_cm, float Aangle_deg); /**< Helper; set structure fields to values  */
+    void set(BotCmdVerb Acommand, float Adist_cm); /**< Helper; set structure fields to values  */
+} BotCommand;
+
+/** \class CommandFIFO
+ * \brief 256 elements deep Command FIFO, to puts BotCommand in a queue.
+ * 
+ *  Internally stores all BotCommand in a static 256 array used as a circular ring buffer.
+ *  Adds incoming commands at the head of the ring buffer at position writeIdx, 
+ *  Gets oldest commands from the tail of the ring buffer at position readIdx,
+ *  Keeps track of the occupied size in count.
+ *  BotCommands are passed back as pointers.
  */
 class CommandFIFO {
   public: 
-    /** Create empty FIFO */
-    CommandFIFO() {readIdx = writeIdx = count = 0; cmd_idle.command = IDLE; cmd_idle.angle=0; cmd_idle.cm=0;};
-    /** Empty the FIFO by setting pointers to 0, commands are left in memory. */
+    /** Class Creator: initializes an empties FIFO
+    *
+    * Ring buffer is allocated statically. Read and Write Index are set to 0. */
+    CommandFIFO();
+    
+    /** Empty the FIFO.
+    *
+    * Since ring buffer is static, it suffice to set all pointers to 0, commands are left in memory. */
     void empty() {readIdx=writeIdx=count=0;};
-    /** If FIFO is full, it passes back NULL 
-        Otherwise Advances the write index once and returns a pointer the next command to write.
-        The caller then fills the command structure at that position.
-        */
-    MotCommand *put();
-    /** If FIFO is empty, it passes back NULL 
-        Otherwise Advances the read index once and returns a pointer the next command in the FIFO.
-        Do not free memory associated with the pointer.
-        */
-    MotCommand *get();
-    /** Returns the number of commands in the FIFO, previously called 'getSize' */
+
+    /** Reserve a new element at the head of the FIFO
+    *
+    *If FIFO is full, it passes back NULL 
+    *Otherwise Advances the write index once and returns a pointer the next free command struct.
+    *The caller then has to fills the command structure at that position. 
+    *Do not free memory associated to the pointer.
+    *
+    *@return <BotCommand*> Pointer to the reserved BotCommand to write to. 
+    */
+    BotCommand *put();
+
+    void put(BotCmdVerb Acommand, float Adist_cm, float Aangle_deg); 
+
+    /** Get and remove the oldest element at the tail of the FIFO
+    *
+    *If FIFO is empty, it passes back NULL 
+    *Otherwise advances the read index once and returns a pointer the oldest stored command in the FIFO.
+    *Do not free memory associated with the pointer.
+    *
+    *@return <BotCommand*> Pointer to the oldest BotCommand. 
+    */
+    BotCommand *get();
+    
+    /** Access FIFO used count. 
+    *
+    *@return <int>  the number of commands in the FIFO */
     int getCount() {return count;}
-    /** Returns true when the FIFO is full */
+    
+     /** Check if FIFO is full. 
+    * 
+    * Space is limited to DEPTH_FIFO=256 BotCommand elements.
+    * Should be checked before trying to put new elements
+    *
+    * @return <bool>  True if FIFO is full*/
     bool isFull() {return count>=DEPTH_FIFO;}
-    /** Returns true when the FIFO is empty */
+    
+     /** Check if FIFO is empty. 
+    * 
+    * Should be checked before trying to get new elements
+    * 
+    * @return <bool>  True if FIFO is empty*/
     bool isEmpty() {return count<=0;}
+    
   private:
-    int readIdx, writeIdx, count;
-    MotCommand cmd[DEPTH_FIFO];
-    MotCommand cmd_idle;
+    int readIdx;  /**< Index in FIFO array where to get the oldest element from. */
+    int writeIdx; /**< Index in FIFO array where to put the next new element to. */
+    int Count;    /**< Counts the number of elements in array used. */
+    BotCommand cmd[DEPTH_FIFO]; /**< Actual static FIFO array where all elements reside. */
+    BotCommand cmd_idle; /**< A Constant Idle command  */
 };
 
+/** \class Creabot
 
-/** Asynchronous Control of 2 motors part of a robot
+* \brief Synchronous Control of 2 motors as part of a two wheel robot
  *
  * Example:
  * @code
@@ -98,25 +181,28 @@
  
 class Creabot {
 public:
-   /** Create a Creabot object to synchronize 2 motors
+   /** Create a Creabot object with 2 motors
      *
      *  @param left Motor object declared before corresponding to left motor of the Creabot
      *  @param right Motor object declared before corresponding to right motor of the Creabot
-     *  @param diameter_wheel_cm diameter in cm of the wheels (both supposed to be at same diameter)
-     *  @param distance_wheel_cm distance in cm between center of left wheel and center of right wheel
+     *  @param diameter_wheel_cm diameter in dist_cm of the wheels (both supposed to be at same diameter)
+     *  @param distance_wheel_cm distance in dist_cm between center of left wheel and center of right wheel
      */
     Creabot(Motor *left, Motor *right, float diameter_wheel_cm, float distance_wheel_cm);
-    int getStatus();
-    void setSpeed(float cm_per_second);
+    
+    /** Property access to Motor state */
+    BotState getState() {return MotState};
+    
+    void setSpeed(float speed_cm_sec);
     void waitEndMove();
     void waitEndMove(uint32_t delay_us); // watchdog
-    void setCallBack(void (*callback)(int status));
-    void moveAndWait(cmdbot_t moveType, float angle_or_cm);
-    void moveAndWait(cmdbot_t moveType, float angle, float cm);
-    void move(cmdbot_t moveType, float angle_or_cm);
-    void move(cmdbot_t moveType, float angle, float cm);
-    void fifo(cmdbot_t moveType, float angle_or_cm);
-    void fifo(cmdbot_t moveType, float angle, float cm);
+    void setCallBack(void (*Acallback)(int status));
+    void moveAndWait(BotCmdVerb moveType, float angle_or_cm);
+    void moveAndWait(BotCmdVerb moveType, float angle_deg, float dist_cm);
+    void move(BotCmdVerb moveType, float angle_or_cm);
+    void move(BotCmdVerb moveType, float angle_deg, float dist_cm);
+    void fifo(BotCmdVerb moveType, float angle_or_cm);
+    void fifo(BotCmdVerb moveType, float angle_deg, float dist_cm);
     void flushFifo();
     void spirale(float b, float turns);
     int moveInFifo();
@@ -124,26 +210,28 @@
     void stopMove();
          
 private:
-    void moveForward(float cm);
-    void moveBackward(float cm);
-    void rotate(float angle);
-    void moveRight(float angle);
-    void moveRight(float angle, float center_cm);
-    void moveLeft(float angle);
-    void moveLeft(float angle, float center_cm);
-    void callBack();
-    uint32_t computeSpeed(Motor *motor, float cm_per_second);
+    void moveForward(float dist_cm);
+    void moveBackward(float dist_cm);
+    void rotate(float angle_deg);
+    void moveRight(float angle_deg);
+    void moveRight(float angle_deg, float center_cm);
+    void moveLeft(float angle_deg);
+    void moveLeft(float angle_deg, float center_cm);
+    uint32_t computeSpeed(Motor *motor, float speed_cm_sec);
     
     void (*extCallBack)(int status);
-    void moveMotorLeft(motorDir dir, float angle);
-    void moveMotorRight(motorDir dir, float angle);
-    void executeCommand(MotCommand *cmd);
-    void setSpeedMot(Motor *motor, float cm_per_second);
+    void moveMotorLeft(motorDir dir, float angle_deg);
+    void moveMotorRight(motorDir dir, float angle_deg);
+    void executeCommand(BotCommand *cmd);
+    void setSpeedMot(Motor *motor, float speed_cm_sec);
 
     
-  private: // The two motors and their physical properties:
-    void callBackLeft();
-    void callBackRight();
+  private: 
+    // The two motors and their physical properties:
+    // Two call back functions that are called back by the motors when they have stopped
+    void cbLeftMotStopped();
+    void cbRightMotStopped();
+    void AllMotorsStopped();
     Motor *motor_left;
     Motor *motor_right;
     float diameter_wheel;
@@ -156,21 +244,18 @@
 
 
     float last_speed;  // last requested speed
-    int status;
-    bool endMoveLeft;
-    bool endMoveRight;
-    bool endMove;
     CommandFIFO fifoBot;
-    MotCommand current_cmd;
+    BotCommand current_cmd;
     Ticker botTicker;
     bool executingFifo;
     
+    BotState MotState;
   private:
     /* members that were not used in last release
      * float macro_move_parameter;
-     * MotCommand macro_move;
-     * void setSpeedLeft(float cm_per_second);
-     * void setSpeedRight(float cm_per_second); */
+     * BotCommand macro_move;
+     * void setSpeedLeft(float speed_cm_sec);
+     * void setSpeedRight(float speed_cm_sec); */
 };
 
 #endif
\ No newline at end of file