For the initial setup, follow this excellent guide, RGB Matrix Panels with Raspberry Pi. Make sure you can get the virtual display running as shown on this page, this is the same method we'll use to display Pico-8.
You'll want to follow the instructions for using SSH since the setup will eventually be headless, in case you need to make adjustments after you've mounted the arcade to the wall.
Pico-8
Next, download and install Pico-8 from the download page. There is a small cost, but that helps the developers and you get all future updates.
Setting Up Pico-8
You'll need to first create a login.
Download the .zip, un-compress it, and move the pico-8 directory to your user directory. The path should look like this:
/home/admin/pico-8
Execute
We'll run the 64-bit version of Pico-8. To make it executable, open a command line, navigate to the pico-8 directory by typing cd ~/pico-8 and press Enter.
Then, make pico_64 executable by typing:
chmod -x ./pico8_64
List the directory contents with ls -l to see the permissions have changed.
Now, you can launch Pico-8 by typing:
./pico8_64
This won't launch to your matrix display, but you should see it on your HDMI display if it's plugged in. You can try it out and play around a bit. When you're done you can press ctrl-q to quit.
Sound
Plug in the mini external USB stereo speaker to a USB port on the Raspberry Pi 5. It seems to "just work" on reboot, but you can check out this guide for details on configuration. Try running Pico8_64 to make sure you hear sound.
Gamepad
Plug in your gamepad or gamepads to USB. These, too, should just work after a reboot. However, some extra configuration may be necessary for Pico-8 to use the proper button mapping.
This page is an excellent resource for determining controller configuration and updating the sdl_controllers.txt file.
Here's what the string looks like for my generic USB SNES-style gamepads:
030000001f08000001e4000006010000,USB gamepad gp100,platform:Linux, X,a:b2,b:b1,x:b3,y:b0,back:b8,start:b9,leftshoulder:b4,rightshoulder:b5,dpup:-a1,dpdown:+a1,dpleft:-a0,dpright:+a0,
What about wireless? You can use Bluetooth controllers directly with Raspberry Pi 5 or 2.4GHz controllers with a dongle, such as those provided with some 8BitDo controllers. Once paired/trusted/connected to the system, follow the same instructions as above to configure specific button mapping.
Virtual Display
Now we can set it up to send the Pico-8 display to the LED matrix.
From the RGB Matrix Panels with Raspberry Pi 5 guide we saw that we can mirror an application to the LED matrix using the Python virtualdisplay.py script. This is one of the example scripts that was automatically installed along with Piomatter.
First, activate the virtual environment:
source ~/venvs/blinka_venv/bin/activate
Copy and paste the command shown here to launch the script and pico8_64 as the mirrored app. The flag -splore will tell Pico-8 to launch into SPLORE which is a sort of kiosk/console mode perfect for using just a game controller to explore and launch games without keyboard and mouse.
python /home/admin/Adafruit_Blinka_Raspberry_Pi5_Piomatter/examples/virtualdisplay.py --brightness 0.5 --pinout AdafruitMatrixBonnet --backend xvfb --width 128 --height 128 --serpentine --num-address-lines 5 --num-planes 6 -- ~/pico-8/pico8_64 -splore
You should see Pico-8 on the LED matrix display now! When you're done playing with it you can quit with a ctrl-c.
You can experiment with different --brightness levels from 0.0 to 1.0 and --num-planes from 1-10 in order to get the best, flicker-free look.
Autorun on Boot
Since we'll use the arcade in headless mode we want to set it up to automatically launch the virtualdisplay.py script on startup.
Shell Script
To do this, we'll first create a shell script and then we'll set it to automatically launch on startup.
Copy the script below and save it to your home directory as start_pico8_splore_matrix.sh.
#!/bin/bash # Add logging exec > /home/admin/pico8_startup.log 2>&1 echo "Starting script at $(date)" # Activate the Python virtual environment echo "Activating virtual environment" source /home/admin/venvs/blinka_venv/bin/activate echo "Virtual environment activated: $VIRTUAL_ENV" # Run the virtual display with PICO-8 echo "Starting virtual display and PICO-8" python /home/admin/Adafruit_Blinka_Raspberry_Pi5_Piomatter/examples/virtualdisplay.py --brightness 0.5 --pinout AdafruitMatrixBonnet --backend xvfb --width 128 --height 128 --serpentine --num-address-lines 5 --num-planes 6 -- ~/pico-8/pico8_64 -splore echo "Script completed at $(date)"
-
#!/bin/bash- This is the "shebang" line that identifies this as a bash script -
exec > /home/admin/pico8_startup.log 2>&1- This redirects all output (both standard output and errors) to a log file at the specified path -
echo "Starting script at $(date)"- Logs the start time of the script -
source /home/admin/venvs/blinka_venv/bin/activate- Activates the Python virtual environment - The main command runs a Python script called
virtualdisplay.pywith several parameters:-
--brightness 0.5- Sets the LED matrix brightness to 50% -
--pinout AdafruitMatrixBonnet- Specifies the hardware as an Adafruit Matrix Bonnet -
--backend xvfb- Uses Xvfb (X virtual framebuffer) to render graphics without a physical display -
--width 128 --height 128- Sets the display resolution to 128x128 pixels -
--serpentine- Indicates the LED matrix has a serpentine layout -
--num-address-lines 5- Specifies 5 address lines for the LED matrix -
--num-planes 6- Specifies color depth/bit planes for the display
-
- After
--the script specifies what to run on the virtual display:~/pico-8/pico8_64 -splore, which launches the 64-bit version of PICO-8 in "splore" mode -
echo "Script completed at $(date)"- Logs the completion time of the script
You can test this script now before we have it auto-run. Make it executable by typing:
chmod +x ~/start_pico8_splore_matrix.sh
Crontab
The crontab can be used to create a cron job that runs our bash script at startup.
Type this in the terminal to launch the crontab editor:
crontab -e
Then add this line:
@reboot /bin/bash ~/start_pico8_splore_matrix.sh
Then save by pressing ctrl-s and close the editor by pressing ctrl-x.
sudo reboot
You should see the Raspberry Pi restart and after about 20 seconds, Pico-8 will start up on the matrix display!
Page last edited March 20, 2025
Text editor powered by tinymce.
