Tarek Lule
My Version of CreaBotLib
Fork of
CreaBotLib
by 
CreaLab
Diff: CreaBot.h
- Revision:
- 8:3b5b0a82b429
- Parent:
- 7:3a793ddc3490
- Child:
- 9:efe9f76d6f76
--- a/CreaBot.h Tue Jan 01 13:05:08 2019 +0000
+++ b/CreaBot.h Tue Jan 01 21:31:14 2019 +0000
@@ -1,8 +1,8 @@
/*
- * at: file CreaBot.h
- * bs_brief File contains Creabot Library.
+ * \file CreaBot.h
+ * \brief File contains Creabot Library.
- * CreaBot.h contains the class Motor, and related enums and structs.
+ * CreaBot.h contains the Motor class, and related enums and structs.
* Includes "mbed.h" and "motor.h"
* Refactorings:
@@ -11,9 +11,9 @@
* cmdbot_t -> BotCmdVerb
* cm -> dist_cm
- * at_author Tarek Lule, Francois Druilhe, et al.
- * at_date 21. Nov. 2018.
- * at_see https://os.mbed.com/users/sepp_nepp/code/CreaBotLib/ */
+ * @author Tarek Lule, Francois Druilhe, et al.
+ * @date 21. Nov. 2018.
+ * @see https://os.mbed.com/users/sepp_nepp/code/CreaBotLib/ */
// -------------------- Motor ---------------------------
@@ -23,60 +23,60 @@
#include "mbed.h"
#include "motor.h"
-#define MAX_SPEED_CM_SEC 30.0f /*star< Clamp maximum advancement speed = 30cm/sec, was MAX_SPEED */
-#define MIN_SPEED_CM_SEC 0.001f /*star< Clamp minimum advancement speed = 10um/sec */
-#define DEFAULT_SPEED_CM_SEC 2.0f /*star< Default advancement speed = 2.0cm/sec, was DEFAULT_SPEED */
+#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
-#define DEPTH_FIFO 256 /*star< Initialize the depth of the command FIFO to 256 */
+#define DEPTH_FIFO 256 /**< Initialize the depth of the command FIFO to 256 */
-/*star \enum BotCmdVerb
-* bs_brief Robot Commands Verbs, gives the movement direction
+/** \enum BotCmdVerb
+* \brief Robot Commands Verbs, gives the movement direction
* */
typedef enum {
- IDLE = 0, /*star< Command to do nothing */
- FORWARD, /*star< Advance the robot straight forward */
- BACKWARD, /*star< Advance the robot straight backwards. */
- ROTATE, /*star< Rotate around its own axis */
- LEFT, /*star< Advance in a left curve */
- RIGHT, /*star< Advance in a right curve */
- REVLEFT, /*star< Reverse in a left curve */
- REVRIGHT /*star< Reverse in a right curve */
+ 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;
-/*star \enum TMotorsState
-* bs_brief Possible states of the two motors of the Bot
+/** \enum TMotorsState
+* \brief Possible states of the two motors of the Bot
* */
typedef enum {
- LRMOTS_STOP = 0,/*star< All Motors have stopped */
- LMOT_RUNS, /*star< Left Motor runs */
- RMOT_RUNS, /*star< Right Motor runs */
- LRMOTS_RUN /*star< Both Motors run */
+ LRMOTS_STOP = 0,/**< All Motors have stopped */
+ LMOT_RUNS, /**< Left Motor runs */
+ RMOT_RUNS, /**< Right Motor runs */
+ LRMOTS_RUN /**< Both Motors run */
} TMotorsState;
-/*star \struct BotCommand
-* bs_brief Structure of a Motor Command.
+/** \struct BotCommand
+* \brief Structure of a Motor Command.
* The command structure is put into command FIFO, and treated by the FIFO-Handler */
typedef struct {
- BotCmdVerb command; /*star< General Command to give movement direction.*/
- float dist_cm; /*star< Distance in dist_cm for translational movements .*/
- float angle_deg; /*star< Angle in degree for rotational movement .*/
- void set(BotCmdVerb Acommand, float Aangle_deg, float Adist_cm); /*star< Helper; set structure fields to values */
- void set(BotCmdVerb Acommand, float Aparam); /*star< Helper; set structure fields to values */
+ 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 Aangle_deg, float Adist_cm); /**< Helper; set structure fields to values */
+ void set(BotCmdVerb Acommand, float Aparam); /**< Helper; set structure fields to values */
} BotCommand;
-/*star \struct geometries
-* bs_brief Some geometric encapsulation
+/** \struct geometries
+* \brief Some geometric encapsulation
* Holds some geometric values */
typedef struct {
float diam_cm;
float perim_cm;
float degree_per_cm;
- void setDiam( float Adiam_cm); /*star< Helper; set diameter and perim to values */
+ void setDiam( float Adiam_cm); /**< Helper; set diameter and perim to values */
} circle_geos;
-/*star \class CommandFIFO
- * bs_brief 256 elements deep Command FIFO, to puts BotCommand in a queue.
+/** \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,
@@ -86,73 +86,73 @@
*/
class CommandFIFO {
public:
- /*star Class Creator: initializes an empties FIFO
+ /** Class Creator: initializes an empties FIFO
*
* Ring buffer is allocated statically. Read and Write Index are set to 0. */
CommandFIFO();
- /*star Empty the FIFO.
+ /** 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;};
- /*star Reserve a new element at the head of the FIFO
+ /** 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.
*
- *at_return <BotCommand*> Pointer to the reserved BotCommand to write to.
+ *@return <BotCommand*> Pointer to the reserved BotCommand to write to.
*/
BotCommand *put();
void put(BotCmdVerb Acommand, float Adist_cm, float Aangle_deg);
- /*star Get and remove the oldest element at the tail of the FIFO
+ /** 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.
*
- *at_return <BotCommand*> Pointer to the oldest BotCommand.
+ *@return <BotCommand*> Pointer to the oldest BotCommand.
*/
BotCommand *get();
- /*star Access FIFO used Count.
+ /** Access FIFO used Count.
*
- *at_return <int> the number of commands in the FIFO */
+ *@return <int> the number of commands in the FIFO */
int getCount() {return Count;}
- /*star Check if 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
*
- * at_return <bool> True if FIFO is full*/
+ * @return <bool> True if FIFO is full*/
bool isFull() {return Count>=DEPTH_FIFO;}
- /*star Check if FIFO is empty.
+ /** Check if FIFO is empty.
*
* Should be checked before trying to get new elements
*
- * at_return <bool> True if FIFO is empty*/
+ * @return <bool> True if FIFO is empty*/
bool isEmpty() {return Count<=0;}
private:
- int readIdx; /*star< Index in FIFO array where to get the oldest element from. */
- int writeIdx; /*star< Index in FIFO array where to put the next new element to. */
- int Count; /*star< Counts the number of elements in array used. */
- BotCommand cmd[DEPTH_FIFO]; /*star< Actual static FIFO array where all elements reside. */
- BotCommand cmd_idle; /*star< A Constant Idle command */
+ 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 */
};
-/*star \class Creabot
+/** \class Creabot
-* bs_brief Synchronous Control of 2 motors as part of a two wheel robot
+* \brief Synchronous Control of 2 motors as part of a two wheel robot
*
* Example:
- * at_code
+ * @code
* // --- Define the Four PINs & Time of movement used for Motor drive -----
* Motor motorLeft(PA_12, PB_0, PB_1, PB_6); // Declare first the 2 motors (to avoid to have an object with 8 pins to create)
* Motor motorRight(PA_5,PA_4,PA_3,PA_1);
@@ -186,20 +186,20 @@
* while(1) {
* };
* }
- * at_endcode
+ * @endcode
*/
class Creabot {
public:
- /*star Create a Creabot object with 2 motors
+ /** Create a Creabot object with 2 motors
*
- * at_param left Motor object declared before corresponding to left motor of the Creabot
- * at_param right Motor object declared before corresponding to right motor of the Creabot
- * at_param wheel_diam_cm diameter in cm of the wheels (both muste be the same diameter)
- * at_param bot_diam_cm distance cm between center of left wheel and center of right wheel
+ * @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 wheel_diam_cm diameter in cm of the wheels (both muste 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);
- /*star Property access to Motor state */
+ /** Property access to Motor state */
TMotorsState getState() {return MotState; };
public:
@@ -224,83 +224,119 @@
bool executingFifo;
public:
- void move(BotCmdVerb moveType, float angle_or_cm);
- void move(BotCmdVerb moveType, float angle_deg, float dist_cm);
+ /** Mid level, immediate: set bot-speed parameter all future motor commands*/
+ void setBotSpeed(float Abot_speed_cm_sec);
+
+ /** Mid level, immediate: move bot according to command and parameter
+ * Use for commands that need only one parameter: FORWARD, BACKWARD, ROTATE
+ * Can also be called with IDLE, but then has no effect.
+ * Preset the speed using setBotSpeed().
+ * 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
+ */
+ void moveBot(BotCmdVerb Acommand, float Aparam);
+ void moveBot(BotCmdVerb Acommand, float Aangle_deg, float Adist_cm);
void executeCommand(BotCommand *cmd);
+ LEFT, /**< Advance in a left curve */
+ RIGHT, /**< Advance in a right curve */
+ REVLEFT, /**< Reverse in a left curve */
+ REVRIGHT /**< Reverse in a right curve */
public:
- /* Mid level access functions: set bot-speed parameter for next motor command*/
- void setBotSpeed(float Abot_speed_cm_sec);
- /* Mid level control function: move bot forward for a given distance */
+ /** Mid level, immediate: move bot forward for a given distance,
+ * Set speed with setBotSpeed, collides with queued commands. */
void moveForward(float dist_cm);
- /* Mid level control function: move bot backwards for a given distance */
+
+ /** Mid level, immediate: move bot backwards for a given distance,
+ * Set speed with setBotSpeed, collides with queued commands. */
void moveBackward(float dist_cm);
- /* Mid level control function: turn bot forward right,
- around a radius twice the bot size */
+
+ /* Mid level, immediate: turn bot forward right,
+ * around a radius twice the bot size ,
+ * Set speed with setBotSpeed, collides with queued commands. */
void moveRight(float angle_deg);
- /* Mid level control function: turn bot forward right,
- around a radius that is center_cm away from the right wheel*/
+
+ /** Mid level, immediate: turn bot forward right,
+ * around a radius that is center_cm away from the right wheel,
+ * Set speed with setBotSpeed, collides with queued commands. */
void moveRight(float angle_deg, float center_cm);
- /* Mid level control function: turn bot forward left,
- around a radius twice the bot size */
+
+ /** Mid level, immediate: turn bot forward left,
+ * around a radius twice the bot size,
+ * Set speed with setBotSpeed, collides with queued commands. */
void moveLeft(float angle_deg);
- /* Mid level control function: turn bot forward left,
- around a radius that is center_cm away from the left wheel*/
+
+ /** Mid level, immediate: turn bot forward left,
+ around a radius that is center_cm away from the left wheel,
+ Set speed with setBotSpeed, collides with queued commands. */
void moveLeft(float angle_deg, float center_cm);
- /* Mid level control function: turn bot on its place for a given angle.
- positive angles turn right, negative angles turn left*/
+
+ /** Mid level, immediate: turn bot on its place for a given angle.
+ * positive angles turn right, negative angles turn left,
+ * Set speed with setBotSpeed, collides with queued commands. */
void rotate(float angle_deg);
- /* Low Level: spends all time with waits,
- returns only once MotorState = LRMOTS_STOP,
- not recommended due its exclusive blocking behavior */
+ /** Low Level: spends all time with waits,
+ * returns only once MotorState = LRMOTS_STOP,
+ * not recommended due its exclusive blocking behavior */
void waitEndMotors();
- /* Low Level: spends all time with waits,
- returns only once MotorState = LRMOTS_STOP,
- but waits no more than max_wait_ms milli seconds,
- not recommended due its exclusive blocking behavior */
+
+ /** Low Level: spends all time with waits,
+ * returns only once MotorState = LRMOTS_STOP,
+ * but waits no more than max_wait_ms milli seconds.
+ * Not recommended due its exclusive blocking behavior */
void waitEndMotors(uint32_t max_wait_ms); // watchdog
private:
- /* geometric properties of each wheel and the bot */
- circle_geos wheel,bot;
- float ratio_wheel_bot;
- float bot_speed_cm_sec; // the requested bot speed
- /* Low level access functions: sets both motor speeds immediately */
- void setMotorsSpeed(float mot_speed_cm_sec)
- /* Low level motor command wrappers, speed, move and stop, state management */
+ /** Low level, immediate: sets both motor speeds */
+ void setMotorsSpeed(float mot_speed_cm_sec);
+
+ /** Low level, immediate: command wrappers, speed, move and stop, state management */
void setMotorSpeed(Motor *motor, float speed_cm_sec);
- /*star Commands the Left Motor to Move for a given angle in a given direction
+
+ /** Low level, immediate: Left Motor Move for a given angle in a given direction
* updates the Motor state MotState */
void moveMotorLeft(motorDir dir, float angle_deg);
- /*star Commands the Right Motor to Move for a given angle in a given direction
+
+ /** Low level, immediate: Right Motor Move for a given angle in a given direction
* updates the Motor state MotState */
void moveMotorRight(motorDir dir, float angle_deg);
- /*star Callback when left Motor stops.
+ /** Callback when left Motor stops;
* updates the Motor state MotState */
void cbLeftMotStopped();
- /*star Callback when right Motor stops.
+
+ /** Callback when right Motor stops.
* updates the Motor state MotState */
void cbRightMotStopped();
- /*star Callback when all Motors have stopped.
+
+ /** Callback when all Motors have stopped.
* updates the Motor state MotState, switch off all Phases */
void AllMotorsStopped();
- /*star Callback function pointer: if set it is called when All Motors Stopped()*/
+ /** Callback function pointer:
+ * If set non-NULL it is called when All Motors Stopped()*/
void (*extCallBack)(int status);
- /*star Motor status register, remember which of the motors still run */
+ /** Motor status register:
+ * Remembers which of the motors still run */
TMotorsState MotState;
- // The two motors, as pointers to their classes
+ /** geometric properties of each wheel and the bot */
+ circle_geos wheel,bot;
+ /** Ratio of wheel diameter and bot diameter */
+ float ratio_wheel_bot;
+ /** last requested bot speed */
+ float bot_speed_cm_sec;
+
+ /** The two motors, as pointers to their classes */
Motor *motor_left;
Motor *motor_right;
- private:
- /* members that were not used in last release
+ /* members that were already stale in last public release
* float macro_move_parameter;
* BotCommand macro_move;
* void setSpeedLeft(float speed_cm_sec);