Arduino IDE: RBD_Light Example Blink Without DelayNeed help writing code? You can hire Robots + Big Data to write Arduino software for your project! Click here to get started...
Arduino

MotorAPI DOCUMENTATION

Control many motors.

See Example  Public Methods  Release Notes
Overview

Control motors without delay with commands like on()off()forward()reverse(), and ramp(). Fire custom events when the motor has reached the target speed with onTargetSpeed(), or when it has changed direction with the onForward() and onReverse() events.

Motors can be wired to move in a single direction, or can be driven in both directions with the help of a motor-shield or H bridge and this library. See the forward and reverse example included with installing this library.

Example Wiring

This is a high powered motor driver circuit that can spin a single motor at variable speed in one direction. It is called a low-side switch that includes over-current and inductive kickback protection. The motor can be powered from batteries or a DC adapter. This circuit requires an Arduino PWM pin for variable speed control.

  1. Connect a motor and power supply (batteries or DC adapter)
  2. Add a diode across the positive and negative motor pins
  3. Add a N-Channel Logic Level MOSFET to the circuit
  4. Connect the MOSFET Gate to a 10KΩ resistor bridged to ground
  5. Also connect the MOSFET Gate to a 150Ω resistor bridged to PWM pin 3
  6. Connect the MOSFET Drain to the negative motor pin
  7. Connect the MOSFET Source to the negative power supply
  8. Connect the Arduino ground to the circuit
  9. Load the Example Sketch onto the Arduino
  10. Watch the motor spin up and down

A motor wired to a low-side switch, a battery pack, and an Arduino Micro PWM pin 3.

Forward & Reverse

The Example Wiring circuit only spins the motor in one direction, but this library is capable of forward and reverse. To enable this capability you should use a motor shield or H bridge, then specify the [optional] forward and reverse pins in the constructor(). See the forward and reverse example included with installing this library.

Example SketchArduinoC++
#include <RBD_Timer.h>
#include <RBD_Motor.h>

RBD::Motor motor(3); // PWM pin

void setup() {
  motor.rampUp(5000);
}

void loop() {
  motor.update();

  if(motor.onTargetSpeed()) {
    if(motor.isOn()) {
      motor.rampDown(3000);
    }
    else {
      motor.rampUp(5000);
    }
  }
}
Public Methods

You can use this library without calling update() and most methods will function correctly. You must continuously call update() inside of loop() in order to use theReal-Time methods tagged below.

RBD::Motor

RBD::Motor constructor(pwm_pin, [forward_pin], [reverse_pin])

Create a new motor and pass in the Arduino PWM pin number. The forward and reverse pins are [optional] and can be used to control the motor in both directions with the help of a motor shield or H bridge. The motor will be set forward() by default if you provide the forward and reverse pins.

EXAMPLE SKETCH
RBD::Motor motor(3); // PWM pin

void setup() {
  ...
}
motor
.on()

Start the motor at full speed.

EXAMPLE SKETCH
void setup() {
  motor.on();
}
motor
.off()

Stop the motor.

EXAMPLE SKETCH
void setup() {
  motor.off();
}
motor
.forward()

Set the spin direction for the motor so that all new commands move it forward. The motor is set forward() by default.

You must provide the optional forward and reverse pins in the constructor() and correctly wire the motor to use this method. The motor should be spun to a full-stop before calling this method. This library will forcibly stop the motor before switching to the forward state.

EXAMPLE SKETCH
void setup() {
  motor.forward();
  motor.rampUp(3000);
}
motor
.reverse()

Set the spin direction for the motor so that all new commands move it in reverse.

You must provide the optional forward and reverse pins in the constructor() and correctly wire the motor to use this method. The motor should be spun to a full-stop before calling this method. This library will forcibly stop the motor before switching to the reverse state.

EXAMPLE SKETCH
void setup() {
  motor.reverse();
  motor.rampUp(3000);
}
motor
.toggleDirection()

Flip the spin direction for the motor so that all new commands will move it in the opposite direction than they do currently. This alternates between forward() and reverse().

You must provide the optional forward and reverse pins in the constructor() and correctly wire the motor to use this method. The motor should be spun to a full-stop before calling this method. This library will forcibly stop the motor before toggling to the new state.

EXAMPLE SKETCH
void loop() {
  if(...) {
    motor.toggleDirection();
    motor.rampUp(3000);
  }
}
motor
.setSpeed(value)

Pass in an integer from 0 - 255 to control the speed of the motor.

EXAMPLE SKETCH
void setup() {
  motor.setSpeed(85); // one-third speed
}
motor
.setSpeedPercent(value)

Pass in an integer from 0 - 100 to control the speed percentage of the motor. This is essentially the same as setSpeed() but with a smaller input scale.

EXAMPLE SKETCH
void setup() {
  motor.setSpeedPercent(50); // half speed
}
motor
.isOn()

Returns true if the motor is running at 100% speed.

EXAMPLE SKETCH
void setup() {
  motor.on();
}

void loop() {
  if(motor.isOn()) {
    ...
  }
}
motor
.isOff()

Returns true if the motor is running at 0% speed.

EXAMPLE SKETCH
void setup() {
  motor.off();
}

void loop() {
  if(motor.isOff()) {
    ...
  }
}
motor
.isForward()

Returns true if the motor is set in the forward() state.

You must provide the optional forward and reverse pins in the constructor() and correctly wire the motor to use this method.

EXAMPLE SKETCH
void loop() {
  // motor set forward by default
  if(motor.isForward()) {
    ...
  }
}
motor
.isReverse()

Returns true if the motor is set in the reverse() state.

You must provide the optional forward and reverse pins in the constructor() and correctly wire the motor to use this method.

EXAMPLE SKETCH
void setup() {
  motor.reverse();
}

void loop() {
  if(motor.isReverse()) {
    ...
  }
}
motor
.getSpeed()

Returns an integer from 0 - 255 for the current motor speed.

EXAMPLE SKETCH
void setup() {
  motor.setSpeed(123);
}

void loop() {
  Serial.println(motor.getSpeed());
}
motor
.getSpeedPercent()

Returns an integer from 0 - 100 for the current motor speed percentage.

EXAMPLE SKETCH
void setup() {
  motor.setSpeedPercent(45);
}

void loop() {
  Serial.println(motor.getSpeedPercent());
}
motor
.update()Update

Keep the real-time functions processing with each loop(). This must be called continuously within loop() in order to use any real-time methods.

EXAMPLE SKETCH
void loop() {
  motor.update();
}
motor
.timedOn(timeout)Real-Time

Start the motor at full speed and turn it off after the specified time in milliseconds.

EXAMPLE SKETCH
void setup() {
  motor.timedOn(5000);
}

void loop() {
  motor.update();
}
motor
.rampUp(timeout)Real-Time

Pass in a timeout in milliseconds for how long it will take to ramp from the current speed to full speed with a linear transition.

EXAMPLE SKETCH
void setup() {
  motor.rampUp(3000);
}

void loop() {
  motor.update();
}
motor
.rampDown(timeout)Real-Time

Pass in a timeout in milliseconds for how long it will take to ramp from the current speed to full stop with a linear transition.

EXAMPLE SKETCH
void setup() {
  motor.on();
  motor.rampDown(4000);
}

void loop() {
  motor.update();
}
motor
.ramp(value, timeout)Real-Time

Pass in a value from 0 - 255 to set the target speed of the motor, and a timeout in milliseconds for how long it will take to ramp from the current speed to the target speed with a linear transition.

EXAMPLE SKETCH
void setup() {
  motor.ramp(85, 2000); // one-third speed in 2 seconds
}

void loop() {
  motor.update();
}
motor
.rampPercent(value, timeout)Real-Time

Pass in a value from 0 - 100 to set the target speed percent of the motor, and a timeout in milliseconds for how long it will take to ramp from the current speed to the target speed percent with a linear transition. This is essentially the same as ramp() but with a smaller input scale.

EXAMPLE SKETCH
void setup() {
  motor.rampPercent(50, 1000); // half speed in 1 second
}

void loop() {
  motor.update();
}
motor
.onForward()Real-TimeEvent

This method will return true once the motor starts moving forward(). This method will then return false until the motor has stopped, moved in reverse, then started moving forward again.

You must provide the optional forward and reverse pins in the constructor() and correctly wire the motor to use this method.

EXAMPLE SKETCH
void setup() {
  motor.rampUp(5000);
}

void loop() {
  motor.update();

  if(motor.onForward()) {
    // code only runs once per event
    Serial.println("Moving Forward");
  }
}
motor
.onReverse()Real-TimeEvent

This method will return true once the motor starts moving in reverse(). This method will then return false until the motor has stopped, moved forward, then started moving in reverse again.

You must provide the optional forward and reverse pins in the constructor() and correctly wire the motor to use this method.

EXAMPLE SKETCH
void setup() {
  motor.reverse();
  motor.rampUp(5000);
}

void loop() {
  motor.update();

  if(motor.onReverse()) {
    // code only runs once per event
    Serial.println("Moving in Reverse");
  }
}
motor
.onTargetSpeed()Real-TimeEvent

This method will return true once the motor hits the target speed set in any of the real-time methods. This method will then return false until a new target speed is set (with a real-time method) and then achieved again by the motor.

EXAMPLE SKETCH
void setup() {
  motor.off();
  motor.rampPercent(50, 5000);
}

void loop() {
  motor.update();

  if(motor.onTargetSpeed()) {
    // code only runs once per event
    Serial.println("Target Speed");
  }
}