# JOY of Arcada — USB Game Pad for Adafruit PyGamer and PyBadge ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/077/082/medium800thumb/gaming_pybadge-blink.jpg?1560570724) Surely you’ve played some little **games**  right on your **PyGamer** or **PyBadge** — perhaps using  **CircuitPython** or Microsoft **MakeCode**. But did you know…you can also use PyGamer or PyBadge as a **USB game controller** with your regular computer or with popular emulators on Raspberry Pi! Not just _any_ game controller though. With that little screen, why not give it some _personality?_ So we made a little animated friend and named her **JOY**. Joy’s eyes blink and follow the joystick, and she makes an occasional encouraging “pew pew!” as buttons are pressed. This is a new take on an earlier project — [JOY Controller for Adafruit Feather](https://learn.adafruit.com/joy-controller-feather) — which required soldering and 3D printing. Now that we have these all-in-one devices like PyGamer, it’s much easier to get something going! ![gaming_original-joy.jpg](https://cdn-learn.adafruit.com/assets/assets/000/077/069/medium640/gaming_original-joy.jpg?1560561241) JOY will watch and cheer you on as you play, but doesn't _have to be_ a game controller. She can control all manner of software or media such as YouTube, Photoshop, Premiere, Ableton Live, etc. Anything that a USB keyboard can do, JOY can operate as well. ## Hardware You can use this project on a number of Adafruit products including the PyBadge and PyGamer lines of products.  ### Adafruit PyGamer Starter Kit [Adafruit PyGamer Starter Kit](https://www.adafruit.com/product/4277) **Please note: you may get a royal blue _or_ purple case with your starter kit (they're both lovely colors)** What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right,... Out of Stock [Buy Now](https://www.adafruit.com/product/4277) [Related Guides to the Product](https://learn.adafruit.com/products/4277/guides) ![Adafruit PyGamer Starter Kit with PCB, enclosure, buttons, and storage bag](https://cdn-shop.adafruit.com/640x480/4277-08.jpg) ### Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino [Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino](https://www.adafruit.com/product/4242) 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... Out of Stock [Buy Now](https://www.adafruit.com/product/4242) [Related Guides to the Product](https://learn.adafruit.com/products/4242/guides) ![Angled shot of Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino.](https://cdn-shop.adafruit.com/640x480/4242-00.jpg) ### Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino [Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/4200) What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino? That's right, its the **Adafruit PyBadge!** We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch rounded rectangle, to make an all-in-one dev board with... In Stock [Buy Now](https://www.adafruit.com/product/4200) [Related Guides to the Product](https://learn.adafruit.com/products/4200/guides) ![Angled shot of a Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino. ](https://cdn-shop.adafruit.com/640x480/4200-01.jpg) ### Adafruit PyBadge LC - MakeCode Arcade, CircuitPython, or Arduino [Adafruit PyBadge LC - MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/3939) What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino even when you're on a budget? That's right, it's the  **Adafruit PyBadge LC!**  We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch... In Stock [Buy Now](https://www.adafruit.com/product/3939) [Related Guides to the Product](https://learn.adafruit.com/products/3939/guides) ![Angled Shot of Adafruit PyBadge - Low Cost. ](https://cdn-shop.adafruit.com/640x480/3939-05.jpg) # JOY of Arcada — USB Game Pad for Adafruit PyGamer and PyBadge ## Software ## Ready-Made Software Plug  **PyGamer**  or **PyBadge**  into your computer with a **USB** cable. Make sure the **power switch** is set to the “ **on** ” position, then **double-click the RESET button** on the top or back of the board. After a moment, a small flash drive called **PYGAMERBOOT**  or **PYBADGEBOOT** should appear on your system. Drag-and-drop one of the **.UF2 files**  (downloadable below) on to this flash drive. There will be a few seconds of LED flashing, then the drive will be ejected. Here’s the .UF2 file specifically for **PyGamer** boards: [JOYGAMER.UF2](https://cdn-learn.adafruit.com/assets/assets/000/077/055/original/JOYGAMER.UF2?1560553995) And a version for **PyBadge** (regular or LC): [JOYBADGE.UF2](https://cdn-learn.adafruit.com/assets/assets/000/077/056/original/JOYBADGE.UF2?1560554003) You can also build JOY from source code (it’s an Arduino project) but it’s quite involved. This is explained on the “How it Works” page. ## Customizing JOY for Different Key Setups The default button-to-key assignments on JOY won’t be ideal for everyone’s needs, but are easily **customized** without having to edit and recompile the code. When connected to USB, a PyGamer or PyBadge appears on your computer as a small flash drive called **CIRCUITPY** (if it does not, you’ll need to go through the one-time [CircuitPython installation](https://circuitpython.org/downloads) for the board, then reload one of the JOY .UF2 files above). In the root level of this drive (not inside any folder), create a text file called `joy.cfg` using any plain-text editor you like. Here’s an example you can copy-and-paste, then edit to your liking: ``` { "a": "Z", "b": "X", "start": "1", "select": "5", "up": "UP_ARROW", "down": "DOWN_ARROW", "left": "LEFT_ARROW", "right": "RIGHT_ARROW" } ``` The file uses “JSON” syntax…which can be fairly picky, but it’s an established standard and we can rely on well-tested code to read it. Each line consists of a _keyword_ (corresponding to one of the buttons on Joy) and a _value_ (corresponding to keys on a keyboard). Both in quotes, with a colon (:) between them and a comma at the end of the line (except for the last item). The entire set is then contained inside a set of { curly braces }. Yes, JSON is that specific. Each  **keyword** is one of eight _specific_ strings, and _must_ be **lower-case** : "a", "b", "start", "select", "up", "down", "left" and "right". _No exceptions._ Each **value** is one key name from the following table (these can be upper or lower case): JOY reads this file on startup. You’ll get an **alert message** if the file is **missing** or the **syntax** is broken (make sure all the quotes and commas are in the right places). If some buttons work but others do not, it’s most likely a key name that’s misspelled or not in the above list (it won’t report an error — the JSON syntax is valid, just the word is wrong). **This file is read on startup _only._ Changes are _not_ detected live.** After editing, write your changes to the file, then tap the **reset** button on PyGamer/PyBadge to reload. # JOY of Arcada — USB Game Pad for Adafruit PyGamer and PyBadge ## How it Works Joy is written as an **Arduino** sketch. For something that basically does one task…a USB game pad, albeit one embellished with a lot of graphical flair…it’s an awfully _big and hairy_ Arduino sketch. It was written this way for performance reasons, to keep everything animated and responsive. But to be honest, between ever-faster microcontrollers and ongoing improvements in CircuitPython speed and features, there will probably be no _need_ to program projects like this in such a tedious manner in the future! But if you’re curious, here’s a link to the code: ## [**Joy\_of\_Arcada source code on Github**](https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/Joy_of_Arcada) There are four files:  **Joy\_of\_Arcada.ino** is the main Arduino sketch, which is accompanied by three header files (.h) containing tables of graphics, sound and keyboard codes. Joy\_of\_Arcada is so named because it uses our _Adafruit\_Arcada_ library, which encapsulates a lot of graphics, sound and control-related functions common to several Adafruit boards. The Arcada library, in turn, depends on a _whole bunch_ of other libraries to provide the lower-level functionality. So many libraries, in fact, that rather than list them all here it’s best to [link to this other guide explaining all the prerequisites](https://learn.adafruit.com/pyportal-animated-gif-display/arduino-libraries). You should also have the latest Adafruit SAMD boards package for Arduino (version 1.5 or later, we suggest the latest version in the Arduino library manager). If you’ve used other Adafruit SAMD boards in the past (M0, M4, HalloWing, etc.), it’s worth checking for any recent updates (Tools→Board→Boards Manager…). In addition, before compiling this code, make sure to select Tools→USB Stack→TinyUSB (this lets our code access files on the PyGamer/PyBadge flash filesystem). ## Animating Joy To ensure button and joystick input is processed expediently, the code pulls shenanigans to draw the face very quickly. First, the entire screen is not drawn for every frame of animation. There’s really only a rectangular section in the middle where all the motion occurs — the bounds of the eyes and mouth. So after clearing the screen and drawing a full-face bitmap just once, all subsequent updates refresh only this middle area. ![](https://cdn-learn.adafruit.com/assets/assets/000/077/084/medium800/gaming_face-bounds.png?1560575541) An offscreen buffer for just this area is maintained in RAM (called a _framebuffer_ in Arcada library parlance, or a _GFXcanvas16_ object in Adafruit\_GFX terms). We periodically modify sections of the buffer in RAM and copy it to the screen. The offscreen buffer is processed in regions, of varying height but all the same width. Even though that wastes a little memory (the mouth is not as wide as the eyes, for example), making everything the same width allows us to use a single `memcpy()` call to draw each region, because the scanlines are contiguous in memory (moving data between different-width images would require copying each scanline separately). It’s a one-dimensional operation rather than 2-D. The pupils are a special case. Those _are_ drawn more conventionally (using the `drawRGBBitmap()` function from the Adafruit\_GFX library, because they’re round and we need that code’s masking capability). Then the eyelids are drawn on top of this when needed, using `memcpy()` as previously described. ![](https://cdn-learn.adafruit.com/assets/assets/000/077/085/medium800/gaming_face-regions.png?1560575961) So drawing the face then is mostly a matter of copying one of several fixed-sized bitmap images (encoded in the graphics.h file — more on that in a moment) to a corresponding area in the offscreen buffer. ![](https://cdn-learn.adafruit.com/assets/assets/000/077/086/medium800/gaming_face-bitmaps.png?1560576158) Copying each completed frame of face animation to the screen is done using _direct memory access_ (DMA), which lets the data transfer occur “in the background,” not using any instruction cycles…allowing us to move on with handling more joystick and button input while the screen redraws. ## Preparing the Graphics As alluded to above, the graphics are encoded as tables in a header file (part of program memory), not as image files in the flash filesystem. They’re just **huge arrays of 16-bit values** , one value per pixel. **It’s a frequent misconception that we have some kind of finely-crafted tool for converting images into header files like this, but that’s not true. ** Typically I’ll use some throwaway **Python** code and the **Python Imaging Library** (PIL or its offspring Pillow) for such conversions. This often starts with an existing image conversion script (such as the one from the Uncanny Eyes project — [tablegen.py in this repository](https://github.com/adafruit/Uncanny_Eyes/tree/master/convert)), tweaking it for the task at hand…but it’s _extremely rare_ that anything like this is held onto. **Every project’s needs are different** , and it’s better for your mental health to think of these little one-off scripts as disposable tissues, not precious gems to be hoarded. It’s very informal stuff and that’s actually a good thing. Python makes it so quick. If you really need something ready-made though, [this online tool](https://littlevgl.com/image-to-c-array) can handle quite a number of situations. ## Featured Products ### Adafruit PyGamer Starter Kit [Adafruit PyGamer Starter Kit](https://www.adafruit.com/product/4277) **Please note: you may get a royal blue _or_ purple case with your starter kit (they're both lovely colors)** What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right,... Out of Stock [Buy Now](https://www.adafruit.com/product/4277) [Related Guides to the Product](https://learn.adafruit.com/products/4277/guides) ### Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino [Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/4200) What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino? That's right, its the **Adafruit PyBadge!** We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch rounded rectangle, to make an all-in-one dev board with... In Stock [Buy Now](https://www.adafruit.com/product/4200) [Related Guides to the Product](https://learn.adafruit.com/products/4200/guides) ### Adafruit PyBadge LC - MakeCode Arcade, CircuitPython, or Arduino [Adafruit PyBadge LC - MakeCode Arcade, CircuitPython, or Arduino](https://www.adafruit.com/product/3939) What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino even when you're on a budget? That's right, it's the  **Adafruit PyBadge LC!**  We wanted to see how much we could cram into a ​3 3⁄8 × ​2 1⁄8 inch... In Stock [Buy Now](https://www.adafruit.com/product/3939) [Related Guides to the Product](https://learn.adafruit.com/products/3939/guides) ### Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino [Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino](https://www.adafruit.com/product/4242) 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... Out of Stock [Buy Now](https://www.adafruit.com/product/4242) [Related Guides to the Product](https://learn.adafruit.com/products/4242/guides) ### Adafruit PyGamer Acrylic Enclosure Kit [Adafruit PyGamer Acrylic Enclosure Kit](https://www.adafruit.com/product/4238) 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... In Stock [Buy Now](https://www.adafruit.com/product/4238) [Related Guides to the Product](https://learn.adafruit.com/products/4238/guides) ### USB A/Micro Cable - 2m [USB A/Micro Cable - 2m](https://www.adafruit.com/product/2185) This is your standard USB A-Plug to Micro-USB cable. It's 2 meters long so you'll have plenty of cord to work with for those longer extensions. Out of Stock [Buy Now](https://www.adafruit.com/product/2185) [Related Guides to the Product](https://learn.adafruit.com/products/2185/guides) ### Pink and Purple Braided USB A to Micro B Cable - 2 meter long [Pink and Purple Braided USB A to Micro B Cable - 2 meter long](https://www.adafruit.com/product/4148) This cable is super-fashionable with a woven pink and purple Blinka-like pattern! First let's talk about the cover and over-molding. We got these in custom colors, and if you _have_ to have visible cables, then you might as well have the nicest fabric-bound... No Longer Stocked [Buy Now](https://www.adafruit.com/product/4148) [Related Guides to the Product](https://learn.adafruit.com/products/4148/guides) ### Retro Handheld Game Devices Sticker Set [Retro Handheld Game Devices Sticker Set](https://www.adafruit.com/product/4257) What was your first handheld gaming console? Do you ever wish you could go back to those long car rides as you happily button-mashed in the back seat?  Handheld game devices have come a long way since the 1979 release of the 16x16 pixel  In Stock [Buy Now](https://www.adafruit.com/product/4257) [Related Guides to the Product](https://learn.adafruit.com/products/4257/guides) ## Related Guides - [Adafruit PyBadge and PyBadge LC](https://learn.adafruit.com/adafruit-pybadge.md) - [Introducing Adafruit PyGamer](https://learn.adafruit.com/adafruit-pygamer.md) - [Saving CircuitPython Bitmaps and Screenshots](https://learn.adafruit.com/saving-bitmap-screenshots-in-circuitpython.md) - [PyGamer NeoPixel Controller](https://learn.adafruit.com/pygamer-neopixel-controller.md) - [MakeCode Arcade Platformer Level Design](https://learn.adafruit.com/makecode-arcade-platform-level.md) - [PYOA for PyGamer/PyBadge - Adding Cursor Support to CircuitPython](https://learn.adafruit.com/cursor-for-circuitpython.md) - [Playing Gamebuino META Games on Arcada](https://learn.adafruit.com/playing-gamebuino-meta-games-on-arcada.md) - [PyPaint Drawing Program In CircuitPython](https://learn.adafruit.com/pypaint.md) - [Bounce - an accelerometer game in Arduino for PyGamer and PyBadge](https://learn.adafruit.com/bounce-an-accelerometer-game-in-arduino-for-pygamer-and-pybadge.md) - [Game & Watch Octopus](https://learn.adafruit.com/game-watch-octopus.md) - [Custom Color Palettes for MakeCode Arcade Games](https://learn.adafruit.com/custom-color-palettes-for-makecode-arcade-games.md) - [AdaBox 012](https://learn.adafruit.com/adabox012.md) - [MakeCode Arcade: Sparky Invaders](https://learn.adafruit.com/makecode-arcade-sparky-invaders.md) - [PyGamer MP3 Player with CircuitPython](https://learn.adafruit.com/pygamer-mp3-player-with-circuitpython.md) - [PyBadger Event Badge](https://learn.adafruit.com/pybadger-event-badge.md) - [Arcada Animated GIF Display](https://learn.adafruit.com/pyportal-animated-gif-display.md) - [Adafruit 1.3" and 1.54" 240x240 Wide Angle TFT LCD Displays](https://learn.adafruit.com/adafruit-1-3-and-1-54-240-x-240-wide-angle-tft-lcd-displays.md)