Diff: CreaBot.h

Revision:

10:79509113310a

Parent:

9:efe9f76d6f76

Child:

11:5a94af0afa12

--- a/CreaBot.h	Thu Jan 03 23:16:46 2019 +0000
+++ b/CreaBot.h	Wed Apr 17 21:48:00 2019 +0000
@@ -3,7 +3,7 @@
  * \brief File contains Creabot Library.
  
  * CreaBot.h contains the Creabot class, and required enums and structs.
- * Includes "mbed.h" and "motor.h"
+ * Imports "mbed.h" and "motor.h"
  
  * Refactorings:
  * All variables with suffixes "_cm_sec" = speeds in centimeters per second.
@@ -13,10 +13,10 @@
  * 'motorxx' -> 'wheelxxx': each motor now becomes a 'wheel with a diameter'
  * FIFO queue management merged with Creabot Class, now called Queue 
  * Queue does not use another extra ticker anymore. Instead triggers from Motor End commands. 
- * Queue is worked through, and Callback is not called, until all queue is empty. 
+ * Queue is worked through, and Callback is not called, until queue is empty. 
  *
- * @author Tarek Lule, Francois Druilhe, et al.
- * @date 21. Nov. 2018.
+ * @author Tarek Lule based on work of Francois Druilhe, et al.
+ * @date 21. April 2019
  * @see https://os.mbed.com/users/sepp_nepp/code/CreaBotLib/  */
  
  // -------------------- wheel ---------------------------
@@ -27,15 +27,12 @@
 #include "mbed.h"
 #include "motor.h"
 
-#define MAX_SPEED_CM_SEC 30.0f    /**< Clamp maximum advancement speed = 30cm/sec, was MAX_SPEED */
-#define MIN_SPEED_CM_SEC 0.001f   /**< Clamp minimum advancement speed = 10um/sec */
 #define DEFAULT_SPEED_CM_SEC 2.0f /**< Default advancement speed = 2.0cm/sec, was DEFAULT_SPEED */
-#define PI 3.141592f    /**< PI needed to calcuate from angle to distances */
 #define DEPTH_Queue 256  /**< Initialize the depth of the command Queue to 256 */
 
 /** \enum BotCmdVerb 
 * \brief Robot Commands Verbs, gives the movement direction
-* IDLE is not supported at the moment
+* IDLE is no longer supported 
 */
 typedef enum {
     FORWARD,    /**< Advance the robot straight forward   */  
@@ -49,20 +46,20 @@
 
 
 /** \enum TWheelsState
-* \brief Possible states of the two wheels of the Bot
-*  */
+* \brief Possible states of the two wheels of the CreaBot
+* Can be ored together */
 typedef enum {
     LRWHEELS_STOP = 0, /**< All wheels have stopped */  
     LWHEEL_RUNS   = 1, /**< Left  wheel  runs */  
-    RWHEEL_RUNS,  = 2, /**< Right wheel  runs */  
+    RWHEEL_RUNS   = 2, /**< Right wheel  runs */  
     LRWHEELS_RUN  = 3, /**< Both  wheels run */  
 } TWheelsState;
 
 /** \struct BotCommand
-* \brief Structure of a wheel Command.
+* \brief Structure of a CreaBot Command.
 * The command structure is put into command Queue, and treated by the Queue-Handler */
 typedef struct {
-    BotCmdVerb command; /**< General Command to give movement direction.*/
+    BotCmdVerb command; /**< Command type that gives movement direction.*/
     float dist_cm;      /**< Distance in dist_cm for translational movements .*/
     float turn_angle_deg;    /**< Angle in degree for rotational movement .*/
     void set(BotCmdVerb Acommand, float Aturn_angle_deg, float Adist_cm); /**< Helper; set structure fields to values  */
@@ -74,19 +71,24 @@
 
 * \brief Synchronous Control of 2 wheels as part of a two wheel robot
 *
-* Handles two instances of Motor from motor.h library simultaneously. 
+* Handles two instances of CreaMot from motor.h library simultaneously. 
 * Using the set distance between the wheels, allows to run pecise curves. 
-* One set of movement commands starting with iXXX are executed immediately, 
-*   they override each other if issued too quickly.
-* The other set of movement commands starting with qXXX are queued up in a 
-*   waiting queue, allowing to execute them one by one in programmed order. 
+* A first other set of movement functions starting with qXXX are using command verbs,
+*   these commands are queued up in a waiting queue, 
+*   and are executed one by one in programmed order. 
+* A second set of movement functions starting with iXXX are also using command verbs,
+*   however these commands are executed immediately, 
+*   they override each other if issued while the previous movement still ongoing
+* A third set of movements functions starting with moveXXXX are provided, 
+*   each function performs one specific movement, also immediately. 
+*   So they also override each other, and collide with queued commands.
 * A callback is supplied to react to the end of all programmed movements. 
 *
 * Example:
 * @code
 * // --- Define the Four PINs & Time of movement used for wheel drive -----
-* Motor wheelLeft(PA_12, PB_0, PB_1, PB_6); // Declare first the 2 wheels (to avoid to have an object with 8 pins to create)
-* Motor wheelRight(PA_5,PA_4,PA_3,PA_1);
+* CreaMot wheelLeft(PA_12, PB_0, PB_1, PB_6); // Declare first the 2 wheels (to avoid to have an object with 8 pins to create)
+* CreaMot wheelRight(PA_5,PA_4,PA_3,PA_1);
 * Creabot mybot(&wheelLeft, &WheelRight, 10.0f, 13.0f); // insert the wheels and indicate wheel diameter (10cm) and distance between wheels (13cm)
 * 
 * int main() {
@@ -125,33 +127,33 @@
 public:
    /** Create a Creabot object with 2 wheels
      *
-     *  @param <left motor> object, corresponding to left wheel of the Creabot
-     *  @param <right motor> object, corresponding to right wheel of the Creabot
+     *  @param <left CreaMot> object, corresponding to left wheel of the Creabot
+     *  @param <right CreaMot> object, corresponding to right wheel of the Creabot
      *  @param <wheel_diam_cm> diameter in cm of the wheels (both must be the same diameter)
      *  @param <bot_diam_cm> distance cm between center of left wheel and center of right wheel
      */
-    Creabot(motor *left, motor *right, float wheel_diam_cm, float bot_diam_cm);
+    Creabot(CreaMot *left, CreaMot *right, float wheel_diam_cm, float bot_diam_cm);
     
     /** Property access to wheel state, indicating which of the wheels are moving */
     TWheelsState getState() {return wheelsState; };
     
     /** Setup a Callback method. It is called when all programmed movements are finished. */
-    void setCallBack(void (*Acallback)(int status)); { extCallBack = Acallback; };
+    void setCallBack(void (*Acallback)(int status)) { extCallBack = Acallback; };
 
     /** High level: set bot-speed parameter for all future wheel commands. 
-    * The set speed is used for immediate and queued movements alike.
-    * In a curve movement it determines the speed of the outer wheel. 
-    */ 
+    * The set speed is used for immediate as well as the queued movements.
+    * In a curve movement it determines the speed of the outer wheel.  */ 
     void setSpeed(float AbotSpeed_cm_sec);
 
 public:
 
-    /** High level, queued :  move bot according to command and parameter
+    /** High level, queued:  move bot according to command and parameter
     * Composes a BotCommand and appends it to the queue for queued execution.
     * Use for commands that need only one parameter: FORWARD, BACKWARD, ROTATE
     * For details refer to docu of moveForward(), moveBackward(), moveRotate().
     * Can also be called with IDLE, but then has no effect. 
-    * Preset the speed using setSpeed().
+    * Preset the speed using setSpeed().]
+    *
     * @param[in] <Acommand> Requested movement, of type BotCmdVerb.
     * @param[in] <Aparam>   Requested amount, defines angle for ROTATE, or distance for FORWARD, BACKWARD.
     */
@@ -160,10 +162,10 @@
     /** High level, queued :  move bot according to command and parameters
     * Composes a BotCommand and appends it to the queue for queued execution.
     * Use for commands that need two parameters: LEFT, RIGHT, BACKLEFT, BACKRIGHT
-    * For details refer to docu of moveLeft(), moveRight(), moveRevLeft(), moveRevRight().
+    * For details refer to docu of moveLeft(), moveRight(), moveBackLeft(), moveBackRight().
     * Can also be called with IDLE, but then has no effect. 
     *
-    * Reserves a new element at the head of the Queue
+    * Reserves a new command element at the head of the Queue
     *
     * Adds incoming commands at the head of the ring buffer at position writeIdx, 
     * If Queue is full, it passes back NULL 
@@ -181,8 +183,7 @@
     *
     * If Queue is empty, nothing happens
     * Otherwise executes oldest commands from the tail of the ring buffer at position readIdx,
-    * Then advances the read index once.
-    */
+    * Then advances the read index once.  */
     void qExecuteNext();
 
     /** Public access of Queue used Count. 
@@ -196,17 +197,19 @@
 
 private: 
     /** Empty the Queue.
-    * Since ring buffer is static, it suffice to set all pointers to 0, commands are left in memory. */
+    * Since the ring buffer is static, it suffice to set all pointers to 0, 
+    * Commands are left in memory.   */
     void qReset() { qBlock = true; readIdx=writeIdx=Count=0; qBlock = false; qCollide = false;};
 
-     /** Check if Queue is full. 
+    /** Check if Queue is full. 
     * 
     * Space is limited to DEPTH_Queue=256 BotCommand elements.
-    * Should be checked before trying to put new elements
+    * If in doubt it should be checked before trying to add new elements
     * @return <bool>  True if Queue is full*/
     bool qIsFull() {return Count>=DEPTH_Queue;}
     
-     /** Check if Queue is empty. 
+    /** Check if Queue is empty. 
+    *
     * Should be checked before trying to get new elements
     * @return <bool>  True if Queue is empty*/
     bool qIsEmpty() {return Count<=0;}
@@ -220,15 +223,16 @@
     int Count;    /**< Counts and keeps track of the number of elements in array used. */
     bool qBlock;  /**< Blocks read access while a write is ongoing. */
     bool qCollide;/**< Indicates a colliding access to the queue. */
+    
 public:
     /** High level, immediate:  move bot and wait for movement end. 
-    * Simple wrapper for botMove(Acommand,Aparam) and waitEndWheels().
+    * Simple wrapper for iMove(Acommand,Aparam) and iWaitEnd().
     * Refer to those methods for further docs.
     */
     void iMoveAndWait(BotCmdVerb Acommand, float Aparam);
     
     /** High level, immediate:  move bot and wait for movement end. 
-    * Simple wrapper for botMove(Acommand,Aturn_angle_deg,Adist_cm) and waitEndWheels().
+    * Simple wrapper for iMove(Acommand,Aturn_angle_deg,Adist_cm) and iWaitEnd().
     * Refer to those methods for further docs.
     */
     void iMoveAndWait(BotCmdVerb Acommand, float Aturn_angle_deg, float Adist_cm);
@@ -240,6 +244,7 @@
     * Can also be called with IDLE, but then has no effect. 
     * Preset the speed using setSpeed().
     * Warning: Collides with queued commands. 
+    *
     * @param[in] <Acommand> Requested movement, of type BotCmdVerb.
     * @param[in] <Aparam>   Requested amount, defines angle for ROTATE, or distance for FORWARD, BACKWARD.
     */
@@ -248,10 +253,11 @@
     /** High level, immediate:  move bot according to command and parameters
     * Composes a BotCommand and passes it to executeCommand().
     * Use for commands that need two parameters: LEFT, RIGHT, BACKLEFT, BACKRIGHT
-    * For details refer to docu of moveLeft(), moveRight(), moveRevLeft(), moveRevRight().
+    * For details refer to docu of moveLeft(), moveRight(), moveBackLeft(), moveBackRight().
     * Can also be called with IDLE, but then has no effect. 
     * Preset the speed using setSpeed().
     * Warning: Collides with queued commands. 
+    *
     * @param[in] <Acommand> Requested movement, of type BotCmdVerb.
     * @param[in] <Aturn_angle_deg>   Requested angle in degrees.
     * @param[in] <Adist_cm>   Requested distance in centimeters.
@@ -259,10 +265,11 @@
     void iMove(BotCmdVerb Acommand, float Aturn_angle_deg, float Adist_cm);
     
     /** High level, immediate: move bot according to prefilled command structures.
-    * Recommended to use botMove() methods to fill the command structure correctly. 
+    * Recommended to use iMove() methods to fill the command structure correctly. 
     * Branches to the moveXXXX() methods. For details see docs for those methods. 
     * Preset the speed using setSpeed().
     * Warning: Collides with queued commands if called individually. 
+    *
     * @param[in] <*cmd> Pointer to type BotCommand, the prefilled command structure,
     */
     void iExeCommand(BotCommand *cmd);
@@ -280,9 +287,9 @@
 
     /** High level, immediate: Both wheels get stopped, and turned off
     * updates the wheel state wheelsState, does not call the callback handler!
-    * It does not empty the queue. Adding new elements into the queue after
-    * calling iStop() would continue using all commands still in the queue. 
-    */
+    * It does not empty the queue. 
+    * Adding new elements into the queue after calling iStop() 
+    * Would continue using all commands still in the queue.  */
     void iStop();
 
 public: 
@@ -331,33 +338,33 @@
     
     /* Mid level, immediate: turn bot backwards right, 
     * around a radius twice the bot size ,
-    * Same as  moveRevRight(turn_angle_deg, 0);
+    * Same as  moveBackRight(turn_angle_deg, 0);
     * Preset the speed using setSpeed().
     * Warning: Collides with queued commands. 
     */
-    void moveRevRight(float turn_angle_deg);
+    void moveBackRight(float turn_angle_deg);
     
     /** Mid level, immediate: turn bot backwards right, 
     * around a radius that is center_cm away from the right wheel,
     * Preset the speed using setSpeed().
     * Warning: Collides with queued commands. 
     */
-    void moveRevRight(float turn_angle_deg, float center_cm);
+    void moveBackRight(float turn_angle_deg, float center_cm);
     
     /** Mid level, immediate: turn bot backwards left, 
     * around a radius twice the bot size,
-    * Same as  moveRevLeft(turn_angle_deg, 0);
+    * Same as  moveBackLeft(turn_angle_deg, 0);
     * Preset the speed using setSpeed().
     * Warning: Collides with queued commands. 
     */
-    void moveRevLeft(float turn_angle_deg);
+    void moveBackLeft(float turn_angle_deg);
     
     /** Mid level, immediate: turn bot backwards left, 
     around a radius that is center_cm away from the left wheel,
     * Preset the speed using setSpeed().
     * Warning: Collides with queued commands. 
     */
-    void moveRevLeft(float turn_angle_deg, float center_cm);
+    void moveBackLeft(float turn_angle_deg, float center_cm);
 
     /** Mid level, immediate: turn bot on its place for a given angle.
     * positive angles turn right, negative angles turn left,
@@ -371,18 +378,6 @@
     /** Low level, immediate: sets Both wheel speeds   */ 
     void wheelsSetSpeed(float mot_speed_cm_sec);
     
-    /** Low level, immediate: command wrappers, speed, move and stop, state management 
-    */
-    void wheelSetSpeed(Wheel *Wheel, float speed_cm_sec);
-    
-    /** Low level, immediate: Left wheel Move for a given angle in a given direction 
-    * updates the wheel state wheelsState */
-    void wheelLeftRun(WheelDir dir, float rot_angle_deg);
-    
-    /** Low level, immediate: Right wheel Move for a given angle in a given direction 
-    * updates the wheel state wheelsState */
-    void wheelRightRun(WheelDir dir, float rot_angle_deg);
-
     /** Callback when left wheel stops; 
     * updates the wheel state wheelsState */
     void wheelLeftStoppedCB();
@@ -413,9 +408,8 @@
     float botSpeed_cm_sec;  
 
     /** The two wheels, as pointers to their classes */
-    wheel *wheelLeft;
-    wheel *wheelRight;
-
+    CreaMot *wheelLeft;
+    CreaMot *wheelRight;
 };