Connect to the Internet

To continue setting up the Pi, it will need to be connected to the internet. This is for installing updates and running scripts that need to be downloaded. The Raspberry Pi Zero that came with the AdaBox doesn't have WiFi capabilities and thus a software image was originally provided. You can get it online using an Ethernet Hub such as this one:

Optionally, you can use a Pi Zero W or Pi Zero 2 W to make use of WiFi.

Burn a RetroPie Image

Here's the quick-start for people with some experience:

1. Download the latest Raspberry Pi Imager to your computer
2. Install RetroPie onto your SD card. You can select it through the Imager under Emulation and game OS → RetroPie
3. Plug the SD card into the Pi
4. You'll need to connect an HDMI monitor and keyboard for the initial setup, so this is a good time to do it.

Plug in power to the Pi. You will see the green LED flicker a little. The Pi will reboot while it sets up so wait a good 10 minutes.

Configure Networking

Before you can update and install dependencies, you will need to be connected to a network.

If you have an Ethernet cable plugged in, you should be good to go. If you are using the Pi Zero W or Pi Zero 2 W, and want to use WiFi, you can enable WiFi through raspi-config below.

Enable WiFi

Enable SSH

We recommend enabling SSH to make typing in commands much easier. SSH stands for Secure Shell and allows you to remotely type in commands as well as send files. To do this, you'll want to be sure SSH is enabled on your Pi.

Once that's finished, exit out and reboot your Pi.

To SSH into your Pi, type ssh [email protected] from a terminal program on your computer. 

The default password is raspberry. Once you get to the command prompt, run the command passwd to change the Pi password to a more secure password. Record the password if you need to.

Fix the Mirror Location

Because the RetroPie image is based on Raspberry Pi OS running Buster, which an older version, the software mirrors that it points to are no longer active. Without that, the software dependencies are unable to download. To fix it, enter these commands:

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
echo 'deb http://legacy.raspbian.org/raspbian/ buster main contrib non-free rpi' | \
sudo tee /etc/apt/sources.list

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
echo 'deb http://legacy.raspbian.org/raspbian/ buster main contrib non-free rpi' | \
sudo tee /etc/apt/sources.list

Update Your Pi and Python

Run the standard updates:

sudo apt-get update
sudo apt-get -y upgrade
sudo apt-get install -y python3-pip

sudo apt-get update
sudo apt-get -y upgrade
sudo apt-get install -y python3-pip

and upgrade setuptools:

sudo apt install --upgrade python3-setuptools

sudo apt install --upgrade python3-setuptools

Setup Virtual Environment

While the older kernel (and Python version) doesn't require a Virtual Environment, it's still good practice to set one up. You can find more information in the Python Virtual Environment Usage on Raspberry Pi guide. To Install and activate the virtual environment, use the following commands:

cd ~
sudo apt install -y python3-venv
python3 -m venv env --system-site-packages

cd ~
sudo apt install -y python3-venv
python3 -m venv env --system-site-packages

You will need to activate the virtual environment every time the Pi is rebooted. To activate it:

source env/bin/activate

source env/bin/activate

To deactivate, you can use deactivate, but leave it active for now.

Install Dependencies

The installer scripts are in Python and need a few dependencies. Be sure your Virtual Environment is active and run these commands:

cd ~
pip3 install --upgrade adafruit-python-shell

cd ~
pip3 install --upgrade adafruit-python-shell

Joy Bonnet Installer

The Joy Bonnet Installer is a script that installs a service for the Joy Bonnet to emulate a keyboard. Run these commands to install support for the buttons and joystick:

wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/joy-bonnet.py
sudo -E env PATH=$PATH python3 joy-bonnet.py

wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/joy-bonnet.py
sudo -E env PATH=$PATH python3 joy-bonnet.py

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). This will take effect on the next reboot.
• 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!

Programming with Python

Blinka is the program we use to allow most of our CircuitPython libraries to work through Python. Using Blinka allows you to write your own programs to make use of the Joy Bonnet. You can find the installation procedure on the Installer Page of our Blinka Guide. This will guide you through getting Blinka onto your Pi. In order to prevent GPIO conflicts, you may need to stop the Joy Bonnet Service.

Starting and Stopping the Joy Bonnet Service

If you have run the Joy Bonnet Installer, you can stop the service with:

 systemctl stop joy-bonnet.service

This will stop the service until you either restart it or reboot the Pi. To keep it from starting up automatically, run:

systemctl disable joy-bonnet.service

You can re-enable it by replacing disable with enable. You can also start it back up by using start or restart.

Support Your Joy Bonnet

Thanks to a hot tip from Adafruit Forums member cvadillo, you can take the extra piece of plastic from the case that you removed over the header pins, and use that to support your Joy Bonnet. Just slide it under the Joy Bonnet like so:

And now you are ready to hammer away on those buttons without worrying about causing stress on your hammer header connection.