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.

See also:

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.

    PropertyTypeValue(s)/DescriptionDefaultRequired
    pinsObjectA valid pins object or pins arrayyes
    currentObjectA valid Sensor options object*no
    invertPWMBooleantrue or falseno
    addressNumberAn I2C device addressno
    controllerStringMotor controller interface typeno

  • options.pins An object with pins required for the motor controller being used

    Pin nameRequiredDescription
    pwmYesControls motor speed
    dirYesControls motor direction
    cdirNoOnly necessary for 3-pin motor controllers. Is used in conjunction with dir to control direction and braking
    brakeNoEngages high impedance braking. Only a few motor controllers have a brake pin

  • Shift Register Options An object of property parameters.

    PropertyTypeValue(s)/DescriptionDefaultRequired
    registerObject{data, clock, latch} Pin configurationno
    bitsObject{a, b} Switch bits to be flipped to control an HBridgeonly if register is defined

Shape

Property NameDescriptionRead Only
isOnA boolean flag, true when motor is moving or braking, false when not.Yes

Component Initialization

Two Pin H-Bridge [pwm, dir]

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

new five.Motor({
  pins: {
    pwm: 3,
    dir: 12
  }
});

Three Pin H-Bridge [pwm, dir, cdir]

new five.Motor([9, 8, 11]);

new five.Motor({
  pins: {
    pwm:9,
    dir:8,
    cdir: 11  
  }
});

Three Pin H-Bridge [pwm, dir, brake]

new five.Motor([9, 8, 11]);

new five.Motor({
  pins: {
    pwm:9,
    dir:8,
    brake: 11  
  }
});

Pre-packaged Shield Configs

There are several shields that Johnny-Five provides preset configuration objects for. Instantiating motors using these shield configurations is designed to be extremely simple:

Arduino Motor Shield R3

var configs = five.Motor.SHIELD_CONFIGS.ARDUINO_MOTOR_SHIELD_R3_1;

var motorA = new five.Motor(configs.A);
var motorB = new five.Motor(configs.B);

DF Robot

var configs = five.Motor.SHIELD_CONFIGS.DF_ROBOT;

var motorA = new five.Motor(configs.A);
var motorB = new five.Motor(configs.B);

Rugged Circuits Rugged Motor Driver

var configs = five.Motor.SHIELD_CONFIGS.RUGGED_CIRCUITS;

var motorA = new five.Motor(configs.A);
var motorB = new five.Motor(configs.B);

Sparkfun Ardumoto

var configs = five.Motor.SHIELD_CONFIGS.SPARKFUN_ARDUMOTO;

var motorA = new five.Motor(configs.A);
var motorB = new five.Motor(configs.B);

Seeed Studios Motor Shield V1 or V2

var configs = five.Motor.SHIELD_CONFIGS.SEEED_STUDIO;

var motorA = new five.Motor(configs.A);
var motorB = new five.Motor(configs.B);

Freetronics Dual Channel H-Bridge Motor Driver Shield

var configs = five.Motor.SHIELD_CONFIGS.FREETRONICS_HBRIDGE;

var motorA = new five.Motor(configs.A);
var motorB = new five.Motor(configs.B);

Adafruit Motor/Stepper/Servo Shield V1

var configs = five.Motor.SHIELD_CONFIGS.ADAFRUIT_V1;

var motor1 = new five.Motor(configs.M1);
var motor2 = new five.Motor(configs.M2);
var motor3 = new five.Motor(configs.M3);
var motor4 = new five.Motor(configs.M4);

Adafruit Motor/Stepper/Servo Shield V2

var configs = five.Motor.SHIELD_CONFIGS.ADAFRUIT_V2;

var motor1 = new five.Motor(configs.M1);
var motor2 = new five.Motor(configs.M2);
var motor3 = new five.Motor(configs.M3);
var motor4 = new five.Motor(configs.M4);

Pololu DRV8835 Shield

var configs = five.Motor.SHIELD_CONFIGS.POLOLU_DRV8835_SHIELD;

var motor1 = new five.Motor(configs.M1);
var motor2 = new five.Motor(configs.M2);

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
  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({
    controller: "PCA9685",
    frequency: 200, // Hz
    pins: {
      pwm: 8,
      dir: 9,
      cdir: 10,
    },
  });

  // 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();
});

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
SparkFun Ludus Protoshield Wireless and SparkFun Ludus Protoshield pwm:3
dir:4
cdir: 5		 pwm:6
dir:7
cdir: 8		 SPARKFUN_LUDUS {A, B} 13V 1.2A No
SparkFun Block for Intel® Edison - Dual H-Bridge pwm:20
dir:33
cdir: 46		 pwm:14
dir:48
cdir: 36		 SPARKFUN_DUAL_HBRIDGE_EDISON_BLOCK {A, B} 2.7V-15V 1A 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.

Examples

Hi! The Johnny-Five community is building new projects every day. We made this newsletter to tell you about what's new, what's good, and what's next for Open Source robotics. Join us in exploring what we can make together.

Fork me on GitHub