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:

And a version for PyBadge (regular or LC):

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 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"
}

{
  "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.