From 67e2c23aebe429989e2e04572487f70d88f69e99 Mon Sep 17 00:00:00 2001 From: ploopyco <54917504+ploopyco@users.noreply.github.com> Date: Thu, 19 Nov 2020 18:05:38 -0500 Subject: [PATCH] Updated Appendix D: Programming QMK on Older Ploopy Devices (markdown) --- ...Programming-QMK-on-Older-Ploopy-Devices.md | 86 ++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/Appendix-D:-Programming-QMK-on-Older-Ploopy-Devices.md b/Appendix-D:-Programming-QMK-on-Older-Ploopy-Devices.md index c0ce02e..2661941 100644 --- a/Appendix-D:-Programming-QMK-on-Older-Ploopy-Devices.md +++ b/Appendix-D:-Programming-QMK-on-Older-Ploopy-Devices.md @@ -1 +1,85 @@ -PH \ No newline at end of file +# IMPORTANT! +This guide is strictly for loading [QMK](https://github.com/qmk/qmk_firmware/tree/master/keyboards/ploopyco/trackball) onto Ploopy devices do not yet have it. + +How do you know if your device already has QMK on it? The fastest way is by plugging it in and moving the cursor. If there's a two second(ish) delay before the cursor starts moving on the screen, then QMK is **NOT** present on the device. However, if there is no delay and the cursor starts moving immediately after you've plugged it in, you've got QMK on it! + +The key step in reprogramming is **loading a new bootloader**. This guide will cover how to do that. + +## Before you begin + +Programming a bootloader is much different than programming QMK or any other firmware. To do so, we need to use a special connector on the Ploopy PCB called the **ICSP header**. It looks [like this](https://imgur.com/nh6e5tQ) (note the numbers around the connector). Your PCB will probably just have six holes in the PCB, with no plastic connector prongs jutting out of the board. That's perfectly usable, and you won't need to add a connector in order to proceed. + +**You'll need a programmer.** A "programmer" can be many different things. We use an **Arduino Nano** and six pieces of jumper wire (copper wire, nothing fancy) to program bootloaders, but many different kinds of programmers can be used. See [this list](https://beta.docs.qmk.fm/using-qmk/guides/keyboard-building/isp_flashing_guide#hardware-needed) for more examples. + +The remainder of this guide will assume that you're using an Arduino Nano to reprogram your Ploopy device. If you're using another programmer, you may need to make adjustments to these steps. + +## Get a copy of the bootloader file + +You can find a copy of the necessary bootloader [here](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1.0.0.hex). Download and save it. For the purposes of this guide, it will be assumed that you saved the file as `bootloader_atmega32u4_1.0.0.hex`. + +## Install avrdude + +`avrdude` is the software that we'll use to flash the bootloader. It runs on [Windows](https://www.ladyada.net/learn/avr/setup-win.html), [Mac](https://www.ladyada.net/learn/avr/setup-mac.html), and [Linux](https://www.ladyada.net/learn/avr/setup-unix.html), so you should be good to go. + +Verify that it's installed by opening up a terminal window (`cmd` on Windows machines). Typing in `avrdude` should show that it's installed. + +## Program the programmer, if necessary + +If you've got an Arduino Nano, you'll need to program the Arduino Nano with the ArduinoISP sketch so that it can program the Ploopy PCB. + +**You'll only need to do this step once. If your Arduino Nano is already programmed to be an ArduinoISP, skip this step.** + +1. Plug your Arduino Nano into your computer (via its USB mini-B port). + - The Arduino Nano should have a few status LEDs that illuminate when it's powered on. + - You don't need the Ploopy PCBs for this step. You can put them aside for now. +2. Fire up the [Arduino IDE](https://www.arduino.cc/en/software) (install it if you don't already have it installed). +3. Open up the ArduinoISP sketch in Arduino IDE (in `File -> Examples -> 11.ArduinoISP -> ArduinoISP`). +4. Upload the ArduinoISP sketch onto the Arduino Nano. + - Make sure that, in the Arduino IDE, `Tools > Board` is set to `Arduino Nano` and `Tools > Programmer` is set to `AVRISP mk II`. + +If the Arduino IDE reports that you successfully flashed the firmware onto the Arduino Nano, then you're done. + +## Connect the programmer to the Ploopy PCB + +The Ploopy PCB ICSP header consists of six holes (or six pins, if you've added a connector). The pins are numbered like this: + +``` + 1 -> ■ o <- 2 + 3 -> o o <- 4 + 5 -> o o <- 6 +``` + +Note that pin 1 is a square pad on the board. Also, this is the way the header looks when viewed from the *top* of the board (i.e. when the microcontroller is visible). [Here's a picture of what it looks like](https://i.imgur.com/nh6e5tQ.jpg). + +Hook up the ICSP connector on the Ploopy PCB to the programmer. If you're using an Arduino Nano, make the following connections: + +``` +ICSP Pin 1 -> Arduino Pin D12 (MISO) +ICSP Pin 2 -> Arduino 5V (V_USB) +ICSP Pin 3 -> Arduino Pin D13 (SCLK) +ICSP Pin 4 -> Arduino Pin D11 (MOSI) +ICSP Pin 5 -> Arduino Pin D10 (RST/CS) +ICSP Pin 6 -> Arduion GND (GND) +``` + +If your board doesn't have a header soldered to it (i.e. there are holes that go straight through the board instead of pins that jut out of the board), you'll need to ensure good physical contact between the wire and the pin holes in order for the programming step to work. + +## Flash the bootloader + +Once the programmer is connected to your computer and the Ploopy PCB is connected to the programmer, it's time to flash the bootloader. + +Open up a terminal, and navigate to the location where your bootloader hex file is located. Use the following command to flash the bootloader onto the device via avrdude: + +`avrdude -p m32u4 -c avrisp -b 19200 -U flash:w:bootloader_atmega32u4_1.0.0.hex -U lfuse:w:0x52:m -U hfuse:w:0x99:m -U efuse:w:0xcb:m -P /dev/ttyUSB3` + +`/dev/ttyUSB3` is just a placeholder. You'll need to verify which USB port your programmer is connected to. + +If programming with Windows, you'll replace `/dev/ttyUSB3` with something like `COM3`. + +## It's done! + +At this point, the only thing running on the ATmega32u4 is the bootloader code. Effectively, it's in [bootloader mode](https://docs.qmk.fm/#/newbs_flashing?id=put-your-keyboard-into-dfu-bootloader-mode). + +You can now use the regular technique of flashing new QMK firmware onto the Ploopy PCB. You can check that out at [[Appendix C: QMK Firmware Programming]]. + +If something is clear, check out the [QMK ISP programming guide](https://beta.docs.qmk.fm/using-qmk/guides/keyboard-building/isp_flashing_guide). \ No newline at end of file