How to Set Up PWM Pin on lgpio for Raspberry Pi Motor Control

Pulse Width Modulation (PWM) via the lgpio library is a method of rapidly toggling a Raspberry Pi GPIO pin between 3.3V HIGH and 0V LOW states at a specific frequency to simulate a variable analog voltage. In a real circuit, this changes a simple binary on/off digital output into a precisely metered average voltage, allowing you to dim LEDs, control servo angles, or dictate DC motor speed without wasting power as heat through resistors. If you are migrating from the deprecated RPi.GPIO library, mastering lgpio.tx_pwm() is your first step toward modern, character-device-based GPIO control on Pi OS Bookworm and later.

The Core Mechanics of lgpio PWM

Unlike older libraries that relied on user-space memory mapping, lgpio interfaces directly with the Linux kernel's character device (/dev/gpiochip0). When you call the PWM function, the library configures high-resolution kernel timers to flip the pin state.

Where You Meet This in Practice

You will configure PWM parameters differently depending on the physical load you are driving. The two variables—frequency (Hz) and duty cycle (%)—must be matched to the component's physics.

• Standard RC Servos (e.g., SG90, MG996R): Require exactly 50 Hz. The duty cycle translates to pulse width (1ms to 2ms) to set the physical angle from 0° to 180°.
• LED Dimming: Requires 1 kHz to 5 kHz. Anything below 100 Hz causes visible flicker on camera; anything above 10 kHz can cause electromagnetic interference (EMI) with nearby AM radios or audio equipment.
• DC Motors and Fans: Require 20 kHz to 25 kHz. This pushes the switching frequency above the human hearing range, eliminating the high-pitched squeal that occurs at 1 kHz.
• Proportional Valves / Heaters: Can often run at 10 Hz to 100 Hz, as the thermal mass or fluid inertia naturally filters the pulses.

Software vs. Hardware PWM: The Decision Path

A frequent point of failure on the workbench is using the wrong PWM type for a jitter-sensitive application. The Raspberry Pi has dedicated hardware PWM silicon, but lgpio.tx_pwm() generates software PWM via kernel timers. Use this decision tree to pick your approach.

Step-by-Step: Configuring lgpio.tx_pwm() in Python

Before running this code, ensure the lgpio Python module is installed (pip install lgpio). You must also wire your Pi's GPIO 18 to the gate of a logic-level MOSFET (like the IRLB8721), with a 10kΩ pull-down resistor between the gate and ground to prevent the motor from spinning during Pi boot-up.

Safety Warning: Always include a flyback diode (e.g., 1N4007) wired in reverse-parallel across your DC motor or fan terminals. Inductive kickback will instantly destroy your MOSFET and can feed lethal voltage spikes back into your Pi's 3.3V rail.

import lgpio
import time

# --- Configuration ---
GPIO_CHIP = 0       # /dev/gpiochip0 on standard Pi OS
GPIO_PIN = 18       # Physical pin 12, BCM 18
PWM_FREQ = 25000    # 25 kHz (inaudible for fans/motors)
DUTY_CYCLE = 60.0   # 60% speed

def run_motor_pwm():
    # Open the GPIO chip character device
    h = lgpio.gpiochip_open(GPIO_CHIP)
    
    # Claim the pin as an output
    lgpio.gpio_claim_output(h, GPIO_PIN)
    
    try:
        print(f"Starting PWM at {PWM_FREQ}Hz, {DUTY_CYCLE}% duty cycle.")
        # lgpio.tx_pwm(handle, gpio, frequency, duty_cycle)
        lgpio.tx_pwm(h, GPIO_PIN, PWM_FREQ, DUTY_CYCLE)
        
        # Run for 5 seconds
        time.sleep(5)
        
    except KeyboardInterrupt:
        print("Interrupted by user.")
    finally:
        # CRITICAL: Stop PWM and release pin to prevent runaway motors
        print("Stopping PWM and cleaning up.")
        lgpio.tx_pwm(h, GPIO_PIN, 0, 0) # Set duty cycle to 0 to halt
        lgpio.gpio_free(h, GPIO_PIN)
        lgpio.gpiochip_close(h)

if __name__ == "__main__":
    run_motor_pwm()

According to the official lgpio Python documentation, passing a duty cycle of 0 effectively halts the waveform and leaves the pin in a predictable state, which is why we use it in the finally block rather than just closing the chip.

Common Confusions and Pitfalls

When debugging a circuit that isn't responding correctly to lgpio PWM, builders usually fall into one of three traps:

1. Confusing Duty Cycle with Pulse Width: In lgpio.tx_pwm(), the fourth argument is duty cycle (a percentage from 0.0 to 100.0). Builders coming from older libraries or C-level hardware registers often pass microsecond values (like 1500 for a servo), which the library interprets as 100% (capped) or throws an error. For a 50Hz servo needing a 1.5ms pulse, you must calculate the percentage: 1.5ms / 20ms = 7.5%.
2. Using Standard MOSFETs instead of Logic-Level: A standard IRF520 MOSFET requires 10V on its gate to fully open. The Pi only outputs 3.3V. The MOSFET will operate in its linear (resistive) region, overheat, and fail to pass full current to your load. Always buy Logic-Level MOSFETs (prefix IRL, e.g., IRLZ44N or IRLB8721) which are fully saturated at 3.3V.
3. Ignoring the Pull-Down Resistor: During the 10-15 seconds a Raspberry Pi takes to boot, GPIO pins float. A floating gate on a MOSFET will pick up ambient EMI and partially turn on, causing your motor to stutter or your MOSFET to overheat before your Python script even starts. A 10kΩ resistor from Gate to Ground holds it firmly at 0V until lgpio claims the pin.