My Version of CreaBotLib
Fork of CreaBotLib by
Diff: CreaBot.h
- Revision:
- 8:3b5b0a82b429
- Parent:
- 7:3a793ddc3490
- Child:
- 9:efe9f76d6f76
diff -r 3a793ddc3490 -r 3b5b0a82b429 CreaBot.h --- 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);