RpiMotorLib

Table of contents

• Table of contents
• Overview
• Installation
  • From PyPi with pip or pipx
  • From Github
• Hardware
  • Stepper motors
  • DC motors
  • Servos
  • Motor stop push button
• Software
  • File System
  • Dependencies
• Notes and issues
  • Servo trace back issue
  • Two Motors simultaneously
  • RPi.GPIO cleanup method
  • RPi.GPIO edge detection
• 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:

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

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.

Emergency Stop README

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/ | 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:

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

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 n