My Version of the Crealab MotorLib.
Fork of MotorLib by
Diff: CreaMot.h
- Revision:
- 24:932ea7bdc850
diff -r 6060422cd6eb -r 932ea7bdc850 CreaMot.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/CreaMot.h Thu Apr 18 12:12:48 2019 +0000 @@ -0,0 +1,447 @@ +/** + * @file CreaMot.h + * \brief File contains Crealab CreaMot Library. + + * 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 @@. + + * @author Tarek Lule, Francois Druilhe, et al. + * @date 01. Nov. 2018. + * @see https://os.mbed.com/users/sepp_nepp/code/MotorLib/ */ + + // -------------------- CreaMot --------------------------- + +#ifndef CREAMOT_H +#define CREAMOT_H + +#include "mbed.h" + +#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 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 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, /**< 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 CreaMot state machine +* +* 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. +* +* MOTOR_restart is equivalent to and replaced by MOTOR_run. +*/ +typedef enum { + MOTOR_nop = 0, /**< No active command to execute. */ + 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; + +/** ATTENTION UNDER CONSTRUCTION, DO NOT YET USE. +* +* Class of a Four Phase Stepper CreaMot. +* +* 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. +* +* 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 +* +* 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 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. +* +* NB: all times are uint32_t, step numbers are int32_t +*/ +class CreaMot +{ +public: + /** 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. + * Pin names are used to create digital outputs: Pin0 = new DigitalOut(_MPh0) + * + @code + PinName MotPhases[] = {PB_1, PB_15, PB_14, PB_13}; + CreaMot MotorName(MotPhases); // Call this creator for example like this: + @endcode + * + * @param _MPh Array of Names of the 4 Digital Pins of type PinNames + */ + CreaMot(PinName _MPh[4] ); + + /** 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. + * Pin names are used to create digital outputs: Pin0 = new DigitalOut(_MPh0) + * + @code + // Call this creator for example like this: + 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 + */ + CreaMot(PinName _MPh0, PinName _MPh1, PinName _MPh2, PinName _MPh3); + + /** CreaMot Class Creator + * + * Creates the class, initiallizes all fields, creates Phase Pins. + * Time between two steps is passed as parameter. + * Pin names are used to create digital outputs: Pin0 = new DigitalOut(_MPh0) + * + @code + // Call this creator for example like this: + 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> the time in usec between two steps, thats used initially. + */ + 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); + void initialization(PinName _MPh[4], uint32_t AStepTime_us); + +public: + /** Attach a basic Callback function. + * + * 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() + * + @code + // Simple callback function, state variable endMove can be polled elsewhere + void CallBackFunction() + { endMove=true; } + + // main routine + void main() + { ... + // Attach callback function: + MotorInstance->callbackSet(CallBackFunction); + ... + while (true) { + .... + if (endMove) // poll the endMove flag + { ... } // react to Movement End + + .... + } + } + @endcode + * @param <*CBfunction> Callback function, must not be member of a class. + + */ + void callbackSet(void (*CBfunction)(void)) {_callback = CBfunction;}; + + + /** Attach a Callback function, member of a class. + * Only called when a Run 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. + * @param <*object> Class pointer which possesses callback member. + * @param <*CBmember> Pointer to callback function, member of Class. + * + @code + // Class Creator: + AClass::AClass(Class Creation Parameters) + { ... + // Attach callback function: + MotorInstance->setMotorCallback(this, &AClass::CallBackMemberFunction); + ... + } + + // Simple callback function, state variable endMove can be polled by main thread + void AClass::CallBackMemberFunction() + { endMove=true; } + @endcode + */ + template<typename T> + void callbackSet(T *object, void (T::*CBmember)(void)) { + _callback = callback(object,CBmember); + } + + /** Remove the Callback function that may have been attached previously. */ + void callbackRemove() { _callback = NULL; }; + +public: + // ********************************************************************* + // all following functions use wheel diameter to achieve cm distance + // ********************************************************************* + + /** High Level: Run CreaMot for a given number of centimeters. + * + * 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] <AClockWise> Given Direction, true for CLOCKWISE, false for COUNTERCLOCKWISE. + * @param[in] <Dist_cm> Circumference to rotate for, in cm, Dist_cm<0 are run in opposite direction. + */ + void RunDist_cm (bool AClockWise, float Dist_cm); + + /** 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 turn angle in degrees with a given turn radius. + * in default direction. Negative angles are rotated in opposite direction. + * turn-radius must be positive. Zero or negative radius are not executed. + * 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 */ + void 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 CreaMot speed in centimeter/sec, based on perimeter in cm */ + void setSpeed_cm_sec(float speed_cm_sec); + + /** Default rotation direction that serves as local storage, but not as actual direction */ + 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 CreaMot. */ + char StateValue; +private: + + /** Additional geometric information: wheel diameter in centimeter */ + float diam_cm; + + /** Additional geometric information: wheel perimeter in centimeter */ + float perim_cm; + + /** Additional geometric information: rotation angle in degrees per cm circumference */ + float degree_per_cm; + +public: + // ***************************************************************** + // following functions are agnostic of wheel dimensions in centimeters + // ***************************************************************** + + /** High Level: Run CreaMot for a given angle. + * + * 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 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. + * At the end: calls the Callback, stops ticker; State: Motor_OFF. + * @param[in] <AClockWise> Given Direction, true for CLOCKWISE, false for COUNTERCLOCKWISE. + * @param[in] <Nsteps> Number of steps to run for; Nsteps<0 are run in opposite direction! + */ + void RunSteps (bool AClockWise, int32_t Nsteps); + + /** High Level: Run CreaMot "unlimited" + * + * 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 CreaMot run. + * @param[in] <AClockWise> Given Direction, true for CLOCKWISE, false for COUNTERCLOCKWISE. + */ + void RunInfinite (bool AClockWise); + + /** 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. */ + void PauseRun(); + + /** High Level: Restart a Paused Run. + * Restart the Run that was launched before calling PuaseRun. + * Only effective if Status.cmd=MOTOR_pause, otherwise no re/action. + * Status afterwards is same as afterRun commands. */ + void RestartRun(); + + /** High Level: End any Run. + * Force stop of any ongoing run, but does not call the Callback function. + * Only effective if Status.cmd=MOTOR_run, otherwise no re/action. + * Emits first cmd=MOTOR_stop then cmd=MOTOR_nop. + * Aftewards: ticker is detached; State: Motor_OFF; */ + void StopRun(); + +public: // All the ticker timing related parameters + + /** 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 uint32_t The number of motor steps needed for a full turn. */ + uint32_t getStepsFullTurn(); + + /** MidLevel: Set number of Steps per Full turn. + + * 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 CreaMot turn + */ + void setStepsFullTurn(uint32_t StepsFullTurn); + + /** Mid Level: Get the CreaMot step time. + + * 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 CreaMot speed. + * Defaults to MOTOR_STEP_TIME_DEFAULT_US = 5000. + * @return uint32_t The structure of CreaMot status registers. + */ + uint32_t getStepTime_us(); + + /** 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 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 CreaMot will do 360° in 20 seconds. + */ + void setRotationPeriodSec(float Seconds_Per_Turn) ; + + + motStates CurrState; /**< General state that the CreaMot state machine is in.*/ + motCmands CurrCmd; /**< Command asked to be executed currently by the state machine.*/ + +private: + void setCommand(motCmands aCmd, bool aClockWise, int32_t aNSteps); + /**< Helper; set Command, Direction and NSteps in one call. */ + + // 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(); + timestamp_t StepTime_us; // Time in µs for one CreaMot step + Ticker MotorSysTick; // System Timer for CreaMot + uint32_t Steps_FullTurn; // Number of step for a complete turn + 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 + + /** Low Level: Run one full turn clockwise then anticlockwise. + * After: State: Motor_OFF. + * Blocking function, returns back only after end of full movement. + */ + void MotorTest(); + + /** 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 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 CreaMot one step, rotates in direction of variable AClockWise. */ + void StepOnce(); + + /** Low Level: Advance CreaMot one step, rotates CounterClockwise. */ + void StepCCW(); + + /** Low Level: Advance CreaMot one step, rotates Clockwise. */ + void StepClkW(); + + /** Low Level: turn on the CreaMot Phases in Zero Position. + * After: State: Motor_ZERO, StepPhases==0 + */ + void MotorZero(); + +private: + + /** Low Level: Engage CreaMot Phases according to MotorIndex. */ + void SetPhases(); + + DigitalOut *MPh[4]; // Digital outputs, one per phase + int StepPhase; // CreaMot Phase Variable, counts up and down with every step +}; + +#endif