Arduino Libs Wiki

Arduino Libraries

Brought to you by: perrotti

DcMotorCouple

Authors:

Class DcMotorCouple

Class to drive a dc motor's pair to move robots.

File: pDcMotors.h
Dependences: pGlobals.h

Public declarations:

#define DC_BLINK_LAPSE  16
#define DC_BRAKE_TIME   255
#define DC_NO_ENB_PIN   255

// Move types
#define mv_Off       0
#define mv_Ahead     1
#define mv_Back      2
#define mv_Brake     3
#define mv_SpinLf    4
#define mv_SpinRg    5
#define mv_TurnLf    6
#define mv_TurnRg    7
#define mv_TurnBkLf  8
#define mv_TurnBkRg  9
#define mv_CurveLf   10
#define mv_CurveRg   11
#define mv_Moves     12

class DcMotorCouple{
public:
    byte mvType;
    int lastSpeed;

    DcMotorCouple();
    void begin();
    void beginLf(byte lfAheadPin, byte lfBackPin, byte lfEnablePin= DC_NO_ENB_PIN);
    void beginRg(byte rgAheadPin, byte rgBackPin, byte rgEnablePin= DC_NO_ENB_PIN);

    void move(byte mvType, int speed, ulong milliseconds=0);
    void moveOff();
    void stopNow(int milliseconds= DC_BRAKE_TIME);
    void run();
    boolean isMoving();

    void setSpeedRatio(float lfRatio, float rgRatio);
    void updateSpeed(int speed);
    void updateSpeed();
};

How to use

Call begin() before any other method. Next, call beginLf() and beginRg() to inform pins to control the motors.
Some boards have Enable pin, others dont. If enabled pins are used they must have PWM, but ahead pins and back pins dont. If enabled pins are not used, them ahead pins and back pins must have PWM.

Call move() to start a move and moveOff() or stopNow() to stop move. If milliseconds param of move() method is greater than zero the move will go on for the time informed and stop.
Call run() at least once per loop.

Motor brake (mv_brake)
This is not really a movement, in this state the ahead and back signals are activated simultaneously which causes the motors to lock in the current position. It is a useful feature for emergency stops, but can not be maintained for long, otherwise the drive board or even the motors can burn. In addition, the energy consumption in this state is extremely high and increases over time.

Turn movements also use motor brake but only on one of the motors.

To avoid damages, whenever a motor enters in brake state, the class switches the motor on and off in the period setted by DC_BLINK_LAPSE. Even so, it is not a good idea to keep motor brake for a long time.

Speed ratio
The speed informed in speed param of move() method is in fact a reference speed. The final speed aplied to motors is the reference speed multiplied by motor speed ratio. This technique allows individual motor speed corrections, which is very useful when using wheel decoders.
Also the curves are obtained by adjusting the values of speed ratio, for example to start a left curve you can use the code below:

setSpeedRatio(0.8, 1.2);
move(mv_Ahead, 120);

If the robot is already moving ahead and you want start a left curve, you can use the code:

setSpeedRatio(0.8, 1.2);
updateSpeed();

void begin()

Call before any method.

void beginLf(byte lfAheadPin, byte lfBackPin, byte lfEnablePin= DC_NO_ENB_PIN)

Call after begin() to inform left motor's pins.

lfAheadPin: Left motor's ahead pin. If enable pin is not used, this pin must have PWM.
lfBackPin: Left motor's back pin. If enable pin is not used, this pin must have PWM.
lfEnablePin: Left motor's enable pin. If used, this pin must have PWM but the others pins dont.

void beginRg(byte rgAheadPin, byte rgBackPin, byte rgEnablePin= DC_NO_ENB_PIN)

Call after begin() to inform right motor's pins.

rgAheadPin: Right motor's ahead pin. If enable pin is not used, this pin must have PWM.
rgBackPin: Right motor's back pin. If enable pin is not used, this pin must have PWM.
rgEnablePin: Right motor's enable pin. If used, this pin must have PWM but the others pins dont.

void move(byte mvType, int speed, ulong milliseconds=0)

Start a move.

mvType: Type of move. Must be one of moves listed above.
speed: Reference speed. Value beetwen 0 and 255.
milliseconds: If greater then zero, the move will go on for the time informed and stop.

void moveOff()

Stop the move turning off the motors. The robot can continue for a little more due to inertia.

void stopNow(int milliseconds= DC_BRAKE_TIME)

Stop the move and activate motor brake to stop the robot immediately.

milliseconds: Motor brake duration.

void run()

Call at least once per loop.

boolean isMoving()

Check if robot is moving.

return: true if robot is moving, false if not.

void setSpeedRatio(float lfRatio, float rgRatio)

Set the speed ratio for motors. Has no immediate effect on the current movement, new ratios will be used on next movement. To apply the new ratios in the current movement, call updateSpeed().

lfRatio: Left speed ratio
rgRatio: Right speed ratio

void updateSpeed()

It only takes effect if the robot is moving. Call after setSpeedRatio() to apply new ratios keeping the same movement and same reference speed.

void updateSpeed(int speed)

It only takes effect if the robot is moving. Call to change reference speed keeping the same movement. If the speed ratio was change, new values will be used.

speed: New reference speed.

Wiki: Home