Log In  



Read all steps before proceeding with the installation. Feedback is appreciated!

  • If you want to avoid the headache of Step 4, I recommend using a Pi or other Linux computer to write the installation image to the SD card! It can be the same Pi you use for the Lite installation, you just need to switch SD cards to change OSs.

Hello everyone,

I haven't seen any tutorials for doing exactly this so I thought it would be helpful if there was a guide for anyone who specifically just wants a little portable machine that launches PICO-8 after booting, and without using Retropie or a desktop environment. This installation won't have a super fast boot like PICOPi (https://github.com/keints/picopi) but it will have online functionality and will be a great starting point for a physical fantasy console project.

The whole process takes about 45 minutes to complete

Things you will need:

  • The latest PICO-8 for Raspberry Pi zip: https://www.lexaloffle.com/games.php?page=updates
  • Raspberry Pi (any model) setup with a display and keyboard
  • SD card or microSD card (depending on the model of Pi) at least 16GB
  • SD card reader

  • Windows/macOS/Linux computer with internet access (this can also be a Pi, in fact it can even be the same Pi if you have two SD cards!)

    • Optional: USB thumb drive to transfer files from your PC to the Pi
    • Optional: Second SD card to install a desktop version of Raspberry Pi OS to transfer files to your "Lite" installation

Step 1: Download & install the latest Raspberry Pi OS Lite image


You can get the latest Raspberry Pi OS installation images here: https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-32-bit

  • We'll use the "Lite" image, but this tutorial also works with the desktop versions if you change the boot option to the command line

Follow these instructions to write the "Lite" image to your SD card: https://www.raspberrypi.com/documentation/computers/getting-started.html#installing-the-operating-system

  • If you flashed the image with a Linux PC or a Raspberry Pi, the SD card should be automatically mounted. You can copy your PICO-8 zip to the rootfs partition's /home/pi/ directory now and skip Step 4 later!

Step 2: Setup Raspberry Pi OS


If you are using HDMI for your display, make sure your Pi is connected to your monitor before powering the Pi on!

When your new Raspberry Pi OS installation boots for the first time, it will generate SSH keys and then reboot shortly after. You will then be asked to select your keyboard layout. If you don't see yours, use the up and down arrow keys to select Other and press Enter. A complete list will be displayed. Select an option and press Enter.

  • If your keyboard has an English (US) layout, be sure NOT to pick the default English (UK) option or your keys will not be mapped correctly! This can be changed again later with the raspi-config tool.

Next you will be asked to create a username and password. After creating these credentials, the system will prompt you to log in. Once you've logged in, you should see the command prompt below

[username]@raspberrypi:~$

Type sudo raspi-config and press Enter. The screen will turn blue and a menu will be displayed.

(If you are using a wired internet connection, you can skip the following paragraph)

  • The option 1 System Options should be selected. Press Enter to confirm the selection. Now the option S1 Wireless LAN should be selected. Press Enter and use the up and down arrow keys to select your country. A dialog box will confirm your selection, and you will next need to enter your Wi-Fi SSID and password.

Once you are connected to your network, select 8 Update on the menu and press Enter.

After the raspi-config tool has been updated, you should be automatically returned to the first menu. Select 1 System Options again and then S5 Boot / Auto Login. Select B2 Console Autologin and press Enter.

  • This is also a good time to setup your locale and timezone should you choose to, but it isn't necessary for the purpose of this tutorial.

Press the right arrow key two times and Finish should now be highlighted orange at the bottom of the menu. Press Enter. If you are asked if you want to reboot the Pi, select No.

Step 3: Update Raspberry Pi OS and install PICO-8 dependencies


You should be back at a command prompt again that says

[username]@raspberrypi:~$

Type sudo apt update and press Enter. This command checks if there are any newer versions of your installed software packages. If any packages can be upgraded, you can use the command sudo apt upgrade to download and install them. Upgrading packages may take several minutes.

Once you've done that, type sudo apt install libsdl2-dev pulseaudio and press Enter. A big list of additional packages that must also be installed will be displayed. Press Enter again. This process will take several more minutes to complete.

When the command finishes, the prompt will return. Type reboot and press Enter.

  • If you are taking your SD card out of your Pi to transfer your zip to it in the next step, type shutdown now instead of reboot and wait for the flashing green light on your Pi to shut off completely before removing the card

Step 4: Copy and extract your PICO-8 zip to your Pi user's home directory


The zip goes in the directory /home/[username]/ on the rootfs partition of your SD card.

There are several ways you can go about completing this step. Here are three:

  • 1) SSH This is probably the most optimal way to copy your zip over if you don’t have a Linux computer or an additional Raspberry Pi OS Desktop installation, though it is a little more involved. You can find instructions for copying files to the Pi via SSH here: https://www.raspberrypi.com/documentation/computers/remote-access.html#ssh

    • The Pi is internet-connected at this point so ensure that your password can't be easily brute-forced! I recommend disabling SSH again after copying over the zip

  • 2) USB drive You can learn how to access a USB thumb drive via the command line here: https://www.raspberrypi-spy.co.uk/2014/05/how-to-mount-a-usb-flash-disk-on-the-raspberry-pi/

  • 3) Another Linux installation If you have a Linux OS with a desktop (or a second SD card for your Pi with Raspberry Pi OS Desktop), you can just insert your Raspberry Pi OS Lite SD card into a card reader and just click and drag the zip onto it using a file explorer.

You can use the unzip command on the Pi to extract the zip once you've transferred it.

Step 5: Create a startup script


Now that we have our PICO-8 zip extracted to our home directory, we can create a script that executes the appropriate binary after logging in, which should happen automatically after boot

At the familiar command prompt, type nano startpico8.sh and press Enter. This will launch a text editor called nano with a new file open called startpico8.sh. Add the following two lines:

echo "Starting PICO-8..."

./pico-8/pico8_dyn

  • Optionally, you can boot straight to SPLORE with this line instead:
    ./pico-8/pico8_dyn -splore

NOTE: On older Pi models, you may need to add a line that just says sleep 15 above the echo "Starting PICO-8..." line to allot time for startup processes to finish. This unfortunately adds 15 extra seconds to the startup, so only add the line if you can't get PICO-8 to launch correctly after login!

Press Ctrl+S and then Ctrl+X. You should be back at the command prompt.

Next type chmod +x startpico8.sh and press Enter. Then type ./startpico8.sh and press Enter again. If everything worked up to this point, PICO-8 should startup!

Press Ctrl+Q to shutdown PICO-8, then type nano .bashrc and press Enter. Press and hold the down arrow key until the cursor reaches the last line of the file. Press Enter to create a new line, then type ./startpico8.sh and press Enter. Now press Ctrl+S and then Ctrl+X.

Back at the command prompt, type reboot and press Enter. After the Pi boots, it should immediately login and launch PICO-8! :D

Troubleshooting

  • No sound
    If there is no sound, go back to the raspi-config tool and select System Options and then Audio and make sure audio is being routed to the correct output device.

  • The command line doesn't show the usual prompt or display PICO-8 after logging in
    Usually this is because PICO-8 starts and bash runs in the foreground. Try pressing Ctrl+C and wait to see if the command prompt appears after a few moments. I've found that adding the sleep 15 command to the first line of the startup script avoids this issue. If anyone knows what causes it any info would be appreciated!

  • A number of SDL-related errors are displayed, but no PICO-8
    Happens because PICO-8 starts too early after login. Press Ctrl+C to terminate the process and try adding the sleep 15 command before your echo "Starting PICO-8..." command in the startup script.

A few notes

  • While the goal is to effectively create a physical fantasy console, remember that the Raspberry Pi is still a real computer with an OS that is connected to the internet. It's good to upgrade packages every so often to fix issues and keep your system secure. If you've completed this tutorial, you should now know how to check for updated software packages and how to install them. If this sounds like a hassle, I would recommend considering keeping your installation offline. Or you can learn how to automate the process of keeping your system up to date. The world is your oyster!

Hope this was helpful! If this is your first experience with a Pi or Linux, I can promise you it isn't normally this much work to get an OS setup. You can always install the desktop version of Raspberry Pi OS (or any other OS) and use it just like you would use a Windows or macOS computer. I hope you'll continue to explore and learn how Linux works, maybe you can write a better guide than this one! See if you can figure out how to get the Pi to shutdown by itself after shutting down PICO-8 ;)

9
2

one note: no need to use sudo to run chmod on a file you own! also, the goal of chmod +x is to let us run a script with ./start-pico8 rather than sh start-pico8! this is great because it means you don’t need to know if an executable is a shell script, a python program, a native binary: it’s just an executable and you run it like all executables :]

but are you sure you can run reboot without sudo?

Thanks for teaching me this @merwok! I just assumed you couldn't run a script without putting sh beforehand, I'll update the guide. As for the reboot command, I've just always typed reboot and it has worked, should I be doing it with sudo ?
1

no, the rule is to only use sudo when necessary! if reboot alone works it means the system is configured to allow the pi user to control power, which is good and convenient

Thanks for the info. I'm still figuring out a lot about how to use Linux OSs, I'm always happy to learn new things about good practices and how it all works

Thanks for this. This guide works flawlessly with my Raspi 4 and official Raspi touch screen. What else do I need for thhis to boot up using the composite out?



Hey @KidColeco! Glad the tutorial worked out. I don't have a Pi or TV with composite input to test it right now but I'm pretty sure you can find the toggle for composite out in the raspi-config tool somewhere! I'll edit this comment after I can check.
1

This tutorial worked with my Raspberry Pi 3B+ as well. When I switch to composite out within raspi-config I can see the rainbow color screen and then all black. It works fine connected to my official Raspi touchscreen. I can't get it to work through composite.



one note: libsdl2 is needed, not libsdl2-dev

(edit: other libs too… will look for more info when I get a chance to boot my raspi)

Hey again @merwok, I can't find a package that's named just libsdl2 on Raspberry Pi OS bookworm repos. However, there is a package named libsdl2-2.0-0. Following this guide but replacing libsdl2-dev with libsdl2-2.0-0 will result in a message that says ** FATAL ERROR: Unable to create window, but if you subsequently install the packages that libsdl2-dev installs PICO-8 boots right up. I'm not really sure what is fixing the issue but I can't get it to work without libsdl2-dev. As for the composite out, I'll have an opportunity to investigate that this weekend and see if there's something I'm missing that would enable that functionality.

This is awesome! I created a similar guide for auto-boot Pico8 on Ubuntu 22.04 (laptop): https://www.lexaloffle.com/bbs/?tid=142426

This guide was a great help for getting my pi 3B+ running! Alas... now I too am stuck trying to get the composite out working. HDMI is fine. Composite shows the linux command line text on boot just fine, but once pico-8 boots, composite becomes black screen whilst sound continues to work. I'm running the pico_64 version. I guess I can try other versions, and older pico-8 builds. Did any of you find a solution for composite that works? @gfd @merwok

Hey @dannycisco, I did find a resource (https://www.raspberrypi.com/documentation/computers/config_txt.html#composite-video-mode) that explains how to enable composite video but I haven't tried it myself. I moved since writing this guide and don't have any composite cables for my pi at the moment so I need to order one. Let us know if you get the black screen figured out!

Thanks for the tuto
I followed up to installing pico-8’s dependencies then just added ”/home/pi/pico-8/pico8_dyn -splore” to /home/pi/.bashrc
I’m on a 3a+ btw
1

thanks @gfd no luck yet. I think I might start again with a 32bit OS...

UPDATE:
I got it working.

I found it easier to troubleshoot composite first, before installing pico-8 dependencies.
The problem was a black screen after the raspberry logo, which turns out to be a problem with the KMS driver, so switching KMS to FKMS in the config.txt solved it.

Once I got the comandline working with composite, then i continued the rest of the setup via the TV out

I used the 32bit legacy lite OS... (but Fake KMS is probably all it needed)



[Please log in to post a comment]