From 30310a0bae3da4cce3c34e06ac8815a409ec1741 Mon Sep 17 00:00:00 2001
From: ploopyco <54917504+ploopyco@users.noreply.github.com>
Date: Wed, 10 Feb 2021 15:19:19 -0500
Subject: [PATCH] Created Appendix C: QMK Firmware Programming (markdown)

---
 Appendix-C:-QMK-Firmware-Programming.md | 70 +++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 Appendix-C:-QMK-Firmware-Programming.md

diff --git a/Appendix-C:-QMK-Firmware-Programming.md b/Appendix-C:-QMK-Firmware-Programming.md
new file mode 100644
index 0000000..6093b96
--- /dev/null
+++ b/Appendix-C:-QMK-Firmware-Programming.md
@@ -0,0 +1,70 @@
+# Working with QMK
+
+The Ploopy Mini 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 <keyboard>`
+
+Whenever you see that, use the following syntax:
+
+`-kb ploopyco/trackball_mini/rev1_001`
+
+and you'll be fine.
+
+## Flashing a bootloader
+
+You only need to flash a bootloader if you're building a Ploopy Mini 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_mini/rev1_001 -km via`
+
+Alternatively, you can invoke the Makefile directly with the following:
+
+`make ploopyco/trackball_mini/rev1_001:via`
+
+If you wish, you can use the default keymap (with `qmk compile -kb ploopyco/trackball_mini/rev1_001 -km default` or `make ploopyco/trackball_mini/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 Trackball into bootloader mode
+
+Putting the Ploopy Trackball into bootloader mode is very easy.
+
+1. Unplug it from your computer.
+2. Hold the "forward" button. This is the button just to the right of the ball; it normally sits under your ring (fourth) finger.
+3. While holding the forward button, plug the Ploopy Mini 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 Mini 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