Skip to content
Rick Waldron edited this page Feb 24, 2015 · 49 revisions

The Motor class constructs objects that represent a single Motor. The motor may attach to the physical board or a motor controller. The controller may be a third party shield or custom built motor controller. This class works well with both Directional and Non-Directional motors. It also works well with 2-pin or 3-pin controllers.

Parameters

  • pin A Number or String address for the Non-Directional Motor pin (PWM).
  • pins An array of 2 or 3 Numbers or String addresses for the Bi-Directional Motor pins.
  • options An object of property parameters.
Property Name Type Value/Description Required
pins Object A valid pins object or pins array yes
current Object A valid Sensor options object* no
invertPWM Boolean true or false no
address Number (usually in hexadecimal) An I2C device address no
controller String Motor controller interface type no
register Object {data, clock, latch} Pin configuration for a ShiftRegister no
bits Object {a, b} Switch bits to be flipped to control an HBridge from a ShiftRegister only if register is defined

Shape

{ 
  isOn: A boolean flag, true when motor is moving or braking, false when not READONLY
}

Component Initialization

// Two elements passed [pwm, dir]
var motor = new five.Motor([3, 12]);
// Three elements passed [pwm, dir, cdir]
var motor = new five.Motor([3, 12, 11]);

*See Sensor for valid options on the current object

// Create a motor with...
//
//   - pwm (speed) on pin 3
//   - dir (direction) on pin 12
//   - and brake on pin 11
//
// ... with a current sensor...
//
//   - that gets the value from pin "A0"
//   - every 250ms
//   - and scales the raw data to value between 0 and 2000
//
var motor = new five.Motor({
  pins: {
    pwm: 3,
    dir: 12,
    brake: 11
  }, 
  current: {
    pin: "A0",
    freq: 250,
    range: [0, 2000]
  }
});

Usage

Non-Directional Motor

var five = require("johnny-five"), 
    board = new five.Board();

board.on("ready", function() {

  var motor = new five.Motor(5);

  // Start the motor at maximum speed, wait 2 seconds and stop.
  motor.start(255);

});

Directional Motor

var five = require("johnny-five"), 
    board = new five.Board();

board.on("ready", function() {

  var motor = new five.Motor([3, 12]);

  // Reverse the motor at maximum speed
  motor.reverse(255);

});

Directional Motor with Brake

var five = require("johnny-five"), 
    board = new five.Board();

board.on("ready", function() {

  var motor = new five.Motor({
    pins: {
      pwm: 3,
      dir: 12,
      brake: 9
    }
  });

  motor.on("forward", function(err, timestamp) {
    // demonstrate braking after 5 seconds
    board.wait(5000, function() {
      motor.brake();
    });
  });

  motor.on("brake", function(err, timestamp) {
    // Release the brake after .1 seconds
    board.wait(100, function() {
      motor.stop();
    });
  });

  // Start the motor at maximum speed
  motor.forward(255);

});

Directional Motor with Current Sensing

var five = require("johnny-five"), 
    board = new five.Board();

board.on("ready", function() {

  var motor = new five.Motor({
      pins: [3, 12]
    },
    current: {
      pin: "A0",
      freq: 250,
      threshold: 10
    }
  });

  // Log current mA every 250ms if that value has changed by 10 or more since the last log
  motor.current.scale([0, 3030]).on("change", function() {
    console.log("Motor A: " + this.value.toFixed(2) + "mA");
  });

  // Start the motor at maximum speed
  motor.forward(255);

});

Directional Motor with ShiftRegister to control HBridge (Like the AdaFruit Motor Shield V1)

var five = require("johnny-five"), 
    board = new five.Board();

board.on("ready", function() {

  var motor = new five.Motor({
      pins: { pwm: 11 },
      register: { data: 8, clock: 4, latch: 12 },
      bits: { a: 2, b: 3 }
    }
  });

  // Start the motor at maximum speed
  motor.forward(255);

});

Directional Motor via Adafruit Motor Shield V2

var five = require("johnny-five"), 
    board = new five.Board();

board.on("ready", function() {

  var motor = new five.Motor({
      pins: {
        pwm: 8,
        dir: 9,
        cdir: 10
      },
      address: 0x60,
      controller: "PCA9685"
    }
  });

  // Start the motor at maximum speed
  motor.forward(255);

});

API

  • forward(speed 0-255) Set a motor moving forward

  • fwd(speed 0-255) Alias to forward()

    var motor = new five.Motor([11, 12]);
    
    // Forward at half speed
    motor.forward(128);
  • reverse(speed 0-255) Set a motor moving in reverse

  • rev(speed 0-255) Alias to reverse()

    var motor = new five.Motor([11, 12]);
    
    // Reverse at full speed
    motor.reverse(255);
  • start([speed 0-255]) Set a motor moving in the current direction

    var motor = new five.Motor([11, 12]);
    
    // Forward at half speed
    motor.forward(128);
    
    // Stop
    motor.stop();
    
    // Resume forward at half speed
    motor.start();
    
    // Continue forward at full speed
    motor.start(255);
  • stop() Let the motor coast to a stop

    var motor = new five.Motor([11, 12]);
    
    // Forward at full speed
    motor.forward(255);
    
    // Roll to stop
    motor.stop();
  • brake() Force a motor to stop (as opposed to coasting). Please note that this only works on boards with a dedicated brake pin. Other boards and interfaces will simply coast.

    var motor = new five.Motor([11, 12]);
    
    // Forward at full speed
    motor.forward(255);
    
    // Stop fast
    motor.brake();
    
    board.wait(100, function() {
      motor.stop();
    });
  • release() Release the brake and resume current speed and direction

    var motor = new five.Motor([11, 12]);
    
    // Forward at full speed
    motor.forward(255);
    
    // Stop fast
    motor.brake();
    
    // Wait five seconds and release the brake
    board.wait(5000, function() {
      motor.release();
    });

Examples

Additional Notes

The PWM pins on an Arduino Uno only output about 40mA. That is barely enough to power a humble hobby motor. You are going to need a motor controller between your Arduino and your motor(s) to deliver power from an external source. Most motor controllers are based on the H-Bridge circuit which uses a set of four switches to direct the voltage being sent through each pole of the motor. Different shields handle different input voltages and output currents. Use the Motor Control Shield Survey below to find a shield that works for you.

Forward and Reverse are Interchangeable

Keep in mind that "forward" and "reverse" are arbitrary labels. If your motor is turning in the wrong direction you can just switch the poles on the motor. Consider a robot with two motors connected directly to the drive wheels. For your bot to go forward, one should turn clockwise and the other should turn counter-clockwise. Switch the poles on one of those motors so that you can use forward() on both and have them work together.

Situations Where invertPWM: true is Required

Most motor controller board/shield manufacturers abstract the need for this away. If you have wired up your own motor controller or you have purchased a very basic motor controller board you may need this property. To check, set both pwm and dir to their highest values by calling motor.forward(255). If nothing happens try calling motor.stop(). If this makes the motor move you need to add invertPWM: true as in the example below. Instead of the pins being used for PWM and DIR they are being used to directly control the voltage applied to each pole of the motor. If both are set to high, the motor will not move.

var motor = new five.Motor({pins:[8,9], invertPWM:true});

Differences Between 2 and 3 pin Directional Motor Controllers

Controllers that use 2 pins instead of 3 are essentially the same. Both arrangements use one PWN pin to control speed. The switches on the H-Bridge work in pairs. With 3-pin controllers you control the state of each pair. With 2-pin controllers the pairs are toggled for you based on the state of that one digital pin.

Motor Control Shield Survey

This is by no means exhaustive

2 Pin

Name Motor A pins Motor B pins Shield Config Operating Voltage(1) Max A per Channel Stackable(2)
Arduino Motor Shield R3 pwm:3,
                                            dir:12,       
                                            [brake:9,]    
                                            [current:A0]  | pwm:11,      
                                                           dir:13,       
                                                           [brake:8,]    
                                                           [current:A1]  | ARDUINO_MOTOR_SHIELD_R3_1 {A, B} (vanilla)           
                                                                          ARDUINO_MOTOR_SHIELD_R3_2 {A, B} (w/brake)            
                                                                          ARDUINO_MOTOR_SHIELD_R3_3 {A, B} (w/brake & current)  | 7-12V                | 2A                | No           |

| DF Robot 1A | pwm:6,
dir:7 | pwm:5,
dir:4 | DF_ROBOT {A, B} | 7 - 12V | 1A | No | | DF Robot 2A | pwm:6,
dir:7 | pwm:5,
dir:4 | DF_ROBOT {A, B} | 4.8 - 35V | 2A | No | | NKC Electronics Motor Control Shield Kit | pwm:9,
dir:12 | pwm:10,
dir:13 | NKC_ELECTRONICS_KIT {A, B} | 6 - 15V shared | 1A | No | | Rugged Circuits Rugged Motor Driver | pwm:3,
dir:12 | pwm:11,
dir:13 | RUGGED_CIRCUITS {A, B} | 8-30V | 2.8A | Yes | | Rugged Circuits Basic Motor Driver | pwm:3,
dir:12 | pwm:11,
dir:13 | RUGGED_CIRCUITS {A, B} | 8-30V | 2A | Yes | | Sparkfun Ardumoto | pwm:3,
dir:12 | pwm:11,
dir:13 | SPARKFUN_ARDUMOTO {A, B} | 6 - 15V shared | 2A | No |

3 Pin

Name Motor A pins Motor B pins Shield Config Operating Voltage(1) Max A Stackable(2)
Seeed Studios Motor Shield V1 and V2 pwm:9,
                                                         dir:8,        
                                                         cdir: 11      | pwm:10,      
                                                                        dir:12,       
                                                                        cdir: 13      | SEEED_STUDIO {A, B}         | 6-15V                | 2A    | No           |

| Freetronics Dual Channel H-Bridge Motor Driver Shield | pwm:6,
dir:4,
cdir: 7 | pwm:5,
dir:3,
cdir: 2 | FREETRONICS_HBRIDGE: {A, B} | 8-40V | 2A | No |

I2C

Name Address Controller Shield Config Operating Voltage(1) Max A Stackable(2)
Adafruit Motor/Stepper/Servo Shield V2 0x60 - 0x80 PCA9685 ADAFRUIT_V2 {M1, M2, M3, M4} 4.5-13.5V 3A Yes
M1 M2 M3 M4
pwm:8,
dir:9,
cdir: 10
pwm:13,
dir:12,
cdir: 11
pwm:2,
dir:3,
cdir: 4
pwm:7,
dir:6,
cdir: 5

ShiftRegister

Name Register Shield Config Operating Voltage(1) Max A Stackable(2)
SainSmart L293D Motor Drive Shield
(clone of AdaFruit Motor Shield v1)
data: 8,
clock: 4,
latch: 12
ADAFRUIT_V1: {M1, M2, M3, M4} 4.5-10V 1.2A per motor No
M1 M2 M3 M4
pins: { pwm: 11 }
bits: {a: 2, b: 3}
pins: { pwm: 3 }
bits: {a: 1, b: 4}
pins: { pwm: 6 }
bits: {a: 5, b: 7}
pins: { pwm: 5 }
bits: {a: 0, b: 6}
  1. Beware of shared voltage, the shield may be able to handle higher voltages than your Arduino.
  2. Indicates that the pins can be reconfigured so that you can stack multiple shields of this type or other shields that use the same pins.

Pre-packaged Shield Configs

There are several shields that Johnny-Five has created pre-configured objects for. Instantiating motors using these shield configurations is designed to be extremely simple. If the tables above include a shield config, you can use them like this:

var config = five.Motor.SHIELD_CONFIGS.ADAFRUIT_V1;

var m1 = new five.Motor(config.M1);
var m2 = new five.Motor(config.M2);
var m3 = new five.Motor(config.M3);
var m4 = new five.Motor(config.M4);
Clone this wiki locally