We recommend you use the latest Raspberry Pi OS flashed onto one of the official Raspberry Pi SDCards. The Raspberry Pi Imager app makes it easy to prepare your SD Card. 

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 apt update
sudo apt upgrade

sudo apt update
sudo apt upgrade

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.

python -m venv ~/venvs/blinka_venv

python -m venv ~/venvs/blinka_venv

For more info about virtual environments see this guide.

Install Requirements

Next you need to activate the new virtual environment and then install the required libraries within it.

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

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.

sudo nano /etc/udev/rules.d/99-com.rules

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.

SUBSYSTEM=="*-pio", GROUP="gpio", MODE="0660"

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.

sudo raspi-config

sudo raspi-config