My Version of the Crealab MotorLib.
Fork of MotorLib by
Diff: motor.h
- Revision:
- 23:6060422cd6eb
- Parent:
- 22:d2c742bdae16
--- a/motor.h Thu Jan 03 23:15:42 2019 +0000 +++ b/motor.h Wed Apr 17 21:48:14 2019 +0000 @@ -1,10 +1,12 @@ /** - * @file motor.h - * \brief File contains Crealab Motor Library. + * @file CreaMot.h + * \brief File contains Crealab CreaMot Library. - * motor.h contains the class Motor, and related enums and structs. + * CreaMot.h contains the class CreaMot, and related enums and structs. * Includes only "mbed.h". - + * + * MotStatus structure is dissolved into the CreaMot Class + * * Rotation directions are now consistently called Clockwise, and Counterclockwise (CCW), * instead of mix them with Left and Right. * Doxygens Tags are preceeded by either a backslash @\ or by an at symbol @@. @@ -13,35 +15,38 @@ * @date 01. Nov. 2018. * @see https://os.mbed.com/users/sepp_nepp/code/MotorLib/ */ - // -------------------- Motor --------------------------- + // -------------------- CreaMot --------------------------- #ifndef MOTOR_H #define MOTOR_H #include "mbed.h" -#define MOTOR_STEP_TIME_MIN_US 700 /**< Shortest Time between two motor steps = 0.7ms, was MOTOR_STEP_TIME_MIN*/ -#define MOTOR_STEP_TIME_DEFAULT_US 5000 /**< Default Time between two motor steps = 5ms, was MOTOR_STEP_TIME_DEFAULT*/ -#define MOTOR_STEPS_FOR_A_TURN 4096 /**< Default number of motor steps to complete a turn = 4096 steps */ +#define MOTOR_STEP_TIME_MIN_US 700 /**< Shortest Time between two CreaMot steps = 0.7ms, was MOTOR_STEP_TIME_MIN*/ +#define MOTOR_STEP_TIME_DEFAULT_US 5000 /**< Default Time between two CreaMot steps = 5ms, was MOTOR_STEP_TIME_DEFAULT*/ +#define MOTOR_STEPS_FOR_A_TURN 4096 /**< Default number of CreaMot steps to complete a turn = 4096 steps */ #define CLOCKWISE true /**< Constant for Clockwise direction */ #define COUNTERCLOCKWISE false /**< Constant for Counter-Clockwise direction */ -#define MIN_SPEED_CM_SEC 0.1f /**< Constant for minimum speed in cm/sec */ +#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 PI 3.141592f /** PI needed to calcuate from angle to distances */ +#define PI_OVER_180 (PI/180.0f) /** needed to translate from angle to circumference */ /** \enum motStates -* \brief Possible States of Motor state machine +* \brief Possible States of CreaMot state machine * * Motor_CALIB is deprecated, was removed from the enum structure */ typedef enum { Motor_OFF = 0, /**< All phase currents is off, replaces Motor_STOP. */ - Motor_ZERO, /**< Motor at phase position 0 and ON, only reached by call of Zero() procedure. */ - Motor_ON, /**< Phases are engaged, but Motor state machine stopped, replaces Motor_PAUSE. */ - Motor_RUN /**< Phases are engaged, and Motor state machine runs*/ + Motor_ZERO, /**< CreaMot at phase position 0 and ON, only reached by call of Zero() procedure. */ + Motor_ON, /**< Phases are engaged, but CreaMot state machine stopped, replaces Motor_PAUSE. */ + Motor_RUN /**< Phases are engaged, and CreaMot state machine runs*/ } motStates; /** \enum motCmands -* \brief Commands that are handled by the Motor state machine +* \brief Commands that are handled by the CreaMot state machine * -* These Commands are issued asynchonously by call Motor class methods. +* These Commands are issued asynchonously by calling CreaMot class methods. * They are executed in the state machine called by the ticker handler. * * OFF and STOP commands do not go through the state machine. @@ -50,72 +55,65 @@ */ typedef enum { MOTOR_nop = 0, /**< No active command to execute. */ - MOTOR_run, /**< Run Motor until Nsteps are achieved. */ - MOTOR_stop, /**< Stop immediately all activity, turn off Motor. */ - MOTOR_pause /**< Motor is temporarily paused from the state run. */ + MOTOR_run, /**< Run CreaMot until Nsteps are achieved. */ + MOTOR_stop, /**< Stop immediately all activity, turn off CreaMot. */ + MOTOR_pause /**< CreaMot is temporarily paused from the state run. */ } motCmands; -/** \struct MotStatus -* \brief Structure of Motor Status registers. -* -* Used by Motor Class to hold all Status 'Registers'. -* The structure can be requested to get by Motor.getStatus(). -*/ -typedef struct { - motStates state; /**< General state that the motor state machine is in.*/ - motCmands cmd; /**< Command asked to be executed currently by the state machine.*/ - bool ClockWise; /**< Direction that the Motor is asked to run. True if Clockwise */ - int32_t NSteps; /**< Number of steps remain for the Motor to run. - NSteps=0: all steps finished; NSteps<0: indicates to run "forever" */ - bool TickIsAttached; - /**< Indicates if Ticker is attached. - Ticker is automatically attached while Motor runs, or paused; - detaches when finished a run, or stopped. */ - void set(motCmands aCmd, bool AClockWise, int32_t aNSteps); - /**< Helper; set Command, Direction and NSteps in one call. */ -} MotStatus; - /** ATTENTION UNDER CONSTRUCTION, DO NOT YET USE. * -*Class of a Four Phase Stepper Motor. +* Class of a Four Phase Stepper CreaMot. +* +* Perform Runs for number of steps, or given amount angle, but also Low-Level steps. * -*Perform Runs for number of steps, or given amount angle, but also Low-Level steps. +* High-Level Run functions have 'Run' in their name. +* They rely on tickers and return immediately after ticker is set up. +* A state-machine evaluates the one ongoing command versus the CreaMot state at every tick. +* When End of Run is detected tickers stop, and CreaMot turns off. * -*High-Level Run functions have 'Run' in their name. -*They rely on tickers and return immediately after ticker is set up. -*A state-machine evaluates commands versus the Motor state at every tick. -*When End of Run is detected tickers stop, and Motor turns off. +* To define the speed of the CreaMot set the variable StepTime_us, either by +* a) Using the createor CreaMot(...., uint32_t AStepTime_us); +* b) Calling function setStepTime_us(uint32_t AStepTime_us); any time +* c) or leave it to the default value MOTOR_STEP_TIME_DEFAULT_US = 5000 * -*Callbacks can be attached to react to 'end of run' events. +* To be able to run the CreaMot for a given angle, set the number of steps per full turn +* with the function "setStepsFullTurn" +* That value defaults to MOTOR_STEPS_FOR_A_TURN = 4096 +* +* To be able to run the CreaMot for a given perimeter distance in centimeters, +* set the wheel diameter with the function setDiamCM( float Adiam_cm); +* +* Callbacks can be attached to react to 'end of run' events. +* *Attention: the attached Callback is called within a Ticker Callback. * Your code you execute in the Callback should be short, must not use waits, or any long routines. -* Do not call any Motor run commands in the callback, as it creates conflict situations. +* Do not call any CreaMot run commands in the callback, as it creates conflict situations. * Long Callback code may impair this and any other Ticker functions that run in your application. * *Low-Level functions directly talk to the hardware without ticker. -*Use of Low-Level functions while tickers still run may lead to unexpected behavior. +* Use of Low-Level functions while tickers still run may lead to unexpected behavior. * * NB: all times are uint32_t, step numbers are int32_t */ -class Motor +class CreaMot { public: - /** Motor Class Creator + /** CreaMot Class Creator * * Creates the class, initiallizes all fields, creates Phase Pins. - * Time between two steps defaults here to MOTOR_STEP_TIME_DEFAULT_US=5000usec. + * Time between two steps defaults here to MOTOR_STEP_TIME_DEFAULT_US = 5000usec. * Pin names are used to create digital outputs: Pin0 = new DigitalOut(_MPh0) * @code PinName MotPhases[] = {PB_1, PB_15, PB_14, PB_13}; - Motor MotorName(MotPhases); // Call this creator for example like this: + CreaMot MotorName(MotPhases); // Call this creator for example like this: @endcode * * @param _MPh Array of Names of the 4 Digital Pins of type PinNames */ - Motor(PinName _MPh[4] ); + CreaMot(PinName _MPh[4] ); - /** Motor Class Creator + /** CreaMot Class Creator * * Creates the class, initiallizes all fields, creates Phase Pins. * Time between two steps defaults here to MOTOR_STEP_TIME_DEFAULT_US=5000usec. @@ -123,14 +121,14 @@ * @code // Call this creator for example like this: - Motor MotorName(PB_1, PB_15, PB_14, PB_13); + CreaMot MotorName(PB_1, PB_15, PB_14, PB_13); @endcode * * @param <_MPh0, _MPh1, _MPh2, _MPh3> List of Names of the 4 Digital Pins of type PinNames */ - Motor(PinName _MPh0, PinName _MPh1, PinName _MPh2, PinName _MPh3); + CreaMot(PinName _MPh0, PinName _MPh1, PinName _MPh2, PinName _MPh3); - /** Motor Class Creator + /** CreaMot Class Creator * * Creates the class, initiallizes all fields, creates Phase Pins. * Time between two steps is passed as parameter. @@ -138,13 +136,13 @@ * @code // Call this creator for example like this: - Motor MotorName(PB_1, PB_15, PB_14, PB_13); + CreaMot MotorName(PB_1, PB_15, PB_14, PB_13, 6000); @endcode * * @param <_MPh0, _MPh1, _MPh2, _MPh3> List of Names of the 4 Digital Pins of type PinNames - * @param <AStepTime_us> Lthe time in usec between two steps, thats used initially. + * @param <AStepTime_us> the time in usec between two steps, thats used initially. */ - Motor(PinName _MPh0, PinName _MPh1, PinName _MPh2, PinName _MPh3, uint32_t AStepTime_us); + CreaMot(PinName _MPh0, PinName _MPh1, PinName _MPh2, PinName _MPh3, uint32_t AStepTime_us); private: // deprecated: void initialization(PinName _MPh0, PinName _MPh1, PinName _MPh2, PinName _MPh3, uint32_t AStepTime_us); @@ -153,8 +151,8 @@ public: /** Attach a basic Callback function. * - * Only called when a Run Command reaches it's requested end. - * Not called when the Motor is stopped by a call of Stop Function, or any other events. + * A callback is called when the current Command reaches it's requested end. + * Not called when the CreaMot is stopped by a call of Stop Function, or any other events. * For use see precautions at Class description above. * Formerly called setMotorCallback() * @@ -186,7 +184,7 @@ /** Attach a Callback function, member of a class. * Only called when a Run Command reaches it's requested end. - * Not called when the Motor is stopped by a call of Stop Function, or any other events. + * Not called when the CreaMot is stopped by a call of Stop Function, or any other events. * For use see precautions at Class description above. * @param <*object> Class pointer which possesses callback member. * @param <*CBmember> Pointer to callback function, member of Class. @@ -213,37 +211,46 @@ /** Remove the Callback function that may have been attached previously. */ void callbackRemove() { _callback = NULL; }; -public +public: // ********************************************************************* - // all following functions are agnostic of centimeter-information + // all following functions use wheel diameter to achieve cm distance // ********************************************************************* - /** High Level: Run Motor for a given number of centimeters. + /** High Level: Run CreaMot for a given number of centimeters. * - * Runs Motor for a given circumference in cimeters in given direction. + * Runs CreaMot for a given wheel circumference in cimeters in given direction. * You must setup the perimeter and diameter with setDiam(Adiam_cm) in advance, otherwise no reaction. - * Call Pause() or Stop() to pause or end the Motor run prematurely. + * Call Pause() or Stop() to pause or end the CreaMot run prematurely. * While run: Uses ticker; State: first Motor_ON then Motor_RUN; cmd=MOTOR_run. * At end: calls attached Callback, stops ticker; State: Motor_OFF; cmd=MOTOR_stop then MOTOR_nop. * @param[in] <AClockWise> Given Direction, true for CLOCKWISE, false for COUNTERCLOCKWISE. - * @param[in] <centimeters> Circumference to rotate for, in cm, centimeters<0 are run in opposite direction. + * @param[in] <Dist_cm> Circumference to rotate for, in cm, Dist_cm<0 are run in opposite direction. */ - void RunCentimeters (bool AClockWise, float centimeters); + void RunDist_cm (bool AClockWise, float Dist_cm); - /** High Level: Run Motor for a given number of centimeters in default direction. - * Same as RunCentimeters(AClockWise,centimeters) but uses Default diretion.*/ - void RunCentimeters (float centimeters); + /** High Level: Run CreaMot for a given number of centimeters in default direction. + * Same as RunDist_cm(AClockWise,Dist_cm) but uses Default diretion.*/ + void RunDist_cm (float Dist_cm); + + /** High Level: Run CreaMot for a turn angle around a turn_radius_cm in default direction + * + * Runs CreaMot for a given wheel circumference in cimeters in given direction. + * You must setup the perimeter and diameter with setDiam(Adiam_cm) in advance, otherwise no reaction. + * Call Pause() or Stop() to pause or end the CreaMot run prematurely. + * While run: Uses ticker; State: first Motor_ON then Motor_RUN; cmd=MOTOR_run. + * At end: calls attached Callback, stops ticker; State: Motor_OFF; cmd=MOTOR_stop then MOTOR_nop. + * @param[in] <turn_angle_deg> Given turn angle in degrees that should be run + * @param[in] <turn_radius_cm> Given Trun radius that should be run */ + float RunTurnAngle(float turn_angle_deg, float turn_radius_cm); /** Additional geometric information: set the wheel diameter, also sets perimeter and degrees per cm.*/ void setDiamCM( float Adiam_cm); - /** Set Motor speed in centimeter/sec, based on perimeter in cm */ - void setSpeed_cm_sec(float speed_cm_sec) + /** Set CreaMot speed in centimeter/sec, based on perimeter in cm */ + void setSpeed_cm_sec(float speed_cm_sec); - /** Helper: calculate the needed wheel angle from a turn angle and a turn_radius_cm */ - float calcAngle(float turn_angle_deg, float turn_radius_cm) - /** Calculated wheel Angle from calcAngle Helper function */ + /** Calculated wheel Angle from calcAngle() Helper function */ float rotate_angle_deg; /** Additional geometric information: wheel diameter in centimeter */ @@ -259,27 +266,34 @@ bool defaultDirection; /** State value that is used and managed by the class owner. - * Used for example by Creabot library to indicate if this is the left or right motor. + * Used for example by Creabot library to indicate if this is the left or right CreaMot. */ char StateValue; -public +public: // ***************************************************************** - // all following functions are agnostic of centimeter-information + // following functions are agnostic of wheel dimensions in centimeters // ***************************************************************** - /** High Level: Run Motor for a given angle. + /** High Level: Run CreaMot for a given angle. * - * Runs Motor for a given angle in given direction. - * Call Pause() or Stop() to pause or end the Motor run prematurely. - * While run: Uses ticker; State: first Motor_ON then Motor_RUN; cmd=MOTOR_run. + * Runs CreaMot for a given angle in given direction. + * Angles<0 are run in opposite direction. + * Call Pause() or Stop() to pause or end the CreaMot run prematurely. + * While running: Uses ticker; + * State: first Motor_ON then Motor_RUN; cmd=MOTOR_run. * At end: calls attached Callback, stops ticker; State: Motor_OFF; cmd=MOTOR_stop then MOTOR_nop. * @param[in] <AClockWise> Given Direction, true for CLOCKWISE, false for COUNTERCLOCKWISE. * @param[in] <angle_deg> Angle>0 to rotate for, in degrees, Angles<0 are run in opposite direction. */ void RunDegrees (bool AClockWise, float angle_deg); + + /** High Level: Run CreaMot for a given angle in default direction + * for details see RunDegrees (bool AClockWise, float angle_deg); + */ + void RunDegrees (float angle_deg); - /** High Level: Run Motor for a number of Steps. + /** High Level: Run CreaMot for a number of Steps. * * During Run: Uses ticker; State: first Motor_ON then Motor_RUN; cmd=MOTOR_run. * Call Pause() or Stop() to pause or end the run prematurely. @@ -289,17 +303,17 @@ */ void RunSteps (bool AClockWise, int32_t Nsteps); - /** High Level: Run Motor "unlimited" + /** High Level: Run CreaMot "unlimited" * - * Runs Motor with out limit in given direction, precisely runs 4Billion Steps. + * Runs CreaMot with out limit in given direction, precisely runs 4Billion Steps. * While run: Uses ticker; State: first Motor_ON then Motor_RUN; cmd=MOTOR_run. - * Call Pause() or Stop() to pause or end the Motor run. + * Call Pause() or Stop() to pause or end the CreaMot run. * @param[in] <AClockWise> Given Direction, true for CLOCKWISE, false for COUNTERCLOCKWISE. */ void RunInfinite (bool AClockWise); - /** High Level: Pause a motor Run. - * Put Motor into Pause state, Run is suspended, but only effective if Status.cmd=MOTOR_run. + /** High Level: Pause a CreaMot Run. + * Put CreaMot into Pause state, Run is suspended, but only effective if Status.cmd=MOTOR_run. * Retains the number of steps that remain to be run if restarting run. * While paused: still uses ticker; State: Motor_RUN; cmd=MOTOR_pause. * Use RestartRun(); to continue. */ @@ -320,19 +334,12 @@ public: // All the ticker timing related parameters - /** MidLevel: Get Motor status - * - * Gets the Status of the different internal mechanisms. - * See documentation of MotStatus Structure. - * @return MotStatus The structure of Motor status registers. */ - MotStatus getStatus(); - /** MidLevel: Get number of Steps per Full turn * Defaults to MOTOR_STEPS_FOR_A_TURN = 4096. * Used by RunDegrees() to translate from angle in degrees to number of steps. * Old Name was: getCalibration, but that was not a good explicit name. - * @return int32_t The structure of Motor status registers. */ + * @return int32_t The structure of CreaMot status registers. */ int32_t getStepsFullTurn(); /** MidLevel: Set number of Steps per Full turn. @@ -340,50 +347,60 @@ * Defaults is MOTOR_STEPS_FOR_A_TURN = 4096. * Used by RunDegrees() to translate from degrees to number of steps. * Old Name was: setCalibration, but not good explicit name. - * @param <StepsFullTurn> Number of steps needed to complete a full motor turn + * @param <StepsFullTurn> Number of steps needed to complete a full CreaMot turn */ void setStepsFullTurn(int32_t StepsFullTurn); - /** Mid Level: Get the Motor step time. + /** Mid Level: Get the CreaMot step time. - * Step time is time between two Motor steps, and is given in microseconds + * Step time is time between two CreaMot steps, and is given in microseconds * and is passed to the ticker as delay time. - * So the larger the value the slower the motor speed. + * So the larger the value the slower the CreaMot speed. * Defaults to MOTOR_STEP_TIME_DEFAULT_US = 5000. - * @return uint32_t The structure of Motor status registers. + * @return uint32_t The structure of CreaMot status registers. */ - uint32_t getStepTime_us; + uint32_t getStepTime_us(); - /** Set the time in microseconds between two Motor steps. + /** Set the time in microseconds between two CreaMot steps. * Defaults to MOTOR_STEP_TIME_DEFAULT_US = 5000usec. * Filters values below Minimum Value = 700. * Passed to the ticker as delay time. * Can be called while ticker is running, and takes immediate effect. * Was previously called setStepTime(), but was not clear which units. - * @param <AStepTime_us> the time in microseconds between two Motor steps + * @param <AStepTime_us> the time in microseconds between two CreaMot steps */ void setStepTime_us(uint32_t AStepTime_us); /** Set the time in seconds to get one full turn, rotation of 360°. * was previously called setSpeed(). - * @param <Seconds_Per_Turn> Period of Rotation, e.g. if =20.0 then Motor will do 360° in 20 seconds. + * @param <Seconds_Per_Turn> Period of Rotation, e.g. if =20.0 then CreaMot will do 360° in 20 seconds. */ void setRotationPeriodSec(float Seconds_Per_Turn) ; private: - // all the Ticker and Timing procedures, used to run the Motor for a duration + // all the Ticker and Timing procedures, used to run the CreaMot for a duration void StartTick(); void ProcessMotorStateMachine(); // The call back function pointer that is called when the Processor // State Machine reaches its end. Callback<void()> _callback; void StopTick(); - MotStatus Status; - timestamp_t StepTime_us; // Time in µs for one Motor step - Ticker MotorSysTick; // System Timer for Motor + timestamp_t StepTime_us; // Time in µs for one CreaMot step + Ticker MotorSysTick; // System Timer for CreaMot int32_t Steps_FullTurn; // Number of step for a complete turn - -public: // all the low level direct Motor HW access, States are immediately reached + bool ClockWise; /**< Direction that the CreaMot is asked to run. True if Clockwise */ + int32_t NStepsToDo; /**< Number of steps remain for the CreaMot to run. + NSteps=0: all steps finished; NSteps<0: indicates to run "forever" */ + bool TickIsAttached; /**< Indicates if Ticker is attached. + Ticker is automatically attached while CreaMot runs, or paused; + detaches when finished a run, or stopped. */ + +public: // all the low level direct CreaMot HW access, States are immediately reached + motStates CurrState; /**< General state that the CreaMot state machine is in.*/ + motCmands CurrCmd; /**< Command asked to be executed currently by the state machine.*/ + void setStatus(motCmands aCmd, bool AClockWise, int32_t aNSteps); + /**< Helper; set Command, Direction and NSteps in one call. */ + /** Low Level: Run one full turn clockwise then anticlockwise. * After: State: Motor_OFF. @@ -391,41 +408,40 @@ */ void MotorTest(); - /** Low Level: turn off all Motor Phases + /** Low Level: turn off all CreaMot Phases * No more current flows, reduces holding force. * After: State: Motor_OFF. * StepPhases memorizes the last used phase. * Equivalent what previously the function "void Stop();" did . */ void MotorOFF(); - /** Low Level: turn on the Motor Phases in the last used phase. + /** Low Level: turn on the CreaMot Phases in the last used phase. * The last used phase is held in StepPhases. * After: State: Motor_ON, or Motor_ZERO if StepPhases==0 * Equivalent to what previously the function "void Start();" did. */ void MotorON(); - /** Low Level: Advance Motor one step, rotates in direction of variable AClockWise. */ + /** Low Level: Advance CreaMot one step, rotates in direction of variable AClockWise. */ void StepOnce(); - /** Low Level: Advance Motor one step, rotates CounterClockwise. */ + /** Low Level: Advance CreaMot one step, rotates CounterClockwise. */ void StepCCW(); - /** Low Level: Advance Motor one step, rotates Clockwise. */ + /** Low Level: Advance CreaMot one step, rotates Clockwise. */ void StepClkW(); - /** Low Level: turn on the Motor Phases in Zero Position. + /** Low Level: turn on the CreaMot Phases in Zero Position. * After: State: Motor_ZERO, StepPhases==0 */ void MotorZero(); - private: - /** Low Level: Engage Motor Phases according to MotorIndex. */ + /** Low Level: Engage CreaMot Phases according to MotorIndex. */ void SetPhases(); DigitalOut *MPh[4]; // Digital outputs, one per phase - int StepPhase; // Motor Phase Variable, counts up and down with every step + int StepPhase; // CreaMot Phase Variable, counts up and down with every step }; #endif