使用 Raspberry Pi GPIO 控制最多三个由 64x64、32x32、16x32 或类似 RGB LED 显示器组成的链
使用 Raspberry Pi GPIO 控制最多三个由 64x64、32x32、16x32 或类似 RGB LED 显示器组成的链
A library to control commonly available 128x64, 64x64, 32x32 or 16x32 RGB LED panels with the Raspberry Pi. Can support PWM up to 11Bit per channel, providing true 24bpp color with CIE1931 profile.
Supports 3 chains with many panels each on a regular Pi. On a Raspberry Pi 2 or 3, you can easily chain 12 panels in that chain (so 36 panels total), but you can theoretically stretch that to up to 96-ish panels (32 chain length) and still reach around 100Hz refresh rate with full 24Bit color (theoretical - never tested this; there might likely be timing problems with the panels that will creep up then).
With fewer colors or so-called 'outdoor panels' you can control even more, faster.
The LED-matrix library is (c) Henner Zeller [email protected], licensed with GNU General Public License Version 2.0 (or any later version) (which means, if you use it in a product somewhere, you need to make the source and all your modifications available to the receiver of such product so that they have the freedom to adapt and improve). Yes, you are also allowed to use this code under the GNU General Public License Version 3.0 which allows linking with Apache 2.0 code and LGPL-3.0 code.
If you'd like help, please do not file a bug, use the discussion board instead: https://rpi-rgb-led-matrix.discourse.group/ (obviously please read this whole page first). If you file a bug asking for personal help instead of using the discourse group, please state in your bug that you have read this entire page and that you're indeed filing a bug or request for improvement. Otherwise, please use the discourse group.
The RGB LED matrix panels can be scored at [Sparkfun][sparkfun], [AdaFruit][ada] or eBay and Aliexpress. If you are in China, I'd try to get them directly from some manufacturer, Taobao or Alibaba.
The RGBMatrix class provided in include/led-matrix.h does what is needed
to control these. You can use this as a library in your own projects or just
use the demo binary provided here which provides some useful examples.
Check out utils/ directory for some ready-made tools to get started using the library, or the examples-api-use/ directory if you want to get started programming your own utils.
This library does not support PWM panels (which actually are better, but need
a completely different driver).
It should support most other panels with direct addressing (3 to 5 address lines,
ABC for 8x2=16 lines, ABCD for 16x2=32 lines, and ABCDE for 32x2=64 lines).
It also supports panels using shift registers for line addressing, also called ABC
panels up to 64 lines.
However some amount of panels have uncommon pixel layouts, especially the brighter
panels and may require special pixel mappers (some are called zigzag or zagzig, see
https://rpi-rgb-led-matrix.discourse.group/t/p10rgb-3535-4s-zaggiz-1-4scan-abc-p10-panels-and-https-github-com-2dom-pxmatrix/921 )
Until this wiki has its own confirmed list of working panels, you can refer to
this list: https://github.com/board707/DMD_STM32/wiki/Led_drivers and assume
that all supported panels there should work with this library, or could work
with minimal work to create a pixel mapper.
Please do refer to --led-multiplexing=<0..17> mentioned below and try all values.
2025/11 update: DMD_STM32 has started adding experimental support for some PWM panels.
These should be labelled as "special" in the table above. They are not supported by this
lib, as it only supports non PWM panels (until someone contributes PWM support).
Newer PWM panels are not currently supported by this lib, but support would really be appreciated.
Some experimentation and success has been made with the following fork. Some panel support with FM6373, FM6363, SM16380SH
This library supports the old Raspberry Pi's Version 1 with 26 pin header and also the B+ models, the Pi Zero, Raspberry Pi 2,3,4 and 5 with 40 pins, as well as the Compute Modules which have 44 GPIOs.
There are two modes to run this on the Pi 5
--led-rp1-pio=0 - Uses the Pi 5 RP1 RIO backend (default) - Higher CPU usage but much faster performance.
--led-rp1-pio=1 - Uses the Pi 5 RP1 PIO backend - Very minimal CPU usage. NOTE: --led-slowdown-gpio can have the opposite effect in RIO mode, so going from 2 to 3 may increase performance slightly with --led-rp1-pio=0.
Pi 5 Discussion - https://github.com/hzeller/rpi-rgb-led-matrix/issues/1603
Thanks to contributions from the following libraries to help implement this.
https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter
https://github.com/bitslip6/rpi-gpu-hub75-matrix
https://www.i-programmer.info/programming/148-hardware/16887-raspberry-pi-iot-in-c-pi-5-memory-mapped-gpio.html
The 26 pin models can drive one chain of RGB panels, the 40 pin models up to three chains in parallel (each chain 12 or more panels long). The Compute Module can drive up to 6 chains in parallel. The Raspberry Pi 2 and 3 are faster and generally preferred to the older models (and the Pi Zero). With the faster models, the panels sometimes can't keep up with the speed; check out this troubleshooting section what to do.
A lightweight, non-GUI, distribution such as [DietPi] is recommended. [Raspbian Lite][raspbian-lite] is a bit easier to get started with and is a good second choice.
There are various types of displays that come all with the same Hub75 connector. They vary in the way the multiplexing is happening so this library supports options to choose that. All these are configured by flags (or, programmatically, in an Options struct).
If you have a 64x32 display, you need to supply the flags
--led-cols=64 --led-rows=32 for instance.
Depending on the Matrix, there are various configuration options that
you might need to set for it to work. See further below in the README for the
detailed description of these.
While the --led-rows and --led-cols can be derived from simply looking
at the panels, the other options might require some experimenting to find the
right setting if there is no description provided by the manufacturer of
the panel. Going through these options for experiments would typically not do
harm, so you're free to experiment to find your setting.
| Flag | Description |
|---|---|
--led-cols |
Columns in the LED matrix, the 'width'. |
--led-rows |
Rows in the LED matrix, the 'height'. |
--led-multiplexing |
In particular bright outdoor panels with small multiplex ratios require this. Often an indicator: if there are fewer address lines than expected: ABC (instead of ABCD) for 32 high panels and ABCD (instead of ABCDE) for 64 high panels. |
--led-row-addr-type |
Addressing of rows; in particular panels with only AB address lines might indicate that this is needed. |
--led-panel-type |
Chipset of the panel. In particular if it doesn't light up at all, you might need to play with this option because it indicates that the panel requires a particular initialization sequence. |
Panels can be chained by connecting the output of one panel to the input of the next panel. You can chain quite a few together, but the refresh rate will reduce with longer chains.
The 64x64 matrixes typically come in two kinds: with 5 address
lines (A, B, C, D, E), or (A, B); the latter needs a --led-row-addr-type=1
parameter. So-called 'outdoor panels' are typically brighter and allow for
faster refresh-rate for the same size, but do some multiplexing internally
of which there are a few types out there; they can be chosen with
the --led-multiplexing parameter.
Many 128x64 panels now use ABC addressing using shift registers, instead of direct
ABCDE addressing. Look at using --led-row-addr-type=5 or --led-row-addr-type=3
with them (and you may need to use --led-slowdown-gpio of 2 or more. Please
see this bug for more details: https://github.com/hzeller/rpi-rgb-led-matrix/issues/1774
There are some panels that have a different chip-set than the default HUB75.
These require some initialization sequence. The current supported types are
--led-panel-type=FM6126A and --led-panel-type=FM6127.
Generally, the higher scan-rate (e.g. 1:8), a.k.a. outdoor panels generally allow faster refresh rate, but you might need to figure out the multiplexing mapping if one of the three provided does not work.
Some 32x16 outdoor matrixes with 1:4 scan (e.g. Qiangli Q10(1/4) or X10(1/4))
have 4 address line (A, B, C, D). For such matrices is necessary to
use --led-row-addr-type=2 parameter. Also the matrix Qiangli Q10(1/4)
have "Z"-stripe pixel mapping and in this case, you'd use two parameters
at the same time --led-row-addr-type=2 --led-multiplexing=4.
This documentation is split into parts that help you through the process
The python bindings have been overhauled as of February 2026 and are now built with scikit-build-core and cmake. While this update has been tested there are likely edge cases that have not been caught. Please subscribe to the master Python bug to assist or check for the latest updates. https://github.com/hzeller/rpi-rgb-led-matrix/issues/1749.
The entire repository itself is PIP-able and can be installed as a package directly. Python dev packages are required.
sudo apt-get install python-dev-is-python3 python3-pil cython3
pip install git+https://github.com/hzeller/rpi-rgb-led-matrix
While this code should still work on rPi1 or Rpi0, those are underpowered and not recommended. An ESP32 is cheaper and faster. Rpi2 is honestly old and slow too. Rpi3 / Rpi3a / Rpi0 2wl will work for most displays but will be slow if you are rotating a huge display in a mapper (Rpi0 2wl is a slightly faster version of Rpi3) Rpi4 is the fastest supported chip which will need a higher slowdown gpio value to avoid overwhelming panels (if they display garbage) Rpi5 is not officially supported as of 2025/11, but see https://github.com/hzeller/rpi-rgb-led-matrix/issues/1603
make -C examples-api-use
sudo examples-api-use/demo -D0
暂无开放 Issues，或尚未同步最近议题。