Arduino library 路 Motion

The Arduino Stepper library and the 28BYJ-48

Stepper.h is the small stepper library that comes with the Arduino IDE. It knows how many steps make one turn, a speed in revolutions per minute, and a coil pattern, and step(n) walks the motor n steps through that pattern, blocking until it is done. It has no acceleration and no position counter: it is for moving a motor a set number of steps at a steady speed.

Built in on Mokxi: #include <Stepper.h> and it builds, with nothing to install. Free, and no account needed.

What Stepper does

Most people meet it with the 28BYJ-48 geared motor and its ULN2003 driver board from a starter kit. In the library鈥檚 full-step mode that motor needs 2048 steps for one turn of the output shaft, and it will not follow much faster than about 15 rpm before it starts missing steps.

The part every kit lesson gets people to type without explaining is the pin order. The library鈥檚 four-wire sequence was written for a bipolar motor on an H bridge, so for the ULN2003 inputs IN1 to IN4 the constructor must be given IN1, IN3, IN2, IN4. With pins 8, 9, 10 and 11 in plain order the motor energizes opposite coils and just hums.

Library Manager nameStepper
AuthorArduino
Include#include <Stepper.h>
Boardsevery board Mokxi compiles for but ATtiny85
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesStepper motor, 28BYJ-48 with ULN2003

Install it

It builds on every board Mokxi compiles for but ATtiny85.

In Mokxi it is built in: #include <Stepper.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "Stepper" by Arduino from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add Stepper to lib_deps in PlatformIO. Mokxi follows the calls of release 1.1.3, so a sketch written here builds there too.

ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi

The calls you will use

In the order a sketch meets them.

Stepper myStepper(2048, 8, 10, 9, 11)

Steps per revolution, then the four driver inputs in the order IN1, IN3, IN2, IN4 for a 28BYJ-48 on a ULN2003 board.

Stepper myStepper(200, 8, 9)

The two-pin form, for a motor behind a driver that takes two control lines.

myStepper.setSpeed(10)

Sets the speed in rpm. The library turns it into the gap between steps; it changes nothing until the next step().

myStepper.step(2048)

Makes that many steps, negative for the other direction, and returns only when it has finished. Nothing else in loop() runs meanwhile.

myStepper.step(2048);   // one turn clockwise
delay(500);
myStepper.step(-2048);  // and back

myStepper.version()

Returns the library version number, handy only for checking which Stepper a sketch was built against.

Example: ULN2003 board stepping its LEDs

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino 路 Arduino Uno R3
// A 28BYJ-48 stepper on its ULN2003 board: one turn forward, one back.
//
//   ULN2003 IN1 -> pin 8    IN2 -> pin 9    IN3 -> pin 10    IN4 -> pin 11
//   ULN2003 +   -> 5V (on the bench, the breadboard power module)
//   ULN2003 -   -> GND
//
// A stepper does not spin when you power it. It turns one small step each
// time the coils are switched in the right order, so the code decides exactly
// how far it goes. Through its gearbox the 28BYJ-48 takes 2048 steps for one
// turn of the output shaft.
//
// The Stepper library wants the pins as IN1, IN3, IN2, IN4: that is why the
// constructor says 8, 10, 9, 11. Given 8, 9, 10, 11 the motor hums and does
// not turn.

#include <Stepper.h>

const int STEPS_PER_TURN = 2048;
Stepper motor(STEPS_PER_TURN, 8, 10, 9, 11);

void release() {
  for (int pin = 8; pin <= 11; pin++) digitalWrite(pin, LOW);
}

void setup() {
  motor.setSpeed(15);  // revolutions per minute; this motor manages about 15
  Serial.begin(9600);
  Serial.println("Mokxi Uno: stepper on pins 8 to 11");
}

void loop() {
  Serial.println("one turn clockwise");
  motor.step(STEPS_PER_TURN);
  release();
  delay(500);
  Serial.println("one turn back");
  motor.step(-STEPS_PER_TURN);
  release();
  delay(500);
}

Open it in the editor, wired and ready to run 路 ULN2003 board stepping its LEDs: the project page

Common errors and how to fix them

The 28BYJ-48 hums or vibrates but does not turn

The pins are in the wrong order for the library鈥檚 coil pattern. Pass them as IN1, IN3, IN2, IN4 (for example 8, 10, 9, 11), and keep setSpeed() at 15 rpm or below for this motor.

The motor turns only half or a quarter of a revolution

The steps-per-revolution number does not match the motor. A 28BYJ-48 in full steps is 2048 for one output turn; a 1.8 degree NEMA 17 is 200. Use the right one in the constructor and in step().

Buttons and Serial stop responding while the motor moves

step() blocks until every step is made. Move in small chunks of a few steps per pass of loop(), or switch to AccelStepper, whose run() makes one step at a time and returns.

The motor and ULN2003 board get hot while standing still

The library leaves the last coils switched on so the shaft holds its position. If holding torque is not needed, write the four pins LOW after the move to let the motor go cold.

Try Stepper without installing anything

Open the example, change the sketch, and keep your version in a free account.