Motor Control

Currently supports the following types of motors:

  1. Motor controller boards with just two separate PWM connections; one for forwards / clockwise control, the other for backwards / ant-clockwise control. Examples: CamJam EduKit #3 Robotics Kit, Ryanteck RPi Motor Controller Board.
  2. H-Bridge style motor drivers with three connections; PWM proportionate control, digital forwards / clockwise control, and digital backwards / anti-clockwise control. Examples: Toshiba TB6612FNG Dual Motor Driver.
  3. Servos

API

MotorInterface

interface com.diozero.api.motor.MotorInterface source

Represents a single motor.

forward (speed=1)

Turn the motor forward at the specified speed (range 0..1).

  • speed (float) - Speed, range 0..1. Defaults to 1.
backward (speed=1)

Turn the motor backward at the specified speed (range 0..1).

  • speed (float) - Speed, range 0..1. Defaults to 1.
stop ()

Stop the motor.

reverse ()

Reverse the direction of the motor.

float getValue ()

Get the current motor direction and speed, between -1 (full speed backward) and 1 (full speed forward).

setValue (value)

Set the motor direction and speed.

  • value (float) - Relative value between -1 (full speed backward) and 1 (full speed forward).
boolean isActive ()

Return true if the motor is moving in either direction, false if stopped.

whenForward (action)

Action to perform when going forward

  • action (Action) - Callback action object
whenBackward (action)

Action to perform when going backward

  • action (Action) - Callback action object
whenStop (action)

Action to perform when stopped

  • action (Action) - Callback action object
addListener (listener)

Listener to be notified when the motor value changes

  • listener (MotorListener) - Listener instance
removeListener (listener)

Remove a listener

  • listener (MotorListener) - Listener instance

MotorBase

interface com.diozero.api.motor.MotorBase source

Base motor class, support for events. Implements MotorInterface.

MotorBase ()

Constructor.

reverse ()

Reverse the direction of the motor.

setValue (value)

Set the motor direction and speed.

  • value (float) - Range -1..1. Negative numbers backward.
whenForward (action)

Action to perform when going forward

  • action (Action) - Callback action object
whenBackward (action)

Action to perform when going backward

  • action (Action) - Callback action object
whenStop (action)

Action to perform when stopped

  • action (Action) - Callback action object
addListener (listener)

Listener to be notified when the motor value changes

  • listener (MotorListener) - Listener instance
removeListener (listener)

Remove a listener

  • listener (MotorListener) - Listener instance

Digital Motor

class com.diozero.api.motor.DigitalMotor (forwardGpio, backwardGpio) source

Represents a single motor controlled by two separate digital signals. Extends MotorBase.

  • forwardGpio (int) - GPIO for forward / clockwise control.

  • backwardGpio (int) - GPIO for backward / anti-clockwise control.

forward ()

Stop the backward motor and turn on the forward motor.

backward ()

Stop the forward motor and turn on the backward motor.

stop ()

Stop both motors.

boolean getValue ()

Represents the speed of the motor as a floating point value that will either be -1 (full speed backward), 1 (full speed forward) or 0 (stopped).

boolean isActive ()

Returns true if either motor is active.

PWM Motor

class com.diozero.api.motor.PwmMotor (forwardGpio, backwardGpio) source

Represents a single motor controlled by two separate PWM signals. Extends MotorBase.

  • forwardGpio (int) - PWM-capable GPIO for forward / clockwise control.

  • backwardGpio (int) - PWM-capable GPIO for backward / anti-clockwise control.

PwmMotor (deviceFactory, forwardGpio, backwardGpio)

Constructor.

  • deviceFactory (PwmOutputDeviceFactoryInterface) - Device factory to use for constructing the PWMOutputDevice instances.

  • forwardGpio (int) - PWM-capable GPIO for forward / clockwise control.

  • backwardGpio (int) - PWM-capable GPIO for backward / anti-clockwise control.

forward (speed)

Stop the backward motor and set the forward motor speed.

speed (float) - value range 0..1.

backward (speed)

Stop the forward motor and set the backward motor speed.

speed (float) - value range 0..1.

stop ()

Stop both motors.

boolean getValue ()

Represents the speed of the motor as a floating point value between -1 (full speed backward) and 1 (full speed forward).

boolean isActive ()

Returns true if either motor is active.

TB6612FNGMotor

class com.diozero.sandpit.TB6612FNGMotor (motorForwardControlPin, motorBackwardControlPin, motorPwmControl) source

Represents a single motor controlled by one PWM signal and two separate forwards / backwards control digital signals. Extends MotorBase.

  • motorForwardControlPin (DigitalOutputDevice - Digital device controlling forward movement.

  • motorBackwardControlPin (DigitalOutputDevice - Digital device controlling backward movement.

  • motorPwmControl (PwmOutputDevice - PWM output device controlling relative motor speed.

DualMotor

class com.diozero.api.motor.DualMotor (leftMotor, rightMotor) source

Convenience class for a robot with two Motors.

float[] getValues ()

Get the directional values for both motors (-1 backwards .. 1 forwards).

setValues (leftValue, rightValue)

Set the speed and direction for both let and right motors (clockwise / counter-clockwise).

  • leftValue (float) - Range -1 .. 1. Positive numbers for clockwise, Negative numbers for counter clockwise.

  • rightValue (float) - Range -1 .. 1. Positive numbers for anti-clockwise, Negative numbers for counter clockwise.

forward (speed)

Set both motors forward at the specific speed. Range 0..1.

backward (speed)

Set both motors backward at the specific speed. Range 0..1.

rotateLeft (speed)

Turn the left motor backward and the right motor forward at the specific speed. Range 0..1.

rotateRight (speed)

Turn the left motor forward and the right motor backward at the specific speed. Range 0..1.

forwardLeft (speed)

Turn the right motor forward at the specified speed, stop the left motor. Range 0..1.

forwardRight (speed)

Turn the left motor forward at the specified speed, stop the right motor. Range 0..1.

backwardLeft (speed)

Turn the right motor backward at the specified speed, stop the left motor. Range 0..1.

backwardRight (speed)

Turn the left motor backward at the specified speed, stop the right motor. Range 0..1.

reverse ()

Reverse the direction of both motors.

circleLeft (speed, turnRate)

Circle to the left.

  • speed (float) - Range 0..1.

  • turnRate (float) - Range 0..speed.

circleRight (speed, turnRate)

Circle to the right.

  • speed (float) - Range 0..1.

  • turnRate (float) - Range 0..speed.

stop ()

Stop both motors.

Servo

Work in progress

Only tested with pigpio hence in the sandpit package.

class com.diozero.sandpit.Servo (gpio, pwmFrequency, initialPulseWidthMs) source

Represents a pulse-width controlled servo.

  • gpio (int) - GPIO

  • pwmFrequency (int) - Desired PWM frequency for the servo, typically 50Hz

  • initialPulseWidthMs (float) - Starting pulse width (in milliseconds). Range is 0.5ms - 2.6ms

getPulseWidthMs ()

Get the current pulse width value (milliseconds)

float getPulseWidthMs (float pulseWidthMs)

Set the pulse width value (milliseconds)

pulseWidthMs - New pulse width value (milliseconds)

Common Motor Controllers

CamJamKitDualMotor

class com.diozero.CamJamKitDualMotor source

Extends DualMotor. Convenience class for interfacing with the CamJam EduKit #3 Motor Controller Board with pre-configured GPIOs (left -> 9 and 10, right -> 7 and 8).

RyanteckDualMotor

class com.diozero.RyanteckDualMotor source

Extends DualMotor. Convenience class for interfacing with the Ryanteck RPi Motor Controller Board with pre-configured GPIOs (left -> 17 and 18, right -> 22 and 23).

TB6612FNGDualMotorDriver

class com.diozero.sandpit.TB6612FNGDualMotorDriver source

Extends DualMotor. Convenience class for interfacing with dual H-bridge motor drivers such as the Toshiba TB6612FNG Dual Motor Driver as used in the Pololu Dual Motor Driver Carrier.