Software installation for the Joy Bonnet requires an internet connection. That’s a frequent topic already covered in other Pi getting-started guides, so we’ll assume here that your Pi is already booted and networked, running Raspbian or a gaming-ready OS like RetroPie. (RetroPie is what we use, and recommend!) RetroPie has a nice First Installation guide

You can set up the controls however you like, its easy to change them up later. Just get logged into RetroPie, and setup WiFi. Then get into a terminal either on the HDMI console or by ssh'ing in.

You may find this easiest if ssh is enabled on the Pi, and then log in with a terminal app. This lets you copy-and-paste the commands that follow, as they’re very exact about spelling.


Enter the following few lines to install support for the buttons and joystick:

cd ~
sudo apt-get install python3-pip
sudo pip3 install --upgrade adafruit-python-shell
sudo python3

When run, this script will offer a couple of options:

  • Disable overscan? If you answer “Y” this removes the black border around the screen (common on HDMI monitors). Takes effect on next boot.
  • Install gpio-halt utility? Linux-based systems like the Raspberry Pi don’t like it when you just switch off power…there’s a specific shutdown process, else the SD card may get corrupted. The gpio-halt tool lets you add one more button between ground and any unused GPIO pin to initiate an orderly shutdown. Gaming OSes like RetroPie already include a shutdown command among their menu options, so you probably do not need this, unless you want a dedicated button for it.

When the script finishes you’ll be asked whether to reboot. Answer “N” if you plan on installing other software. Either way, sudo reboot when done to get the joy bonnet software activated!

That's it! The script to generate keycodes is now installed and will be run every time the Pi boots

Once RetroPie has restarted, go to the MENU  and step down to CONFIGURE INPUT and select it to re-start the input configuration. The left joystick can be used for up/down/left/right. The right buttons are A B X Y. Middle buttons are Select and Start as labeled. Then you get two more buttons you can set up as left/right shoulder or trigger buttons.

Note that pressing Select+Start will quit out of games, other than that the controls are used in the emulators by generating 'key presses' - see below for how to change the keypresses!

Although the Joy Bonnet has an analog stick, the software installed above makes this act like a digital 4-way stick emitting key presses. This is on purpose and by design, as Retropie on a single-stick controller like this expects digital inputs.

Advanced Usage

If you need to change the key assignments: edit the file /boot/ say with sudo nano /boot/

Near the top of the code you’ll see this table:

'#' lines are human comments and do nothing for the code. The first eight actual elements in the table correspond to the button inputs, while the last four are the joystick directions.

This guide was first published on Mar 22, 2017. It was last updated on Mar 08, 2024.

This page (Install & Use) was last updated on Mar 08, 2024.

Text editor powered by tinymce.