My Version of CreaBotLib
Fork of CreaBotLib by
Diff: CreaBot.h
- Revision:
- 10:79509113310a
- Parent:
- 9:efe9f76d6f76
- Child:
- 11:5a94af0afa12
diff -r efe9f76d6f76 -r 79509113310a CreaBot.h --- 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; };