Introduction

Documentation Status Discord Build Status

This helper library provides higher level objects to control motors and servos based on one or more PWM outputs.

The PWM inputs can be any object that have a 16-bit duty_cycle attribute. Its assumed that the frequency has already been configured appropriately. (Typically 50hz for servos and 1600hz for motors.)

Dependencies

This driver depends on:

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-motor

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-motor

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install adafruit-circuitpython-motor

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Building locally

To build this library locally you’ll need to install the circuitpython-build-tools package.

python3 -m venv .env
source .env/bin/activate
pip install circuitpython-build-tools

Once installed, make sure you are in the virtual environment:

source .env/bin/activate

Then run the build:

circuitpython-build-bundles --filename_prefix adafruit-circuitpython-motor --library_location .

Sphinx documentation

Sphinx is used to build the documentation based on rST files and comments in the code. First, install dependencies (feel free to reuse the virtual environment from above):

python3 -m venv .env
source .env/bin/activate
pip install Sphinx sphinx-rtd-theme

Now, once you have the virtual environment activated:

cd docs
sphinx-build -E -W -b html . _build/html

This will output the documentation to docs/_build/html. Open the index.html in your browser to view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to locally verify it will pass.

Table of Contents

Simple tests

Ensure your device works with this simple test.

examples/dc_motor.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# This example uses an Adafruit Stepper and DC Motor FeatherWing to run a DC Motor.
#   https://www.adafruit.com/product/2927

import time

from board import SCL, SDA
import busio

# Import the PCA9685 module. Available in the bundle and here:
#   https://github.com/adafruit/Adafruit_CircuitPython_PCA9685
from adafruit_pca9685 import PCA9685

from adafruit_motor import motor

i2c = busio.I2C(SCL, SDA)

# Create a simple PCA9685 class instance for the Motor FeatherWing's default address.
pca = PCA9685(i2c, address=0x60)
pca.frequency = 100

# Motor 1 is channels 9 and 10 with 8 held high.
# Motor 2 is channels 11 and 12 with 13 held high.
# Motor 3 is channels 3 and 4 with 2 held high.
# Motor 4 is channels 5 and 6 with 7 held high.

# DC Motors generate electrical noise when running that can reset the microcontroller in extreme
# cases. A capacitor can be used to help prevent this. The demo uses motor 4 because it worked ok
# in testing without a capacitor.
# See here for more info: https://learn.adafruit.com/adafruit-motor-shield-v2-for-arduino/faq#faq-13
pca.channels[7].duty_cycle = 0xffff
motor4 = motor.DCMotor(pca.channels[5], pca.channels[6])

print("Forwards slow")
motor4.throttle = 0.5
print("throttle:", motor4.throttle)
time.sleep(1)

print("Forwards")
motor4.throttle = 1
print("throttle:", motor4.throttle)
time.sleep(1)

print("Backwards")
motor4.throttle = -1
print("throttle:", motor4.throttle)
time.sleep(1)

print("Backwards slow")
motor4.throttle = -0.5
print("throttle:", motor4.throttle)
time.sleep(1)

print("Stop")
motor4.throttle = 0
print("throttle:", motor4.throttle)
time.sleep(1)

print("Spin freely")
motor4.throttle = None
print("throttle:", motor4.throttle)

pca.deinit()
examples/stepper_motor.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# This example uses an Adafruit Stepper and DC Motor FeatherWing to run a Stepper Motor.
#   https://www.adafruit.com/product/2927

import time

from board import SCL, SDA
import busio

# Import the PCA9685 module. Available in the bundle and here:
#   https://github.com/adafruit/Adafruit_CircuitPython_PCA9685
from adafruit_pca9685 import PCA9685

from adafruit_motor import stepper

i2c = busio.I2C(SCL, SDA)

# Create a simple PCA9685 class instance for the Motor FeatherWing's default address.
pca = PCA9685(i2c, address=0x60)
pca.frequency = 1600

# Motor 1 is channels 9 and 10 with 8 held high.
# Motor 2 is channels 11 and 12 with 13 held high.
# Motor 3 is channels 3 and 4 with 2 held high.
# Motor 4 is channels 5 and 6 with 7 held high.

pca.channels[7].duty_cycle = 0xffff
pca.channels[2].duty_cycle = 0xffff
stepper_motor = stepper.StepperMotor(pca.channels[4], pca.channels[3], # Motor 3
                                     pca.channels[5], pca.channels[6]) # Motor 4

for i in range(100):
    stepper_motor.onestep()
    time.sleep(0.01)

for i in range(100):
    stepper_motor.onestep(direction=stepper.BACKWARD)
    time.sleep(0.01)

pca.deinit()
examples/servo_sweep.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
import time

from board import SCL, SDA
import busio

# Import the PCA9685 module. Available in the bundle and here:
#   https://github.com/adafruit/Adafruit_CircuitPython_PCA9685
from adafruit_pca9685 import PCA9685
from adafruit_motor import servo

i2c = busio.I2C(SCL, SDA)

# Create a simple PCA9685 class instance.
pca = PCA9685(i2c)
# You can optionally provide a finer tuned reference clock speed to improve the accuracy of the
# timing pulses. This calibration will be specific to each board and its environment. See the
# calibration.py example in the PCA9685 driver.
# pca = PCA9685(i2c, reference_clock_speed=25630710)
pca.frequency = 50

# To get the full range of the servo you will likely need to adjust the min_pulse and max_pulse to
# match the stall points of the servo.
# This is an example for the Sub-micro servo: https://www.adafruit.com/product/2201
# servo7 = servo.Servo(pca.channels[7], min_pulse=580, max_pulse=2350)
# This is an example for the Micro Servo - High Powered, High Torque Metal Gear:
#   https://www.adafruit.com/product/2307
# servo7 = servo.Servo(pca.channels[7], min_pulse=500, max_pulse=2600)
# This is an example for the Standard servo - TowerPro SG-5010 - 5010:
#   https://www.adafruit.com/product/155
# servo7 = servo.Servo(pca.channels[7], min_pulse=400, max_pulse=2400)
# This is an example for the Analog Feedback Servo: https://www.adafruit.com/product/1404
# servo7 = servo.Servo(pca.channels[7], min_pulse=600, max_pulse=2500)
# This is an example for the Micro servo - TowerPro SG-92R: https://www.adafruit.com/product/169
# servo7 = servo.Servo(pca.channels[7], min_pulse=500, max_pulse=2400)

# The pulse range is 750 - 2250 by default. This range typically gives 135 degrees of
# range, but the default is to use 180 degrees. You can specify the expected range if you wish:
# servo7 = servo.Servo(pca.channels[7], actuation_range=135)
servo7 = servo.Servo(pca.channels[7])

# We sleep in the loops to give the servo time to move into position.
for i in range(180):
    servo7.angle = i
    time.sleep(0.03)
for i in range(180):
    servo7.angle = 180 - i
    time.sleep(0.03)

# You can also specify the movement fractionally.
fraction = 0.0
while fraction < 1.0:
    servo7.fraction = fraction
    fraction += 0.01
    time.sleep(0.03)

pca.deinit()
examples/continuous_servo.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import time

from board import SCL, SDA
import busio

# Import the PCA9685 module. Available in the bundle and here:
#   https://github.com/adafruit/Adafruit_CircuitPython_PCA9685
from adafruit_pca9685 import PCA9685

from adafruit_motor import servo

i2c = busio.I2C(SCL, SDA)

# Create a simple PCA9685 class instance.
pca = PCA9685(i2c)
# You can optionally provide a finer tuned reference clock speed to improve the accuracy of the
# timing pulses. This calibration will be specific to each board and its environment. See the
# calibration.py example in the PCA9685 driver.
# pca = PCA9685(i2c, reference_clock_speed=25630710)
pca.frequency = 50

# The pulse range is 750 - 2250 by default.
servo7 = servo.ContinuousServo(pca.channels[7])
# If your servo doesn't stop once the script is finished you may need to tune the
# reference_clock_speed above or the min_pulse and max_pulse timings below.
# servo7 = servo.ContinuousServo(pca.channels[7], min_pulse=750, max_pulse=2250)

print("Forwards")
servo7.throttle = 1
time.sleep(1)

print("Backwards")
servo7.throttle = -1
time.sleep(1)

print("Stop")
servo7.throttle = 0

pca.deinit()

adafruit_motor.motor

Simple control of a DC motor. DC motors have two wires and should not be connected directly to the PWM connections. Instead use intermediate circuitry to control a much stronger power source with the PWM. The Adafruit Stepper + DC Motor FeatherWing, Adafruit TB6612 1.2A DC/Stepper Motor Driver Breakout Board and Adafruit Motor/Stepper/Servo Shield for Arduino v2 Kit - v2.3 do this for popular form factors already.

Note

The TB6612 boards feature three inputs XIN1, XIN2 and PWMX. Since we PWM the INs directly its expected that the PWM pin is consistently high.

  • Author(s): Scott Shawcroft
class adafruit_motor.motor.DCMotor(positive_pwm, negative_pwm)[source]

DC motor driver. positive_pwm and negative_pwm can be swapped if the motor runs in the opposite direction from what was expected for “forwards”.

Parameters:
  • positive_pwm (PWMOut) – The motor input that causes the motor to spin forwards when high and the other is low.
  • negative_pwm (PWMOut) – The motor input that causes the motor to spin backwards when high and the other is low.
deinit()[source]

Stop using the motor.

throttle

Motor speed, ranging from -1.0 (full speed reverse) to 1.0 (full speed forward), or None. If None, both PWMs are turned full off. If 0.0, both PWMs are turned full on.

adafruit_motor.servo

Servos are motor based actuators that incorporate a feedback loop into the design. These feedback loops enable pulse width modulated control to determine position or rotational speed.

  • Author(s): Scott Shawcroft
class adafruit_motor.servo.ContinuousServo(pwm_out, *, min_pulse=750, max_pulse=2250)[source]

Control a continuous rotation servo.

Parameters:
  • min_pulse (int) – The minimum pulse width of the servo in microseconds.
  • max_pulse (int) – The maximum pulse width of the servo in microseconds.
deinit()[source]

Stop using the servo.

throttle

How much power is being delivered to the motor. Values range from -1.0 (full throttle reverse) to 1.0 (full throttle forwards.) 0 will stop the motor from spinning.

class adafruit_motor.servo.Servo(pwm_out, *, actuation_range=180, min_pulse=750, max_pulse=2250)[source]

Control the position of a servo.

Parameters:
  • pwm_out (PWMOut) – PWM output object.
  • actuation_range (int) – The physical range of motion of the servo in degrees, for the given min_pulse and max_pulse values.
  • min_pulse (int) – The minimum pulse width of the servo in microseconds.
  • max_pulse (int) – The maximum pulse width of the servo in microseconds.

actuation_range is an exposed property and can be changed at any time:

servo = Servo(pwm)
servo.actuation_range = 135

The specified pulse width range of a servo has historically been 1000-2000us, for a 90 degree range of motion. But nearly all modern servos have a 170-180 degree range, and the pulse widths can go well out of the range to achieve this extended motion. The default values here of 750 and 2250 typically give 135 degrees of motion. You can set actuation_range to correspond to the actual range of motion you observe with your given min_pulse and max_pulse values.

Warning

You can extend the pulse width above and below these limits to get a wider range of movement. But if you go too low or too high, the servo mechanism may hit the end stops, buzz, and draw extra current as it stalls. Test carefully to find the safe minimum and maximum.

actuation_range

The physical range of motion of the servo in degrees.

angle

The servo angle in degrees. Must be in the range 0 to actuation_range.

adafruit_motor.stepper

Stepper motors feature multiple wire coils that are used to rotate the magnets connected to the motor shaft in a precise way. Each increment of the motor is called a step. Stepper motors have a varying number of steps per rotation so check the motor’s documentation to determine exactly how precise each step is.

  • Author(s): Tony DiCola, Scott Shawcroft
adafruit_motor.stepper.BACKWARD = 2

“Step backward

adafruit_motor.stepper.DOUBLE = 2

Step so that each step only activates two coils to produce more torque.

adafruit_motor.stepper.FORWARD = 1

Step forward

adafruit_motor.stepper.INTERLEAVE = 3

Step half a step to alternate between single coil and double coil steps.

adafruit_motor.stepper.MICROSTEP = 4

Step a fraction of a step by partially activating two neighboring coils. Step size is determined by microsteps constructor argument.

adafruit_motor.stepper.SINGLE = 1

Step so that each step only activates a single coil

class adafruit_motor.stepper.StepperMotor(ain1, ain2, bin1, bin2, *, microsteps=16)[source]

A bipolar stepper motor or four coil unipolar motor.

Parameters:
  • ain1 (PWMOut) – pulseio.PWMOut-compatible output connected to the driver for the first coil (unipolar) or first input to first coil (bipolar).
  • ain2 (PWMOut) – pulseio.PWMOut-compatible output connected to the driver for the third coil (unipolar) or second input to first coil (bipolar).
  • bin1 (PWMOut) – pulseio.PWMOut-compatible output connected to the driver for the second coil (unipolar) or second input to second coil (bipolar).
  • bin2 (PWMOut) – pulseio.PWMOut-compatible output connected to the driver for the fourth coil (unipolar) or second input to second coil (bipolar).
  • microsteps (int) – Number of microsteps between full steps. Must be at least 2 and even.
onestep(*, direction=1, style=1)[source]

Performs one step of a particular style. The actual rotation amount will vary by style. SINGLE and DOUBLE will normal cause a full step rotation. INTERLEAVE will normally do a half step rotation. MICROSTEP will perform the smallest configured step.

When step styles are mixed, subsequent SINGLE, DOUBLE or INTERLEAVE steps may be less than normal in order to align to the desired style’s pattern.

Parameters:
release()[source]

Releases all the coils so the motor can free spin, also won’t use any power

Indices and tables