Using Stepper Motors

Stepper motors are great for (semi-)precise control, perfect for many robot and CNC projects. This HAT supports up to 2 stepper motors. The python library works identically for bi-polar and uni-polar motors.

Running a stepper is a little more intricate than running a DC motor but its still very easy.

Connecting Stepper Motors

For unipolar motors: to connect up the stepper, first figure out which pins connected to which coil, and which pins are the center taps. If its a 5-wire motor then there will be 1 that is the center tap for both coils. Theres plenty of tutorials online on how to reverse engineer the coils pinout. The center taps should both be connected together to the center GND terminal on the Motor HAT output block. then coil 1 should connect to one motor port (say M1 or M3) and coil 2 should connect to the other motor port (M2 or M4).

For bipolar motors: its just like unipolar motors except there's no 5th wire to connect to ground. The code is exactly the same.

For this demo, please connect it to M1 and M2

Run python3 to get to the Python REPL.

Controlling Stepper Motors

To demonstrate the usage, we'll initialise the library and use Python code to control a DC motor from the Python REPL.

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

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

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

There are a number of optional features available for the onestep() function. Let's take a look!


Stepper motors differ from DC motors in that the controller (in this case, Raspberry Pi) must tick each of the 4 coils in order to make the motor move. Each two 'ticks' is a step. By alternating the coils, the stepper motor will spin all the way around. If the coils are fired in the opposite order, it will spin the other way around.

If the python code or Pi crashes or stops responding, the motor will no longer move. Compare this to a DC motor which has a constant voltage across a single coil for movement.

There are four essential types of steps you can use with your Motor HAT. All four kinds will work with any unipolar or bipolar stepper motor

  1. Single Steps - this is the simplest type of stepping, and uses the least power. It uses a single coil to 'hold' the motor in place, as seen in the animated GIF above
  2. Double Steps - this is also fairly simple, except instead of a single coil, it has two coils on at once. For example, instead of just coil #1 on, you would have coil #1 and #2 on at once. This uses more power (approx 2x) but is stronger than single stepping (by maybe 25%)
  3. Interleaved Steps - this is a mix of Single and Double stepping, where we use single steps interleaved with double. It has a little more strength than single stepping, and about 50% more power. What's nice about this style is that it makes your motor appear to have 2x as many steps, for a smoother transition between steps
  4. Microstepping - this is where we use a mix of single stepping with PWM to slowly transition between steps. It's slower than single stepping but has much higher precision. We recommend 8 microstepping which multiplies the # of steps your stepper motor has by 8.

You can 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):

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

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

kit = MotorKit()

for i in range(100):
This guide was first published on Jan 27, 2015. It was last updated on Jan 27, 2015. This page (Using Stepper Motors) was last updated on May 22, 2019.