树莓派5硬件PWM实战：告别软件抖动，实现精准控制

threejs5artist

399人浏览 · 2026-03-11 02:23:13

threejs5artist · 2026-03-11 02:23:13 发布

1. 为什么你的树莓派PWM信号总在“跳舞”？软件PWM的致命软肋

如果你玩过树莓派控制舵机、调光LED或者驱动电机，大概率用过Python里的gpiozero或者RPi.GPIO库来生成PWM信号。上手确实快，几行代码就能让舵机动起来，LED呼吸起来。但不知道你有没有遇到过这样的糟心事儿：当你同时跑一个稍微复杂点的程序，比如用OpenCV处理摄像头画面，或者做点数据分析时，原本转得稳稳的舵机突然开始“抽风”，灯光呼吸的节奏也变得一卡一卡的。你检查了代码逻辑，似乎没问题，但问题就是真实存在。

这背后的“元凶”，就是软件PWM。让我用个生活化的比喻来解释：软件PWM就像一个需要你手动不停掐表、喊“开”和“关”的计时员。CPU就是那个计时员，它必须全神贯注，每隔一个极短的时间（微秒级）就去查看一下系统时钟，然后决定是否翻转GPIO引脚的电平。这个“查看-决定-翻转”的循环，完全依赖于CPU的实时调度。

那么问题来了，当你的树莓派开始运行一个计算密集型的任务时，CPU会变得非常繁忙。操作系统为了公平，会把CPU时间片分给各个进程。这时候，那个负责“掐表”的PWM线程就可能被暂时挂起，等它再次获得CPU时间时，可能已经错过了精确的翻转时间点。这就导致了PWM信号的周期和占空比产生抖动。对于LED调光，你可能只是觉得光线闪烁不均匀；但对于舵机控制，这种抖动会直接转化为舵臂的震颤和定位不准；在电机驱动中，则可能导致转速不稳，产生噪音甚至损坏。

我亲身经历过一个项目，用树莓派4控制一个机械臂，同时运行视觉识别算法。当算法开始工作时，机械臂的末端执行器就开始不受控制地高频微颤，精度完全丧失。排查了很久，最终才锁定就是软件PWM在CPU高负载下的不稳定造成的。所以，如果你正在构建一个对控制精度和稳定性有要求的系统，比如机器人、CNC雕刻机、高精度温控设备，那么告别软件PWM，拥抱硬件PWM，就是你必须走的一步。

2. 硬件PWM：树莓派5内置的“精准时钟发生器”

那硬件PWM又是什么神仙？你可以把它想象成树莓派芯片内部的一个独立、专精的时钟发生模块。这个模块自带高精度时钟源和计数器，一旦你设置好周期和占空比，它就会像石英钟一样，自顾自地、精准地输出方波信号，完全不需要CPU的持续干预。

CPU只需要在初始化时对它说一句：“嘿，哥们儿，在这个引脚上，帮我输出一个周期20毫秒、高电平占1.5毫秒的方波。” 之后，CPU就可以去忙别的重活了，比如疯狂处理图像数据，而硬件PWM模块会一丝不苟地执行命令，输出信号稳如磐石，不受系统负载的任何影响。这就是“硬件”二字的精髓：专用硬件处理，与软件解耦。

树莓派5（BCM2712芯片）的硬件PWM能力比前代更加强大和清晰。它主要通过RP1这颗独立的I/O芯片来管理GPIO和PWM等外设。树莓派5提供了多个硬件PWM通道，但我们需要通过配置，将特定的GPIO引脚映射到这些通道上。常用的引脚是GPIO12、13、18和19，它们可以被配置到PWM0控制器上。理解这一点很重要：不是所有GPIO都支持硬件PWM，我们需要通过一种叫“设备树覆盖”的机制，去告诉系统：“请把这几根引脚的功能，从普通的数字IO，切换成PWM输出模式。”

这就好比给你的树莓派安装一个“驱动程序”，只不过在Linux世界里，我们通过编辑和编译一个描述硬件连接关系的“设备树”文件来实现。下面，我们就来手把手完成这个配置。

3. 实战第一步：为树莓派5“安装”硬件PWM驱动

原始文章给出了一个设备树覆盖文件（.dts）的内容，我们一步步拆解，并补充更多细节，让你不仅会做，还明白为什么这么做。

3.1 创建并理解设备树覆盖文件

首先，我们需要在树莓派上创建一个新文件。你可以用nano或vim编辑器，我习惯用nano，对新手更友好。

sudo nano /home/pi/pwm-pi5-overlay.dts

然后把下面的代码完整地粘贴进去。别怕，我逐段给你解释：

/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2712";

    fragment@0 {
        target = <&rp1_gpio>;
        __overlay__ {
            pwm_pins: pwm_pins {
                pins = "gpio12", "gpio13", "gpio18", "gpio19";
                function = "pwm0", "pwm0", "pwm0", "pwm0";
            };
        };
    };

    fragment@1 {
        target = <&rp1_pwm0>;
        frag1: __overlay__ {
            pinctrl-names = "default";
            pinctrl-0 = <&pwm_pins>;
            status = "okay";
        };
    };
};

compatible = "brcm,bcm2712";：这行告诉系统，这个覆盖文件是给树莓派5（BCM2712芯片）用的，确保兼容性。
fragment@0：第一个片段，目标是rp1_gpio（RP1芯片的GPIO控制器）。我们在它上面创建一个“覆盖层”，定义了一组名为pwm_pins的引脚配置。这里明确指出，GPIO 12, 13, 18, 19这四个引脚，它们的功能（function）要设置为pwm0。也就是说，把它们从普通GPIO模式切换到PWM0控制器模式。
fragment@1：第二个片段，目标是rp1_pwm0（RP1芯片上的PWM0控制器）。我们在这个控制器上启用覆盖，并将它的引脚控制（pinctrl-0）指向我们刚刚定义的pwm_pins组，最后将其状态设置为okay（启用）。

简单说，这个文件做了两件事：1. 把四个物理引脚的功能切换到PWM模式；2. 启用对应的PWM控制器。保存并退出编辑器（在nano中是按Ctrl+X，然后按Y确认，再按回车）。

3.2 编译并启用覆盖

创建好文本描述文件（.dts）后，需要把它编译成系统能直接加载的二进制格式（.dtbo）。这需要用到设备树编译器dtc。通常树莓派系统已经自带，如果没有，可以sudo apt install device-tree-compiler安装。

dtc -I dts -O dtb -o pwm-pi5.dtbo pwm-pi5-overlay.dts

这条命令的意思是：输入（-I）是dts格式，输出（-O）是dtb格式，输出文件名为pwm-pi5.dtbo，输入文件是pwm-pi5-overlay.dts。执行成功后，当前目录下会生成一个pwm-pi5.dtbo文件。

接下来，把这个编译好的驱动文件放到系统启动时自动加载的覆盖层目录：

sudo cp pwm-pi5.dtbo /boot/firmware/overlays/

关键一步：告诉系统在启动时加载这个覆盖。编辑启动配置文件：

sudo nano /boot/firmware/config.txt

滚动到文件末尾，另起一行添加：

dtoverlay=pwm-pi5

注意，这里写的是pwm-pi5，而不是带.dtbo后缀的全名。系统会自动在overlays目录下寻找同名文件。保存退出。

最后，重启你的树莓派5，让配置生效：

sudo reboot

重启后，硬件PWM的驱动就加载好了。你可以通过以下命令检查PWM设备是否出现：

ls -l /sys/class/pwm/

你应该能看到类似pwmchip0、pwmchip2这样的目录。对于树莓派5，我们配置的PWM0通常对应pwmchip2。这个路径会在我们接下来的脚本中使用。

4. 打造你的硬件PWM命令行控制神器

驱动装好了，怎么用呢？直接操作/sys/class/pwm/下的文件节点是标准方法，但命令比较繁琐。原始文章提供了一个非常棒的Bash脚本，我们把它拿来，并深入优化和讲解，让它成为你得心应手的工具。

4.1 脚本详解与增强

在你的家目录（/home/pi）下创建脚本文件：

nano pwm_control.sh

将以下脚本内容粘贴进去。这个版本我在原始基础上做了一些错误处理和提示优化：

#!/bin/bash

# 硬件PWM控制脚本 for 树莓派5
# 用法: ./pwm_control.sh <引脚号> <周期(纳秒)> <占空比(纳秒)>
# 示例: ./pwm_control.sh 12 20000000 1500000  # GPIO12, 20ms周期, 1.5ms高电平

NODE="/sys/class/pwm/pwmchip2"  # 树莓派5上PWM0通常对应的设备节点
PIN="$1"
PERIOD="$2"
DUTY_CYCLE="$3"

# 引脚到PWM通道和功能的映射
# 树莓派5上，PWM0控制器可以映射到多组引脚，功能标识不同
case $PIN in
    "12")
        CHANNEL="0"
        FUNC="a0"  # PWM0功能映射到引脚组0
        ;;
    "13")
        CHANNEL="1"
        FUNC="a0"
        ;;
    "18")
        CHANNEL="2"
        FUNC="a3"  # PWM0功能映射到引脚组3
        ;;
    "19")
        CHANNEL="3"
        FUNC="a3"
        ;;
    *)
        echo "错误：不支持的引脚 '$PIN'。"
        echo "请使用 12, 13, 18 或 19 号引脚。"
        exit 1
        ;;
esac

# 帮助信息函数
function show_usage {
    echo "硬件PWM控制脚本 (树莓派5)"
    echo "=========================="
    echo "用法: $0 <引脚> <周期> <占空比>"
    echo "  或: $0 <引脚> off        (关闭指定引脚的PWM输出)"
    echo ""
    echo "参数:"
    echo "  引脚        -  GPIO编号 (支持: 12, 13, 18, 19)"
    echo "  周期        -  PWM信号总周期，单位纳秒 (ns)。例如 20000000 表示20毫秒"
    echo "  占空比      -  高电平持续时间，单位纳秒 (ns)。必须小于周期。"
    echo ""
    echo "示例 (控制舵机到中立位):"
    echo "  $0 12 20000000 1500000   # 标准舵机50Hz，1.5ms脉宽"
    echo "  $0 18 off                 # 关闭GPIO18的PWM输出"
    exit 0
}

# 检查参数数量
if [ $# -lt 1 ]; then
    show_usage
fi

# 处理“关闭PWM”的请求
if [ "$PERIOD" == "off" ]; then
    echo "正在关闭 GPIO $PIN 上的PWM输出..."
    if [ -d "$NODE/pwm$CHANNEL" ]; then
        # 先禁用PWM输出
        echo 0 | sudo tee "$NODE/pwm$CHANNEL/enable" > /dev/null
        # 等待一小段时间确保禁用生效
        sleep 0.1
        # 取消导出通道，释放资源
        echo $CHANNEL | sudo tee "$NODE/unexport" > /dev/null
        # 将引脚功能设置回默认输入（可选，防止意外输出）
        sudo pinctrl set $PIN ip
        echo "GPIO $PIN 的PWM输出已关闭，引脚已设置为输入模式。"
    else
        echo "GPIO $PIN 上未发现活跃的PWM通道。"
    fi
    exit 0
fi

# 验证数字参数
if [[ ! $PERIOD =~ ^[0-9]+$ ]] || [[ ! $DUTY_CYCLE =~ ^[0-9]+$ ]]; then
    echo "错误：周期和占空比必须是正整数（纳秒）。"
    show_usage
fi

# 检查占空比是否小于周期
if [ $DUTY_CYCLE -ge $PERIOD ]; then
    echo "错误：占空比 ($DUTY_CYCLE ns) 必须小于周期 ($PERIOD ns)。"
    exit 1
fi

# 一个封装好的函数，用于向sysfs写入值，并处理可能的错误
function write_sysfs {
    local FILE="$1"
    local VALUE="$2"
    if ! echo "$VALUE" | sudo tee "$FILE" > /dev/null; then
        echo "警告：写入 $FILE 失败，请检查权限或路径。"
        return 1
    fi
    return 0
}

# 主配置流程
echo "正在配置 GPIO $PIN (PWM通道 $CHANNEL)..."

# 1. 导出PWM通道（如果尚未导出）
if [ ! -d "$NODE/pwm$CHANNEL" ]; then
    echo "导出 PWM通道 $CHANNEL ..."
    if ! write_sysfs "$NODE/export" "$CHANNEL"; then
        echo "错误：无法导出通道 $CHANNEL。可能已被占用或无权限。"
        exit 1
    fi
    # 给系统一点时间创建设备节点
    sleep 0.2
fi

# 2. 先禁用PWM，以便配置
write_sysfs "$NODE/pwm$CHANNEL/enable" "0"

# 3. 设置周期和占空比
# 注意：有些内核版本要求先设置占空比，再设置周期；脚本已做兼容处理
echo "设置周期为 $PERIOD ns..."
if ! write_sysfs "$NODE/pwm$CHANNEL/period" "$PERIOD"; then
    echo "尝试先设置占空比再设置周期..."
    write_sysfs "$NODE/pwm$CHANNEL/duty_cycle" "$DUTY_CYCLE"
    write_sysfs "$NODE/pwm$CHANNEL/period" "$PERIOD"
else
    write_sysfs "$NODE/pwm$CHANNEL/duty_cycle" "$DUTY_CYCLE"
fi

# 4. 重新启用PWM输出
write_sysfs "$NODE/pwm$CHANNEL/enable" "1"

# 5. 使用pinctrl工具将引脚功能切换到PWM模式
sudo pinctrl set $PIN $FUNC 2>/dev/null || echo "注意：pinctrl设置功能可能失败，但PWM输出应已生效。可尝试安装'pinctrl'工具：sudo apt install pinctrl"

echo "成功！GPIO $PIN 已输出PWM信号。"
echo "  周期: $PERIOD ns ($(echo "scale=3; $PERIOD/1000000" | bc) ms)"
echo "  占空比: $DUTY_CYCLE ns ($(echo "scale=3; $DUTY_CYCLE/1000000" | bc) ms)"
echo "  占空比百分比: $(echo "scale=1; 100*$DUTY_CYCLE/$PERIOD" | bc)%"

保存并退出。给脚本添加执行权限：

chmod +x pwm_control.sh

这个脚本的强大之处在于：

参数化：通过命令行参数动态控制任意已配置的引脚。
安全关闭：提供了off参数，可以安全地关闭PWM输出并将引脚恢复为安全状态。
错误检查：检查参数有效性、占空比是否小于周期。
友好提示：输出包含毫秒和百分比换算，更直观。
兼容性处理：处理了不同内核版本在设置周期/占空比顺序上的差异。

4.2 从理论到实践：控制舵机与调光LED

现在，让我们用这个脚本干点实事。最经典的两个例子就是舵机和LED。

案例一：控制标准舵机 标准舵机（如SG90）的控制信号是周期20毫秒（50Hz），脉宽在0.5ms到2.5ms之间对应0到180度。

让舵机转到中间位置（90度）：脉宽约1.5ms。
```
sudo ./pwm_control.sh 12 20000000 1500000
```
让舵机转到最左边（0度）：脉宽约0.5ms。
```
sudo ./pwm_control.sh 12 20000000 500000
```
关闭PWM输出：
```
sudo ./pwm_control.sh 12 off
```

关键提示：务必使用sudo，因为操作/sys/和pinctrl需要root权限。你可以把脚本放到/usr/local/bin/并设置sudo免密码，但那是后话了。

案例二：控制LED亮度（无闪烁调光） 假设我们想用GPIO18控制一个LED，实现呼吸灯效果。软件PWM做呼吸灯在低频率下可能看到闪烁，硬件PWM则可以做到极高频率下的平滑调光。人眼对超过100Hz的光变化就基本感觉不到闪烁了。

设置一个高频PWM，比如1kHz（周期1ms），50%亮度：
```
sudo ./pwm_control.sh 18 1000000 500000
```
这里周期是1,000,000纳秒（1ms），占空比500,000纳秒（0.5ms），正好50%。

实现一个简单的呼吸灯脚本：创建一个新文件breath.sh：

#!/bin/bash
PIN=18
PERIOD=1000000 # 1ms周期，1kHz频率
for i in {0..100..2}; do
    # 计算占空比：从0%到100%再到0%
    if [ $i -le 50 ]; then
        DUTY=$(($PERIOD * $i / 100))
    else
        DUTY=$(($PERIOD * (100 - $i) / 100))
    fi
    sudo ./pwm_control.sh $PIN $PERIOD $DUTY
    sleep 0.05 # 每50毫秒改变一次亮度
done
sudo ./pwm_control.sh $PIN off

运行这个脚本，你会看到LED平滑地由暗变亮再变暗，完全没有软件PWM可能产生的抖动或闪烁。即使此时你用stress-ng命令让CPU满载，这个呼吸灯的动画依然会流畅如初，这就是硬件PWM的威力。

5. 深入排查：常见问题与高级技巧

走到这一步，大部分朋友应该都能成功驱动硬件PWM了。但总会遇到一些特殊情况，我这里分享几个踩过的坑和对应的解决办法。

问题一：运行脚本提示“找不到/sys/class/pwm/pwmchip2目录” 这通常意味着设备树覆盖没有成功加载。

检查：ls /boot/firmware/overlays/ 看看pwm-pi5.dtbo文件是否存在。
检查：cat /boot/firmware/config.txt | grep dtoverlay 确认配置行已添加。
检查内核日志：dmesg | grep pwm 查看启动时是否有PWM相关的加载信息或错误。
终极方案：手动加载测试。可以先不修改config.txt，重启后手动加载：sudo dtoverlay /boot/firmware/overlays/pwm-pi5.dtbo。如果加载成功，再回头检查config.txt的语法或位置。

问题二：提示“write error: Device or resource busy” 这说明你要操作的PWM通道已经被其他进程或内核模块占用了。树莓派上最常见的情况是风扇控制。树莓派5的官方主动散热风扇就是通过PWM控制的，它可能占用了某个通道。

检查占用者：cat /sys/class/pwm/pwmchip2/pwm0/device/consumer（将pwm0换成对应的通道号）。如果输出显示platform:cooling_fan之类的，那就是被风扇占用了。
解决方案：
1. 更换引脚：使用另一个未被占用的PWM引脚，比如如果GPIO18被风扇用了，就试试GPIO12或13。
2. 修改风扇配置：如果你不需要官方风扇的PWM温控，可以在config.txt中禁用或修改它的控制引脚。但这需要谨慎操作，以免影响散热。

问题三：PWM输出频率或占空比不准 硬件PWM的精度理论上非常高，但如果你发现实测值与设定值有微小偏差，可能是以下原因：

时钟源：硬件PWM的时钟源有其固有频率，你设置的周期（纳秒）可能不能被时钟周期整除，系统会自动取最接近的整数值。你可以通过cat /sys/class/pwm/pwmchip2/pwm0/period查看实际设置值。
测量工具误差：用普通的逻辑分析仪或示波器测量时，注意采样率和精度。对于高频PWM（如>100kHz），需要更高带宽的测量设备。

高级技巧：在Python程序中直接控制硬件PWM 虽然Bash脚本很方便，但在复杂的Python项目中，你可能希望直接调用。你可以用Python的subprocess模块来调用我们写的shell脚本，但更“原生”的方法是直接读写/sys/class/pwm/下的文件。这里提供一个简单的Python类示例：

import time
import os

class HardwarePWM:
    def __init__(self, chip=2, channel=0):
        self.chip = chip
        self.channel = channel
        self.base_path = f"/sys/class/pwm/pwmchip{chip}/"
        self.export_path = self.base_path + "export"
        self.channel_path = self.base_path + f"pwm{channel}/"

        # 导出通道
        if not os.path.exists(self.channel_path):
            with open(self.export_path, 'w') as f:
                f.write(str(channel))
            time.sleep(0.1) # 等待节点创建

    def set(self, period_ns, duty_cycle_ns):
        """设置周期和占空比（单位：纳秒）"""
        with open(self.channel_path + 'enable', 'w') as f:
            f.write('0') # 先禁用
        with open(self.channel_path + 'period', 'w') as f:
            f.write(str(period_ns))
        with open(self.channel_path + 'duty_cycle', 'w') as f:
            f.write(str(duty_cycle_ns))
        with open(self.channel_path + 'enable', 'w') as f:
            f.write('1') # 重新启用

    def disable(self):
        """禁用PWM输出"""
        with open(self.channel_path + 'enable', 'w') as f:
            f.write('0')

    def unexport(self):
        """取消导出通道（清理）"""
        self.disable()
        time.sleep(0.05)
        with open(self.base_path + 'unexport', 'w') as f:
            f.write(str(self.channel))

# 使用示例：控制GPIO12（对应pwmchip2, channel 0）
if __name__ == "__main__":
    # 注意：需要以sudo权限运行此Python脚本
    pwm = HardwarePWM(chip=2, channel=0)
    try:
        # 设置50Hz，7.5%占空比（舵机中立位）
        pwm.set(period_ns=20000000, duty_cycle_ns=1500000)
        time.sleep(2)
        # 改变占空比，让舵机转动
        pwm.set(period_ns=20000000, duty_cycle_ns=1000000)
        time.sleep(2)
    finally:
        pwm.unexport() # 程序退出前清理

这个类封装了基本的操作，你可以把它集成到你的机器人或自动化控制项目中，享受硬件PWM带来的稳定和精准。记住，在需要高实时性、高稳定性的场合，把时间敏感的控制任务交给硬件，让CPU专心处理复杂的上层逻辑，这才是嵌入式系统设计的精髓。从被软件PWM的抖动问题折磨，到亲手配置好硬件PWM并看到稳定输出的信号，这个过程本身就是一个极好的学习体验。

乐奇 Rokid 开放社区

更多推荐