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.

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
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 550 - 2400 by default.
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)
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 550 - 2400 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=550, max_pulse=2400)

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

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 and None will let the motor spin freely.

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=550, max_pulse=2400)[source]

Control a continuous rotation servo.

Parameters:
  • min_pulse (int) – The minimum pulse length of the servo in microseconds.
  • max_pulse (int) – The maximum pulse length 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=550, max_pulse=2400)[source]

Control the position of a servo.

Parameters:
  • pwm_out (PWMOut) – PWM output object.
  • actuation_range (int) – The physical range of the servo corresponding to the signal’s duty in degrees.
  • min_pulse (int) – The minimum pulse length of the servo in microseconds.
  • max_pulse (int) – The maximum pulse length of the servo in microseconds.
angle

The servo angle in degrees.

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

“Step backward

adafruit_motor.stepper.DOUBLE

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

adafruit_motor.stepper.FORWARD

Step forward

adafruit_motor.stepper.INTERLEAVE

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

adafruit_motor.stepper.MICROSTEP

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

adafruit_motor.stepper.SINGLE

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=<sphinx.ext.autodoc.importer._MockObject object>, style=<sphinx.ext.autodoc.importer._MockObject object>)[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:

Indices and tables