RPi Motor Library
Python 3 library to connect various motors & servos to the Pi.
RpiMotorLib
Table of contents
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:
- RPI 3 model B. Raspbian 12 Bookworm, 64 bit. Python 3.11.2.
- RPI 5 model B. Raspbian 12 Bookworm, 64 bit. Python 3.11.2.
Installation
Latest version 4.0.0
Raspberry Pi compatibility:
Prior to v4.0.0, RpiMotorLib used RPi.GPIO as its GPIO dependency. RPi.GPIO does not support Raspberry Pi 5 and is no longer actively maintained. From v4.0.0 onwards, rpi-lgpio is the recommended GPIO library — it is a drop-in replacement for RPi.GPIO that works on all Pi models including Pi 5. Backward compatibility with RPi.GPIO is maintained via an internal GPIO abstraction layer.
| 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. pipx README . 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
rpilgpioandlegacyextras together — both provide theRPi.GPIOnamespace 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 |
Depending on Environment and location installed, you may also need to install swig which is dependency of lgpio or install lgpio globally, lgpio homepage
sudo apt install swig
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 |
Motor stop push button
All example scripts include support for a motor movement stop push button.
Software
- 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.
- Hardware example scripts are in the
examples/folder of the repository. - 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/ | Markdown library documentation files |
| 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:
RPIMOTORLIB_GPIO_BACKENDenvironment variable (if set)~/.config/rpiMotorLib/config.ini(created automatically on first run)- Auto-detect: tries rpi-lgpio/RPi.GPIO first, then lgpio
Valid backend values in config: null (auto-detect), rpigpio, lgpio.
Notes and issues
Servo trace back issue
rpi-lgpio 0.6 may produce a harmless TypeError traceback
after GPIO.cleanup() when PWM has been used. This is a known upstream
bug in rpi-lgpio (see PR #23)
and does not affect motor or servo operation. A fix exists in the PR but
has not yet been merged by the upstream maintainer.
Two Motors simultaneously
Running two stepper 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/:
- For Unipolar 28BYJ-48:
MultiMotorThreading_BYJ.py - For Bipolar DRV8825 Stepper:
MultiMotorThreading_DRV8825.py
RPi.GPIO cleanup method
RPi.GPIO legacy issue:
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.
RPi.GPIO edge detection
RPi.GPIO legacy issue:
RPi.GPIO add_event_detect raises RuntimeError: Failed to add edge detection
on Raspberry Pi due to removal of the sysfs GPIO interface
in recent kernels(~6.6.y). This affects EmergencyStop when using the legacy extra.
Switch to 'rpilgpio'.
References:
See Also
- Partial port to Raspberry Pi PICO SDK C++ at link.