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

CircuitPython Microcontroller and Python Wiring

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

  • Connect the two motor wires from the first motor to the M1 terminal on the FeatherWing.
  • Connect the two motor wires from the second motor to the M2 terminal on the FeatherWing.
  • 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 Feather 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, initialize the MotorKit class and provide the I2C device.

import board
from adafruit_motorkit import MotorKit
kit = MotorKit(i2c=board.I2C())

You can also initialise the library without specifying I2C as follows:

from adafruit_motorkit import MotorKit
kit = MotorKit()

DC Motors

The four motor spots on the FeatherWing 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.  The SAMD21 Feather M0 boards in particular have been susceptible to this issue.  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

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

kit.motor1.throttle = 0.5

Or to reverse the direction use a negative throttle:

kit.motor1.throttle = -0.5

You can stop the motor with a throttle of 0:

kit.motor1.throttle = 0

To let the motor coast and then spin freely set throttle to 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()

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

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

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)

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.

Using MotorKit with Multiple I2C Devices

Using multiple I2C devices with MotorKit is super simple. The important thing is how you instantiate the other I2C devices.

This example shows how to use the APDS9960 gesture and proximity sensor along with MotorKit. The following will work with any other I2C device as well.

First import all of the necessary libraries.

import board
from adafruit_motorkit import MotorKit
from adafruit_apds9960.apds9960 import APDS9960

Next, create an I2C object, and instantiate the two libraries.

i2c = board.I2C()
kit = MotorKit(i2c=i2c)
apds = APDS9960(i2c)

From there you can use both MotorKit and the APDS9960 sensor however you'd like in your code!

This will work with any I2C sensor. Simply import the appropriate library, and instantiate the I2C object and the library.

That's all there is to using multiple I2C devices with MotorKit!

Full Example Code

For DC motors:

# 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)

This guide was first published on Jul 29, 2016. It was last updated on Mar 28, 2024.

This page (CircuitPython Usage) was last updated on Mar 28, 2024.

Text editor powered by tinymce.