如何使用Java在树莓派上通过GPIO控制WS2811可寻址RGB LED灯带

核心原理说明 #

WS2811采用单总线通信协议，通过不同占空比的高低电平信号区分逻辑0、逻辑1和复位指令，单条总线即可串联控制任意数量的LED灯珠，每个灯珠对应24位GRB颜色数据（注意不是RGB顺序）。

硬件接线要求 #

• 供电：WS2811额定工作电压多为5V，灯带长度超过5颗灯珠建议单独供电，不要使用树莓派GPIO供电避免烧毁主板
• 共地：灯带电源GND必须和树莓派GND连接，是通信稳定的核心前提
• 信号：WS2811的DIN引脚建议通过3.3V转5V电平转换模块连接树莓派的PWM引脚（推荐GPIO18，对应PWM0通道），短灯带（≤10颗）也可以直接连接

软件实现步骤 #

1. 时序参数适配 #

WS2811标准时序要求：

• 单bit总时长固定为1.25μs
• 逻辑0：高电平0.4μs + 低电平0.85μs，对应PWM占空比≈32%
• 逻辑1：高电平0.8μs + 低电平0.45μs，对应PWM占空比≈64%
• 复位信号：持续≥50μs的低电平，用于通知灯带刷新显示

2. 核心代码示例 #

首先初始化Pi4j和PWM引脚：

import com.pi4j.io.gpio.*;
import com.pi4j.wiringpi.Gpio;

public class Ws2811Controller {
    // 选择PWM引脚 GPIO18（树莓派物理引脚12）
    private static final Pin PWM_PIN = RaspiPin.GPIO_01;
    private static GpioPinPwmOutput pwmOutput;
    
    public static void init() {
        GpioController gpio = GpioFactory.getInstance();
        pwmOutput = gpio.provisionPwmOutputPin(PWM_PIN);
        // 设置PWM模式为mark-space模式，保证占空比输出准确
        Gpio.pwmSetMode(Gpio.PWM_MODE_MS);
        // PWM时钟基准为19.2MHz，分频系数设为24，得到800kHz的PWM时钟，对应周期1.25μs
        Gpio.pwmSetClock(24);
        Gpio.pwmSetRange(100);
    }
}

实现单bit、单灯颜色发送和复位逻辑：

// 发送单个bit
private static void sendBit(boolean isOne) {
    pwmOutput.setPwm(isOne ? 64 : 32);
    // 等待1.25μs保证单bit传输完成
    Gpio.delayMicroseconds(1);
}

// 发送单个灯珠的24位GRB颜色数据
public static void sendColor(int red, int green, int blue) {
    // 先发8位绿色数据
    for (int i = 7; i >= 0; i--) {
        sendBit(((green >> i) & 1) == 1);
    }
    // 再发8位红色数据
    for (int i = 7; i >= 0; i--) {
        sendBit(((red >> i) & 1) == 1);
    }
    // 最后发8位蓝色数据
    for (int i = 7; i >= 0; i--) {
        sendBit(((blue >> i) & 1) == 1);
    }
}

// 发送复位信号刷新灯带
public static void refresh() {
    pwmOutput.setPwm(0);
    Gpio.delayMicroseconds(50);
}

使用示例：

public static void main(String[] args) {
    init();
    // 给第1个灯发红色
    sendColor(255, 0, 0);
    // 给第2个灯发绿色
    sendColor(0, 255, 0);
    // 给第3个灯发蓝色
    sendColor(0, 0, 255);
    // 刷新显示
    refresh();
}

常见问题排查 #

• 灯珠不亮/颜色错乱：优先检查是否共地，再微调占空比参数（不同批次WS2811时序允许±15%误差）
• 后面的灯珠不显示：检查灯带供电功率是否足够，信号是否有衰减

内容的提问来源于stack exchange，提问作者error13660