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:

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:

Download: file
{
  "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):

A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
1
2
3
4
5
6
7
8
9
0

 

 

RETURN
ESCAPE
BACKSPACE
TAB
SPACE
MINUS
EQUAL
LEFT_BRACKET
RIGHT_BRACKET
BACKSLASH
EUROPE_1
SEMICOLON
APOSTROPHE
GRAVE
COMMA
PERIOD
SLASH
CAPS_LOCK
F1
F2
F3
F4
F5
F6
F7
F8
F9
F10
F11
F12
PRINT_SCREEN
SCROLL_LOCK
PAUSE
INSERT
HOME
PAGE_UP
DELETE
END

PAGE_DOWN
RIGHT_ARROW
LEFT_ARROW
DOWN_ARROW
UP_ARROW
NUM_LOCK
KEYPAD_DIVIDE
KEYPAD_MULTIPLY
KEYPAD_SUBTRACT
KEYPAD_ADD
KEYPAD_ENTER
KEYPAD_1
KEYPAD_2
KEYPAD_3
KEYPAD_4
KEYPAD_5
KEYPAD_6
KEYPAD_7
KEYPAD_8
KEYPAD_9
KEYPAD_0
KEYPAD_DECIMAL
EUROPE_2
APPLICATION
POWER
KEYPAD_EQUAL
F13
F14
F15
LEFT_CONTROL
LEFT_SHIFT
LEFT_ALT
LEFT_GUI
RIGHT_CONTROL
RIGHT_SHIFT
RIGHT_ALT
RIGHT_GUI

 

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.

This guide was first published on Jun 15, 2019. It was last updated on Jun 15, 2019. This page (Software) was last updated on Oct 14, 2019.