Tarek Lule / CreaBotLib

My Version of CreaBotLib

Fork of CreaBotLib by CreaLab

CreaBot.h@9:efe9f76d6f76, 2019-01-03 (annotated)

Committer:
sepp_nepp
Date:
Thu Jan 03 23:16:46 2019 +0000
Revision:
9:efe9f76d6f76
Parent:
8:3b5b0a82b429
Child:
10:79509113310a
Publish all those major refactorings done on this library. ; In alpha state, for code review. No debug done so far.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
sepp_nepp 7:3a793ddc3490 1 /*
sepp_nepp 8:3b5b0a82b429 2 * \file CreaBot.h
sepp_nepp 8:3b5b0a82b429 3 * \brief File contains Creabot Library.
sepp_nepp 6:4d8938b686a6 4
sepp_nepp 9:efe9f76d6f76 5 * CreaBot.h contains the Creabot class, and required enums and structs.
sepp_nepp 6:4d8938b686a6 6 * Includes "mbed.h" and "motor.h"
sepp_nepp 6:4d8938b686a6 7
sepp_nepp 6:4d8938b686a6 8 * Refactorings:
sepp_nepp 9:efe9f76d6f76 9 * All variables with suffixes "_cm_sec" = speeds in centimeters per second.
sepp_nepp 9:efe9f76d6f76 10 * MotCommand -> BotCommand.
sepp_nepp 9:efe9f76d6f76 11 * cmdbot_t -> BotCmdVerb.
sepp_nepp 9:efe9f76d6f76 12 * cm -> dist_cm.
sepp_nepp 9:efe9f76d6f76 13 * 'motorxx' -> 'wheelxxx': each motor now becomes a 'wheel with a diameter'
sepp_nepp 9:efe9f76d6f76 14 * FIFO queue management merged with Creabot Class, now called Queue
sepp_nepp 9:efe9f76d6f76 15 * Queue does not use another extra ticker anymore. Instead triggers from Motor End commands.
sepp_nepp 9:efe9f76d6f76 16 * Queue is worked through, and Callback is not called, until all queue is empty.
sepp_nepp 9:efe9f76d6f76 17 *
sepp_nepp 8:3b5b0a82b429 18 * @author Tarek Lule, Francois Druilhe, et al.
sepp_nepp 8:3b5b0a82b429 19 * @date 21. Nov. 2018.
sepp_nepp 8:3b5b0a82b429 20 * @see https://os.mbed.com/users/sepp_nepp/code/CreaBotLib/ */
sepp_nepp 6:4d8938b686a6 21
sepp_nepp 9:efe9f76d6f76 22 // -------------------- wheel ---------------------------
sepp_nepp 6:4d8938b686a6 23
garphil 0:a7fb03c9ea9d 24 #ifndef CREABOT_H
garphil 0:a7fb03c9ea9d 25 #define CREABOT_H
garphil 0:a7fb03c9ea9d 26
garphil 0:a7fb03c9ea9d 27 #include "mbed.h"
garphil 0:a7fb03c9ea9d 28 #include "motor.h"
garphil 0:a7fb03c9ea9d 29
sepp_nepp 9:efe9f76d6f76 30 #define MAX_SPEED_CM_SEC 30.0f /**< Clamp maximum advancement speed = 30cm/sec, was MAX_SPEED */
sepp_nepp 9:efe9f76d6f76 31 #define MIN_SPEED_CM_SEC 0.001f /**< Clamp minimum advancement speed = 10um/sec */
sepp_nepp 8:3b5b0a82b429 32 #define DEFAULT_SPEED_CM_SEC 2.0f /**< Default advancement speed = 2.0cm/sec, was DEFAULT_SPEED */
sepp_nepp 9:efe9f76d6f76 33 #define PI 3.141592f /**< PI needed to calcuate from angle to distances */
sepp_nepp 9:efe9f76d6f76 34 #define DEPTH_Queue 256 /**< Initialize the depth of the command Queue to 256 */
garphil 0:a7fb03c9ea9d 35
sepp_nepp 8:3b5b0a82b429 36 /** \enum BotCmdVerb
sepp_nepp 8:3b5b0a82b429 37 * \brief Robot Commands Verbs, gives the movement direction
sepp_nepp 9:efe9f76d6f76 38 * IDLE is not supported at the moment
sepp_nepp 9:efe9f76d6f76 39 */
sepp_nepp 6:4d8938b686a6 40 typedef enum {
sepp_nepp 9:efe9f76d6f76 41 FORWARD, /**< Advance the robot straight forward */
sepp_nepp 9:efe9f76d6f76 42 BACKWARD, /**< Reverse the robot straight backwards */
sepp_nepp 9:efe9f76d6f76 43 ROTATE, /**< Rotate around its own axis*/
sepp_nepp 9:efe9f76d6f76 44 LEFT, /**< Advance in a left curve */
sepp_nepp 9:efe9f76d6f76 45 RIGHT, /**< Advance in a right curve */
sepp_nepp 9:efe9f76d6f76 46 BACKLEFT, /**< Reverse in a left curve */
sepp_nepp 9:efe9f76d6f76 47 BACKRIGHT /**< Reverse in a right curve */
sepp_nepp 6:4d8938b686a6 48 } BotCmdVerb;
sepp_nepp 6:4d8938b686a6 49
sepp_nepp 5:efe80c5db389 50
sepp_nepp 9:efe9f76d6f76 51 /** \enum TWheelsState
sepp_nepp 9:efe9f76d6f76 52 * \brief Possible states of the two wheels of the Bot
sepp_nepp 6:4d8938b686a6 53 * */
sepp_nepp 6:4d8938b686a6 54 typedef enum {
sepp_nepp 9:efe9f76d6f76 55 LRWHEELS_STOP = 0, /**< All wheels have stopped */
sepp_nepp 9:efe9f76d6f76 56 LWHEEL_RUNS = 1, /**< Left wheel runs */
sepp_nepp 9:efe9f76d6f76 57 RWHEEL_RUNS, = 2, /**< Right wheel runs */
sepp_nepp 9:efe9f76d6f76 58 LRWHEELS_RUN = 3, /**< Both wheels run */
sepp_nepp 9:efe9f76d6f76 59 } TWheelsState;
sepp_nepp 6:4d8938b686a6 60
sepp_nepp 8:3b5b0a82b429 61 /** \struct BotCommand
sepp_nepp 9:efe9f76d6f76 62 * \brief Structure of a wheel Command.
sepp_nepp 9:efe9f76d6f76 63 * The command structure is put into command Queue, and treated by the Queue-Handler */
sepp_nepp 6:4d8938b686a6 64 typedef struct {
sepp_nepp 8:3b5b0a82b429 65 BotCmdVerb command; /**< General Command to give movement direction.*/
sepp_nepp 8:3b5b0a82b429 66 float dist_cm; /**< Distance in dist_cm for translational movements .*/
sepp_nepp 9:efe9f76d6f76 67 float turn_angle_deg; /**< Angle in degree for rotational movement .*/
sepp_nepp 9:efe9f76d6f76 68 void set(BotCmdVerb Acommand, float Aturn_angle_deg, float Adist_cm); /**< Helper; set structure fields to values */
sepp_nepp 8:3b5b0a82b429 69 void set(BotCmdVerb Acommand, float Aparam); /**< Helper; set structure fields to values */
sepp_nepp 6:4d8938b686a6 70 } BotCommand;
sepp_nepp 6:4d8938b686a6 71
garphil 0:a7fb03c9ea9d 72
sepp_nepp 8:3b5b0a82b429 73 /** \class Creabot
garphil 0:a7fb03c9ea9d 74
sepp_nepp 9:efe9f76d6f76 75 * \brief Synchronous Control of 2 wheels as part of a two wheel robot
sepp_nepp 9:efe9f76d6f76 76 *
sepp_nepp 9:efe9f76d6f76 77 * Handles two instances of Motor from motor.h library simultaneously.
sepp_nepp 9:efe9f76d6f76 78 * Using the set distance between the wheels, allows to run pecise curves.
sepp_nepp 9:efe9f76d6f76 79 * One set of movement commands starting with iXXX are executed immediately,
sepp_nepp 9:efe9f76d6f76 80 * they override each other if issued too quickly.
sepp_nepp 9:efe9f76d6f76 81 * The other set of movement commands starting with qXXX are queued up in a
sepp_nepp 9:efe9f76d6f76 82 * waiting queue, allowing to execute them one by one in programmed order.
sepp_nepp 9:efe9f76d6f76 83 * A callback is supplied to react to the end of all programmed movements.
sepp_nepp 9:efe9f76d6f76 84 *
sepp_nepp 9:efe9f76d6f76 85 * Example:
sepp_nepp 9:efe9f76d6f76 86 * @code
sepp_nepp 9:efe9f76d6f76 87 * // --- Define the Four PINs & Time of movement used for wheel drive -----
sepp_nepp 9:efe9f76d6f76 88 * 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)
sepp_nepp 9:efe9f76d6f76 89 * Motor wheelRight(PA_5,PA_4,PA_3,PA_1);
sepp_nepp 9:efe9f76d6f76 90 * Creabot mybot(&wheelLeft, &WheelRight, 10.0f, 13.0f); // insert the wheels and indicate wheel diameter (10cm) and distance between wheels (13cm)
sepp_nepp 9:efe9f76d6f76 91 *
sepp_nepp 9:efe9f76d6f76 92 * int main() {
sepp_nepp 9:efe9f76d6f76 93 *
sepp_nepp 9:efe9f76d6f76 94 * mybot.setSpeed(12.5); // Preset speed to 12.5cm/s
sepp_nepp 9:efe9f76d6f76 95 * mybot.iMove(FORWARD,10); // Go forward of 10cm
sepp_nepp 9:efe9f76d6f76 96 * mybot.iWaitEnd(); // Wait end of Move
sepp_nepp 9:efe9f76d6f76 97 * mybot.iMove(ROTATE,90); // Start rotation of 90° around the center between wheels (two wheels running in same direction at same speed)
sepp_nepp 9:efe9f76d6f76 98 * mybot.iMove(BACKWARD,40); // Stop immediately the rotation and go backward of 40cm
sepp_nepp 9:efe9f76d6f76 99 * mybot.iWaitEnd(); // Wait end of Backward
sepp_nepp 9:efe9f76d6f76 100 * mybot.iMoveAndWait(LEFT,60); // Move Left of 60° in circle, center being the left wheel (off). Wait end of move
sepp_nepp 9:efe9f76d6f76 101 * mybot.iWaitEnd(); // Not needed, as already waited...
sepp_nepp 9:efe9f76d6f76 102 * mybot.iMoveAndWait(RIGHT,45, 33); // Move Right of 45°, center being at 33cm of the right wheel. Right wheel moving slower and on a shorter distance than left one.
sepp_nepp 9:efe9f76d6f76 103 * mybot.iMoveAndWait(ROTATE,90);
sepp_nepp 9:efe9f76d6f76 104 * mybot.iMove(ROTATE,-90); // Opposite direction.
sepp_nepp 9:efe9f76d6f76 105 * mybot.iWaitEnd(6); // with time-out => if after 6s the move is not ended, continue the execution
sepp_nepp 9:efe9f76d6f76 106 * mybot.iStop(); // Stop the movement in case it was not ended before ...
sepp_nepp 9:efe9f76d6f76 107 *
sepp_nepp 9:efe9f76d6f76 108 * // Same with a Queue of command, opposite to the move, receiving a new command will not stop the current execution, but the bot will store it.
sepp_nepp 9:efe9f76d6f76 109 * mybot.qMove(FORWARD,10); // Already starting...
sepp_nepp 9:efe9f76d6f76 110 * mybot.qMove(BACKWARD,10); // will wait end of previous command to go
sepp_nepp 9:efe9f76d6f76 111 * mybot.qMove(ROTATE,120.0);
sepp_nepp 9:efe9f76d6f76 112 * mybot.qMove(LEFT, 30, 120);
sepp_nepp 9:efe9f76d6f76 113 * mybot.qMove(RIGHT, 25);
sepp_nepp 9:efe9f76d6f76 114 * ... // insert other code here that executes while the motors continue to move
sepp_nepp 9:efe9f76d6f76 115 * mybot.iWaitEnd(100000); // wait until Queue end... can flush anytime with stopMove...
sepp_nepp 9:efe9f76d6f76 116 * mybot.qEmpty(); // before end... Flush the Queue and remove all instructions…
sepp_nepp 9:efe9f76d6f76 117 *
sepp_nepp 9:efe9f76d6f76 118 * while(1) {
sepp_nepp 9:efe9f76d6f76 119 * };
sepp_nepp 9:efe9f76d6f76 120 * }
sepp_nepp 9:efe9f76d6f76 121 * @endcode
sepp_nepp 9:efe9f76d6f76 122 */
sepp_nepp 5:efe80c5db389 123
garphil 0:a7fb03c9ea9d 124 class Creabot {
garphil 0:a7fb03c9ea9d 125 public:
sepp_nepp 9:efe9f76d6f76 126 /** Create a Creabot object with 2 wheels
garphil 0:a7fb03c9ea9d 127 *
sepp_nepp 9:efe9f76d6f76 128 * @param <left motor> object, corresponding to left wheel of the Creabot
sepp_nepp 9:efe9f76d6f76 129 * @param <right motor> object, corresponding to right wheel of the Creabot
sepp_nepp 9:efe9f76d6f76 130 * @param <wheel_diam_cm> diameter in cm of the wheels (both must be the same diameter)
sepp_nepp 9:efe9f76d6f76 131 * @param <bot_diam_cm> distance cm between center of left wheel and center of right wheel
garphil 0:a7fb03c9ea9d 132 */
sepp_nepp 9:efe9f76d6f76 133 Creabot(motor *left, motor *right, float wheel_diam_cm, float bot_diam_cm);
sepp_nepp 6:4d8938b686a6 134
sepp_nepp 9:efe9f76d6f76 135 /** Property access to wheel state, indicating which of the wheels are moving */
sepp_nepp 9:efe9f76d6f76 136 TWheelsState getState() {return wheelsState; };
garphil 0:a7fb03c9ea9d 137
sepp_nepp 9:efe9f76d6f76 138 /** Setup a Callback method. It is called when all programmed movements are finished. */
sepp_nepp 9:efe9f76d6f76 139 void setCallBack(void (*Acallback)(int status)); { extCallBack = Acallback; };
sepp_nepp 9:efe9f76d6f76 140
sepp_nepp 9:efe9f76d6f76 141 /** High level: set bot-speed parameter for all future wheel commands.
sepp_nepp 9:efe9f76d6f76 142 * The set speed is used for immediate and queued movements alike.
sepp_nepp 9:efe9f76d6f76 143 * In a curve movement it determines the speed of the outer wheel.
sepp_nepp 9:efe9f76d6f76 144 */
sepp_nepp 9:efe9f76d6f76 145 void setSpeed(float AbotSpeed_cm_sec);
sepp_nepp 7:3a793ddc3490 146
sepp_nepp 7:3a793ddc3490 147 public:
sepp_nepp 9:efe9f76d6f76 148
sepp_nepp 9:efe9f76d6f76 149 /** High level, queued : move bot according to command and parameter
sepp_nepp 9:efe9f76d6f76 150 * Composes a BotCommand and appends it to the queue for queued execution.
sepp_nepp 9:efe9f76d6f76 151 * Use for commands that need only one parameter: FORWARD, BACKWARD, ROTATE
sepp_nepp 9:efe9f76d6f76 152 * For details refer to docu of moveForward(), moveBackward(), moveRotate().
sepp_nepp 9:efe9f76d6f76 153 * Can also be called with IDLE, but then has no effect.
sepp_nepp 9:efe9f76d6f76 154 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 155 * @param[in] <Acommand> Requested movement, of type BotCmdVerb.
sepp_nepp 9:efe9f76d6f76 156 * @param[in] <Aparam> Requested amount, defines angle for ROTATE, or distance for FORWARD, BACKWARD.
sepp_nepp 9:efe9f76d6f76 157 */
sepp_nepp 9:efe9f76d6f76 158 void qMove(BotCmdVerb Acommand, float Aparam);
sepp_nepp 9:efe9f76d6f76 159
sepp_nepp 9:efe9f76d6f76 160 /** High level, queued : move bot according to command and parameters
sepp_nepp 9:efe9f76d6f76 161 * Composes a BotCommand and appends it to the queue for queued execution.
sepp_nepp 9:efe9f76d6f76 162 * Use for commands that need two parameters: LEFT, RIGHT, BACKLEFT, BACKRIGHT
sepp_nepp 9:efe9f76d6f76 163 * For details refer to docu of moveLeft(), moveRight(), moveRevLeft(), moveRevRight().
sepp_nepp 9:efe9f76d6f76 164 * Can also be called with IDLE, but then has no effect.
sepp_nepp 9:efe9f76d6f76 165 *
sepp_nepp 9:efe9f76d6f76 166 * Reserves a new element at the head of the Queue
sepp_nepp 9:efe9f76d6f76 167 *
sepp_nepp 9:efe9f76d6f76 168 * Adds incoming commands at the head of the ring buffer at position writeIdx,
sepp_nepp 9:efe9f76d6f76 169 * If Queue is full, it passes back NULL
sepp_nepp 9:efe9f76d6f76 170 * Otherwise Advances the write index once and returns a pointer the next free command struct.
sepp_nepp 9:efe9f76d6f76 171 * The caller then must fill the command structure at that position.
sepp_nepp 9:efe9f76d6f76 172 * Do not free memory associated to the pointer.
sepp_nepp 9:efe9f76d6f76 173 *
sepp_nepp 9:efe9f76d6f76 174 * @param[in] <Acommand> Requested movement, of type BotCmdVerb.
sepp_nepp 9:efe9f76d6f76 175 * @param[in] <Aturn_angle_deg> Requested angle in degrees.
sepp_nepp 9:efe9f76d6f76 176 * @param[in] <Adist_cm> Requested distance in centimeters.
sepp_nepp 9:efe9f76d6f76 177 */
sepp_nepp 9:efe9f76d6f76 178 void qMove(BotCmdVerb Acommand, float Aturn_angle_deg, float Adist_cm);
sepp_nepp 9:efe9f76d6f76 179
sepp_nepp 9:efe9f76d6f76 180 /** Execute and remove the oldest element at the tail of the Queue
sepp_nepp 9:efe9f76d6f76 181 *
sepp_nepp 9:efe9f76d6f76 182 * If Queue is empty, nothing happens
sepp_nepp 9:efe9f76d6f76 183 * Otherwise executes oldest commands from the tail of the ring buffer at position readIdx,
sepp_nepp 9:efe9f76d6f76 184 * Then advances the read index once.
sepp_nepp 9:efe9f76d6f76 185 */
sepp_nepp 9:efe9f76d6f76 186 void qExecuteNext();
sepp_nepp 9:efe9f76d6f76 187
sepp_nepp 9:efe9f76d6f76 188 /** Public access of Queue used Count.
sepp_nepp 9:efe9f76d6f76 189 *
sepp_nepp 9:efe9f76d6f76 190 * @return <int> the number of commands in the Queue */
sepp_nepp 9:efe9f76d6f76 191 int qCount() {return Count;}
sepp_nepp 8:3b5b0a82b429 192
sepp_nepp 9:efe9f76d6f76 193 /* Immediately end all queue activites, and the motor
sepp_nepp 9:efe9f76d6f76 194 * Does not call the external callback handler */
sepp_nepp 9:efe9f76d6f76 195 void qStopAll();
sepp_nepp 9:efe9f76d6f76 196
sepp_nepp 9:efe9f76d6f76 197 private:
sepp_nepp 9:efe9f76d6f76 198 /** Empty the Queue.
sepp_nepp 9:efe9f76d6f76 199 * Since ring buffer is static, it suffice to set all pointers to 0, commands are left in memory. */
sepp_nepp 9:efe9f76d6f76 200 void qReset() { qBlock = true; readIdx=writeIdx=Count=0; qBlock = false; qCollide = false;};
sepp_nepp 9:efe9f76d6f76 201
sepp_nepp 9:efe9f76d6f76 202 /** Check if Queue is full.
sepp_nepp 9:efe9f76d6f76 203 *
sepp_nepp 9:efe9f76d6f76 204 * Space is limited to DEPTH_Queue=256 BotCommand elements.
sepp_nepp 9:efe9f76d6f76 205 * Should be checked before trying to put new elements
sepp_nepp 9:efe9f76d6f76 206 * @return <bool> True if Queue is full*/
sepp_nepp 9:efe9f76d6f76 207 bool qIsFull() {return Count>=DEPTH_Queue;}
sepp_nepp 9:efe9f76d6f76 208
sepp_nepp 9:efe9f76d6f76 209 /** Check if Queue is empty.
sepp_nepp 9:efe9f76d6f76 210 * Should be checked before trying to get new elements
sepp_nepp 9:efe9f76d6f76 211 * @return <bool> True if Queue is empty*/
sepp_nepp 9:efe9f76d6f76 212 bool qIsEmpty() {return Count<=0;}
sepp_nepp 9:efe9f76d6f76 213
sepp_nepp 9:efe9f76d6f76 214 /** 256 elements deep Command Queue, to put BotCommand in a queue.
sepp_nepp 9:efe9f76d6f76 215 * Stores all BotCommand in this static 256 array used as a circular ring buffer. */
sepp_nepp 9:efe9f76d6f76 216 BotCommand cmd[DEPTH_Queue]; /**< Actual static Queue array where all elements reside. */
sepp_nepp 9:efe9f76d6f76 217
sepp_nepp 9:efe9f76d6f76 218 int writeIdx; /**< Index in Queue array where to put the next new element to. */
sepp_nepp 9:efe9f76d6f76 219 int readIdx; /**< Index in Queue array where to get the oldest element from. */
sepp_nepp 9:efe9f76d6f76 220 int Count; /**< Counts and keeps track of the number of elements in array used. */
sepp_nepp 9:efe9f76d6f76 221 bool qBlock; /**< Blocks read access while a write is ongoing. */
sepp_nepp 9:efe9f76d6f76 222 bool qCollide;/**< Indicates a colliding access to the queue. */
sepp_nepp 9:efe9f76d6f76 223 public:
sepp_nepp 9:efe9f76d6f76 224 /** High level, immediate: move bot and wait for movement end.
sepp_nepp 9:efe9f76d6f76 225 * Simple wrapper for botMove(Acommand,Aparam) and waitEndWheels().
sepp_nepp 9:efe9f76d6f76 226 * Refer to those methods for further docs.
sepp_nepp 9:efe9f76d6f76 227 */
sepp_nepp 9:efe9f76d6f76 228 void iMoveAndWait(BotCmdVerb Acommand, float Aparam);
sepp_nepp 9:efe9f76d6f76 229
sepp_nepp 9:efe9f76d6f76 230 /** High level, immediate: move bot and wait for movement end.
sepp_nepp 9:efe9f76d6f76 231 * Simple wrapper for botMove(Acommand,Aturn_angle_deg,Adist_cm) and waitEndWheels().
sepp_nepp 9:efe9f76d6f76 232 * Refer to those methods for further docs.
sepp_nepp 9:efe9f76d6f76 233 */
sepp_nepp 9:efe9f76d6f76 234 void iMoveAndWait(BotCmdVerb Acommand, float Aturn_angle_deg, float Adist_cm);
sepp_nepp 9:efe9f76d6f76 235
sepp_nepp 9:efe9f76d6f76 236 /** High level, immediate: move bot according to command and parameter
sepp_nepp 9:efe9f76d6f76 237 * Composes a BotCommand and passes it to executeCommand().
sepp_nepp 8:3b5b0a82b429 238 * Use for commands that need only one parameter: FORWARD, BACKWARD, ROTATE
sepp_nepp 9:efe9f76d6f76 239 * For details refer to docu of moveForward(), moveBackward(), moveRotate().
sepp_nepp 8:3b5b0a82b429 240 * Can also be called with IDLE, but then has no effect.
sepp_nepp 9:efe9f76d6f76 241 * Preset the speed using setSpeed().
sepp_nepp 8:3b5b0a82b429 242 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 243 * @param[in] <Acommand> Requested movement, of type BotCmdVerb.
sepp_nepp 9:efe9f76d6f76 244 * @param[in] <Aparam> Requested amount, defines angle for ROTATE, or distance for FORWARD, BACKWARD.
sepp_nepp 9:efe9f76d6f76 245 */
sepp_nepp 9:efe9f76d6f76 246 void iMove(BotCmdVerb Acommand, float Aparam);
sepp_nepp 9:efe9f76d6f76 247
sepp_nepp 9:efe9f76d6f76 248 /** High level, immediate: move bot according to command and parameters
sepp_nepp 9:efe9f76d6f76 249 * Composes a BotCommand and passes it to executeCommand().
sepp_nepp 9:efe9f76d6f76 250 * Use for commands that need two parameters: LEFT, RIGHT, BACKLEFT, BACKRIGHT
sepp_nepp 9:efe9f76d6f76 251 * For details refer to docu of moveLeft(), moveRight(), moveRevLeft(), moveRevRight().
sepp_nepp 9:efe9f76d6f76 252 * Can also be called with IDLE, but then has no effect.
sepp_nepp 9:efe9f76d6f76 253 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 254 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 255 * @param[in] <Acommand> Requested movement, of type BotCmdVerb.
sepp_nepp 9:efe9f76d6f76 256 * @param[in] <Aturn_angle_deg> Requested angle in degrees.
sepp_nepp 9:efe9f76d6f76 257 * @param[in] <Adist_cm> Requested distance in centimeters.
sepp_nepp 8:3b5b0a82b429 258 */
sepp_nepp 9:efe9f76d6f76 259 void iMove(BotCmdVerb Acommand, float Aturn_angle_deg, float Adist_cm);
sepp_nepp 9:efe9f76d6f76 260
sepp_nepp 9:efe9f76d6f76 261 /** High level, immediate: move bot according to prefilled command structures.
sepp_nepp 9:efe9f76d6f76 262 * Recommended to use botMove() methods to fill the command structure correctly.
sepp_nepp 9:efe9f76d6f76 263 * Branches to the moveXXXX() methods. For details see docs for those methods.
sepp_nepp 9:efe9f76d6f76 264 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 265 * Warning: Collides with queued commands if called individually.
sepp_nepp 9:efe9f76d6f76 266 * @param[in] <*cmd> Pointer to type BotCommand, the prefilled command structure,
sepp_nepp 9:efe9f76d6f76 267 */
sepp_nepp 9:efe9f76d6f76 268 void iExeCommand(BotCommand *cmd);
sepp_nepp 9:efe9f76d6f76 269
sepp_nepp 9:efe9f76d6f76 270 /** High Level: spends all time with waits,
sepp_nepp 9:efe9f76d6f76 271 * returns only once wheelState = LRWHEELS_STOP,
sepp_nepp 9:efe9f76d6f76 272 * not recommended due its blocking behavior */
sepp_nepp 9:efe9f76d6f76 273 void iWaitEnd();
sepp_nepp 9:efe9f76d6f76 274
sepp_nepp 9:efe9f76d6f76 275 /** High Level: spends all time with waits,
sepp_nepp 9:efe9f76d6f76 276 * returns only once wheelState = LRWHEELS_STOP,
sepp_nepp 9:efe9f76d6f76 277 * but waits no more than max_wait_ms milli seconds.
sepp_nepp 9:efe9f76d6f76 278 * Not recommended due its blocking behavior */
sepp_nepp 9:efe9f76d6f76 279 void iWaitEnd(uint32_t max_wait_ms); // time-out
sepp_nepp 9:efe9f76d6f76 280
sepp_nepp 9:efe9f76d6f76 281 /** High level, immediate: Both wheels get stopped, and turned off
sepp_nepp 9:efe9f76d6f76 282 * updates the wheel state wheelsState, does not call the callback handler!
sepp_nepp 9:efe9f76d6f76 283 * It does not empty the queue. Adding new elements into the queue after
sepp_nepp 9:efe9f76d6f76 284 * calling iStop() would continue using all commands still in the queue.
sepp_nepp 9:efe9f76d6f76 285 */
sepp_nepp 9:efe9f76d6f76 286 void iStop();
garphil 0:a7fb03c9ea9d 287
sepp_nepp 7:3a793ddc3490 288 public:
sepp_nepp 5:efe80c5db389 289
sepp_nepp 9:efe9f76d6f76 290 /** Mid level, immediate: advance bot straight forward for a given distance,
sepp_nepp 9:efe9f76d6f76 291 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 292 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 293 */
sepp_nepp 7:3a793ddc3490 294 void moveForward(float dist_cm);
sepp_nepp 8:3b5b0a82b429 295
sepp_nepp 9:efe9f76d6f76 296 /** Mid level, immediate: reverse bot straight backwards for a given distance,
sepp_nepp 9:efe9f76d6f76 297 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 298 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 299 */
sepp_nepp 7:3a793ddc3490 300 void moveBackward(float dist_cm);
sepp_nepp 8:3b5b0a82b429 301
sepp_nepp 8:3b5b0a82b429 302 /* Mid level, immediate: turn bot forward right,
sepp_nepp 8:3b5b0a82b429 303 * around a radius twice the bot size ,
sepp_nepp 9:efe9f76d6f76 304 * Same as moveRight(turn_angle_deg, 0);
sepp_nepp 9:efe9f76d6f76 305 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 306 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 307 */
sepp_nepp 9:efe9f76d6f76 308 void moveRight(float turn_angle_deg);
sepp_nepp 8:3b5b0a82b429 309
sepp_nepp 8:3b5b0a82b429 310 /** Mid level, immediate: turn bot forward right,
sepp_nepp 8:3b5b0a82b429 311 * around a radius that is center_cm away from the right wheel,
sepp_nepp 9:efe9f76d6f76 312 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 313 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 314 */
sepp_nepp 9:efe9f76d6f76 315 void moveRight(float turn_angle_deg, float center_cm);
sepp_nepp 8:3b5b0a82b429 316
sepp_nepp 8:3b5b0a82b429 317 /** Mid level, immediate: turn bot forward left,
sepp_nepp 8:3b5b0a82b429 318 * around a radius twice the bot size,
sepp_nepp 9:efe9f76d6f76 319 * Same as moveLeft(turn_angle_deg, 0);
sepp_nepp 9:efe9f76d6f76 320 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 321 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 322 */
sepp_nepp 9:efe9f76d6f76 323 void moveLeft(float turn_angle_deg);
sepp_nepp 8:3b5b0a82b429 324
sepp_nepp 8:3b5b0a82b429 325 /** Mid level, immediate: turn bot forward left,
sepp_nepp 9:efe9f76d6f76 326 * around a radius that is center_cm away from the left wheel,
sepp_nepp 9:efe9f76d6f76 327 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 328 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 329 */
sepp_nepp 9:efe9f76d6f76 330 void moveLeft(float turn_angle_deg, float center_cm);
sepp_nepp 9:efe9f76d6f76 331
sepp_nepp 9:efe9f76d6f76 332 /* Mid level, immediate: turn bot backwards right,
sepp_nepp 9:efe9f76d6f76 333 * around a radius twice the bot size ,
sepp_nepp 9:efe9f76d6f76 334 * Same as moveRevRight(turn_angle_deg, 0);
sepp_nepp 9:efe9f76d6f76 335 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 336 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 337 */
sepp_nepp 9:efe9f76d6f76 338 void moveRevRight(float turn_angle_deg);
sepp_nepp 9:efe9f76d6f76 339
sepp_nepp 9:efe9f76d6f76 340 /** Mid level, immediate: turn bot backwards right,
sepp_nepp 9:efe9f76d6f76 341 * around a radius that is center_cm away from the right wheel,
sepp_nepp 9:efe9f76d6f76 342 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 343 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 344 */
sepp_nepp 9:efe9f76d6f76 345 void moveRevRight(float turn_angle_deg, float center_cm);
sepp_nepp 9:efe9f76d6f76 346
sepp_nepp 9:efe9f76d6f76 347 /** Mid level, immediate: turn bot backwards left,
sepp_nepp 9:efe9f76d6f76 348 * around a radius twice the bot size,
sepp_nepp 9:efe9f76d6f76 349 * Same as moveRevLeft(turn_angle_deg, 0);
sepp_nepp 9:efe9f76d6f76 350 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 351 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 352 */
sepp_nepp 9:efe9f76d6f76 353 void moveRevLeft(float turn_angle_deg);
sepp_nepp 9:efe9f76d6f76 354
sepp_nepp 9:efe9f76d6f76 355 /** Mid level, immediate: turn bot backwards left,
sepp_nepp 8:3b5b0a82b429 356 around a radius that is center_cm away from the left wheel,
sepp_nepp 9:efe9f76d6f76 357 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 358 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 359 */
sepp_nepp 9:efe9f76d6f76 360 void moveRevLeft(float turn_angle_deg, float center_cm);
sepp_nepp 9:efe9f76d6f76 361
sepp_nepp 8:3b5b0a82b429 362 /** Mid level, immediate: turn bot on its place for a given angle.
sepp_nepp 8:3b5b0a82b429 363 * positive angles turn right, negative angles turn left,
sepp_nepp 9:efe9f76d6f76 364 * Preset the speed using setSpeed().
sepp_nepp 9:efe9f76d6f76 365 * Warning: Collides with queued commands.
sepp_nepp 9:efe9f76d6f76 366 */
sepp_nepp 9:efe9f76d6f76 367 void moveRotate(float turn_angle_deg);
sepp_nepp 7:3a793ddc3490 368
sepp_nepp 6:4d8938b686a6 369 private:
sepp_nepp 7:3a793ddc3490 370
sepp_nepp 9:efe9f76d6f76 371 /** Low level, immediate: sets Both wheel speeds */
sepp_nepp 9:efe9f76d6f76 372 void wheelsSetSpeed(float mot_speed_cm_sec);
sepp_nepp 8:3b5b0a82b429 373
sepp_nepp 9:efe9f76d6f76 374 /** Low level, immediate: command wrappers, speed, move and stop, state management
sepp_nepp 9:efe9f76d6f76 375 */
sepp_nepp 9:efe9f76d6f76 376 void wheelSetSpeed(Wheel *Wheel, float speed_cm_sec);
sepp_nepp 8:3b5b0a82b429 377
sepp_nepp 9:efe9f76d6f76 378 /** Low level, immediate: Left wheel Move for a given angle in a given direction
sepp_nepp 9:efe9f76d6f76 379 * updates the wheel state wheelsState */
sepp_nepp 9:efe9f76d6f76 380 void wheelLeftRun(WheelDir dir, float rot_angle_deg);
sepp_nepp 8:3b5b0a82b429 381
sepp_nepp 9:efe9f76d6f76 382 /** Low level, immediate: Right wheel Move for a given angle in a given direction
sepp_nepp 9:efe9f76d6f76 383 * updates the wheel state wheelsState */
sepp_nepp 9:efe9f76d6f76 384 void wheelRightRun(WheelDir dir, float rot_angle_deg);
sepp_nepp 7:3a793ddc3490 385
sepp_nepp 9:efe9f76d6f76 386 /** Callback when left wheel stops;
sepp_nepp 9:efe9f76d6f76 387 * updates the wheel state wheelsState */
sepp_nepp 9:efe9f76d6f76 388 void wheelLeftStoppedCB();
sepp_nepp 8:3b5b0a82b429 389
sepp_nepp 9:efe9f76d6f76 390 /** Callback when right wheel stops.
sepp_nepp 9:efe9f76d6f76 391 * updates the wheel state wheelsState */
sepp_nepp 9:efe9f76d6f76 392 void wheelRightStoppedCB();
sepp_nepp 8:3b5b0a82b429 393
sepp_nepp 9:efe9f76d6f76 394 /** Callback when all wheels have stopped.
sepp_nepp 9:efe9f76d6f76 395 * updates the wheel state wheelsState, switch off all Phases */
sepp_nepp 9:efe9f76d6f76 396 void wheelsAllStoppedCB();
sepp_nepp 7:3a793ddc3490 397
sepp_nepp 8:3b5b0a82b429 398 /** Callback function pointer:
sepp_nepp 9:efe9f76d6f76 399 * If set non-NULL it is called when All wheels Stopped()*/
sepp_nepp 7:3a793ddc3490 400 void (*extCallBack)(int status);
sepp_nepp 7:3a793ddc3490 401
sepp_nepp 9:efe9f76d6f76 402 /** Wheel status register:
sepp_nepp 9:efe9f76d6f76 403 * Remembers which of the wheels still run */
sepp_nepp 9:efe9f76d6f76 404 TWheelsState wheelsState;
sepp_nepp 7:3a793ddc3490 405
sepp_nepp 9:efe9f76d6f76 406 /** geometric properties of the bot */
sepp_nepp 9:efe9f76d6f76 407 float botDiameter;
sepp_nepp 9:efe9f76d6f76 408
sepp_nepp 8:3b5b0a82b429 409 /** Ratio of wheel diameter and bot diameter */
sepp_nepp 8:3b5b0a82b429 410 float ratio_wheel_bot;
sepp_nepp 9:efe9f76d6f76 411
sepp_nepp 8:3b5b0a82b429 412 /** last requested bot speed */
sepp_nepp 9:efe9f76d6f76 413 float botSpeed_cm_sec;
sepp_nepp 8:3b5b0a82b429 414
sepp_nepp 9:efe9f76d6f76 415 /** The two wheels, as pointers to their classes */
sepp_nepp 9:efe9f76d6f76 416 wheel *wheelLeft;
sepp_nepp 9:efe9f76d6f76 417 wheel *wheelRight;
sepp_nepp 5:efe80c5db389 418
garphil 0:a7fb03c9ea9d 419 };
garphil 0:a7fb03c9ea9d 420
sepp_nepp 9:efe9f76d6f76 421
garphil 0:a7fb03c9ea9d 422 #endif