Appendix C: QMK Firmware Programming

IMPORTANT!

This guide is strictly for Ploopy devices that come preloaded with QMK. How do you know if your device has QMK on it? The fastest way is by using a piece of software such as QMK Toolbox. If you're running that program and plug in your Ploopy device, it'll show up as a QMK device.

You can also try jumping into the bootloader:

• If you've got a right-handed Ploopy Classic, hold the "back" button and plug in the trackball. If moving the ball doesn't move the cursor, then you've got QMK. (Try unplugging and plugging it back in without holding the forward button just to make sure that moving the ball still works as normal.)
• If you've got a left-handed Ploopy Classic, hold the "forward" button and plug in the trackball. If moving the ball doesn't move the cursor, then you've got QMK. (Try unplugging and plugging it back in without holding the back button just to make sure that moving the ball still works as normal.)

You can reprogram your older Ploopy device with new QMK firmware. The instructions for doing so are in Appendix D: Programming QMK on Older Ploopy Devices.

Working with QMK

The Ploopy 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/rev1_005

and you'll be fine.

Choose the correct firmware

Look for some writing on the base PCB (it sits flat against the bottom of the case, and it holds the microcontroller and the sensor optic). If you see that it has a version of "R1.005" or higher, use the rev1_005 firmware. If it's "R1.004" or lower, use the rev1 firmware.

LEFTIES ONLY:

• If you're compiling from source, use the rev1 version of the firmware. Make sure to change the rev1/rules.mk configuration file to have the line BOOTLOADER=atmel-dfu instead of BOOTLOADER=caterina.
• If you don't want to be bothered with all that, a precompiled hex file is available for you right here. It comes with VIA already configured.

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/rev1_005 -km via

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

make ploopyco/trackball/rev1_005:via

If you wish, you can use the default keymap (with qmk compile -kb ploopyco/trackball/rev1_005 -km default or make ploopyco/trackball/rev1_005:default). However, the VIA keymap is particularly interesting because it allows for customization of the trackball's functions without reflashing the firmware, through the use of the convenient VIA software package. It's incredibly handy, so definitely check it out.

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

Putting the Ploopy Trackball into bootloader mode

Putting the Ploopy Trackball into bootloader mode is very easy.

1. Unplug it from your computer.
2. If you're using a right-handed Ploopy Classic, hold the "back" button. This is the button just to the right of the ball; it normally sits under your ring (fourth) finger. If you're using a left-handed Ploopy Classic, hold the "forward" button.
3. While holding the button, plug the Ploopy 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.

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

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!