Appendix D: QMK Firmware Programming

Working with QMK

The Ploopy Nano Trackball is fairly easy to program and reprogram, thanks to the excellent work by all of the developers and maintainers of the QMK firmware suite. This guide will focus specifically on flashing firmware to the Ploopy Trackball.

Before you begin

If you have never used QMK before, go through all of the steps in the QMK guide to set up your environment.

QMK was built for keyboards, so you'll see lots of references to code that looks like the following:

-kb <keyboard>

Whenever you see that, use the following syntax:

-kb ploopyco/trackball_nano/rev1_001

and you'll be fine.

Flashing a bootloader

You only need to flash a bootloader if you're building a Ploopy Nano Trackball from scratch, or if your bootloader has become corrupted in some way.

Follow the steps in QMK's flashing guide. You may require hardware that we don't provide, such as an Arduino device.

You'll require the following fuse settings when programming the bootloader:

Fuse	Setting
Low	0x5E
High	0x99
Extended	0xC3

Building the Ploopy Trackball firmware

With your terminal window open and pointed at your QMK build environment, compile the firmware with the following command:

qmk compile -kb ploopyco/trackball_nano/rev1_001 -km default

Alternatively, you can invoke the Makefile directly with the following:

make ploopyco/trackball_nano/rev1_001:default

For more details on building QMK firmware in general, see the QMK firmware guide.

Putting the Ploopy Nano Trackball into bootloader mode

Putting the Ploopy Trackball into bootloader mode is very easy.

1. Unplug it from your computer.
2. Open it by removing the screw in the base and removing the top.
3. Pop the PCB out of the base. (Note: once you've done this a few times, you can reflash the board without popping the PCB out, since the holes are obviously also exposed on the back of the PCB.)
4. Look for a pair of vias (gold-plated holes) that have the words BOOTLOADER above them. If you're looking at the board "right side up", then you should see the words in the top-right corner, and the two holes will be right below the words.
5. Get a paper clip (non-insulated, i.e. no plastic shit covering it) or a pair of tweezers, or some wire. Whatever you've got on hand that's metal.
6. Stick the paper clip or tweezers into the holes. You're trying to form an electrical connection between the two holes.
7. While you've got the two vias connected with your metal bridge, plug the Ploopy Nano Trackball into your computer. If you're using QMK Toolbox, it should show up in the console. If using dmesg, it'll show up as an Atmel DFU device.
8. Let go with the paper clip or tweezers. That's done for now.

And that's it. While plugged in this way, the Ploopy Nano Trackball will accept new firmware.

Whenever you want to put new firmware onto the Ploopy Nano, go through these steps again.

Flashing the firmware

Use your preferred method of flashing QMK firmware.

• QMK Toolbox has been verified as working.
• Using dfu-programmer from a terminal window has also been verified as working.

For more details, see the QMK guide on flashing firmware.

And that's it!

Unplug it, replug it in, and you should be good to go!

Happy customizing!