# AdaBox 005

## Introduction

https://www.youtube.com/watch?v=KXWd9noYqxg

[If you're looking to subscribe to AdaBox, click here!](https://www.adafruit.com/adabox)

# Hi there!

If you're here, it's because you were given the gift of electronics with an AdaBox! You are a beginner who is getting started with your AdaBox or you just want to relive what it's like being a beginner at electronics again. But most of all, you want to learn how to build and make stuff with electronics! ([If, rather than learn electronics, you'd like to look at pictures of cats instead, please check https://www.adafruit.com/galleries/cats-of-engineering](https://www.adafruit.com/galleries/cats-of-engineering))

And, you're in luck: there's _never_ been a better time.

Gone are the days where you need thousands of dollars of equipment and lots physics/math background. Nowadays, if you want to learn to work with electronics, you can jump right in for $100 or less, and any sort of computer. And we're talking about learning _a lot_ of electronics - from the basics of analog to the complexities of embedded Linux. With a good pack of parts, you can build a base of knowledge that will take you from your first blinking LED to someone who can start prototyping and inventing custom products.

# Who is this for?

Anyone with a computer they can install software on, with a TV and a love of video games! That's pretty much the minimum. Remember, this guide is specifically for people who have purchased or received an AdaBox subscription.

**You don't need to know a lot of physics or math** , and just like an Art Degree isn't required for making art and being creative, **you _don't_ need to have a computer science degree**. It helps if you're comfortable using computers but that's a skill most people pick up through life.

**If you know how to solder or use Raspberry Pi already - great! If not, don't worry, we'll teach you enough to be dangerous.**

# Who **isn't** this for?

While you can follow along without an AdaBox, it will not make as much sense unless you have _all_ of the components and more which either came as a gift or purchased yourself - remember, the goal is helping beginners!

If you're an expert, please visit our hundreds other tutorials and jump right in at [learn.adafruit.com](learn.adafruit.com)

# Who are you?

Great question. This is me:

https://youtu.be/VDIwnLllLZQ

I'm Ladyada, and I love to teach people how to build stuff and how they can be creative with technology.

So, are you ready?

Let's do this thing!

# AdaBox 005

## Unboxing AdaBox 005

You've consumed four AdaBoxes - the equivalent of a delicious, nutritious, meal of DIY electronics. And now it's time for dessert.

Pour yourself some coffee (or a nice cold glass of milk) because it is finally time for Raspberry Pi.

![](https://cdn-learn.adafruit.com/assets/assets/000/045/837/medium800/raspberry_pi_Adabox_05_kit_ORIG.jpg?1504019771)

# Kit Contents

- [Raspberry Pi Zero](https://www.adafruit.com/product/2885) - This is the slimmest, most pared down Raspberry Pi to date.  It's kind of like the little cousin to the [Pi 2](https://www.adafruit.com/product/2358) - with just a micro SD card slot, a mini HDMI port, two micro USB ports (one for power, one for USB), and 512MB of RAM. It has a single-core 1 GHz processor chip, similar to the Pi A+ and B+. These Pi's are limited but the Pi Foundation kindly helped us out to get one in each Adabox!
- [Adafruit Joy Bonnet](https://www.adafruit.com/product/3464) - Pocket-sized fun is the name of this game, with the **Joy Bonnet**  – our most fun Bonnet ever (no we didn't even think that was possible, either!). This Bonnet fits perfectly on top of your Raspberry Pi Zero (any kind) and gives you adorable hand-held arcade controls. Once you install our script onto your Pi, the controls will act like a keyboard, for easy use with any emulator or media player.
- [Raspberry Pi Zero Case](https://www.adafruit.com/product/3252) - This is a basic, classic **Pi Zero enclosure** with a black base and a clear top. The case is as minimal as it gets, coming in just two pieces of polycarbonate that snap snugly together. This case will keep your Pi Zero safe and secure while also looking super sleek.
- [Mini HDMI Cable](https://www.adafruit.com/product/2775)- This cable is nice and long, you can plug in one half into your Pi Zero and the other into a TV
- [Hammer Headers](https://www.adafruit.com/product/3413) - courtesy of our friends at Pimoroni -  **Absolutely no soldering required!** All that's needed is a few gentle taps with a hammer and bazinga! Your header is securely attached to your Pi Zero.
- [USB Power Supply](https://www.adafruit.com/product/1995)- This power adapter has a long cord and a micro USB connector on one end. Plug it into your Pi Zero to power it. Its plenty strong! If you are not in the US, you can use a common '$1' plug adapter, the power supply can take 100V-240V 50-60Hz power and just needs a plug adapter.
- [8GB SD Card](https://www.adafruit.com/product/2767)- Lots of space! This SD card will hold the _operating system_ (Raspbian) and video games you will play
- [USB MicroSD Card Reader](https://www.adafruit.com/product/939)- We added one of these in case you do not already (Adabox is for beginners!) You can use it to read/write data from the SD card

![](https://cdn-learn.adafruit.com/assets/assets/000/045/838/medium800/raspberry_pi_Adabox_05_iso_packaging_ORIG.jpg?1504019801)

# Bonus parts (for subscribers only!)

- **EAGLE insert** - Check out the EAGLE design for the Adafruit Joy Bonnet! This is the real design, with some nifty colors, so you can get a sense of what it's like to design a PCB. Autodesk's EAGLE is a great way to start designing electronics. Makers and students can download EAGLE for free.
- **Pi Foundation swag** - it wouldn't be a pi-break without some fun stuff from the Raspberry Pi foundation. They've included the latest MagPi magazine, a fun offer for MagPi subscribers, and a few stickers to show your love of all things Pi.
- **Limited Edition Collectible Pin** - Joy is the super fun game controller friend you've always wanted. While most everything makes her smile, DIY gaming rigs make her grin tooth to tooth. 

![](https://cdn-learn.adafruit.com/assets/assets/000/045/839/medium800/raspberry_pi_Adabox_05_top_Magpi_ORIG.jpg?1504019812)

# AdaBox 005

## Getting started with your new AdaBox

![](https://cdn-learn.adafruit.com/assets/assets/000/046/185/medium800/raspberry_pi_3464-06.jpg?1504729189)

With this AdaBox, you will be able to create a tiny gaming machine that will fit in your pocket. Take it out, attach to power and your tv and play all of your favorite classic games.

Like all AdaBoxes, there is no soldering required. We have partnered with our pals at Pimoroni to include the neat Hammer Headers. With this project, you should be gaming in no time.

As usual, our team of Creative Engineers have come up with some really unique projects for those who want to take the theme of this box to the next level.

Let's get started!

# AdaBox 005

## Step 1: Install the Hammer Headers

These awesome Hammer Headers from our friends at [Pimoroni](https://pimoroni.com/) allow you to fit the male header to your Pi Zero with absolutely no soldering required. Nifty! Here, you'll learn how to fit them using the jig that comes with the kit.

**It's important to hammer on a sturdy, stable, well-supported surface like a worktop or a solid wood table (although not your expensive dining table!)**

The jig comes in three pieces, and has two nylon bolts. Snap apart the acrylic pieces, and peel off the protective film (althought this isn't absolutely necessary).

Danger: 

https://vimeo.com/232544504

Push the nylon bolts through the larger plastic piece with the long rectangular hole cut in it for the GPIO pins. It doesn't matter which way up this piece is.

![](https://cdn-learn.adafruit.com/assets/assets/000/045/856/medium800/raspberry_pi_hammer-header-tut-1.jpg?1504036133)

Next, put the other rectangular acrylic piece below it, so that the heads of the nylon bolts fit neatly into the two holes. This piece prevents the pins from being pushed too far through.

![](https://cdn-learn.adafruit.com/assets/assets/000/045/855/medium800/raspberry_pi_hammer-header-tut-2.jpg?1504036131)

Now, push your Pi Zero PCB, right way up, onto the jig.

![](https://cdn-learn.adafruit.com/assets/assets/000/045/854/medium800/raspberry_pi_hammer-header-tut-3.jpg?1504036130)

Place the hammer header on top of the pin holes on your Pi Zero, making sure that the longer ends of the pins (without the retaining nubbins) are pointing upwards.

![](https://cdn-learn.adafruit.com/assets/assets/000/045/853/medium800/raspberry_pi_hammer-header-tut-4.jpg?1504036128)

Now, place the last acrylic piece on top of the pins and push it down until it touches them.

![](https://cdn-learn.adafruit.com/assets/assets/000/045/852/medium800/raspberry_pi_hammer-header-tut-5.jpg?1504036126)

Using a hammer, gently tap back and forth on the top acrylic piece to push the pins through. Pushing one end of the header all the way it can cause the other pins to bend when you hammer them in. It's worth taking your time over this part.

Danger: 

![](https://cdn-learn.adafruit.com/assets/assets/000/045/851/medium800/raspberry_pi_hammer-header-tut-6.jpg?1504036125)

# AdaBox 005

## Step 2: Software Setup

## 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:

Featured
### Ethernet Hub and USB Hub w/ Micro USB OTG Connector

[Ethernet Hub and USB Hub w/ Micro USB OTG Connector](https://www.adafruit.com/product/2992)
One can never have enough socks, or USB ports. Add some more USB and Ethernet capability to your Raspberry Pi Zero or, really, any kind of tablet or computer with an OTG connector with this **USB 2.0 and Ethernet Hub**!

This handy combo-hub has 3 USB 2.0 ports, and...

Out of Stock
[Buy Now](https://www.adafruit.com/product/2992)
[Related Guides to the Product](https://learn.adafruit.com/products/2992/guides)
![Angled shot of White hub with USB micro-B cable and Ethernet socket.](https://cdn-shop.adafruit.com/640x480/2992-10.jpg)

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](https://www.raspberrypi.com/software/) 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
Once the Pi boots up, you should see a welcome screen. Press F4 on your connected keyboard to exit to the command prompt.

![](https://cdn-learn.adafruit.com/assets/assets/000/144/496/medium640/gaming_00_retropie_welcome.png?1780601592)

Run `sudo raspi-config`

Go to  **System Options**   **→**   **Wireless LAN**

![](https://cdn-learn.adafruit.com/assets/assets/000/144/489/medium640/gaming_01_raspi-config_main_menu.png?1780601327)

![](https://cdn-learn.adafruit.com/assets/assets/000/144/491/medium640/gaming_02_system_options.png?1780601400)

Enter the settings for your WiFi.

While you're in here, you can go to the next section to be sure SSH is enabled.

![](https://cdn-learn.adafruit.com/assets/assets/000/144/492/medium640/gaming_04_wifi_ssid_filled.png?1780601452)

![](https://cdn-learn.adafruit.com/assets/assets/000/144/493/medium640/gaming_06_wifi_passphrase_filled.png?1780601463)

## Enable SSH

We recommend enabling SSH to make typing in commands much easier. SSH stands for **S** ecure **Sh** ell 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.

Run `sudo raspi-config` if you're not already in there from the previous step.

Go to  **Interface Options**   **→**   **SSH**  and choose  **Yes**.

![](https://cdn-learn.adafruit.com/assets/assets/000/144/494/medium640/gaming_07_interface_options.png?1780601492)

![](https://cdn-learn.adafruit.com/assets/assets/000/144/495/medium640/gaming_08_ssh_enable_prompt.png?1780601503)

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

To SSH into your Pi, type `ssh pi@retropi.local` 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:

```terminal
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
```

Danger: The mirror location must be fixed in order to install any other software

## Update Your Pi and Python

Run the standard updates:

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

and upgrade `setuptools`:

```terminal
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](https://learn.adafruit.com/python-virtual-environment-usage-on-raspberry-pi) guide. To Install and activate the virtual environment, use the following commands:

```terminal
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:

```terminal
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:

```terminal
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:

```terminal
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](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi). 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](https://forums.adafruit.com/viewtopic.php?f=50&t=123637&p=619544#p618773), 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:

![](https://cdn-learn.adafruit.com/assets/assets/000/144/465/medium800/gaming_raspberry_pi_262-rz.jpg?1780422060)

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

![](https://cdn-learn.adafruit.com/assets/assets/000/144/466/medium800/gaming_raspberry_pi_268-rz.jpg?1780422081)

# AdaBox 005

## Step 3: Play!

![](https://cdn-learn.adafruit.com/assets/assets/000/046/184/medium800/raspberry_pi_3464-05.jpg?1504728427)

First, install the micro SD card into the Raspberry Pi Zero. Then, plug in the HDMI cable to a monitor or TV. You will need to use the mini HDMI side of the cable on the Raspberry Pi Zero, and the full size HDMI for your TV or monitor. Now, use the included power adapter and plug it in to the 'PWR IN' port on the Raspberry Pi Zero.

You should see it almost instantly start to boot up into the RetroPie system. Give it plenty of time to fully boot up and you should be able to scan through all of the available emulators and we have included some free games to get you started.

# Adding Games

If you want to add games to your tiny new gaming system, load them up on a USB drive [as instructed here.](https://github.com/retropie/retropie-setup/wiki/Transferring-Roms) Then, using the included micro USB adapter, transfer them using the USB port on the Raspberry Pi Zero labeled 'USB'.

# AdaBox 005

## AdaBox Upgrade: Haunted Portrait

![](https://cdn-learn.adafruit.com/assets/assets/000/046/686/medium800thumb/raspberry_pi_projects_mainLoopWPark.jpg?1505921524)

With the help of Adabox 005 parts, John Park built this super creepy haunted portrait project.

> You can make a seemingly innocuous portrait come to life using an ornately framed flat panel TV powered by a Raspberry Pi. With proper lighting, it will look just like a painting, but every so often, the portrait subject's eyes will shift their gaze ever so slighting, sending chills up the spines of your unsuspecting victims, er, friends.
> 
> You'll use a hidden Raspberry Pi Zero as the image playback device to drive the TV over HDMI. Plus, you'll have a set of controls available using the buttons and thumbstick of the Joy Bonnet so you can pause and start the show, and more!

[Check out the full guide here!](../../../../haunted-portrait)

# AdaBox 005

## Need Help? Questions?

# AdaBox 005

## Redeem your coupon code

To redeem your AdaBox coupon code, sign into your Adafruit account then click 'My Account' on the top right of the Adafruit page.

![](https://cdn-learn.adafruit.com/assets/assets/000/035/495/medium800/arduino_Screen_Shot_2016-09-05_at_11.48.13_AM.png?1473090515)

Once you're in your account page, click 'Gift Certificates and Coupons.

![](https://cdn-learn.adafruit.com/assets/assets/000/035/496/medium800/arduino_Screen_Shot_2016-09-05_at_11.48.54_AM.png?1473090556)

Your coupon code will appear under 'account coupons.'

This code is associated with your AdaBox order and can be used once per AdaBox subscription. You must be logged into the Adafruit account associated with your AdaBox order to redeem your coupon code. If you received AdaBox as a gift, the code will appear in your account once you link your Adafruit account to the AdaBox you received.

Shipping costs do not count towards free items. Discount codes do not apply to shipping costs. Discount codes do not apply to gift certificates and software. Only one discount code can be applied if available. Discount does not apply to orders placed before the sale time start. Discount can not combine with reseller, educational, or any other discounted orders.

 


## Guide Products

### Ethernet Hub and USB Hub w/ Micro USB OTG Connector

[Ethernet Hub and USB Hub w/ Micro USB OTG Connector](https://www.adafruit.com/product/2992)
One can never have enough socks, or USB ports. Add some more USB and Ethernet capability to your Raspberry Pi Zero or, really, any kind of tablet or computer with an OTG connector with this **USB 2.0 and Ethernet Hub**!

This handy combo-hub has 3 USB 2.0 ports, and...

Out of Stock
[Buy Now](https://www.adafruit.com/product/2992)
[Related Guides to the Product](https://learn.adafruit.com/products/2992/guides)

## Related Guides

- [Haunted Portrait](https://learn.adafruit.com/haunted-portrait.md)
- [PiGRRL Zero](https://learn.adafruit.com/pigrrl-zero.md)
- [PixelDust Digital Sand Demos for Arcada](https://learn.adafruit.com/pixeldust-digital-sand-demos-for-arcada.md)
- [AdaBox 004](https://learn.adafruit.com/adabox004.md)
- [Intel 286 Emulator on Fruit Jam](https://learn.adafruit.com/intel-286-emulator-on-fruit-jam.md)
- [MacroPad Remote Procedure Calls over USB to Control Home Assistant](https://learn.adafruit.com/macropad-remote-procedure-calls-over-usb-to-control-home-assistant.md)
- [SNES EZ Key Bluefruit Game Pad](https://learn.adafruit.com/snes-ez-key-bluefruit-game-pad.md)
- [Creating Custom LED Animations](https://learn.adafruit.com/creating-custom-led-animations.md)
- [Wakanda Forever Game](https://learn.adafruit.com/wakanda-forever-game.md)
- [USB SNES Gamepad](https://learn.adafruit.com/usb-snes-gamepad.md)
- [Dragon Drop: a CircuitPython Game for MacroPad](https://learn.adafruit.com/dragon-drop-a-circuitpython-game-for-macropad.md)
- [Adafruit Pi Cobbler Kit](https://learn.adafruit.com/adafruit-pi-cobbler-kit.md)
- [Digital Free Library](https://learn.adafruit.com/digital-free-library.md)
- [Spy Theme Playback Device](https://learn.adafruit.com/spy-theme-playback-device.md)
- [3D Printed Personal Monitor Game Controller Mount](https://learn.adafruit.com/3d-printed-personal-monitor-game-controller-mount.md)