diff --git a/Appendix-D:-QMK-Firmware-Programming.md b/Appendix-D:-QMK-Firmware-Programming.md new file mode 100644 index 0000000..681b09f --- /dev/null +++ b/Appendix-D:-QMK-Firmware-Programming.md @@ -0,0 +1,71 @@ +# 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](https://github.com/qmk/qmk_firmware). 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](https://docs.qmk.fm/#/newbs_getting_started). + +QMK was built for keyboards, so you'll see lots of references to code that looks like the following: + +`-kb ` + +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](https://beta.docs.qmk.fm/using-qmk/guides/keyboard-building/isp_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 via` + +Alternatively, you can invoke the Makefile directly with the following: + +`make ploopyco/trackball_nano/rev1_001:via` + +If you wish, you can use the default keymap (with `qmk compile -kb ploopyco/trackball_nano/rev1_001 -km default` or `make ploopyco/trackball_nano/rev1_001: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](https://github.com/the-via/releases/releases). It's incredibly handy, so definitely check it out. + +For more details on building QMK firmware in general, see the [QMK firmware guide](https://docs.qmk.fm/#/newbs_building_firmware). + +## 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. +3. Hold the hardware reset button. It's the only tactile push buttons switch on the board. +4. While holding the hardware reset button, 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. + +And that's it. While plugged in this way, the Ploopy Nano 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](https://docs.qmk.fm/#/newbs_flashing) on flashing firmware. + +## And that's it! + +Unplug it, replug it in, and you should be good to go! + +Happy customizing! \ No newline at end of file