Log In  

EDIT: See the first reply below if you'd rather compile and use the native tool, which does seem more streamlined!

Hi, friends!

I just put Pico-8 on my Raspberry Pi for the first time and ran into problems getting my USB gamepads to work. Unfortunately, there's no ARM build for the General Arcade SDL2 Gamepad Tool, and I didn't want to bother with compiling the native helper, so I had to take this manual route. This will only take you a couple minutes.

The final SDL string will look something like this:

First, let's get the GUID.

This issue in the GameControllerDB repo tells us a little bit about the GUID structure in SDL 2.0.5+. It varies between operating systems, and so if you copied it from a different OS to Raspbian, this might be the cause of your woes (as it was mine)!

Open a terminal and run:

$ cat /proc/bus/input/devices

You should see your device listed in the output. We'll be concerned with the three circled values in the sysfs path, and also the version number above it. We'll come back to this output later for the name and input device path:

Convert the endianness of the three syspath IDs, and append the version. (Swap the first two characters with the last two and add four 0s). So for my gamepad:

  • 0003 = 03000000
  • 081f = 1f080000
  • e401 = 01e40000
  • 0110 = 10010000

and the end result: 030000001f08000001e4000010010000

I'm not sure if case matters here, but I went with all lowercase since I know it works.

I tried different names and SDL doesn't seem to care what you call the gamepad, but I went with the weirdo name I was provided, extra spaces and all:

Finally, let's get our mappings. Install jstest if you don't have it:

$ sudo apt update
$ sudo apt install jstest

And also refer to the Handler section in our original output to know which input device to pass to jstest.

For me, it's js0, so I'll pass /dev/input/js0 to jstest:

$ jstest --normal /dev/input/js0

The output looks like this, and is interactive. Each switch should flip when you push a button on the gamepad. Be sure to note the corresponding axis or button numbers.

Now that we know what button is what, we just need to add them to our config string. SDL assumes an Xbox-like gamepad layout. Together with the standard Pico-8 layout it will be mapped like this, but with the button numbers you collected from jstest:

  • a: ❎
  • b: πŸ…ΎοΈ
  • x: πŸ…ΎοΈ
  • y: ❎
  • start: pause/options menu
  • dpup: ⬆️
  • dpdown: ⬇️
  • dpleft: β¬…
  • dpright: ➑

Finally, put it all together! Here's what mine looks like, with funky spaces in the name and all buttons mapped: (note how the axes are expressed as -a1, +a1, -a0, +a0)

030000001f08000001e4000010010000,USB gamepad           ,a:b2,b:b1,x:b3,y:b0,back:b8,start:b9,leftshoulder:b4,rightshoulder:b5,dpup:-a1,dpdown:+a1,dpleft:-a0,dpright:+a0,lefttrigger:b6,righttrigger:b7,

Drop that into your sdl_controllers.txt, and it should map successfully. Fire up Pico-8 in a separate terminal window, and then check the log. You should see something like this towards the end:

If it was unsuccessful, it will look like this:

Good luck! πŸ˜ƒ

P#79379 2020-07-16 04:53 ( Edited 2020-07-28 08:34)

I recently had an issue with my Raspberry Pi build and wish this had been posted a few days sooner lol, I was using GPIO pins to set the controls.. for those looking for an alternative and because it took me so long to find the info, here's how I resolved my issues

This was setup and working on a RetroPie setup, but could be replicated on any Distro


Step 1

Get SDL2 and compile controllermap

cd /home/pi/RetroPie-Setup/tmp/build
wget http://libsdl.org/release/SDL2-2.0.7.tar.gz
tar -zxvf SDL2-2.0.7.tar.gz
cd SDL2-2.0.7/test
make controllermap
Step 2

Copy controllermap to its own folder

cd /home/pi/RetroPie-Setup/tmp/build/
mkdir controllermap
cp ./SDL2-2.0.7/test/controllermap ./controllermap/
cp ./SDL2-2.0.7/test/*bmp ./controllermap/
cd ./controllermap/
Step 3

run controllermap
type ./controllermap
(this will show info about your connected controller)
./controllermap 0
(where 0 is the joystick number we just found out)
[you should now see a picture of what looks like an xbox 360 controller]
press equivalent buttons that are highlighted on the screen
(if you need to skip any PRESS SPACE)
this will display your setup config for your joystick
030000001f08000001e4000010010000,USB gamepad           ,a:b2,b:b1,x:b3,y:b0,back:b8,start:b9,leftshoulder:b4,rightshoulder:b5,dpup:-a1,dpdown:+a1,dpleft:-a0,dpright:+a0,lefttrigger:b6,righttrigger:b7,
Step 4

Add your config file to PICO-8

sudo nano ~/.lexaloffle/pico-8/sdl_controllers.txt

add your config text in here
030000001f08000001e4000010010000,USB gamepad           ,a:b2,b:b1,x:b3,y:b0,back:b8,start:b9,leftshoulder:b4,rightshoulder:b5,dpup:-a1,dpdown:+a1,dpleft:-a0,dpright:+a0,lefttrigger:b6,righttrigger:b7,

save and exit

good luck

P#79440 2020-07-16 19:42

Nice! I didn't realize controllermap came with a GUI, this looks a lot more streamlined than I assumed! How long did it take to compile? (I did this on my 1B+ and compiling anything on it feels like it takes an eternity or two, lol)

P#79443 2020-07-16 19:54

took less time than downloading SDL2-2.0.7

it certainly is quicker if you want to add multiple controllers - and once you have it setup its always there

theres apparently a way to get it to output directly to a text file but I couldn't get it to work

./controllermap 0 > controller.txt

Here’s my device

P#79444 2020-07-16 19:59 ( Edited 2020-07-16 20:04)

lol, that's funny. anyone reading this, just go ahead and compile the native tool, i guess! πŸ˜…

P#79445 2020-07-16 20:07

@NaeD, that's neat! I assume that's powered by a Zero? I'm a huge fan of unique and weirdo handhelds and own a bunch of Ingenic-powered devices but haven't built any Pi-powered ones, mostly bc I think they're too bulky to shove in my pocket.

P#79446 2020-07-16 20:09 ( Edited 2020-07-16 20:10)

yeah a zero, only thing I need to do is upgrade the battery on it, but super happy i got PICO-8 on it it definitely makes it a unique handheld console

P#79447 2020-07-16 20:12

@NaeD Do you have any good tutorial on how to install a pico8 system on the GAMEPI20? I'm pretty new to this whole topic and I'd like to build a pico8 handheld with exactly the same device...

P#80082 2020-07-29 10:07 ( Edited 2020-07-29 11:55)


You can get an image for retropie here that saves you having to manually setup drivers for screen (which I wasn’t able to achieve) https://www.waveshare.com/wiki/GamePi20

Download your pico-8 raspberry pi version from your download page and copy to your raspberry pi

Then follow this guide https://www.lexaloffle.com/bbs/?tid=3935

You can skip the start and jump about halfway down to launching pico-8 from emulation station

I then had to do the controls part above to get my buttons working on pico-8

If you have any specific questions whilst setting up, drop me a message

P#80089 2020-07-29 12:23

Thanks for your reply. I've been fighting through the tutorials and came close to finishing my pico8 handheld (I hope so)...
I can launch the system from the emulation station menu and I can hear the pico8 start sound. Unfortunately the screen is stuck in this state:

I couldn't finish your controller configuration yet. In the first step the console shows the following message:

Cannot write to 'SDL2-2.0.7.tar.gz' (Permission denied)

Is the screen maybe going further if I successfully finish the controller configuration?

And two general questions came to my mind during the whole installation process:
Is the pico8-in-Retropie build at any disadvantage compared to a picopi build?
Is it really necessary to overclock the RasPi Zero to get a smooth running pico8-system?

P#80334 2020-08-04 09:54

I had a similar issue with starting my version of pico8 and think I resolved it by using ‘chmod’

In you pico folder use this command

Sudo chmod a+x /home/pi/pico-8/pico8

There’s no reason you pi won’t allow you to write to the SDL to that folder, might be worth checking your permissions for the folder your copying it to

P#80335 2020-08-04 11:10 ( Edited 2020-08-04 11:12)

@ongikong Check the log file it mentions for extra insight. Also try just launching pico8 from a regular terminal and see what happens. If that also doesn’t work, check the Pico-8 log file. Looks like your SDL issue might be a config thing, bc it’s trying to write a gzip/tarball rather than a text file? Also, as NaeD mentioned, try chmodding whatever directory it’s trying to write to. For overclocking, I’m not sure about Pico-8 on the 0 but I have a 1B+ which are equivalent specs and you definitely need to overclock for most emulators to run decent. I would suggest trying it at regular clock speed and increasing as needed via raspi-config so as not to void the warranty

P#80356 2020-08-04 20:16

About the Permission denied message: can you show us 1) the command you are running 2) the location where you are (run the pwd command) 3) the permissions for that location (run ls -hla)

P#80393 2020-08-05 20:37

Thanks for your answers. I think I found the problem: I connected the handheld to an HDMI monitor and everything worked fine! :-) So there might be a problem with the handheld display and the resolution PICO8 is running on my Retropie System? I tried to change the resolution by entering the configuration just after starting PICO8 but I couldn't find a resolution that's working...

The display of the handheld has a resolution of 320x240 pixels, but this isn't available in the video output mode list...

I'd be glad if someone can help! Maybe @NaeD who has the same device? Thanks in advance

P#80463 2020-08-07 16:17 ( Edited 2020-08-07 16:19)


Do you get any display on your gamepi20 screen? (Startup text, emulation station?)

P#80464 2020-08-07 16:28

Yes, everything works fine until I start Pico8 from Emulation Station...
I tried NES Emulation and this is also displayed correctly.

P#80469 2020-08-07 17:36


Then it’s not your screen that’s causing the issues

Just found this, make sure you did this too

Don't forget to make the script executable:

chmod a+x "+Start PICO-8.sh"

Worst case scenario is I could share some config files with you and you can compare for any differences

P#80474 2020-08-07 20:07 ( Edited 2020-08-07 20:13)

But with an external HDMI monitor connected to the handheld everything works perfectly!
So I'm pretty sure the handhelds display just can't handle the chosen resolution.
Where can I find the config file within retropie to set the resolution for Pico8?

P#80488 2020-08-08 03:05

@ongikong It's going to be in the ES config files. You can pass a custom resolution in the launch command, like the example given in the release thread. If that doesn't work, then the last stop on the checklist is a problem with DirectFB not offering a video mode your LCD likes, which you may be able to overcome with a custom config. Good luck! :)

P#80494 2020-08-08 09:34

I didn’t have to change any resolution when I set mine up

Like I said, happy to share any config files needed

P#80513 2020-08-08 15:58

Thanks, ridgekuhn! I tried to modify the ES config file. My entry for PICO8 looks like this now:

But unfortunately it didn't help :-(

I couldn't find any DirectFB folder on my system (under "/etc")?
Do I have to install it somehow?

The video output mode list from emulation station only gives me the following possibilities:

EDIT: OK, it works now! :-) I'm pretty confused but somehow the display shows everything correctly now with the settings: "640x480 @ 59Hz" ... I thought I already tested this resolution but it seems that i forgot that one. SORRY @All and thanks for your help!

P#80512 2020-08-08 16:02 ( Edited 2020-08-08 16:42)

@NaeD How do you shutdown your gamepi20? pressing start and select simultaneously doesn't bring me back to emulation station :-(

P#80516 2020-08-08 19:02 ( Edited 2020-08-08 19:02)


Mine loads straight into splore, there’s an option in there to shutdown

You can’t press certain buttons together, the grio pins have been wired up all wrong on the device, so no start and select

The other combo that doesn’t work is up/right

Until I get round to looking into this myself I don’t have a solution

P#80519 2020-08-08 19:31 ( Edited 2020-08-08 20:26)

@ongikong No worries, friend. If I'm not mistaken, u shouldn't need the runcommand.sh bit, I believe that script simply constructs a launch command to pass parameters to the RetroArch CLI, so is more or less meaningless regarding Pico-8 as it's not a libretro core. (Whatever video mode "works" is probably the one that doesn’t introduce conflicts between RetroArch/Pico-8?) You should be able to simply do something like this:

<command>/home/pi/pico-8 -width 320 -height 240 -splore</command>

By the same token, pressing select+start is a RetroArch shortcut, which is why it doesn't work in Pico-8 as it’s not calling the RetroArch API or it may not even be running at that point.

P#80524 2020-08-08 22:20 ( Edited 2020-08-08 22:48)

@NaeD - Oh, I was looking for that option in splore but couldn't find it - I was blind! Thanks!
@ridgekuhn - Thanks also for your useful hints. I will try that command line and gonna look what will happen... :-)

P#80559 2020-08-09 19:08

I just spent a while trying to get this working for my Anbernic RG351P, which can run the Raspberry Pi binary, and this guide is still good. It took me a minute to figure out that jstest reports the dpad as an axes while Pico-8 correctly recognizes it as a hat. If any RG351P owners happen to stumble across this post, the config below may work for you if your GUID is the same (if not, see above). You need an sdl_controllers.txt file next to the proper Pico-8 executable for proper Pico-8 games, and you'll also want one in ~/.lexaloffle/pico-8 for standalone binaries.

03000000091200000031000011010000,OpenSimHardware OSH PB Controller,a:b0,b:b1,x:b2,y:b3,start:b6,dpup:h0.1,dpdown:h0.4,dpleft:h0.8,dpright:h0.2
P#122662 2022-12-18 22:08

[Please log in to post a comment]

Follow Lexaloffle:          
Generated 2023-10-01 17:28:24 | 0.088s | Q:40