# RGB Matrix Panels With Raspberry Pi 5
## Overview
https://youtu.be/Qb7yY5xZX2E?si=EpIJJmE01L7VF_s_
Each new generation of the Raspberry Pi brings improvements over the last, and the Raspberry Pi 5 is no exception. However, along with the great new features and enhanced performance can also come some incompatibility with the way things were done on prior versions of the hardware. One such incompatibility with the Pi 5 was the ability to drive HUB75 compatible RGB Matrices like the older Pi's could.
The new [Adafruit Blinka Raspberry Pi5 PioMatter](https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter) library brings this capability to the Raspberry Pi 5 by way of the PIO peripherals.
Danger: This guide and library support the Raspberry Pi 5 only. They cannot be used with older Raspberry Pi devices.
## Hardware Requirements
You'll need a [Raspberry Pi 5](https://www.adafruit.com/product/5813), we recommend the [official Raspberry Pi 5V power supply](https://www.adafruit.com/product/5814) for it. There are a variety of matrix panels and power supplies to choose from depending on how big or small you're project will be.
Each panel requires up to 4A of power at max brightness with all pixels on. Keeping things a bit dimmer, or not using all the pixels at once will save power. I've had success running 2 panels off of one 4A power adapter, the matrices are still plenty bright for indoor projects.
If you're driving more than 2 panels, you'll need another 4A adapter. The female DC power adapter makes it easy to power additional matrices separate from the two that can be powered from the Bonnet's terminal blocks.
The library supports both the RGB Matrix Bonnet, and the RGB Matrix HAT. Only one is needed though, choice is up to you.
## Parts
### Adafruit RGB Matrix Bonnet for Raspberry Pi
[Adafruit RGB Matrix Bonnet for Raspberry Pi](https://www.adafruit.com/product/3211)
You can now create a dazzling display with your Raspberry Pi with the Adafruit RGB Matrix Bonnet. These boards plug into your Pi and make it super easy to control RGB matrices such as those we stock in the shop and create a colorful scrolling...
Out of Stock
[Buy Now](https://www.adafruit.com/product/3211)
[Related Guides to the Product](https://learn.adafruit.com/products/3211/guides)
### Adafruit RGB Matrix HAT + RTC for Raspberry Pi - Mini Kit
[Adafruit RGB Matrix HAT + RTC for Raspberry Pi - Mini Kit](https://www.adafruit.com/product/2345)
You can now create a dazzling display with your Raspberry Pi Model Zero/A+/B+/Pi 2/3/Pi 4 with the Adafruit RGB Matrix HAT. This HAT plugs into your Pi and makes it super easy to control RGB matrices such as those we stock in the shop and create a colorful scrolling display or mini LED...
Out of Stock
[Buy Now](https://www.adafruit.com/product/2345)
[Related Guides to the Product](https://learn.adafruit.com/products/2345/guides)
### 64x32 RGB LED Matrix - 3mm pitch
[64x32 RGB LED Matrix - 3mm pitch](https://www.adafruit.com/product/2279)
Bring a little bit of Times Square into your home with this sweet 64 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked...
In Stock
[Buy Now](https://www.adafruit.com/product/2279)
[Related Guides to the Product](https://learn.adafruit.com/products/2279/guides)
### 5V 4A (4000mA) switching power supply - UL Listed
[5V 4A (4000mA) switching power supply - UL Listed](https://www.adafruit.com/product/1466)
Need a lot of 5V power? This switching supply gives a clean regulated 5V output at up to **4 Amps** (4000mA). 110 or 240 input, so it works in any country. The plugs are "US 2-prong" style so you may need a plug adapter, but you can pick one up at any hardware store for $1 or so,...
Out of Stock
[Buy Now](https://www.adafruit.com/product/1466)
[Related Guides to the Product](https://learn.adafruit.com/products/1466/guides)
### 5V 10A switching power supply
[5V 10A switching power supply](https://www.adafruit.com/product/658)
This is a beefy switching supply, for when you need a lot of power! It can supply 5V DC up to 10 Amps, running from 110V or 220V power (the plug it comes with is for US/Canada/Japan but you can use any plug adapter for your country, or just replace the cable with a standard computer/appliance...
In Stock
[Buy Now](https://www.adafruit.com/product/658)
[Related Guides to the Product](https://learn.adafruit.com/products/658/guides)
### Female DC Power adapter - 2.1mm jack to screw terminal block
[Female DC Power adapter - 2.1mm jack to screw terminal block](https://www.adafruit.com/product/368)
If you need to connect a DC power wall wart to a board that doesn't have a DC jack - this adapter will come in very handy! There is a 2.1mm DC jack on one end, and a screw terminal block on the other. The terminals are labeled with positive/negative assuming a positive-tip configuration...
In Stock
[Buy Now](https://www.adafruit.com/product/368)
[Related Guides to the Product](https://learn.adafruit.com/products/368/guides)
### GPIO Ribbon Cable 2x8 IDC Cable - 16 pins 12" long
[GPIO Ribbon Cable 2x8 IDC Cable - 16 pins 12" long](https://www.adafruit.com/product/4170)
Connect this to that! If you want to bridge those contacts out onto another PCB, you'll want this **GPIO Ribbon Cable**! Comes in a classic Adafruit Black, has a nice soft flexible 16-line 0.05" ribbon cable and keyed IDC connectors on both ends.
In Stock
[Buy Now](https://www.adafruit.com/product/4170)
[Related Guides to the Product](https://learn.adafruit.com/products/4170/guides)
# RGB Matrix Panels With Raspberry Pi 5
## Raspberry Pi 5 Setup
We recommend you use the latest Raspberry Pi OS flashed onto one of the [official Raspberry Pi SDCards](https://www.adafruit.com/product/6010). The [Raspberry Pi Imager](https://www.raspberrypi.com/software/) app makes it easy to prepare your SD Card.
- Click **Choose Device** then select the **Raspberry Pi 5**.
- Click **Choose OS** then select **Raspberry Pi OS (64-bit)**.
- Click **Choose Storage** then select your SDCard adapter. The name will depend on your device and it may differ from the screenshot.
Once all 3 values are selected you should see them filled in to the appropriate areas of the main screen.
When everything has been set, click the **Next** button. You'll be asked if you'd like to apply OS customization settings. This step is optional, it allows you to put in username, WiFi credentials, and SSH public key which will get baked in to the image that is flashed to the SD Card.
Enter your details and click **Yes** if you'd like to do it, otherwise click **No**. Next you'll be warned that the storage device you've select is going to be erased. Make certain it's the drive you're intending to flash and then click **Yes** to start the writing process.
A pop-up will be shown once the writing has completed successfully.
## Boot & Update
If you did enter your network credentials and SSH key to the OS customization step, and you can use nmap or some other tool to locate the Pi 5 on the network and then you can do this step entirely "headless". If not you can temporarily plug in an HDMI display and USB keyboard to do it.
Plug in the Pi 5, let it boot up, then update the software on it using the following commands.
`sudo rpi-update` is needed especially for older Pi 5 boards.
```auto
sudo rpi-update
sudo apt update
sudo apt upgrade
sudo apt-get install python3-pip
sudo reboot
```
## Create a Virtual Environment
The best practice for installing Python libraries is to use virtual environments to keep things isolated and minimize conflicts between different versions of libraries that might be required for different projects or purposes. You can name your virtual environment anything, but it's best to use something you'll remember and associate with the project your working on. I use the name `blinka_venv` for the environment containing Adafruit Blinka and all associated libraries on my Pi's.
It's easy to create one with the following command.
```auto
python -m venv ~/venvs/blinka_venv
```
For more info about virtual environments see [this guide.](https://learn.adafruit.com/python-virtual-environment-usage-on-raspberry-pi/overview)
## Install Requirements
Next you need to activate the new virtual environment and then install the required libraries within it.
```auto
source ~/venvs/blinka_venv/bin/activate
pip install adafruit-blinka
pip install pillow
pip install numpy
pip install click
pip install Adafruit-Blinka-Raspberry-Pi5-Piomatter
```
## Add PIO Subsystem Rule Configuration
By default one requires root privilege to access the PIO hardware peripherals. We'll setup a rule that makes it so that the standard user can do it. We need to edit the file `/etc/udev/rules.d/99-com.rules`.
```auto
sudo nano /etc/udev/rules.d/99-com.rules
```
Add a new empty line or two at the top of the file by pressing enter. Then add this to one of the empty lines.
```auto
SUBSYSTEM=="*-pio", GROUP="gpio", MODE="0660"
```
To save the file press **Ctrl-S** on the keyboard. Then press **Ctrl-X** to exit. After you've done this, reboot the Pi with `sudo reboot`
## Accessing Console
At present time, the python scripts that drive the matrices work best when run from the console context rather than the desktop UI context. There are a few ways you can achieve this, and depending on whether your Pi is dedicated to this usage or not you may want to set it up to boot directly to the console.
### Temporary
If you don't want to make any config changes then you can simply press **Ctrl-Alt-F1** on a keyboard connected to the Pi to change from the desktop context to the console. The HDMI screen will go from showing the desktop to just the basic terminal prompt. At this prompt you can activate your virtual environment as shown above, and then run Python scripts that draw to the matrix. To go back to the desktop context you can press **Ctrl-Alt-F7**.
### SSH
If you access the Pi over SSH then it already counts as the console so you can activate your virtual environment and run the matrix scripts with nothing further needed.
### Auto Boot to Console
If you intend to keep using the same Pi for RGB Matrix projects, and you typically use a keyboard and HDMI screen to interact with the Pi directly, rather than SSH, then it may be convenient to configure your Pi to automatically boot directly to the console rather than the desktop.
To enter the config utility run this command.
```auto
sudo raspi-config
```
- Ensure **System Options** is highlighted and press enter.
- Arrow down to highlight **Boot / Auto Login** and press enter.
- Highlight either **B1 Console** , or **B2 Console Autologin** and press enter.
- After the setting is applied you'll be taken back to the main raspi-config screen
- Arrow right until **Finish** is highlighted and press enter.
- When prompted to reboot now highlight **Yes** and press enter.
When the Pi boots up you'll be ready to activate your virtual environment and run the python scripts that interact with the RGB Matrix.
# RGB Matrix Panels With Raspberry Pi 5
## Wiring
The [RGB Matrix Bonnet](https://www.adafruit.com/product/3211) and [RGB Matrix HAT](https://www.adafruit.com/product/2345) make it easy to wire up the RGB Matrix and required power supply.
It is best to make all of these connections with the power unplugged, and then once everything is connected and you've double-checked that it's all correct, plug in the power to turn everything on. I've found that the Pi can complain about low power if its USB C power is not plugged in prior to the DC jack power on the Bonnet or Hat. So be sure to plug in the USB C power adapter first, then the adapters powering the Bonnet and any additional panels.
For more info see [this guide page.](https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/powering)
## Pi 5 & Bonnet Connections
Warning: A substantial USB-C power supply is required for the Pi. The 45W or 27W USB-C Official Raspberry Pi power supplies are recommended. If you see a "Failed to open PIO device" it is a power supply issue.
- Attach the Matrix Bonnet or Hat to the Raspberry Pi 5 GPIO pin rows.
- Connect the **USB C power cable** to the **USB C jack** to power the Pi.
- Connect the **barrel jack** of the DC 5V 4A power adapter into the **barrel jack connector** on the Matrix Bonnet or Hat.
- Connect the fork on the end of **GND (black wire)** lead on the matrix power cable to the **- terminal block** on the Matrix Bonnet or Hat.
- Connect the fork on the end of the **5V (red wire)** lead on the matrix power cable to the **+ terminal block** on the Matrix Bonnet or Hat.
- Connect one end of a **2x8 IDC ribbon cable** to the **2x8 pin connector** on the Matrix Bonnet or Hat.
## Matrix Panel Connections
- Connect one end of the **4 pin matrix power cable** connector to the **4 pin power input connector** on the back of the matrix panel.
- Connect the other end of the **2x8 IDC ribbon cable** to the input **2x8 pin connector** on the back of the matrix panel. The input connector is the one that the arrows in the long direction point away from.
# RGB Matrix Panels With Raspberry Pi 5
## Basic Test
Once you're [Pi 5 is all set up](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/raspberry-pi-5-setup) and you've got the [RGB Matrix panels all wired](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/wiring) you're ready to test it out!
As always, you need to activate the virtual environment before running the example. If you haven't already then activate it like this.
```auto
source ~/venvs/blinka_venv/bin/activate
```
Next you can run the **single\_panel\_simpletest.py** script.
```auto
python single_panel_simpletest.py
```
The code for this example is embedded below. You can download it, or copy/paste the text into a file.
https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter/blob/main/examples/single_panel_simpletest.py
## Code Explanation
After initializing the matrix, this example uses the Pillow library (PIL) to draw 3 basic shapes and colors. It can serve as a good test to ensure your wiring and software are all setup properly.
# RGB Matrix Panels With Raspberry Pi 5
## Initialization Config
Initializing matrix panels to display things onto requires 3 main steps:
- Create a Geometry object to define the size and shape of the panel(s)
- Create a framebuffer to hold display data
- Create the PioMatter instance.
## Geometry
The `Geometry` object defines the size and shape of the panel(s) that will serve as the display. There 6 arguments that can be passed to configure it.
- `width` - The total width of the panel(s) in pixels.
- `height` - The total height of the panel(s) in pixels.
- `n_addr_lines` - The number of connected address lines. The number of pixels in the shift register is automatically computed from these values. Many panels use `4` as a standard. The [64x64 panels](https://www.adafruit.com/product/5362) that we stock use `5` address lines. Set this value according to which panels you're using. Note that using 5 addr lines also requires soldering a jumper as described on [this guide page](https://learn.adafruit.com/adafruit-rgb-matrix-bonnet-for-raspberry-pi/driving-matrices#step-2982866).
- `serpentine` - Controls the arrangement of multiple panels when they are stacked in rows. If it is `True`, then each row goes in the opposite direction of the previous row. Default is `True`.
- `rotation` - controls the orientation of the panel(s). Must be one of the `Orientation` constants. Default is `Orientation.Normal`. Over valid values are `Orientation.R180`, `Orientation.CW`, and `Orientation.CCW`
- `n_planes` - Controls the color depth of the panel. This is separate from the framebuffer layout. Decreasing `n_planes` can increase FPS at the cost of reduced color fidelity. The default, `10`, is the maximum value.
- `n_temporal_planes` - Controls the temporal dithering. Valid values are `0`, `2`, and `4`. Cannot be higher than `n_planes`. The default is `0`. Using larger values can increase the framerate in some cases experiment with your panels and application.
- `map` - A pixel/lanes mapping list. For Active3 configurations use `simple_multilane_mapper(width, height, n_addr_lines, n_lanes)`. For single matrix bonnet/HAT this can be omitted.
## Framebuffer
Next you need a `framebuffer`, this is a numpy array that will contain pixel data in the appropriate colorspace. When refreshed the matrix will show the data that is in this framebuffer on the display. Depending on what you're displaying it can be created in a few different ways.
```auto
# For displaying an image from PIL, canvas is the PIL.Image instance
framebuffer = np.asarray(canvas) + 0
# For displaying arbitrary data, start with zeros
framebuffer = np.zeros(shape=(geometry.height, geometry.width, 3), dtype=np.uint8)
```
## PioMatter
Now the `PioMatter` instance can be initialized. Aside from the Geometry, and Framebuffer created above, it also accepts arguments for `colorspace` and `pinout`.
- `colorspace` - Controls the colorspace that will be used for data to be displayed.
It must be one of the `Colorspace` constants. Which to use depends on what data
your displaying and how it is processed before copying into the framebuffer. Many of the examples use `Colorspace.RGB888Packed`. Other valid values are `Colorspace.RGB565` and `Colorspace.RGB888`
- `pinout` - Defines which pins the panels are wired to. Different pinouts can support different hardware breakouts and panels with different color order. The value must be one of the `Pinout` constants `Pinout.AdafruitMatrixBonnet`, `Pinout.AdafruitMatrixBonnetBGR`, `Pinout.AdafruitMatrixHat`, or `Pinout.AdafruitMatrixHatBGR`. For the active3/Triple Matrix Bonnet use `Pinout.Active3` or `Pinout.Active3BGR`
- `framebuffer` - A `numpy.array` buffer as noted above.
- `geometry` - A `Geometry` instance as noted above.
## Example Initialization Code
Single matrix Bonnet/HAT:
```python
geometry = piomatter.Geometry(width=64, height=32, n_addr_lines=4, rotation=piomatter.Orientation.Normal)
matrix_framebuffer = np.zeros(shape=(geometry.height, geometry.width, 3), dtype=np.uint8)
matrix = piomatter.PioMatter(colorspace=piomatter.Colorspace.RGB888Packed, pinout=piomatter.Pinout.AdafruitMatrixBonnet, framebuffer=matrix_framebuffer, geometry=geometry)
```
Triple Matrix Bonnet:
```auto
pixelmap = simple_multilane_mapper(width, height, n_addr_lines, n_lanes)
geometry = piomatter.Geometry(width=width, height=height, n_addr_lines=n_addr_lines, n_planes=10, n_temporal_planes=4, map=pixelmap, n_lanes=n_lanes)
framebuffer = np.asarray(canvas) + 0 # Make a mutable copy
matrix = piomatter.PioMatter(colorspace=piomatter.Colorspace.RGB888Packed,
pinout=piomatter.Pinout.Active3,
framebuffer=framebuffer,
geometry=geometry)
```
# RGB Matrix Panels With Raspberry Pi 5
## Multiple Matrix Panels
Is one panel too small to contain your epic ideas? No problem, you can chain multiple panels together in a serpentine configuration to assemble a larger total display size. When wiring multiple panels, be sure to pay attention to the arrows on the silkscreen of the back of the matrix panels. The arrows in the long direction point away from the input 2x8 IDC connector and point towards the output 2x8 IDC connector.
Various possible configurations are illustrated below.
## Horizontal Layouts
2 x 1 panel layout with a total size of 128x32 pixels.
4 x 1 panel layout with a total size of 256x32 pixels.
2 x 2 panel layout with a total size of 128x64 pixels.
## Vertical Layouts
1 x 2 panel layout with a total size of 64x64 pixels.
1 x 4 panel layout with a total size of 64x128 pixels.
Once your panels are properly wired up be sure to update the `width` and `height` values used in the code when the matrices are initialized.
# RGB Matrix Panels With Raspberry Pi 5
## Animated GIF
As always, you need to activate the virtual environment before running the example. If you haven't already then activate it like this.
```auto
source ~/venvs/blinka_venv/bin/activate
```
Next you can run the **play\_gif.py** script.
```auto
python play_gif.py
```
The code for this example is embedded below. You can download it, or copy/paste the text into a file.
https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter/blob/main/examples/play_gif.py
## Code Explanation
After initializing the matrix panel, this example loads a GIF file using PIL. Within the main loop it iterates over the frames of the GIF, pasting each one into the `canvas` image. The `framebuffer` gets filled with data from the `canvas` image and then shown on the matrix panel.
# RGB Matrix Panels With Raspberry Pi 5
## Scrolling Text
As always, you need to activate the virtual environment before running the example. If you haven't already then activate it like this.
```auto
source ~/venvs/blinka_venv/bin/activate
```
Next you can run the **quote\_scroller.py** script.
```auto
python quote_scroller.py
```
The code for this example is embedded below. You can download it, or copy/paste the text into a file.
https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter/blob/main/examples/quote_scroller.py
## Code Explanation
This example fetches a quote from the Adafruit Quotes API using the `requests` library. Once fetched the quote is rendered in it's entirety in a single line into a very wide image `full_txt_img`. This image is too wide to display all at once on the matrix hence the need for scrolling.
The matrix gets initialized and then the code moves to the main loop. Once inside, an inner for loop iterates over horizontal pixel indexes. A matrix sized section of the `full_text_img` is copied out and pasted into `single_frame_img`. From there it's copied into the `framebuffer` and shown on the matrix.
# RGB Matrix Panels With Raspberry Pi 5
## Mirror Console
## Display Configuration
This example will mirror the console's framebuffer to the matrix panel. In order to make it fit better, and to ensure that the requisite `/dev/fb0` exists whether or not an HDMI display is plugged in, there will be a modification to the file `/boot/firmware/cmdline.txt` that adds a video configuration with the smallest allowed display size.
```auto
sudo nano /boot/firmware/cmdline.txt
```
Scroll to the end of the line by pressing end or holding right arrow for a while.
Press space bar to insert a space at the end of the existing line.
Add the following after the space at the end of the existing line.
```auto
video=HDMI-A-1:640x480M@60D
```
Press **Ctrl-S** to save the file.
Press **Ctrl-X** to exit.
Then reboot the Pi for it to take effect
```auto
sudo reboot
```
When the Pi boots back up, the file `/dev/fb0` should now exist even if you don't have an HDMI display plugged in. If you do have an HDMI display, you'll notice that the text on it is now scaled bigger since we've overridden the display size to be 640x480
## Run The Example
As always, you need to activate the virtual environment before running the example. If you haven't already, then activate it like this.
```auto
source ~/venvs/blinka_venv/bin/activate
```
Next you can run the **fbmirror\_scaled.py** script. The script accepts several arguments to configure the panels. The first 3 are specific to the fbmirror examples.
- `--scale` - a number to scale the full display down by. What is best depends on what you're showing. `2` or `4` are good places to start and then tune it to your content and desired look.
- `--x-offset` - the number of pixels in the x axis to skip when getting the region to mirror.
- `--y-offset` - the number of pixels in the y axis to skip when getting the region to mirror.
The remaining arguments are of the configuration options described on the [Initialization Config page](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/initialization-config). The first two are required.
- `--width` - the number of pixels wide the total panel is. 128px is for a 2x2 matrix panel.
- `--height` - the number of pixels tall the total panel is. 64px is for a 2x2 matrix panel.
The rest are optional if you're using default the configuration for everything.
- `--orientation` - the rotation angle, must be one of `Normal`, `CW`, `CCW`, `R180`.
- `--pinout` - the pinout to use for the panel(s) e.g. `AdafruitMatrixBonnet`
- `--num-address-lines` - the number of address lines. The 64x64 panels we stock use `5`, all smaller panels use `4`
- `--num-planes` - the color depth, defaults to `10`. Lower values can improve refresh rate speed.
- `--serpentine` - the organization of multiple panels, serpentine is default. Use `--no-serpentine` if your panels are wired in the non-serpentine configuration.
The command should look as follows with appropriate values filled in for your panel:
`python fbmirror_scaled.py --scale [scale] --width [width] --height [height] --orientation [orientation]`
The values for a 2x2 matrix panel made from 64x32 panels rotated 180 are shown below, adjust them for your panel(s).
```auto
python fbmirror_scaled.py --scale 3 --width 128 --height 64 --orientation R180
```
The code for this example is embedded below. You can download it, or copy/paste the text into a file.
https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter/blob/main/examples/fbmirror_scaled.py
## Code Explanation
After initializing the matrix panel(s), this example mirrors the `/dev/fb0` framebuffer using `numpy.memmap`. Inside the main loop it copies the current values from the mirrored instance into a PIL Image, scales it down to the specified size, then copies it into `matrix_framebuffer` to be shown on the panel.
# RGB Matrix Panels With Raspberry Pi 5
## MP4 Video
Playing mp4 video files to the console framebuffer can be done with the VLC application, which is pre-loaded by default in the Raspberry Pi OS. In order to get the video to the matrix panel, we'll use the [Mirror Console](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/mirror-console) example from the previous page, so check that out first if you haven't already. The trick is to keep the Mirror Console example running and then play the video so that the video is mirrored to the matrix panels.
You can run the **fbmirror\_scaled.py** script via SSH, or directly from the console with a keyboard. If you run it directly from the console then you'll need to add `&` to the end of the command to run it in the background so that you can get a new prompt to run the VLC command.
```auto
source ~/venvs/blinka_venv/bin/activate
cd ~/Adafruit_Blinka_Raspberry_Pi5_PioMatter/examples
# Via SSH
python fbmirror_scaled.py --scale 16 --width 128 --height 64 --orentation R180
# Direct Console
python fbmirror_scaled.py --scale 16 --width 128 --height 64 --orientation R180 &
```
If you ran it directly in the console, and want to stop the mirroring process you can do so using the `ps` and `kill` commands. First run `ps` and look for the row with "python" in the CMD column, follow that row to the PID column and note the PID number for the process. Then run `kill [number]` swapping in the pid number of the process.
Info: The VLC command must be run directly from the console, not via SSH.
Once the display is being mirrored, all that's left is to start up the video. We must use the `--vout fb` argument to tell VLC to send the video output to the framebuffer. It can also be handy to modify the brightness of the video to darken it some if you see lines or other artifacts in the bright regions of your video. That can be done by adding `--video-filter=adjust --brightness=0.85` to the command before the video is specified. Change the `0.85` to whatever brightness percentage you want.
The whole command looks like this.
```auto
vlc --vout fb --video-filter=adjust --brightness=0.85 your_video_file.mp4
```
You can stop the video early by pressing **Ctrl-C**. If you let the entire video play then it will bring you back to the terminal after it's over, but it will still be waiting for you to exit VLC by pressing **Ctrl-C**.
The code for this is the **fbmirror\_scaled.py** script from the [previous page.](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/mirror-console)
# RGB Matrix Panels With Raspberry Pi 5
## Mirror X Display
## Display Configuration
This example will mirror a display running under the [X Window System](https://en.wikipedia.org/wiki/X_Window_System) to the matrix panel. Raspberry Pi OS now defaults to the Wayland window system instead of X. In order to use this example, you must configure the Pi 5 to use X for its window system display.
Launch raspi-config with `sudo raspi-config`.
- Scroll down to Advanced Options and press enter
- Scroll down to Wayland and press enter
- Select the X11 option and press enter
- Press enter for Ok on the dialog confirming the configuration of X11.
- Scroll over to Finish and press enter
- When prompted select Yes to reboot and press enter.
To ensure that the system and any applications running believe that a display exists whether or not an HDMI display is plugged in, there will be a modification to the file `/boot/firmware/cmdline.txt` that adds a video configuration with the smallest allowed display size.
```auto
sudo nano /boot/firmware/cmdline.txt
```
Scroll to the end of the line by pressing end or holding right arrow for a while.
Press space bar to insert a space at the end of the existing line.
Add the following after the space at the end of the existing line.
```auto
video=HDMI-A-1:640x480M@60D
```
Press **Ctrl-S** to save the file.
Press **Ctrl-X** to exit.
Then reboot the Pi for it to take effect
```auto
sudo reboot
```
## Run X Display Mirror Example
As always, you need to activate the virtual environment before running the example. If you haven't already, then activate it like this.
```auto
source ~/venvs/blinka_venv/bin/activate
```
Next you can run the **xdisplay\_mirror.py** script. The script accepts several arguments to configure the panels. The first 2 are specific to the **xdisplay\_mirror.py** example.
- `--mirror-region` - The region of the display to mirror. x,y,w,h values seperated by commas. If omitted it will mirror the entire screen by default. Example: `--mirror-region 0,0,128,128` to mirror a 128x128 pixel square of the display at real size on the matrices.
- `--x-display` - The X display to use. The default is `:0`. Only needs to be specified if you aren't mirroring the default display.
- `--resample-method` - The PIL resample method to use when resizing the image to be sent to the panel. Valid values are: `nearest`, `bilinear`, `lanczos`, and `bicubic`. The default is `nearest` which works best for pixel art style graphics that have been scaled up to fit a larger display. Other methods may look better for different graphics.
The remaining arguments are of the configuration options described on the [Initialization Config page](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/initialization-config). The first two are required.
- `--width` - the number of pixels wide the total panel is. 128px is for a 2x2 matrix panel.
- `--height` - the number of pixels tall the total panel is. 64px is for a 2x2 matrix panel.
The rest are optional if you're using default the configuration for everything.
- `--orientation` - the rotation angle, must be one of `Normal`, `CW`, `CCW`, `R180`.
- `--pinout` - the pinout to use for the panel(s) e.g. `AdafruitMatrixBonnet`
- `--num-address-lines` - the number of address lines. The 64x64 panels we stock use `5`, all smaller panels use `4`
- `--num-planes` - the color depth, defaults to `10`. Lower values can improve refresh rate speed.
- `--num-temporal-planes` - the temporal dithering control. Valid values are `0`, `2`, or `4`.
- `--serpentine` - the organization of multiple panels, serpentine is default. Use `--no-serpentine` if your panels are wired in the non-serpentine configuration.
The values for a 2x2 matrix panel made fro 64x64 matrices rotated 180 are shown below, adjust them for your panel(s).
```auto
python xdisplay_mirror.py --pinout AdafruitMatrixHatBGR --width 128 --height 128 --serpentine --num-address-lines 5 --num-planes 8
```
Once the display is mirrored simply open another terminal or SSH session and launch whatever app you want to mirror.
The code for **xdisplay\_mirror.py** is embedded below. You can download it, or copy/paste the text into a file.
https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter/blob/main/examples/xdisplay_mirror.py
# RGB Matrix Panels With Raspberry Pi 5
## X Virtual Display
## Install Requirements
In addition to everything covered on the [Raspberry Pi 5 Setup](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/raspberry-pi-5-setup) page, these examples require a few additional requirements to be installed: [Xvfb](https://en.wikipedia.org/wiki/Xvfb) and [PyVirtualDisplay](https://pypi.org/project/PyVirtualDisplay/). Install them with the following commands.
```auto
sudo apt install xvfb
source ~/venvs/blinka_venv/bin/activate
pip install pyvirtualdisplay
```
## Run Virtual Display Example
This example provides a mirrored display only. This works well if the app that you are mirroring has its own built-in support for handling USB gamepads or other inputs. Some game console emulators have support for controllers built-in, any that do can be used with this script. If your app does not have its own input support, you can use the example from the [Mirror X Display](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/mirror-x-display) page for a different method that allows the keyboard and mouse to work, but it requires different setup and configuration from this one.
As always, you need to activate the virtual environment before running the example. If you haven't already, then activate it like this.
```auto
source ~/venvs/blinka_venv/bin/activate
```
Next you can run the **virtualdisplay.py** script. The script accepts several arguments to configure the panels. The first 5 are specific to the virtualdisplay example.
- `--scale` - The scale factor, larger numbers mean more virtual pixels. Default is 1.
- `--backend` - The pyvirtualdisplay backend to use. Supported values are xvfb, and xvnc, default is xvfb.
- `--extra-args` - Extra arguments to pass to the backend server.
- `--rfbport` - The port number for the `--backend xvnc`.
- `--use-xauth/--no-use-xauth` - If a Xauthority file should be created. Default is False.
The remaining arguments are of the configuration options described on the [Initialization Config page](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/initialization-config). The first two are required.
- `--width` - the number of pixels wide the total panel is. 128px is for a 2x2 matrix panel.
- `--height` - the number of pixels tall the total panel is. 64px is for a 2x2 matrix panel.
The rest are optional if you're using default the configuration for everything.
- `--orientation` - the rotation angle, must be one of `Normal`, `CW`, `CCW`, `R180`.
- `--pinout` - the pinout to use for the panel(s) e.g. `AdafruitMatrixBonnet`
- `--num-address-lines` - the number of address lines. The 64x64 panels we stock use `5`, all smaller panels use `4`
- `--num-planes` - the color depth, defaults to `10`. Lower values can improve refresh rate speed.
- `n_temporal_planes` - Controls the temporal dithering. Valid values are `0`, `2`, and `4`. Cannot be higher than `n_planes`. The default is `0`. Using larger values can increase the framerate in some cases experiment with your panels and application.
- `--serpentine` - the organization of multiple panels, serpentine is default. Use `--no-serpentine` if your panels are wired in a non-serpentine configuration.
### Mirrored App Command
After all of the other arguments, at the end of the command you will include two dashes surrounded by spaces ` -- `, following those you put what ever command is needed to launch the app that you want to mirror including any arguments that it requires.
The command should look as follows with the appropriate values filled in for your panel:
`python virtualdisplay.py --scale [scale] --width [width]
--height [height] --orientation [orientation] --num-address-lines
[addrlines] --num-planes [planes] -- [command launching app to mirror]`
The values for a 2x2 matrix panel made from 64x64 panels rotated 180 are shown below, adjust them for your panel(s).
```auto
python virtualdisplay.py --pinout AdafruitMatrixHatBGR --scale 2 --backend xvfb --width 128 --height 128 --serpentine --num-address-lines 5 --num-planes 4 -- mednafen -snes.xscalefs 1 -snes.yscalefs 1 -snes.xres 128 -video.fs 1 -video.driver softfb /tmp/snesrom.smc
```
This command is launching [Mednafen](https://mednafen.github.io/), a multi-system emulator application. If you're launching something different then replace everything after the double hyphen with your own launch command.
The code for **virtualdisplay.py** is embedded below. You can download it, or copy/paste the text into a file.
https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter/blob/main/examples/virtualdisplay.py
# RGB Matrix Panels With Raspberry Pi 5
## USB HDMI Input
Using the X Virtual Display script from the previous page along with a [USB HDMI Capture Adapter](https://www.adafruit.com/product/4669) and the Linux program `guvcview` you can mirror any HDMI compatible device to the RGB Matrix panels. For this example we used a Nintendo Switch, but you can plug in whatever device you want to mirror.
### HDMI Input to USB 2.0 Video Capture Adapter
[HDMI Input to USB 2.0 Video Capture Adapter](https://www.adafruit.com/product/4669)
Here's one of the easiest capture solutions for getting HDMI data into your computer or Raspberry Pi, really any system with a USB port..
Use this capture device to convert a video signal from a camera (or another device) into a digital format your computer can recognize. ...
In Stock
[Buy Now](https://www.adafruit.com/product/4669)
[Related Guides to the Product](https://learn.adafruit.com/products/4669/guides)
## Install Requirements
In addition to everything covered on the [Raspberry Pi 5 Setup](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/raspberry-pi-5-setup) page, these examples require a few additional requirements to be installed: [Xvfb,](https://en.wikipedia.org/wiki/Xvfb) [PyVirtualDisplay](https://pypi.org/project/PyVirtualDisplay/), and [guvcview](https://en.wikipedia.org/wiki/Guvcview). Install them with the following commands.
```auto
sudo apt install xvfb
sudo apt install guvcview
source ~/venvs/blinka_venv/bin/activate
pip install pyvirtualdisplay
```
## Run the Virtual Display with guvcview
To display the HDMI input to the panels, you can run the **virtualdisplay.py** script using `guvcview` as the mirrored app command. See the [Run Virtual Display Example](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/x-virtual-display#run-virtual-display-example-3194884) and [Mirrored App Command](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/x-virtual-display#mirrored-app-command-3194853) sections on the previous page for more details about all possible arguments that can be used for configuring different sizes and amounts of RGB matrices.
By default, `guvcview` will try to open up two app windows, one with a bunch of configuration options, and the other showing the actual feed from the HDMI input. For mirroring onto the panels, we want to get only the input feed, not the configuration window. The `--gui=none` argument instructs guvcview to launch only input feed window.
The following command is for 64x64 panels arranged in a 2x2 grid with the no-serpentine arrangement, and in the R180 flipped orientation. Adjust the arguments as needed for your own panel arrangement.
The code for this is the **virtualdisplay.py** script from the [previous page](https://learn.adafruit.com/rgb-matrix-panels-with-raspberry-pi-5/x-virtual-display).
```auto
python virtualdisplay.py --pinout AdafruitMatrixBonnetBGR --backend xvfb --width 128 --height 128 --no-serpentine --num-address-lines 5 --num-planes 10 --orientation R180 --scale 5 --brightness 0.50 --num-temporal-planes 4 -- guvcview --gui=none
```
## Featured Products
### Adafruit RGB Matrix Bonnet for Raspberry Pi
[Adafruit RGB Matrix Bonnet for Raspberry Pi](https://www.adafruit.com/product/3211)
You can now create a dazzling display with your Raspberry Pi with the Adafruit RGB Matrix Bonnet. These boards plug into your Pi and make it super easy to control RGB matrices such as those we stock in the shop and create a colorful scrolling...
Out of Stock
[Buy Now](https://www.adafruit.com/product/3211)
[Related Guides to the Product](https://learn.adafruit.com/products/3211/guides)
### Adafruit RGB Matrix HAT + RTC for Raspberry Pi - Mini Kit
[Adafruit RGB Matrix HAT + RTC for Raspberry Pi - Mini Kit](https://www.adafruit.com/product/2345)
You can now create a dazzling display with your Raspberry Pi Model Zero/A+/B+/Pi 2/3/Pi 4 with the Adafruit RGB Matrix HAT. This HAT plugs into your Pi and makes it super easy to control RGB matrices such as those we stock in the shop and create a colorful scrolling display or mini LED...
Out of Stock
[Buy Now](https://www.adafruit.com/product/2345)
[Related Guides to the Product](https://learn.adafruit.com/products/2345/guides)
### 64x32 RGB LED Matrix - 3mm pitch
[64x32 RGB LED Matrix - 3mm pitch](https://www.adafruit.com/product/2279)
Bring a little bit of Times Square into your home with this sweet 64 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked...
In Stock
[Buy Now](https://www.adafruit.com/product/2279)
[Related Guides to the Product](https://learn.adafruit.com/products/2279/guides)
### 5V 4A (4000mA) switching power supply - UL Listed
[5V 4A (4000mA) switching power supply - UL Listed](https://www.adafruit.com/product/1466)
Need a lot of 5V power? This switching supply gives a clean regulated 5V output at up to **4 Amps** (4000mA). 110 or 240 input, so it works in any country. The plugs are "US 2-prong" style so you may need a plug adapter, but you can pick one up at any hardware store for $1 or so,...
Out of Stock
[Buy Now](https://www.adafruit.com/product/1466)
[Related Guides to the Product](https://learn.adafruit.com/products/1466/guides)
### 5V 10A switching power supply
[5V 10A switching power supply](https://www.adafruit.com/product/658)
This is a beefy switching supply, for when you need a lot of power! It can supply 5V DC up to 10 Amps, running from 110V or 220V power (the plug it comes with is for US/Canada/Japan but you can use any plug adapter for your country, or just replace the cable with a standard computer/appliance...
In Stock
[Buy Now](https://www.adafruit.com/product/658)
[Related Guides to the Product](https://learn.adafruit.com/products/658/guides)
### Female DC Power adapter - 2.1mm jack to screw terminal block
[Female DC Power adapter - 2.1mm jack to screw terminal block](https://www.adafruit.com/product/368)
If you need to connect a DC power wall wart to a board that doesn't have a DC jack - this adapter will come in very handy! There is a 2.1mm DC jack on one end, and a screw terminal block on the other. The terminals are labeled with positive/negative assuming a positive-tip configuration...
In Stock
[Buy Now](https://www.adafruit.com/product/368)
[Related Guides to the Product](https://learn.adafruit.com/products/368/guides)
### GPIO Ribbon Cable 2x8 IDC Cable - 16 pins 12" long
[GPIO Ribbon Cable 2x8 IDC Cable - 16 pins 12" long](https://www.adafruit.com/product/4170)
Connect this to that! If you want to bridge those contacts out onto another PCB, you'll want this **GPIO Ribbon Cable**! Comes in a classic Adafruit Black, has a nice soft flexible 16-line 0.05" ribbon cable and keyed IDC connectors on both ends.
In Stock
[Buy Now](https://www.adafruit.com/product/4170)
[Related Guides to the Product](https://learn.adafruit.com/products/4170/guides)
## Related Guides
- [NextBus transit clock for Raspberry Pi](https://learn.adafruit.com/nextbus-transit-clock-for-raspberry-pi.md)
- [Raspberry Pi LED Matrix Display](https://learn.adafruit.com/raspberry-pi-led-matrix-display.md)
- [Image Correction for RGB LED Matrices](https://learn.adafruit.com/image-correction-for-rgb-led-matrices.md)
- [Adafruit Protomatter RGB Matrix Library](https://learn.adafruit.com/adafruit-protomatter-rgb-matrix-library.md)
- [RGB LED Matrix Cube with 25,000 LEDs](https://learn.adafruit.com/rgb-led-matrix-cube-for-pi.md)
- [RGB LED Matrix Basics](https://learn.adafruit.com/32x16-32x32-rgb-led-matrix.md)
- [Use an art canvas to diffuse an RGB matrix](https://learn.adafruit.com/use-an-art-canvas-to-diffuse-rgb-matrix.md)
- [Adafruit MatrixPortal M4](https://learn.adafruit.com/adafruit-matrixportal-m4.md)
- [Animated GIF Player for Matrix Portal](https://learn.adafruit.com/animated-gif-player-for-matrix-portal.md)
- [Adafruit RGB Matrix + Real Time Clock HAT for Raspberry Pi](https://learn.adafruit.com/adafruit-rgb-matrix-plus-real-time-clock-hat-for-raspberry-pi.md)
- [Raspberry Pi RGB LED Matrix Webapp](https://learn.adafruit.com/raspberry-pi-rgb-led-matrix-webapp.md)
- [Matrix Portal Creature Eyes](https://learn.adafruit.com/matrix-portal-creature-eyes.md)
- [Build an ML Rock Paper Scissors Game with Lobe](https://learn.adafruit.com/lobe-rock-paper-scissors.md)
- [Adafruit 5x5 NeoPixel Grid BFF](https://learn.adafruit.com/adafruit-5x5-neopixel-grid-bff.md)
- [Raspberry Pi Video Looper 2](https://learn.adafruit.com/raspberry-pi-video-looper-2.md)