Log In  

At 128 x 128 pixels, the Waveshare 1.44 inch display with controller is a perfect fit for Pico-8.

The screen Driver being installed, requires a Waveshare 1.44" 128x128 pixel colour LCD display, with joystick & 3 buttons which utilises an ST7735S controller.

Amazon UK link: https://www.amazon.co.uk/gp/product/B077YK8161
Amazon US link: https://www.amazon.com/waveshare-1-44inch-LCD-HAT-Interface/dp/B0781BNC9L/

Built, tested and confirmed working with both Raspbian Stretch lite and Buster lite-based images.

Begin by writing a fresh Raspbian Stretch or Buster Lite image to a 4GB or larger MicroSD card using your favoured image writing tool.


Raspbian Buster appears to generate more heat after short periods on a Pi ZeroWH than Stretch does.

Whichever image you begin your build with, please monitor CPU temperature during use. I won't be held responsible for a baked Pi!

A Pi ZeroW can be set-up headless if a properly configured "wpa_supplicant.conf" and a blank file named "ssh" are copied to the root of the MicroSD card, after writing the image but before unplugging and inserting into the Pi.


SSH into the Pi or plug-in a keyboard and monitor. Login with username "pi" and password "raspberry"

sudo raspi-config

Expand the filesystem
Set boot to CLI with auto-login
enable SPI
disable VNC
disable serial

I recommend changing the default password from "raspberry" to something more secure while you're still in raspi-config.

You may also wish to change the hostname while you're in here. I named mine pico8, so I can ssh to pico8.local from other machines for maintenance.

Exit raspi-config and reboot with

sudo reboot

Once rebooted, login as pi, then update and upgrade the OS and programs:

sudo apt-get update
sudo apt-get upgrade

Reboot once again and re-login if recommended by the upgrade process

Let's begin by getting Pico8 running on the Pi

sudo apt-get install libasound2-dev wiringpi
wget https://t.co/jZy96cDeCC?amp=1 -O sndio-1.2.0.tar.gz
tar -xf sndio-1.2.0.tar.gz
cd sndio-1.2.0
sudo make install
cd ~

Use SFTP (or USB) to transfer your personal Pico download zip file into /home/pi folder

Unzip your Pico8 Raspberry Pi zip file into /home/pi.
This should create a /home/pi/pico-8 folder, which will contain all of the files required to run Pico8.

Now we’ll get the Waveshare 1.44" 128x128 pixel LCD display hat working on the Pi

cd ~
sudo apt-get install git cmake
git clone https://github.com/tasanakorn/rpi-fbcp
cd rpi-fbcp/
mkdir build
cd build/
cmake ..
sudo install fbcp /usr/local/bin/fbcp

cd ~

wget http://www.airspayce.com/mikem/bcm2835/bcm2835-1.59.tar.gz
tar zxvf bcm2835-1.59.tar.gz
cd bcm2835-1.59/
sudo make check
sudo make install

Open and edit the modules file to enable the additional modules required to make the LCD function.

sudo nano /etc/modules

Append the two lines below to the end of the file, save and exit.


We need to create a new file for the fbtft configuration

sudo nano /etc/modprobe.d/fbtft.conf

Add the following lines to the empty file and save it.

# /etc/modprobe.d/fbtft.conf
options fbtft_device name=adafruit18_green gpios=reset:27,dc:25,cs:8,led:24 speed=40000000 bgr=1 fps=60 custom=1 height=128 width=128 rotate=180

Fortunately for us, Adafruit created a GPIO controller driver, so let's use this to make the Waveshare hat's controller and buttons work in pico-8.

cd ~
curl https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/retrogame.sh >retrogame.sh
sudo bash retrogame.sh

On the option screen, Select “6 buttons + joystick”. We’ll edit the resulting config file a little later to fit the 3 button and joystick layout of our hat.

Once installed; at the reboot prompt, type “N” so as NOT to reboot your Pi.

Now we’ll edit the configuration file installed and used by Adafruit’s retrogamer driver, to configure the correct number of buttons for the Waveshare hat.

sudo nano /boot/retrogame.cfg

Use CTRL-K to remove all lines from the file and paste the following lines into the now empty file before saving it and exiting nano.

LEFT    5   # Joypad left
RIGHT   26  # Joypad right
UP      6   # Joypad up
DOWN    19  # Joypad down
Z       20  # Button 3
X       16  # Button 2
ESC     21  # Button 1

Please ensure each entry is on a separate line as displayed above.

At this stage, we can set the correct display settings for the Waveshare 128x128 LCD within the file config.txt

sudo nano /boot/config.txt

Add to the end of the file and beginning on a new/empty line, the following lines:

hdmi_cvt=128 128 60 1 0 0 0

Save the file and exit nano.

Now let's put this all together and have Pico-8 run in "splore" mode at boot.

sudo nano /etc/rc.local

This file should should be as below. (All we're adding to the file are three lines near the end, each beginning with sudo):

#!/bin/sh -e
# rc.local
# This script is executed at the end of each multiuser runlevel.
# Make sure that the script will "exit 0" on success or any other
# value on error.
# In order to enable or disable this script just change the execution
# bits.
# By default this script does nothing.

# Print the IP address
_IP=$(hostname -I) || true
if [ "$_IP" ]; then
  printf "My IP address is %s\n" "$_IP"

sudo /usr/local/bin/fbcp &
sudo /usr/local/bin/retrogame &
sudo /home/pi/pico-8/pico8 -splore &

exit 0

Save this file and exit nano.

Shutdown and power-off the pi with

sudo shutdown now

Wait for the pi to shutdown, unplug the power-cable and connect the Waveshare LCD hat onto the GPIO connectors.

Be careful to connect the hat in the correct orientation, onto all 40 GPIO pins.

Plug-in, power-up and enjoy all colourful 128x128 pixels of Pico-8 glory on a tiny, square display and in complete silence!

Connect the Pi to the Internet via Wi-Fi (ZeroW), then use the joystick and KEY2 to update and download Pico-8 programs directly to the Pi.

KEY1 functions as Escape
KEY2 functions as X
KEY3 functions as Z

P#66331 2019-08-03 11:33 ( Edited 2019-08-11 17:32)

Thanks, this looks great and the tutorial is really easy to undestand, thank you! I would guess that the whole build get's a bit more pricey and bulky when you want to add a battery pack, how does it play in the current state?

P#66421 2019-08-06 21:12

It plays just fine.

There's no sound, but the majority of games I've tried work using the joystick for directional control, along with Z and X.

Adding a battery is also going to bulk-up the experience in terms of portability but I did this as I saw a 128 x 128 pixel, square hat and wondered how Pico-8 would look on a screen that used the same pixel count.

As it turned out; quite well.

I don't believe it scales so that each pixel on the screen contains a single pixel of Pico-8's display but it must be close because there's no blurring and everything is clean and bright.

It's just a pity all of the above is in silence!

P#66439 2019-08-07 15:35

The following command need to be on separate lines:

git clone https://github.com/tasanakorn/rpi-fbcp

cd rpi-fbcp/

P#66553 2019-08-11 17:29

Original post updated.

Thank you for pointing this out.

P#66554 2019-08-11 17:32

I have acquired the same board and I am testing that on a non W Pi Zero.

Except for the typo above, things work for me.
However, it is not perfect.

I see two areas where things can be improved.

1) The screen copy:

fbcp[642]: Primary display is 480 x 640
fbcp[642]: Second display is 128 x 128 16bps

Because of the primary display size, the aspect ratio is not respected and the result is not pixel. The solution is to ask pico8 to draw on a 128x128 area and find a version of fbcp that does pixel perfect copy.

I have seen or done that in the past, so I'll try to recover some documentation on that topic and propose a solution. I'll have a look at the eyesbonet from adafruit, mlx90640 example from pimoroni and other.

2) I don't really like retrogame from adafruit as it is a loop that scan the GPIO. I have seen better solution on ANAVI play pHAT. It should be possible to use overlay with the same result. This is less of an issue, but I also plan to have a look.

Thank you very much for making us discover this board and making it work for us. Everything else is just fine tuning.

P#66559 2019-08-11 18:57

My fault, I may have not followed perfectly your hdmi configuration.
Now the aspect ratio is OK and it seems to be pixel accurate.

pi@pico8:~ $ /opt/vc/bin/tvservice -s
state 0xa [HDMI DMT (87) RGB full 4:3 x4], 128x128 @ 55.00Hz, progressive

Aug 11 23:10:48 pico8 fbcp[402]: Primary display is 128 x 128
Aug 11 23:10:48 pico8 fbcp[402]: Second display is 128 x 128 16bps
Aug 11 23:10:48 pico8 kernel: [ 36.109526] input: retrogame as /devices/virtual/input/input0

The only issue is that this resolution cannot be displayed on a physical HDMI screen.
I would have love to be able to see it both on HDMI and on the LCD like I did here: https://twitter.com/DavidGlaude/status/1018535835904479232

I have found my modified version of fbx2 from Adafruit.
After changing to display_rotation=3 I have a version of fbx2 that work on that board and replace both rpi-fbcp and fbtft.
I reach 42fps so that seems OK for 30fps games, but I believe that some game run at 60fps.

P#66582 2019-08-11 22:33 ( Edited 2019-08-11 22:55)

Thank you for your positive feedback.

I admit I did test this thoroughly while writing the tutorial; formatting new cards, writing Raspbian Lite images and copy/pasting my instructions back into SSH sessions before plugging in the hat and powering up.

I thought I'd caught all of my layout errors before posting but found a couple after publishing and corrected those before you found (what I hope is) the last one. These came from pasting from my original text notes and the inevitable re-formatting of mass-pasting.

I wondered where your errors in aspect ratio came from. As shown in my photo at the head of the tutorial, on all of my builds the screen looks pretty much pixel for pixel, though I had doubts myself as to whether each of Pico 8's pixels fell into an LCD cell.

Even then it was close enough for me, as it was only an experiment using a comparatively cheap add-on, just to see how well it would work and I was pleasantly surprised by the results. Enough to feel it worth sharing.

Pity there's no sound.

How are you obtaining updates from the splore menu? Are you using a dongle Wi-Fi adaptor?

I used the official, White RPI dongle before Wi-Fi became the norm but on my zeroes recently, I've been using a MicroUSB Ethernet adaptor, which Raspbian has built-in driver support for.

P#66589 2019-08-12 00:11 ( Edited 2019-08-12 07:46)

I would like to improve the instructions, such as reducing the number of file edition and increase the number of command that can blindly be cut and pasted. While this is not possible for config.txt, it could be possible with the module list.

My aspect ratio issue was either a typo or a shortcut I took in the content of config.txt.
At one point I did believe the behaviour was different depending if the HDMI was connected or not.

I did not find any unused soldered PiZeroW at home. My last one is in my TinyPi Pro (with a 240*240 screen). So I used an older one and I have my connectivity with a Ethernet over USB and a USB OTG cable. I also attempted to log with a serial console adapter. With your curent setup, HDMI is unusable on my screen. If I could fix that, it would greatly help.

For the sound, I may have a pHAT DAC or best a Speaker pHAT from Pimoroni. So, the first thing to verify is if I can get the sound in I2S... Anyway it will be uggly from a physical integration point of view. But if it work in I2S, then an Adafruit breadboard might do the trick to add a jack to the board.

However it seems like the recreation of the TinyPi: https://pi0cket.com/tinypi/ So I better try building mine and solder what there is to solder. ;-)

P#66624 2019-08-12 20:16

This one looks interesting too:
Has battery and sound...

P#66771 2019-08-19 01:22

Hello. I just want to thank you in advance for this tutorial and I hope it'll work out for me at least.

I do have a couple questions:
1) how may I safely shut it down?
2) do you think a microUSB audio adapter would help with the sound conundrum?

Best wishes.

P#68084 2019-09-24 02:57

On my Pi Zero with Waveshare hat, I modified the line which reads:

sudo /home/pi/pico-8/pico8 -splore &

I removed the & from the end and added an additional line below this:

sudo /home/pi/pico-8/pico8 -splore

sudo shutdown now

By removing the & from the "pico8 -splore" line, the script starts pico8 and then waits for the application to exit before continuing. As the next line tells the Pi to immediately shutdown, simply exiting Pico8 safely shuts down the Pi.

As all three buttons on the Waveshare hat are used by Pico8, there is no option to use one as a safe-shutdown button. Using the method above, I can fire up the Pi, mess around in Pico8 and then safely shutdown.

Of course, you COULD simply SSH into the Pi, if near a computer running a terminal with SSH capabilities and safely shutdown from there, but YMMV.

Re: the MicroUSB sound adaptor, I guess it would work, assuming it can be recognised by Raspbian,

Which audio adaptor were you thinking of using?

P#68093 2019-09-24 10:14 ( Edited 2019-09-24 15:39)

I see. So basically, with those slight modifications, I'll be play a game and then when I exit the game, it'll immediately shut down. Nice.

As for the microUSB audio adapter, I was thinking a generic headphone adapter. What do you think?

P#68098 2019-09-24 15:06

I didn’t know that Escape brings the pause menu like Enter does! Three buttons are enough, this is great news :D

P#71264 2019-12-20 18:32

Great guide ! Thanks a lot It was easy to do.
I'll be trying to add a sound buzzer, I'll post any updates here. Too bad we need a keyboard to save a game locally, but it's great.

P#71418 2019-12-26 14:37

Awesome, I also made one of these, but I never finished my tutorial...


P#71420 2019-12-26 15:03

I find an open source case about waveshare 1.3inch LCD display (Same look like 1.44 inch)
Could someone change it to fit 1.44(128*128 pixel) display?
Basic case can use directly.

P#71726 2020-01-03 07:05

@Dounx I reached out to their support. I accidentally printed the 1.3" LCD display cap and the 1.44" unit fits perfectly into the cap but the screen is slightly misaligned. I'll update here when I hear more.

P#73174 2020-02-17 16:26

The source for sndio has changed. They now recommend the following:

git clone http://caoua.org/git/sndio
cd sndio
sudo make install

Also what tripped me up for 5 minutes: As you instructed us to move the pico8 zipfile to the pi's homefolder it's good to know that one should unzip it via ssh on the Pi itself, not on Windows. Otherwise the permissions will be messed up and pico8 won't start.

Many thanks for giving us these instructions. 😊

P#79571 2020-07-18 17:05

I think i'm gonna try this but with a custom made hat

P#81781 2020-09-13 20:48

Hey guys, hear me out... it´s not ideal but it could work, like @dglaude stated, the problem is that the screen is recieving 640x480 and it is outputing 128x128, but basically if we could "crop" the image with the correct values, we could make it work with something like this:


on /boot/config.txt

these are not correct values, I just copied it from here

I will work on this tonight, will let you guys know if it worked

EDIT: I just realized that the aspect ratio won´t change, it would just stretch the width...

EDIT2: overscan is not working for me, it just ignores whatever value I put there...

P#88354 2021-03-01 03:50 ( Edited 2021-03-01 04:07)

I did it boys

I have a shell script but it is downloading a fork of fbcp-ili9341, for now it will sit on my user, but I´ll see with the author of this repo how can we add it officially to his repository, with some kind of -square-screen flag or something for the build

Here´s the shell script:


P#88393 2021-03-02 01:47

You can pretty easily create a mobile handheld by adding the Pisugar 900mA battery module as you can see here, no cables:

The battery module also includes the needed standoffs. Now all we need is a case. Pisugar provides ready-to-use case designs for the Waveshare:

Buttons & Front:

Body & Back:

3D-printing these should cost no more than 10 bucks.

I'm thinking of a nice Gameboy Color Scheme, like grey for the buttons and yellow for the case. If you go down that route please post photos of your finished handheld here.

The buttons of the Waveshare display will be probably a lot more usable as well.

As for audio you could connect Bluetooth headphones to the device.

P#89096 2021-03-17 13:12

Hey, I have a question on how to mount the screen together(I don't wanna blow a fuse ;)), do I just put them together, one on top of each other and connect every pin that's above it? THANKS!!

P#123464 2023-01-02 00:58

Did this stop working? I get the following when starting pico8

SDL Error: The video driver did not add any displays

** FATAL ERROR: Unable to initialize SDL

P#136384 2023-10-25 17:52 ( Edited 2023-10-25 17:53)

I had all the pieces for this around my office so I tried to get the software running on an original Pi Zero and Waveshare 1.44" HAT. I followed the instructions closely, with the exception that I installed the newest versions of bcm2835 (1.75) and sndio (1.9.0).

I also get the same SDL error as cybernesto. I think the issue is with fbtft. I tried installing libsdl2 separately but that didn't work. I might try building the newest version from source. I read somewhere that libsdl2 did not have to be installed separately, but who knows. I'm running out of ideas.

Any suggestions welcome!

P#143790 2024-03-19 01:06

[Please log in to post a comment]