3D Printing Handheld Linux Pico 8 Soldering Tutorial

How to make your own Pico 8 handheld

My fanmade handheld. Banana for scale.

Hello there. I’m Grhmhome and today I’m going to show you how you can make your own Pico 8 handheld. This will be a long written guide, but hopefully, this will help people who want to make a Pico 8 handheld.

Before we start

Warning! This is for educational purposes only and this project will be using a Lithium-ion battery. Don’t try this at home if you aren’t experienced with soldering and/or working with Lithium-ion batteries as they can explode! This project is not for beginners. This project is not endorsed by Lexaloffle! There is no guarantee that you will successfully make a Pico 8 handheld by following this guide. If there are any errors in my guide, please let me know and I will make any changes to this post.

This is what the handheld should look like in the end if you follow this tutorial:

Powered off
Powered on

Parts list

What you will need:

  • Soldering iron
  • Solder and flux
  • Helping hands to hold the parts you are trying to solder. You don’t need helping hands, but it helps me out when I use them.
  • Hot glue gun for keeping the power switch in place

I personally use the soldering iron linked down below, and it comes with lead-free solder. It works great and comes with helping hands to hold the boards and wires you are trying to solder – YIHUA 926 III Digital Soldering Iron Station Kit

I used this flux pen and it works well. – Chip Quik CQ4LF Liquid Flux No-Clean in 10ml

You will need access to a 3D printer or 3D printing service or see if someone like a friend or family member could 3d print you the front shell, buttons, and backplate.

Parts list for the handheld (Amazon US):

  • – Fancasee (2 Pack) Replacement 3.5mm Male Plug to Bare Wire Open End TS 2 Pole Mono 1/8″ 3.5mm Plug Jack Connector
  • – ELEGOO 120pcs Multicolored Dupont Wire 40pin Male to Female, 40pin Male to Male, 40pin Female to Female Breadboard Jumper Wires Ribbon Cables Kit Compatible with Arduino Projects
  • – Gc Electronics Board Type: Prototype Board – 22-516 – You don’t need this exact one, just something to solder the buttons and wires to
  • – 120 Pcs QTEATAK 6 x 6mm x 5mm Momentary Tactile Tact Push Button Switch for PCB 4 Pin DIP Black
  • – 180Pcs M2.0 Series Laptop Screws Notebook Screws Set
  • – Waveshare 1.5inch RGB OLED Display Module
  • – Adafruit Powerboost 1000C
  • – Adafruit 328 Battery, Lithium-Ion Polymer, 3.7V, 2500mAh
  • – Adafruit Breadboard-Friendly SPDT Slide Switch [ADA805]
  • – UGREEN Micro USB 2.0 OTG Cable On The Go Adapter Male Micro USB to Female USB
  • – Plugable USB Audio Adapter with 3.5mm Speaker-Headphone and Microphone Jack

I use a 32 Ohm speaker that I bought on

You can use another 32 Ohm speaker, but it needs to be 1 inch (25.4mm) in diameter or smaller if you plan to use my 3d printable shell.

You will also need a Raspberry Pi Zero W so you can remotely SSH into the system. You could buy one on Amazon, but they tend to be more expensive as they come in a kit. Also, you will need a heatsink for the Pi Zero if you want your system to be less warm. You will also need wires. I forgot which ones I bought, but Adafruit sells wires

You can get a Pi Zero W with the GPIO pins pre-soldered making things easier, but if you are capable, you can just solder the pins on yourself.

If you don’t have one already, you will need a Micro SD card that is at least 16 GB in size for Retropie. I might recommend another Linux distro in the future, but I found that Retropie seemed to work well out of the box when installing drivers for the screen and controls.

Part 1: 3D printing

You will need access to a 3D printer or have someone print the files for you if you decide to use the same files. This project guide assumes you are using the files linked below.

If you decide to print this, you are free to use whatever filament or color that you own. Also, you have the choice of printing a 2 button version or a 4 button version. The guide assumes you are printing a 4 button version, but if you choose the 2 action button version, just tweak the settings in part 4 of this guide.

Part 2: Software and drivers

You will need to flash a micro-SD card with Retropie. Retropie can be found here:

The version I used in this project was v4.7.1, but later versions might be released in the future and some of the drivers might not work out of the box in later releases, but they should work in v4.7.1 just fine.

First, you will want to use a micro-SD card reader and flash the SD card. After that, you will want to create a blank file (no file extensions) called ssh and put it in the root of your /boot partition on the SD card. If you use Microsoft Windows, you can install Notepad++ and create one using that. This will allow you remote access to your handheld while you install the drivers, updates, etc. If you do not want to do this, you can plug in your Pi Zero to a keyboard and monitor, but I feel like that is way less convenient. This guide will assume you are connecting via SSH. Also, you will want to add a file called wpa_supplicant.conf – The Retropie website has a great guide on setting up that as this file will allow your Pi Zero W to connect to your wireless network

Part 2B

Once you power on your Pi Zero W and remotely connect to it via SSH, you will be prompted for a username and password. The default username for Retropie is pi and the password is raspberry. You will want to type in the following: ‘sudo apt install update’ without the semiquotes. You might be prompted to put in a password. This will update the package list for installing software. Next, you will want to install the drivers needed for getting the screen and controller working properly. You will want to type in ‘sudo raspi-config’ without the semiquotes and enable SPI interfaces.

You will then want to go into Retropie settings and download the GPIO driver in the packages menu ‘mk_arcade_joystick_rpi’.

You will also need to buy a copy of Pico 8 if you don’t have one already. It has a large library of games and should give you hours of fun.

What I did was copy the Raspberry Pi version of Pico 8 and placed it in the root of my /boot partition then when I remotely connect to the Pi, I copy that directory over to /home/pi using the command (without semiquotes) ‘cp -r /boot/pico-8 ~/’ or ‘cp -r /boot/pico-8 /home/pi’

After that, we will want to install the screen driver. I have a guide for doing that on the Pico 8 forums:

Part 3 – Soldering the controls

Crude diagram

Measure the inside of your handheld then break a large piece of perfboard that will fit on the bottom half of the console. Also, you will want to make some holes for screwing in the perf board to the front shell.

You will then want to line up the tactile pushbuttons with the front shell and place them on the perfboard. Make sure everything lines up or you will have to resolder the buttons that don’t line up. They don’t have to be 100% exactly lined up, but enough for when everything is done and assembled, that pushing on all of the 3d printed buttons will push on the correct buttons they are lined up with. Same with the d-pad, make sure the pushbuttons will line up with the d-pad. Solder them in place.

All 4 pins of each button should be soldered so they stay in place and not flex and break or fall out.

You will then want to solder a ground wire on only one corner pin of each of the tactile buttons. You will want to take all the ground wires that were soldered to each of the buttons and take the other ends of each of those wires and solder them together at the center of the board. It is highly recommended that you use color-coded wires.

Example of what which wires you solder to each of the buttons

I used yellow for the ground wires and a separate color for each of the buttons connecting to the GPIO. You will want to take one of your jumper cables and solder one end to the ground wires in the center, and plug the female end into a ground GPIO pin of your choice on the Raspberry Pi. What I did was cut one end of the jumper cable and soldered that directly to all the other ground wires in the middle of the board. You will then want to make sure you solder separate jumper cables to only one corner pin of each of the tactile buttons, but make sure you do not solder to the same pin as ground. Make sure these wires are all color-coded. The reason why you want things to be separate colors is to prevent confusion if a button decides to not work and to help troubleshoot if something goes wrong.

Part 4 – Controller driver

Once all that is set up, you will want to configure the controller driver. This will be important as you will not want the screen to use the same GPIO pins as the buttons and d-pad. Edit the file ‘/etc/modprobe.d/mk_arcade_joystick_rpi.conf’ without the semiquotes and add replace the text inside with this: ‘options mk_arcade_joystick_rpi map=5 gpio=16,5,6,20,19,-1,12,4,-1,13,21,-1’ without semiquotes. Make sure the jumper cables are using the same pins as in the modified config file.

If you plan on using only 2 action buttons, just put ‘ options mk_arcade_joystick_rpi map=5 gpio=16,5,6,20,19,-1,12,4,-1,-1,-1,-1’ without semiquotes instead.

If you are unsure which pin goes where on the GPIO, check this handy website out:

You can change which pins you want the buttons to use, but make sure you follow the button order Y-,Y+,X-,X+,start,select,a,b,tr,y,x,tl. If you don’t want to use a button, just put -1 as the value. Once you reboot your system, type in jstest /dev/input/js0 and test to see if your buttons are working. Make sure your jumper cable for ground is on one of the GPIO pins for ground or these buttons will not work. Also, if one of the buttons isn’t working, jstest will let you know.

Part 5 – Soldering the Powerboost 1000C

I used this guide for soldering the Powerboost 1000C from Adafruit The instructions there are perfect for this guide, but instead, I soldered 2 jumper cables, one for positive, and one for negative, and plugged the positive jumper cable into the 4th GPIO pin and negative into the 6th GPIO pin. Once everything is assembled, you can plug in your battery, flip the power switch and you should see the Pi and screen turning on.

Part 6 – Soldering the 32 Ohm speaker

Grab your mono jack and solder the red wire to one side on the back of the speaker and do the same with the black wire on the other side. I don’t know if polarity matters or not, but I believe you can solder red to the left pad and black to the right pad and visa-versa.

Part 7 – Autostarting Pico 8 and audio

If you didn’t add to /etc/rc.local: ‘sudo /home/pi/pico-8/pico8 -splore &’ without semiquotes from the screen tutorial on part 2B, you will want to do that now so you can boot into Pico 8 every time you turn on your console. Make sure you put that above exit 0. Also, plug in your USB audio adapter into your Pi Zero and plug in your speaker. I used this guide here for setting that up:

You will want to make sure volume is up to 100% as I didn’t add an amplifier. Once you are done, you will want to reboot your system and test all your components together. If everything is working correctly, you can move onto the final step

Part 8 – Final assembly

Make sure the 3d printed buttons are lined up and screw in the soldered perfboard from earlier with 2m screws. Also, screw in the screen. You will also want to make sure the speaker is put behind the speaker grille and use a hot glue gun to keep it in place. On the backplate, you should screw in the Powerboost 1000C and use a hot glue gun to keep the power switch in place. After that, you can start putting everything else in, such as the Raspberry Pi Zero. I used electrical tape on the bottom of the Pi Zero to prevent any of the pins from touching other components inside the console. After that, attach the battery and place it inside. Some things can be a bit snug, such as the USB cable and audio adapter, but once everything is in, turn on your system one last time to see if it will power on and that you hear sound. If everything is working, you can screw in the backplate to the front shell and you should be done.

The end

If everything works properly, you should be good to go. If there are any issues in this tutorial, please let me know, and I’ll correct them asap. Thanks for reading and have a wonderful day.

3D Printing Cad Handheld Pico 8

Version 1.0 has arrived

I’ve reached version 1.0. These pictures aren’t from version 1, but I made some last-minute changes. The power switch on the top of the console needs some hot glue to hold it in place better, but other than that, it is done.


  • Raspberry Pi Zero W – The computer that powers Pico 8.
  • Waveshare 1.5 inch OLED screen with a resolution of 128×128, the exact screen resolution for Pico 8
  • A mono speaker.
  • Powerboost 1000C charging board that recharges a Lithium-ion battery, but also lets people plug their consoles into a wall for long play sessions. This battery is much more powerful than 3 AA batteries so you can play on the go for much longer. Also, AA batteries are wasteful, especially if someone intends on playing with this console all the time.
  • Clicky buttons for the Dpad, pause button, and 4 action buttons. Pico 8 uses 2 action buttons, X and O, but I will see if there is a way in Pico 8 where you can use the top two buttons. Pico 8 apparently can access the Raspberry Pi GPIO, so I’ll look into that. The X, O, and pause buttons are keyed in, so they don’t rotate 360 degrees.

The final changes I made were making the screen hole 0.5mm larger and made the screw holes for the bottom of the Powerboost 2mm further down. Other than that, it is now done. I may add a venthole or vent strips on the backplate to make things cooler to prevent any overheating, but it is now pretty much done. Thanks for reading and have a wonderful day. The tutorial post should be out soon, depending on how busy I’ll be at work next week.

3D Printing Handheld Pico 8 Soldering

Performance issues fixed and plan B

I am realizing that AA batteries are a wasteful solution and that the battery holder is causing the screen to freeze randomly, so I’m switching over to rechargeable batteries using a Adafruit Powerboost 1000C. I don’t see a short and there aren’t any bridged connections causing a short. When I plugged in the Pi Zero to a wall outlet, it runs perfectly fine. I did a test connection with the powerboost 1000c and the Pi Zero powers up just fine. Not only that, people will be able to plug in their system to a wall outlet for long play sessions or to charge the battery at home then play on the go. Portable power that should last much longer. I will update once I 3d print the new shell today.

3D Printing Cad Handheld Linux Pico 8 Soldering

My Pico 8 fanmade handheld

The first beta version of my handheld.

Project background

Hello, I’m grhmhome and this is my first soldering project from scratch. I’m teaching myself how to solder and wanted to do more projects so I could learn more. I’m a fan of retro-gaming and enjoy the Pico 8 platform. What is Pico 8? It is software that replicates the look and feel of an old computer or game console with fake limitations. It is available for Mac, PC, Linux, and the Raspberry Pi (the hardware we are going to be using). If you are interested in learning more, check out their website here. The best part is that you don’t even need to buy Pico 8. You can play Pico 8 games using a web browser, but if you decide to make your own Pico 8 handheld, you will need to buy a copy.

Project Goals

My goals for this project were the following:

  • The console was to be designed for Pico 8 and Pico 8 only using a Raspberry Pi Zero or Zero W. It was intended to boot directly into Pico 8 and have a screen meant for Pico 8.
  • The console was to be designed using readily available parts such as a Raspberry Pi Zero W, generic buttons, perfboard, etc.
  • The project is meant to be a beginner friendly project so people who are new to soldering could use this as their first project if they wanted to.
  • The console is meant to be comfortable to hold for longer play sessions and the buttons should also feel great to press.
  • The project cad files will be open source so people can fork, modify, or do whatever else they want with the cad files. I will not provide cad files with the Pico 8 logo or any Lexaloffle branding as this project isn’t affiliated with their company.

The design work

The first design

I fired up my favorite cad software and got to work in making a basic handheld design and had to decide on the screen resolution, the number of buttons, and overall shape. Originally, I wanted a semicircle shape, but realized, that it wouldn’t work, due to the parts used, so I went with a rectangular shape with rounded edges instead. After I bought some of the supplies I would need, I measured the screen bezel, screen PCB, speaker diameter, Raspberry Pi Zero, and AA battery holder, as I needed to see how thick the console was going to be and had to make sure everything would fit.

After that, I printed a prototype shell to see if the button spacing was good enough. I was able to subtract another 5mm from the overall thickness once the parts arrived and found I had room to spare. Shrinking the handheld by 5mm made the console less bulky and more comfortable to hold. I believe comfort should be an important factor when making consoles.

The first printed shell prototype

After I printed the first prototype, I had to figure out where I want the battery holder to be. That was going to be the largest component and I needed to make sure it wasn’t going to be in the way of any of the other components. I ended up deciding on using the back-plate to hold the battery holder and be where the battery door would screw in. I added 2mm screw holes for the front half of the shell and added screw holes for the back plate. The battery holder would be on the left side of the unit away from most of the components.

Battery holder design prototype

The screen

Once the screen arrived, I had to learn how to make it work with the GPIO pins. I learned a lot about display drivers and had to scour the internet looking at ways to get my display to work properly. I opted for one display driver, but I couldn’t get that to work and since SPI was all new territory for me, I spent hours looking up other ways to get things to work, such as use another display driver, and edit source files. I found a display driver that would work perfectly after compiling, I finally got the display to work, well, sort of. The screen was displaying a bunch of glitches, and after recompiling another time, it finally worked perfectly.

Waveshare OLED 128×128 screen

The controls

Now, I was able to work on soldering the controls. I ended up buying some tactile buttons, a perfboard, and got to work. This was my first time ever using a perfboard, as my previous project involved me soldering PCB’s from a kit, and I had to research how I was going to get everything to work, so I settled on placing all the buttons in the right positions, followed by soldering each button to a wire that was soldered to a central ground jumper cable, and that ground jumper was connected to a ground pin on the gpio. The rest of the buttons also had a jumper cable soldered to them. After that, I installed a gpio controller driver, and one button refused to work. I soldered a new button, and it still didn’t work, so after replacing the jumper cable, it finally worked.

After I bought the last of the supplies needed, I soldered a 32-ohm speaker to a mono cable. I originally thought I ran out of space on the gpio, so I opted in using a usb adapter. The only issue is the sound is a bit quiet, so I might try an amplifier and use one of my 8ohm speakers, so I can have much louder audio, but for the time being, it seems to work for now.

Problems started to form

I made sure that Pico 8 would auto start when you first start up the machine and made sure the system wouldn’t boot into Emulationstation, but I quickly ran into a problem. Something was making Pico 8 think I was constantly pressing the up button. I thought, strange, this isn’t happening in Emulationstation, but had to figure a solution and fast if I wanted this project done by Sunday. What I did was removed all the jumper cables and connected them to the Raspberry Pi via SSH. Fortunately, I realized it wasn’t the buttons, or the screen causing this, but it was due to the controller gpio driver. Apparently, one of the pins, I think pin 11 was being used by both the screen driver, and controller driver, so I replaced the gpio controller driver with something that would allow me more freedom of which pin I could use, and the problem was gone.

After I reconnected everything, I found one more issue, the system performance was taking a hit, and I’m assuming it’s due to a driver conflicting somewhere, or maybe it’s something causing the hardware to throttle, but for now it at least ‘works’.

I then went back into the cad software and put in the final screw holes and was able to print the console, buttons, and assemble the first beta version. I found some glaring issues such as the buttons freely rotating so I’m making new buttons that will not rotate and they will only move forward and back.

The end

I want to thank the Pico 8 community for being supportive and having an interest in my project. The tutorial post should be available soon. I will not go over how to solder, but I will give a parts list, post links to the cad files and STL files, and will show you how to get the gpio drivers to work. The files are available here on Thingiverse:

Have a wonderful day.

Handheld Soldering

Soldering fun

I finally finished soldering the buttons. It was my first time soldering a perfboard. I had a few issues though. First, I had to reposition a tactile button then I had to replace one of the buttons because Retropie wouldn’t recognize the button and then I replaced a jumper cable. Now the buttons all work. When the speaker arrives, I’ll finish the last bit of the soldering and test it out. Have a great day.

Cad Handheld Pico 8

The battery compartment

I’m using a battery holder that will use 3 AA batteries. I had to create a door and make it simple to remove. On the backplate of the shell, I also made a housing for the battery holder. I’m thinking of making the backplate mount all the electronics, but the front part of the shell will have holes that will allow you to attach both parts of the shell together.

I will probably smooth everything out everything and will update you on this project once I start on sound and the controls. Have a good rest of your day.

Handheld Linux Pico 8

The screen now works

This 128×128 OLED screen looks better off camera. The game featured is Pico Snail by: GiantLNT –

This part of the project took me a whole day just to get to work. I had some help on the Pico 8 Discord channel and scoured the internet looking for information on how to get this screen to work properly. Now, everything seems to be working on the display, but I might find ways to tweak the performance a little more.

The tutorial on how to get the screen working on your Raspberry Pi Zero

The tutorial I created can be found here

The parts I used:

Raspberry Pi Zero W with GPIO headers pre-soldered from Adafruit

1.5inch RGB OLED Display Module 128×128 16-bit High Color SPI Interface SSD1351 Driver – From

1.5inch RGB OLED Display Module 128×128 16-bit High Color SPI Interface SSD1351 Driver – Directly from

3D Printing Cad Handheld Pico 8

First shell prototype

Hello again. I 3d printed a prototype of my shell to see how the console will feel in the hands and if the parts will fit in properly. The parts will fit properly and I have some wiggle room to shrink the shell down so the console will be around the same thickness of a Gameboy. +/- a couple of mm.

The 128×128 screen has arrived so I can try to get that part working and see if Pico 8 will behave properly with that display.

Here are some pictures of what the current prototype looks like.

The first prototype does feel great in the hands and the d-pad and button spacing feels perfect, but it is too thick to hold. Fortunately I’m going to shrink it down 5mm. I will also change where the battery compartment will go and that might let me shrink it down further. I will work on the screen hopefully today and will update the blog soon. Have a wonderful rest of your day.

3D Printing Cad Handheld Pico 8

Update #2

Hello again. Here is another update to my Pico 8 fan handheld project. I have made the front and back rounded. There is no name for this project yet, but I’m open to suggestions. Some of the internal components have arrived in the mail, but the display I’m going to use will arrive soon.

The shell of this device will be 38mm or roughly 1.5 inches. This is temporary until I figure out how I want to house everything. After that, I can shrink the handheld so it wont be so bulky.

The display.

The display is a 128×128 resolution screen from Waveshare. It is the Waveshare 1.5inch RGB OLED Display Module. The part number on the ribbon cable is ssd1351u3. It has a SPI display interface and there are repos on Github that have what I need, the ability to copy the frame buffer. Once I get the display working properly, I will work on sound, then work on the button inputs. I’m thinking of using tactile switch buttons for the action buttons; pause button, and dpad.

3d printing the prototypes

I have a Anycubic Mega Zero 3d printer that I will use for making prototypes. It has a 220 x 220 x 250 mm build area, which is more than enough for this project. The first prototypes will be to see how the handheld will feel in the hands and see if the button spacing is adequate enough. Once most of the parts arrive, I will see if the internal parts will fit properly (they should) and where I want to mount all the components. Once everything is done, I will add the screw holes and create a battery door. I will post pictures of the prototypes soon.

This is what the handheld looks like in Cura, the slicer program I use for 3D printing. I’ll be printing at 0.3mm layer height and it should take me 3 hours and 25 minutes for the first prototype to finish printing, as long as my printer doesn’t have any issues.

If all things go well, I will post an update on the 3d printed handheld prototype. Have a wonderful day.

Cad Handheld Pico 8 Soldering

Pico 8 inspired fan handheld

Hello there. I’ve been working on a Pico 8 inspired handheld. This is what I’ve been working on for 2 days. It is a bit bulky, but I plan on resizing everything once I figure out what can all fit inside adequately. This is a work-in-progress project and isn’t a project endorsed by Lexaloffle. It is entirely a fan project. I will upload the stl files and parts list on my Thingiverse page as I get further along with this project. The fan console will have 4 action buttons, a pause button, a d-pad, a speaker, and a 128×128 resolution screen.


I wanted to make a custom handheld for the Raspberry Pi Zero W for quite a while, where I could use a knock-off SNES controller inside, but then I decided on creating a niche project instead. I love the Pico 8 platform as I love retro consoles and computers from the 80’s to early 2000’s.

Why 4 action buttons? The Pico 8 fantasy console uses two action buttons. X and O, but I thought some games might use more than two buttons, so I felt like 4 was perfect.

I will update this blog as I continue this project. Have a wonderful day.