Introduction¶
This helper library provides higher level objects to control motors and servos based on one or more PWM outputs.
The PWM outputs 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.
Documentation¶
For information on building library documentation, please check out this guide.
Table of Contents¶
Simple tests¶
Ensure your device works with this simple test.
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import time
import board
import pulseio
from adafruit_motor import servo
# create a PWMOut object on the control pin.
pwm = pulseio.PWMOut(board.D5, duty_cycle=0, 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
# servo = servo.Servo(pwm, 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
# servo = servo.Servo(pwm, min_pulse=500, max_pulse=2600)
# This is an example for the Standard servo - TowerPro SG-5010 - 5010:
# https://www.adafruit.com/product/155
# servo = servo.Servo(pwm, min_pulse=400, max_pulse=2400)
# This is an example for the Analog Feedback Servo: https://www.adafruit.com/product/1404
# servo = servo.Servo(pwm, min_pulse=600, max_pulse=2500)
# This is an example for the Micro servo - TowerPro SG-92R: https://www.adafruit.com/product/169
# servo = servo.Servo(pwm, 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:
# servo = servo.Servo(board.D5, actuation_range=135)
servo = servo.Servo(pwm)
# We sleep in the loops to give the servo time to move into position.
print("Sweep from 0 to 180")
for i in range(180):
servo.angle = i
time.sleep(0.01)
print("Sweep from 180 to 0")
for i in range(180):
servo.angle = 180 - i
time.sleep(0.01)
print("Move to 90 degrees")
servo.angle = 90
time.sleep(1)
print("Release servo motor for 10 seconds")
servo.fraction = None
time.sleep(10)
# You can also specify the movement fractionally.
print("Sweep from 0 to 1.0 fractionally")
fraction = 0.0
while fraction < 1.0:
servo.fraction = fraction
fraction += 0.01
time.sleep(0.01)
|
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 63 64 65 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
# 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()
|
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
# 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], pca.channels[5], pca.channels[6]
)
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()
|
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
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()
|
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
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
andnegative_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.
-
throttle
¶ Motor speed, ranging from -1.0 (full speed reverse) to 1.0 (full speed forward), or
None
. IfNone
, both PWMs are turned full off. If0.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: -
throttle
¶ How much power is being delivered to the motor. Values range from
-1.0
(full throttle reverse) to1.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
andmax_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
and2250
typically give 135 degrees of motion. You can setactuation_range
to correspond to the actual range of motion you observe with your givenmin_pulse
andmax_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
toactuation_range
. Is None when servo is disabled.
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. The use of microstepping requires pins that can output PWM. For non-microstepping, can set microsteps to None and use digital out pins.
PWM
Parameters: - ain1 (PWMOut) –
pwmio.PWMOut
-compatible output connected to the driver for the first coil (unipolar) or first input to first coil (bipolar). - ain2 (PWMOut) –
pwmio.PWMOut
-compatible output connected to the driver for the third coil (unipolar) or second input to first coil (bipolar). - bin1 (PWMOut) –
pwmio.PWMOut
-compatible output connected to the driver for the second coil (unipolar) or second input to second coil (bipolar). - bin2 (PWMOut) –
pwmio.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.
Digital Out
Parameters: - ain1 (DigitalInOut) –
digitalio.DigitalInOut
-compatible output connected to the driver for the first coil (unipolar) or first input to first coil (bipolar). - ain2 (DigitalInOut) –
digitalio.DigitalInOut
-compatible output connected to the driver for the third coil (unipolar) or second input to first coil (bipolar). - bin1 (DigitalInOut) –
digitalio.DigitalInOut
-compatible output connected to the driver for the second coil (unipolar) or first input to second coil (bipolar). - bin2 (DigitalInOut) –
digitalio.DigitalInOut
-compatible output connected to the driver for the fourth coil (unipolar) or second input to second coil (bipolar). - microsteps – set to
None
-
onestep
(*, direction=1, style=1)[source]¶ Performs one step of a particular style. The actual rotation amount will vary by style.
SINGLE
andDOUBLE
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
orINTERLEAVE
steps may be less than normal in order to align to the desired style’s pattern.Parameters:
- ain1 (PWMOut) –