rpimotorlib 4.0.0

A Python 3 library to control various motor types on Raspberry Pi (Pi 1–5)

RpiMotorLib

Table of contents

• Table of contents
• Overview
• Installation
  • From PyPi with pip or pipx
  • From Github
• Hardware
  • Stepper motors
  • DC motors
  • Servos
• Software
  • File System
  • Dependencies
• Notes and issues
  • Two Motors simultaneously
  • GPIO cleanup method
  • Emergency Stop
  • pipx
• See Also

Overview

• Name: RpiMotorLib
• Version: 4.0.0
• Title: Raspberry Pi motor library.
• Description:

A Python 3 library to drive motor controllers and servos with a Raspberry Pi.

These components supported are some of the most widely used by the maker community. There are three categories in the library: Stepper motors, DC Motors and Servos. The end user can import this library into their projects and then control the components with short snippets of code. The library is modular so the user can just import/use the section they need.

• Project URL: URL LINK

• Tested on Toolchains:

  1. RPI 3 model B. Raspbian 12 Bookworm, 64 bit. Python 3.11.2.
  2. RPI 5 model B. Raspbian 12 Bookworm, 64 bit. Python 3.11.2.

Installation

Latest version 4.0.0

Raspberry Pi compatibility:

Raspberry Pi	Supported	Recommended GPIO library
Pi 1 / 2 / 3 / 4	✅	rpi-lgpio (recommended) or RPi.GPIO (legacy)
Pi 5	✅	rpi-lgpio required — RPi.GPIO does not support Pi 5

rpi-lgpio is a drop-in replacement for RPi.GPIO that works on all Raspberry Pi models including Pi 5. It is the recommended GPIO library for all new installations regardless of Pi model.

From PyPi with pip or pipx

The Python Package Index (PyPI) is a repository of software for the Python programming language. Install using pip or pipx to the location or environment of your choice. Recommend set up a virtual environment or use pipx Package name = rpimotorlib Link.

Recommended install (all Pi models including Pi 5):

pip install rpimotorlib[rpilgpio]

Legacy install (Pi 1-4 with existing RPi.GPIO):

pip install rpimotorlib[legacy]

Warning: Do not install rpilgpio and legacy extras together — both provide the RPi.GPIO namespace and will conflict.

Optional extras:

Extra	Description
rpilgpio	Installs rpi-lgpio — recommended for all Pi models including Pi 5
legacy	Installs RPi.GPIO — Pi 1-4 only, not supported on Pi 5
pigpio	Installs pigpio — optional hardware PWM servo, Pi 1-4 only
dev	Installs pytest, pytest-cov, pylint — for development

NB see notes section for more on pipx.

From Github

Clone and install via pip:

git clone https://github.com/gavinlyonsrepo/RpiMotorLib.git
cd RpiMotorLib
pip install .[rpilgpio]

Hardware

Supported Components:

Stepper motors

Motor tested	Motor controller	Help File URL link
Unipolar 28BYJ-48	ULN2003 driver module	URL
Bipolar Nema	TB6612FNG Dual Driver Carrier	URL
Bipolar Nema	L298N H-Bridge controller module	URL
Bipolar Nema	A4988 Stepper Driver Carrier	URL
Bipolar Nema	DRV8825 Stepper Driver Carrier	URL
Bipolar Nema	A3967 Stepper Driver aka "easy driver v4.4"	URL
Bipolar (untested on hw)	LV8729 Stepper Driver Carrier	URL
Bipolar (untested)	DRV8833 Motor controller module	TODO
Bipolar (untested)	L9110S Motor controller module	TODO
Bipolar Nema	MX1508 Motor controller module	URL

DC motors

Motor	Motor controller	Help File URL link
DC Brushed Motor	L298N Motor controller module.	URL
DC Brushed Motor	L9110S Motor controller module.	URL
DC Brushed Motor	DRV8833 Motor controller module.	URL
DC Brushed Motor	TB6612FNG Dual motor driver carrier	URL
DC Brushed Motor	MX1508 Motor controller module	URL
DC Brushed Motor	Transistor control	URL

Servos

There are two different options for controlling the servo. When using the rpi-lgpio/RPi.GPIO option you may notice twitching at certain delays and step sizes. This is the result of software PWM timing. If the application requires precise control the user can pick the pigpio library which uses hardware based timing. The disadvantage is they must install a dependency (pigpio) and start its daemon. Note: pigpio does not support Raspberry Pi 5.

Servo	Pi 5	Link
Servo software timing	✅	rpi-lgpio / RPi.GPIO PWM
Servo hardware timing	❌	pigpio library PWM

Software

1. Separate help files are in the documentation folder to learn how to use the library. Click on the relevant URL link in the tables in the hardware section.
2. Hardware example scripts are in the examples/ folder of the repository.
3. There is a "Software matrix" showing which classes are used to drive which components. This is in the Software_Matrix.md file in extra/Documentation folder.

File System

RpiMotorLib files are listed below:

File Path	Description
RpiMotorLib/RpiMotorLib.py	Stepper motor library file
RpiMotorLib/rpiservolib.py	Servo library — software PWM via rpi-lgpio/RPi.GPIO
RpiMotorLib/rpi_pservo_lib.py	Servo library — hardware PWM via pigpio (Pi 1-4 only)
RpiMotorLib/rpi_dc_lib.py	DC motor library file
RpiMotorLib/gpio_adapter.py	GPIO abstraction layer — supports rpi-lgpio, RPi.GPIO, lgpio
RpiMotorLib/settings.py	Settings manager — reads ~/.config/rpiMotorLib/config.ini
RpiMotorLib/rpi_emergency_stop.py	Emergency stop push button class
RpiMotorLib/RpiMotorScriptLib.py	Script to display version and help information
extra/Documentation/*.md	Markdown library documentation files
extra/Documentation/estop/estopreadme.md	Emergency stop documentation
extra/Documentation/pipx/pipxreadme.md	pipx installation documentation
examples/	Hardware example scripts organised by motor type
tests/	Pytest unit tests with mocked GPIO — run on any machine

A small script is installed to display version and help information. Run the information script by typing:

rpimotorscript -[options]

Option	Description
-h	Print help information and exit
-v	Print version information and exit

Dependencies

Dependency	Required	Pi 5	Notes
rpi-lgpio >= 0.4	Recommended	✅	Drop-in RPi.GPIO replacement, works on all Pi models
RPi.GPIO	Legacy alternative	❌	Pre-installed on most Pi 1-4 systems
pigpio >= 1.78	Optional	❌	Hardware PWM servo only, Pi 1-4 only

The GPIO backend is selected automatically at runtime in the following priority order:

1. RPIMOTORLIB_GPIO_BACKEND environment variable (if set)
2. ~/.config/rpiMotorLib/config.ini (created automatically on first run)
3. Auto-detect: tries rpi-lgpio/RPi.GPIO first, then lgpio

Valid backend values in config: null (auto-detect), rpigpio, lgpio.

Notes and issues

Two Motors simultaneously

Running two motors simultaneously — see github issue #11.

If you want to control two or more steppers simultaneously, there are two example scripts using threading in examples/Multi_Threading_Example/:

1. For Unipolar 28BYJ-48: MultiMotorThreading_BYJ.py
2. For Bipolar DRV8825 Stepper: MultiMotorThreading_DRV8825.py

GPIO cleanup method

As of v4.0.0 the library manages GPIO cleanup internally via the GPIO abstraction layer. User scripts no longer need to call GPIO.cleanup() directly — the motor class cleanup() methods and estop.cleanup() handle this correctly for all backends.

For users on older versions experiencing GPIO cleanup issues see github issues #18 and #21.

Emergency Stop

All example scripts include support for an motor movement stop push button. See the dedicated documentation: Emergency Stop README

pipx

As of PEP 668, users on many systems will get an error if they try to install packages system-wide with pip. pipx installs packages into isolated virtual environments and is a clean solution. See the dedicated documentation: pipx README

See Also

1. Partial port to Raspberry Pi PICO SDK C++ at link.