Maker.io main logo

LED Matrix Wall Arcade for Pico-8

320

2025-04-25 | By Adafruit Industries

License: See Original Project LED Matrix Raspberry Pi SBC

Courtesy of Adafruit

Guide by John Park

Overview

 

Note: there's no flicker in real life, these are just difficult to film!‎

wall_1

Build a wall mounted arcade that's a low-resolution work of art! You can play PICO-8 games ‎on it or just run sweet demoscene code for a retro-tech bit of eye candy.‎

This project uses a Raspberry Pi 5 running Piomatter to drive a 128x128 pixel display made ‎of four RGB LED matrices. A deep frame from IKEA plus some 3D printed brackets makes it ‎straightforward to assemble.‎

The way this works is that PICO-8 is launched against XVFB (a virtual X framebuffer) so it ‎thinks it's running on a really tiny monitor. But in reality, a python script (virtualdisplay.py) ‎will grab that framebuffer and feed it to the LED matrices via Piomatter.‎

Parts

Frame

SANNAHED frame from IKEA. It comes in a few colors to match your decor.‎

frame_2

PICO-8 Fantasy Console

The PICO-8 Fantasy Console cost about $15. This includes all future versions and is cross-‎platform so you can install it on your Windows, Mac, Linux, and Raspberry Pi machines.

console_3

Controllers

You'll want some generic wired USB gamepads such as these SNES-styled ones.‎

Or you can go with some wireless Bluetooth gamepads such as these.‎

controllers_4

Printed Brackets

brackets_5

Print the models attached below on an FDM printer using PLA or PETG. You'll need the ‎following multiples:

  • bracket x1‎

  • speaker x1‎

  • tri-corner_pi x1‎

  • tri-corner x3‎

  • jointA x2‎

  • jointB x2‎

  • corner x4‎

pico8_P3_models

You can print them yourself or send them to a 3D printing service.‎

Build the Arcade

Panel Arrangement

There are currently two supported arrangements for four 64x64 panels in Piomatter --‎serpentine and --no-serpentine

panel_6

No-Serpentine

In this arrangement all four panels are oriented alike.‎

The benefit of this is that view-dependent differences in pixel color are a non-issue. ‎

However, a rather long run of IDC ribbon cable is required to make the connection from ‎panel 2's output to panel 3's input, approximately 50cm for a 3mm pitch matrix panel.‎

If you have a long enough cable, go for this arrangement.‎

arrangement_7

arrangement_8

arrangement_9

Serpentine

In serpentine arrangement, the two bottom panels are oriented upside down.‎

The benefit of this arrangement is shorter cable runs.‎

The downside is that there are view-angle dependent color shifts visible between the upper ‎and lower pairs, particularly when lighter colors span the break, which can cause a blueish ‎line to appear.‎

In the attached screen photos, you can see the cause of this is the physical arrangement of ‎the RGB LED trio per pixel. Blue is at the bottom of the pixel, so it is perceptually stronger ‎where the two bottom rows meet.‎

The build in this guide uses serpentine arrangement since I didn't have a 50cm cable on ‎hand.‎

serpentine_10

serpentine_11

serpentine_12

serpentine_13

serpentine_14

Connector Bracket

Plug in the IDC cables and then mount the back bracket. ‎

Press the bracket onto the panels so the registration pegs are nicely seated, then screw the ‎bracket into place using M3 screws.‎

Note, the bracket is designed to accommodate both panel arrangements, so there are ‎holes that will remain un-used -- check for brass threading before screwing into a given ‎hole.‎

connector_15

Edge Joints

Next, screw in the edge joints to align and secure the panel edges. Note that the side joints ‎‎(printed in magenta filament here) have cutouts in them to accommodate the data sockets.‎

edge_16

edge_17

Matrix Bonnet

Follow the silkscreen polarity markings and screw in the two sets of power cables to the ‎terminal block as shown here.‎

matrix_18

Pi Mount

Use four M2.5 screws and nuts to create mounting points for the Pi 5.‎

Fasten the Pi with nuts or short standoffs so that the Matrix Bonnet can still be connected.‎

mount_19mount_20

mount_21

mount_22

mount_23

mount_24

Mount Pi to Panel

Plug in the IDC cable from the Matrix Bonnet to the input of panel 1.‎

Screw in the Pi tri-corner mount to the panel.‎

Then, screw in the other tri-corner mounts. The keep the display centered in the frame, ‎along with the frame spacer.‎

Plug in the four power connectors.‎

plug_25

plug_26

plug_27

Frame Mounting

Place the acrylic panel in the front of the frame.‎

Set the four corner spacers into place as shown, so the wooden frame spacer will seat into ‎them and hold them flush to the front of the frame.‎

Carefully place the matrix display into the center of the frame.‎

frame_28

frame_29

frame_30

frame_31

frame_32

Speaker Prep

Press fit the speaker into the printed speaker holder.‎

Fit the speaker into the frame, then plug the USB cable into the Raspberry Pi.‎

speaker_33

speaker_34

speaker_35

speaker_36

Two Power Supplies

Plug in the USB C power to the Pi and the 5V center-positive 10A DC power cable to the ‎Matrix Bonnet.‎

power_37

power_38

Back Panel

Dress the cables to exit below the panel 1 corner, then cut out a little mouse hole in the ‎back panel for them using a hobby knife.‎

back_39

back_40

back_41

back_42

back_43

back_44

Pi Setup & Code

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.‎

RGB Matrix Panels with Raspberry Pi 5‎

By Tim C

‎X Virtual Display

View Guide

blinka_image_45

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‎

setting_46

setting_47

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.‎

execute_48

Then, make pico_64 executable by typing:‎

Copy Code
chmod -x ./pico8_64

List the directory contents with ls -l to see the permissions have changed.‎

picturecode

Now, you can launch Pico-8 by typing:‎

Copy Code
./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.‎

Peripherals

This is a good time to add the audio and gamepads to the setup.‎

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.‎

sound_49

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.‎

plugin_50

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:‎

Copy Code
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.‎

Copy Code
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.‎

Copy Code
#!/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.py with several ‎parameters:‎

o ‎--brightness 0.5 - Sets the LED matrix brightness to 50%‎
o ‎--pinout AdafruitMatrixBonnet - Specifies the hardware as an Adafruit Matrix ‎Bonnet
o ‎--backend xvfb - Uses Xvfb (X virtual framebuffer) to render graphics without a ‎physical display
o ‎--width 128 --height 128 - Sets the display resolution to 128x128 pixels
o ‎--serpentine - Indicates the LED matrix has a serpentine layout
o ‎--num-address-lines 5 - Specifies 5 address lines for the LED matrix
o ‎--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:‎

Copy Code
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:‎

Copy Code
crontab -e

Then add this line:‎

Copy Code
@reboot /bin/bash ~/start_pico8_splore_matrix.sh

Then save by pressing ctrl-s and close the editor by pressing ctrl-x.‎

Moment of Truth

OK, let's see if it worked! Restart the system by typing:‎

Copy Code
sudo reboot

You should see the Raspberry Pi restart and after about 20 seconds, Pico-8 will start up on ‎the matrix display!‎

display_51

display_52

Mount and Play

play_53

A simple wall hook is all you need to mount the arcade to the wall.‎

As a bonus, use a cord cover kit to neaten up the wiring.‎

hook_53

hook_54

finished_55

 

finished_57

Build one for every room or give them out as gifts!

finished_58

Mfr Part # 5249
MEMORY CARD MICROSD 64MB CLASS 4
Adafruit Industries LLC
$ 3,50
View More Details
Mfr Part # 3211
RGB LED MATRIX BONNET HUB75
Adafruit Industries LLC
$ 14,95
View More Details
Mfr Part # 4732
64X64 RGB LED MATRIX - 3MM PITCH
Adafruit Industries LLC
$ 64,95
View More Details
Mfr Part # 3369
MINI EXTERNAL USB STEREO SPEAKER
Adafruit Industries LLC
$ 12,50
View More Details
Mfr Part # 658
AC/DC DESKTOP ADAPTER 5V 50W
Adafruit Industries LLC
$ 29,95
View More Details
Mfr Part # SC0445
AC/DC WALL MNT ADAPTER 5.1V 15W
Raspberry Pi
$ 8,00
View More Details
Mfr Part # 3299
BLACK NYLON SCREW AND STAND-OFF
Adafruit Industries LLC
$ 16,95
View More Details
Mfr Part # 4685
BLACK NYLON SCREW AND STAND-OFF
Adafruit Industries LLC
$ 16,95
View More Details
Mfr Part # SC1431
SBC 2.4GHZ 4 CORE 4GB RAM
Raspberry Pi
$ 64,26
View More Details
Add all DigiKey Parts to Cart
Have questions or comments? Continue the conversation on TechForum, DigiKey's online community and technical resource.