Adafruit Motor Shield V2

You will be redirected back to this guide once you sign in, and can then subscribe to this guide.

Intermediate Project guide

Python & CircuitPython

We've written a handy CircuitPython library for the various DC Motor and Stepper kits called Adafruit CircuitPython MotorKit that handles all the complicated setup for you. All you need to do is import the appropriate class from the library, and then all the features of that class are available for use. We're going to show you how to import the MotorKit class and use it to control DC and stepper motors with the Adafruit Stepper + DC Motor Shield.

CircuitPython Microcontroller Wiring

First assemble the Shield exactly as shown in the previous pages. There's no wiring needed to connect the Shield to the Metro. The example below shows wiring two DC motors to the Shield once it has been attached to a Metro. You'll want to connect a barrel jack to the power terminal to attach an appropriate external power source to the Shield. The Shield will not function without an external power source!

Connect the two motor wires from the first motor to the M1 terminal on the Shield.
Connect the two motor wires from the second motor to the M2 terminal on the Shield.
Connect the positive side of the power terminal to the positive side of the barrel jack.
Connect the negative side of the power terminal to the negative side of the barrel jack.

CircuitPython Installation of MotorKit and Necessary Libraries

You'll need to install a few libraries on your Metro board.

First make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our CircuitPython starter guide has a great page on how to install the library bundle.

If you choose, you can manually install the libraries individually on your board:

Before continuing make sure your board's lib folder or root filesystem has the adafruit_pca9685.mpy, adafruit_register, adafruit_motor, adafruit_bus_device and adafruit_motorkit.mpy files and folders copied over.

Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.

CircuitPython Usage

To demonstrate the usage, we'll initialise the library and use Python code to control DC and stepper motors from the board's Python REPL.

First you'll need to import and initialize the MotorKit class.

from adafruit_motorkit import MotorKit kit = MotorKit()

from adafruit_motorkit import MotorKit kit = MotorKit()

The four motor spots on the Shield are available as motor1 , motor2 , motor3 , and motor4 .

In this example we'll use motor1 .

Note: For small DC motors like sold in the shop you might run into problems with electrical noise they generate and erratic behavior on your board. If you see erratic behavior like the motor not spinning or the board resetting at high motor speeds this is likely the problem. See this motor guide FAQ page for information on capacitors you can solder to the motor to reduce noise.

Now to move a motor you can set the throttle attribute. We don't call it speed because it doesn't correlate to a particular number of revolutions per minute (RPM). RPM depends on the motor and the voltage which is unknown.

For example to drive motor M1 forward at a full speed you set it to 1.0 :

kit.motor1.throttle = 1.0

kit.motor1.throttle = 1.0

To run the motor at half throttle forward use a decimal:

kit.motor1.throttle = 0.5

kit.motor1.throttle = 0.5

Or to reverse the direction use a negative throttle:

kit.motor1.throttle = -0.5

kit.motor1.throttle = -0.5

You can stop the motor with a throttle of 0 :

kit.motor1.throttle = 0

kit.motor1.throttle = 0

To let the motor coast and then spin freely set throttle to None .

kit.motor1.throttle = None

kit.motor1.throttle = None

That's all there is to controlling DC motors with CircuitPython! With DC motors you can build fun moving projects like robots or remote controlled cars that glide around with ease.

Stepper Motors

Similar DC motors, stepper motors are available as stepper1 and stepper2 . stepper1 is made up of the M1 and M2 terminals, and stepper2 is made up of the M3 and M4 terminals.

We'll use stepper1 in our example.

The most basic function (and the default) is to do one single coil step.

kit.stepper1.onestep()

kit.stepper1.onestep()

You can also call the onestep function with two optional keyword arguments. To use these, you'll need to import stepper as well.

from adafruit_motor import stepper

from adafruit_motor import stepper

Then you have access to the following options:

direction , which should be one of the following constant values:

stepper.FORWARD (default)
stepper.BACKWARD .

stepper.SINGLE (default) for a full step rotation to a position where one single coil is powered
stepper.DOUBLE for a full step rotation to position where two coils are powered providing more torque
stepper.INTERLEAVED for a half step rotation interleaving single and double coil positions and torque
stepper.MICROSTEP for a microstep rotation to a position where two coils are partially active.

The function returns the current step 'position' in microsteps which can be handy to understand how far the stepper has moved, or you can ignore the result.

To take a double-coil step backward call:

kit.stepper1.onestep(direction=stepper.BACKWARD, style=stepper.DOUBLE)

kit.stepper1.onestep(direction=stepper.BACKWARD, style=stepper.DOUBLE)

You can even use a loop to continuously call onestep and move the stepper, for example a loop of 200 microsteps forward for smooth movement:

for i in range(200): kit.stepper1.onestep(style=stepper.MICROSTEP)

for i in range(200): kit.stepper1.onestep(style=stepper.MICROSTEP)

That's all there is to controlling a stepper motor from CircuitPython! Steppers are handy motors for when you need smooth or precise control of something--for example 3D printers and CNC machines use steppers to precisely move tools around surfaces.

Full Example Code

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT """Simple test for using adafruit_motorkit with a DC motor""" import time import board from adafruit_motorkit import MotorKit kit = MotorKit(i2c=board.I2C()) kit.motor1.throttle = 1.0 time.sleep(0.5) kit.motor1.throttle = 0

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT """Simple test for using adafruit_motorkit with a DC motor""" import time import board from adafruit_motorkit import MotorKit kit = MotorKit(i2c=board.I2C()) kit.motor1.throttle = 1.0 time.sleep(0.5) kit.motor1.throttle = 0

For stepper motors:

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT """Simple test for using adafruit_motorkit with a stepper motor""" import time import board from adafruit_motorkit import MotorKit kit = MotorKit(i2c=board.I2C()) for i in range(100): kit.stepper1.onestep() time.sleep(0.01)

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT """Simple test for using adafruit_motorkit with a stepper motor""" import time import board from adafruit_motorkit import MotorKit kit = MotorKit(i2c=board.I2C()) for i in range(100): kit.stepper1.onestep() time.sleep(0.01)

Text editor powered by tinymce.