Hi there!

If you're looking to subscribe to AdaBox, click here!

Oh! Hello! If you're here, (and we suspect you are) it's because you were given the gift of handheld gaming development and coding with an AdaBox! Perhaps you are a beginner who is getting started with your AdaBox. Or maybe you just want to relive what it's like being a beginner at game development and coding again. But most of all, you want to learn how to build and make creative, awesome games! (If, rather than learn game dev and coding, you'd like to look at pictures of cats instead, please check https://www.adafruit.com/galleries/cats-of-engineering But if we're being honest, learning game development and coding will inevitably lead to even more efficient, creative, and high-tech cat picture viewing. It's pretty much cats all the way down, people.)

Anyway, back to our story: You're in luck: there's never been a better time. Seriously. We're not just saying that. It's bonkers how great a time this is for you to learn game development and coding!

Gone are the days where you need thousands of dollars of equipment and a physics/math background. If you have a dream of creating games with stylin' pixel art and chip-tune soundtracks for your own handheld gaming device, you can build them! Want to design your own RPG? You can do it! How about an re-make of an 8-bit classic? You'll be doing that in no time!

Now is the the time to learn game development and coding for the PyGamer using Microsoft's MakeCode Arcade, the easy-to-use, drag-and-drop development environment you can run right in the browser! And uploading your games to play on your PyGamer is a snap!

Oh, and did we mention, you can also use Arduino and CircuitPython with the PyGamer? You can!

Thanks to the generous sponsorship and support from Digi-Key for making designing and shipping this box a breeze -- they always ship out parts orders super fast! We even made a game in their honor, that's included on your PyGamer and ready to play -- see if you can pack purchase orders as well as they do!

Who is this for?

Anyone who's interested in playing and/or creating their own video games, that's who! If you want to learn how to code your own games, create pixel art sprite and animation, gameplay mechanics, scoring, and even chiptune soundtracks, this is for you! And a desire to play your own games on the go on a totally rad handheld gaming platform. Oh, and with access to a modern web browser to do the coding. 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 or engineering 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 program already - great! If not, don't worry, we'll teach you enough to be dangerous, yet effective!

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

Who are you?

Great question. This is me:

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!

Want to buy past AdaBoxes?

Player One, Ready? This ADABOX will show you how to become your own video game creator with MakeCode Arcade. No need to save your quarters up either, all you need is a computer with a web browser to use Microsoft's game creation engine. Learn about sprites, tile maps, and sound effects to craft your masterpiece, then run it on the PyGamer board for portable gameplay.

PyGamer is our full-featured portable gaming platform. It features a color TFT display, analog joystick, buttons, speaker, headphone jack, SD card slot, as well as light and motion sensors. It's hack-able, you can plug in STEMMA cables or FeatherWings to extend its capabilities. It's designed to work perfectly with MakeCode Arcade, and you can also write games in CircuitPython, Arduino, or even run an emulator to play old 8-bit games of yore.

This ADABOX is possible with the generous sponsorship and support from Digi-Key. They made designing and shipping this box a breeze thanks to how fast they shipped our parts orders. We are so impressed with their accuracy and speed, we wrote a game in their honor, its already included on the PyGamer. Try and see if you can pack purchase orders as well as they do!

AdaBox 012 Contents

Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino

What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right, it's the Adafruit PyGamer! We wanted to make an entry-level gaming handheld for DIY gaming, and maybe a little retro-emulation. It's not the fastest and best of everything but it is an all-in-one dev board with a lot of possibilities!

The PyGamer is powered by our favorite chip, the ATSAMD51, with 512KB of flash and 192KB of RAM. We add 8 MB of QSPI flash for file storage, handy for images, fonts, sounds, or game assets.

On the front you get a 1.8" 160x128 color TFT display with dimmable backlight - we have fast DMA support for drawing so updates are incredibly fast. A dual-potentiometer analog stick gives you great control, with easy diagonal movement - or really any direction you like. There's also 4 square-top buttons, which fit our square top button caps. The buttons are arranged to mimic a gaming handheld, with 2 menu-select buttons and 2 fire-action buttons. There's also 5 NeoPixel LEDs to dazzle or track activity.

On the back we have a full Feather-compatible header socket set, so you can plug in any FeatherWing to expand the capabilities of the PyGamer. There's also 3 STEMMA connectors - two 3-pin with ADC/PWM capability and one 4-pin that connects to I2C - you can use this for Grove sensors as well.

For built in sensors, there's a light sensor that points out the front, and a 3-axis accelerometer that can detect taps and free-fall. To make bleeps and bloops, plug in any set of stereo headphones. For projects where you need more volume, you can plug in one of our 8 ohm speakers. The PyGamer will auto-switch to headphones when they're plugged in, otherwise play through the speaker.

Mini Oval Speaker with Short Wires - 8 Ohm 1 Watt

Plug it into your PyGamer to play music or game sound effects.

This wee speaker is a great addition to any audio project where you need 8 ohm impedance and 1W or less of power. We particularly like this speaker as it is small and comes with nice skinny wires with a connector on the end. It has a handy "Molex PicoBlade" 1.25mm pitch 2-pin cable, which makes plugging into a board easy. Or you can cut off the connector and just solder/clamp onto the wires directly.

Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh

When installed in the PyGamer it will let you take it on the go.

Lithium ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 350mAh for a total of about 1.3 Wh.

Plastic Button Caps For Square Top - 8mm Diameter

Customize your PyGamer with five different button colors that snap onto match your personal style.

These Reese's Piece's lookin' bits fit perfectly on top of tactile buttons with 2.4mm square tops and give a satisfying 8mm diameter surface area for your fingers to press.

You get 10 candy-colored round caps. You get two of each color: red, yellow, white, gray, and Adafruit black.


PyGamer Enclosure Kit

You've got your PyGamer, and you're ready to start jammin' on your favorite arcade games. You gaze adoringly at the charming silkscreen designed by Ada-friend PaintYourDragon. The nostalgia is palpable!

Cradling the PCB in your hands, you realize there's something missing. You feel an overwhelming need to protect this incredible gaming console. 

Prevent monsters, gremlins, big level bosses, or accidentally-spilled coffee giving you a GAME OVER with the PyGamer Enclosure Kit! Expertly crafted and laser-cut, this enclosure will give your PyGamer a minimalist and elegant look. Laser cut acrylic with hardware.

Zipper Case

Keep your PyGamer safe in this soft zipper case, it even h as a storage pocket for cables, headphones or SD cards!

Bonus Extras for AdaBox Subscribers!

Gridded Notebook and Marker Set

Dream up your pixel art of game map on this lay-flat notebook with a square grid background.

Use the twelve colorful markers to plan and design your characters, levels, and effects!

MakeCode Arcade and Retro Handheld Sticker Set

Decorate your case and check out the family tree that inspired PyGamer with these excellent stickers!

Plus, a highly awesome MakeCode Arcade sticker!

Wireframe Magazine

The magazine that lifts the lid on video games. Look at how games are made, who makes them, and even read through the process of making your own.

Update the PyGamer Bootloader to prevent a problem with MacOS 10.14.4 and to fix button problems, and to prevent occasional damage to the loaded program.

Your PyGamer may need its bootloader updated for several reasons.

Bootloaders earlier than v3.9.0 do not protect against a rare problem in which part of internal flash is erased on startup.

Starting with MacOS 10.14.4, Apple changed how USB devices are recognized on certain Macs. This caused a timing problem with boards that were loaded with a MakeCode program, preventing the PYGAMERBOOT drive from appearing. Also the A and B buttons will be reversed in MakeCode if your bootloader is too old.

Updating Your PyGamer Bootloader

To see if you need to update your bootloader, get the UF2 boot drive to appear on your board. If you're running MakeCode, click the reset button once. If you're running CircuitPython or an Arduino program, double-click the reset button.

When you see PYGAMERBOOT, click thePYGAMERBOOT drive in the Finder and then double-click the INFO_UF2.TXT file to see what's inside.

The bootloader version is listed in INFO_UF2.TXT. In this example, the version is v3.6.0.

If the bootloader version you see is smaller than "v3.9.0", you need to update. For instance, the bootloader above needs to be upgraded.

Download the latest version of the PyGamer bootloader updater from the circuitpython.org Downloads page.

The bootloader updater will be named update-bootloader-arcade_pygamer-v3.9.0.uf2 or some later version. Drag that file from your Downloads folder onto the bootloader drive: ARCADE-D5, GAMERBOOT, or PYGAMERBOOT.

After you drag the updater onto the boot drive, the red LED on the board will flicker and then blink slowly about five times. A few seconds later, PYGAMERBOOT will appear in the Finder. After that, you can click onPYGAMERBOOT and double-click INFO_UF2.TXT again to confirm you've updated the bootloader.

Oh no, I updated MacOS already and I can't see the boot drive!

If your Mac has already been updated to MacOS 10.14.4 and now you can't see a boot drivein the Finder, you need to find another computer that will work. Not all upgraded Macs will fail to show the boot drive: older ones can work. Or find a Mac that hasn't been upgraded yet. Any Windows 10 or Linux computer should work for upgrading your bootloader. Windows 7 computers will need drivers installed, but then can work.

Here's how to assemble the laser cut acrylic case for the PyGamer. The kit comes with seven pieces of acrylic, and four screws and nuts. You've got ten button caps to pick from (you'll pick four), and you'll also want to connect the speaker and battery for the full portable experience.


If you haven't already, remove the clear plastic screen protector film from the PyGamer display.

Paper Protection

Remove the protective paper backing from both sides of all the acrylic pieces.


Plug the speaker into the speaker port on the PyGamer.

Then, remove the white oval plastic ring to expose the adhesive and press the speaker to the PyGamer where the silkscreen oval outline indicates.


Plug the battery into the on-board connector. Very carefully, bend the wires so that the battery fits the spot shown.

Button Caps

Pick four of the button caps and click them into place on the square shafts of the buttons. Which color combo will you choose?!

Case Layers

The case assembly is pretty simple. Place the clear top side piece on as shown.

Next, place the smoked gray piece on.


Flip the board over, then place the four spacer pieces onto the back as shown.


The last piece to go on is the thin bottom layer with the Feather header cutouts.


Push the four screws through from front to back, being sure they go through the holes in all layers and the PyGamer.

Screw on the nuts to secure things. Hand tight is fine -- you don't want to crack anything by using excessive force.

That's all there is to it -- you're ready to play with your PyGamer in its excellent, stylish case!

Digi-Key x Adafruit Order Shipper Game

If you need to re-load the Digi-Key Shipping game, here's the .uf2 file below. Download this to your computer.

Plug in your PyGamer to your computer with a known good USB data cable (not a "charge-only" cable which should be killed and burned with fire) then turn on the PyGamer and press the reset button to bring up the bootloader. (Also, try both with and without a USB hub if you have one, sometimes they help, sometimes not.)

Drag the .uf2 file onto the PYGAMERBOOT drive that shows up on your computer.

Screen Adhesive Fix

The screen can become un-adhered pretty easily -- these screens were originally designed to be secured with a bezel. Your PyGamer case does a good job of holding it in place, but if you have it out of a case, it can become unstuck.

Luckily, it's easy to fix! Just use two strips of double stick adhesive tape to hold the screen down to the backing plastic.

The small bits of adhesive may have given up the fight. Go ahead and lift the screen away from the backing, being careful to go gentle on the ribbon connector!

Get some good double stick tape, as shown.

Cut off two short lengths of the tape, you can even use one piece and cut it in half length-wise to make narrow strips.

Place a piece of tape across the bottom and top edges of the backing.

Press the screen down firmly and hold for 30 seconds to ensure good adhesion.


Your PyGamer should be better than ever now, and ready to play!

This guide was first published on Jun 16, 2019. It was last updated on Jun 16, 2019.