Introduction

CircuitPython-compatible PWMOut for Raspberry Pi, intended for use with Adafruit Blinka and CircuitPython libraries. It uses configured BCM/RP1 hardware PWM where available and native software PWM on other GPIOs. No PIO is used.

This package is under development. Installing it does not automatically replace Blinka’s PWM backend or configure hardware PWM.

Dependencies

• Python 3.9 or later on Raspberry Pi Linux with GPIO character-device v2 support.

• The official gpiod Python bindings for software PWM: PyPI 2.2.2 or later within major version 2, or maintained Debian/Raspberry Pi OS system bindings with the upstream 2.2.1 fixes.

• Permission to access GPIO devices and, for hardware PWM, its sysfs controls.

• A C compiler and matching Python development headers for source installation.

Examples using board also need Adafruit-Blinka; the servo example additionally needs adafruit-circuitpython-motor.

Installation

In an activated virtual environment, install the published package:

python -m pip install Adafruit-Blinka-Raspberry-Pi-PWM

For a source checkout instead:

git clone https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi_PWM.git
cd Adafruit_Blinka_Raspberry_Pi_PWM
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .

Debian/Raspberry Pi OS may report Python gpiod version 2.2.0 while shipping fixed bindings from upstream libgpiod 2.2.1 or later. Software PWM accepts these dpkg-owned system bindings when their source package and loaded native API are both at least 2.2.1 within major version 2. This trusts the OS package manager; it is not a file-integrity monitor. Later distro package revisions and normal import order are supported, including importing board or gpiod before software PWM. Package facts are cached within a process; restart Python after installing or upgrading bindings.

To use system bindings, have your system administrator install python3-libgpiod and create the virtual environment with python3 -m venv --system-site-packages .venv. The broader resolver bound preserves these bindings without replacing them automatically. Arbitrary PyPI gpiod==2.2.0 is not supported: it has a native line-request lifetime bug that a function-presence check cannot detect. Ordinary installations still select current major-version-2 PyPI bindings; see the usage guide for details.

Only software PWM validates or imports gpiod. Configured hardware PWM does not need those bindings at runtime. See the system setup guide for supported installation and recovery commands. Installation does not run pip at runtime or bypass the OS externally-managed-environment policy.

Usage

Connect an LED with a suitable series resistor to GPIO18 and ground:

import time
import board
from adafruit_blinka_raspberry_pi_pwm import PWMOut

with PWMOut(board.D18, frequency=500, duty_cycle=32768) as pwm:
    time.sleep(5)

BCM GPIO numbers, such as PWMOut(18), can be used without importing Blinka. Duty cycle ranges from 0 to 65535. To change frequency after construction, pass variable_frequency=True. See examples for LED, servo, and loopback programs.

Hardware PWM and timing

Hardware selection requires a configured kernel PWM driver and a verified single-pin route. The package does not load overlays or change pinmux. Occupied channels and hardware errors are reported rather than silently switching to software. Unconfigured GPIOs use software PWM.

Hardware frequency limits depend on the controller and driver. Software accepts 1–10000 Hz, but Linux scheduling affects timing and jitter. Duty resolution is controller-dependent, and updates are not guaranteed glitch-free. Hardware cleanup releases the channel but leaves its pinmux configured; a forced process termination can leave PWM active.

Read the usage guide for setup, channel mapping, ownership, and safety details. Check the waveform before connecting motors or servos.

Documentation

The documentation sources contain the usage guide, API reference, and examples. Build them locally with:

python -m pip install '.[docs]'
python -m sphinx -W -b html docs docs/_build/html

Development and contributing

See CONTRIBUTING.md for development setup and checks. Participation follows the Code of Conduct. Automated tests do not drive GPIOs; hardware examples require deliberate wiring.

AI-assisted development

OpenAI Codex has assisted with implementation, tests, documentation, and hardware-test tooling and analysis. AI-generated work does not replace human review or physical validation, or establish correctness, timing, safety, or compatibility on its own.

License

This project uses the MIT license; see LICENSE.