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:

  • adafruit_pca9685
  • adafruit_bus_device
  • adafruit_register
  • adafruit_motor
  • adafruit_motorkit

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 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.

Download: file
from adafruit_motorkit import MotorKit
kit = MotorKit()

DC Motors

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:

Download: file
kit.motor1.throttle = 1.0

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

Download: file
kit.motor1.throttle = 0.5

Or to reverse the direction use a negative throttle:

Download: file
kit.motor1.throttle = -0.5

You can stop the motor with a throttle of 0:

Download: file
kit.motor1.throttle = 0

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

Download: file
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.

Download: file
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.

Download: file
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.
  • style, which should be one of the values:
    • 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.
  • release() which releases all the coils so the motor can free spin, and also won't use any power

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:

Download: file
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:

Download: file
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

For DC motors:

"""Simple test for using adafruit_motorkit with a DC motor"""
import time
from adafruit_motorkit import MotorKit

kit = MotorKit()

kit.motor1.throttle = 1.0
time.sleep(0.5)
kit.motor1.throttle = 0

For stepper motors:

"""Simple test for using adafruit_motorkit with a stepper motor"""
from adafruit_motorkit import MotorKit

kit = MotorKit()

for i in range(100):
    kit.stepper1.onestep()
This guide was first published on Jul 09, 2013. It was last updated on Jul 09, 2013. This page (Python & CircuitPython) was last updated on Apr 22, 2019.