Raspberry Pi 使用说明

树莓派4b/5使用说明

准备材料

RGB-Matrix-P4-64x64（本产品）
杜邦线 2 × 8PIN(本产品)
树莓派 4B 或树莓派 5 （须另购）
5V 独立电源（建议按屏幕数量预留足够电流,需另购）

硬件连接

树莓派最多支持3种共享连接LED点阵屏面板的方式。为便于工程接线，本文使用统一编号标记：

[1]：面板1接线组
[2]：面板2接线组
[3]：面板3接线组

说明：[1]、[2]、[3] 表示三套独立的面板接线组，并非三种完全不同的接口标准；其中部分控制引脚为公共信号。

安装并启用树莓派系统（Raspbian bullseye）
按上表完成 16PIN 连线后，再接入屏幕 5V 供电

注意：如果仅接入 1 块面板，只需连接标记为 [1] 和通用的引脚,下图为16pin排线连接示意图：

项目拉取/环境配置流程

步骤 1：进入工作目录

cd ~/Desktop

步骤 2：拉取仓库（稀疏克隆）

git clone --depth 1 --filter=blob:none --sparse https://github.com/waveshareteam/RGB-Matrix-Px-xx.git RGB-Matrix-Px-xx

// 如果github拉取不成功可以尝试从gitee拉取

git clone --depth 1 --filter=blob:none --sparse https://gitee.com/waveshare/RGB-Matrix-Px-xx.git RGB-Matrix-Px-xx

步骤 3：进入仓库目录

cd ~/Desktop/RGB-Matrix-Px-xx

步骤 4：仅拉取树莓派示例目录

git sparse-checkout set example/Rasberry-Pi

运行C++示例demo

编译 C++ 示例（examples-api-use）

cd ~/Desktop/RGB-Matrix-Px-xx/example/Rasberry-Pi/examples-api-use
make -j4

运行示例(Pi 4B)（建议把 --led-slowdown-gpio 设为 4 以上，太快容易花屏）

sudo ./demo -D0 --led-rows=64 --led-cols=64 --led-chain=1 --led-slowdown-gpio=4 --led-no-hardware-pulse

运行示例(Pi 5)

sudo ./demo -D0 --led-rows=64 --led-cols=64 --led-chain=1 --led-slowdown-gpio=2 --led-no-hardware-pulse

运行效果

运行Python示例

步骤 1：进入示例目录

cd ~/Desktop/RGB-Matrix-Px-xx/example/Rasberry-Pi

步骤 2：安装依赖

sudo apt update

sudo apt install -y git build-essential cmake \
  pkg-config \
  python3-full python3-dev python3-venv \
  python3-pip \
  cython3 libjpeg-dev zlib1g-dev

步骤 3：设置项目目录权限

sudo chown -R pi:pi ~/Desktop/RGB-Matrix-Px-xx

步骤 4：创建并激活虚拟环境

python3 -m venv ~/.venvs/rgbmatrix
source ~/.venvs/rgbmatrix/bin/activate
python -m pip install --upgrade pip setuptools wheel

步骤 5：安装 Python 依赖并安装当前项目

cd ~/Desktop/RGB-Matrix-Px-xx/example/Rasberry-Pi
python -m pip install numpy pillow scikit-build-core cython
python -m pip install -v .

步骤 6：进入示例目录

cd ~/Desktop/RGB-Matrix-Px-xx/example/Rasberry-Pi/bindings/python/samples

步骤 7：验证环境

python -c "import sys, rgbmatrix, numpy, PIL, Cython; from rgbmatrix import RGBMatrix, RGBMatrixOptions, graphics; print('ALL_OK', sys.version)"

输出示例（时间日期版本等消息不一定相同）：

ALL_OK 3.13.5 (main, Jun 25 2025, 18:55:22) [GCC 14.2.0]

参数说明/运行命令

参数速查（点击展开）

参数	作用	常用/建议
`--led-rows` / `--led-cols`	单块面板行/列	rows：16/32/64；cols：32/64
`--led-chain` / `--led-parallel`	横向串接数量 / 并行链路数	单屏常用：chain=1、parallel=1；两块横拼：cols=64 + chain=2
`--led-gpio-mapping`	GPIO 映射/帽子板定义	常用：regular / adafruit-hat / adafruit-hat-pwm；常规接法用 regular
`--led-rp1-rio`	RP1 后端选择	0=PIO；1=RIO
`--led-no-drop-privs`	初始化后不降权	需要持续高权限/访问设备时可开
`--led-slowdown-gpio`	放宽 GPIO 时序	常用：1/2/3；2 常见稳妥折中
`--led-show-refresh`	打印实际刷新率	调参建议打开
`--led-pwm-bits`	PWM 位深（灰阶）	11 负载高；动态常用 7；追刷新可试 6
`--led-pwm-lsb-nanoseconds`	LSB 点亮基准时间	50 偏快；80/100/130 更保守
`--led-pwm-dither-bits`	低位抖动改善观感	先试 1；若出现特殊闪烁再试 0
`-i`	输入图片或 GIF	still-viewer.py / image-scroller.py / gif-viewer.py
`-f` / `-t`	字体 / 文本	runtext.py
`--framerate-fraction`	播放节奏控制	值越大通常越慢更稳（可试 8/10/12）
`--led-row-addr-type` / `--led-multiplexing`	行寻址/特殊 multiplex	画面正常一般不动；有映射问题再试
`--led-rgb-sequence` / `--led-brightness`	颜色顺序 / 亮度	红蓝反了试 RBG/BRG/GRB；长测亮度先 30–60
`--led-limit-refresh` / `--led-no-hardware-pulse`	限制刷新上限 / 禁用硬件脉冲	一般后置排查项，遇到兼容性问题再考虑

运行示例（通用命令模板：Pi 5）

sudo /home/pi/.venvs/rgbmatrix/bin/python 脚本名.py \
  --led-rows=64 \
  --led-cols=64 \
  --led-chain=1 \
  --led-parallel=1 \
  --led-gpio-mapping=regular \
  --led-slowdown-gpio=2 \
  --led-rp1-rio=0 \
  --led-no-drop-privs

亮度测试（Pi 5）

sudo /home/pi/.venvs/rgbmatrix/bin/python pulsing-brightness.py \
  --led-rows=64 \
  --led-cols=64 \
  --led-chain=1 \
  --led-parallel=1 \
  --led-gpio-mapping=regular \
  --led-slowdown-gpio=2 \
  --led-rp1-rio=0 \
  --led-no-drop-privs

显示文字（Pi 5）

sudo /home/pi/.venvs/rgbmatrix/bin/python hello-layout.py \
  --led-rows=64 \
  --led-cols=64 \
  --led-chain=1 \
  --led-parallel=1 \
  --led-gpio-mapping=regular \
  --led-slowdown-gpio=2 \
  --led-rp1-rio=0 \
  --led-no-drop-privs \
  --led-show-refresh

运行示例（通用命令模板：Pi 4）

sudo /home/pi/.venvs/rgbmatrix/bin/python 脚本名.py \
  --led-rows=64 \
  --led-cols=64 \
  --led-chain=1 \
  --led-parallel=1 \
  --led-gpio-mapping=regular \
  --led-slowdown-gpio=4 \
  --led-no-drop-privs \
  --led-no-hardware-pulse=1

显示文字（Pi 4）

sudo /home/pi/.venvs/rgbmatrix/bin/python hello-layout.py \
  --led-rows=64 \
  --led-cols=64 \
  --led-chain=1 \
  --led-parallel=1 \
  --led-gpio-mapping=regular \
  --led-slowdown-gpio=4 \
  --led-no-drop-privs \
  --led-no-hardware-pulse=1 \
  --led-show-refresh

显示图片（Pi 4）

sudo /home/pi/.venvs/rgbmatrix/bin/python still-viewer.py \
  --led-rows=64 \
  --led-cols=64 \
  --led-chain=1 \
  --led-parallel=1 \
  --led-gpio-mapping=regular \
  --led-slowdown-gpio=4 \
  --led-no-drop-privs \
  --led-no-hardware-pulse=1 \
  -i ~/Desktop/test_image.png

运行效果

文档反馈

树莓派4b/5使用说明​

准备材料​

硬件连接​

项目拉取/环境配置流程​

运行C++示例demo​

运行效果​

运行Python示例​

参数说明/运行命令​

运行效果​

树莓派4b/5使用说明

准备材料

硬件连接

项目拉取/环境配置流程

运行C++示例demo

运行效果

运行Python示例

参数说明/运行命令

运行效果