diff --git a/Appendix-E:-Flashing-a-Bootloader.md b/Appendix-E:-Flashing-a-Bootloader.md index 930d893..c9f378b 100644 --- a/Appendix-E:-Flashing-a-Bootloader.md +++ b/Appendix-E:-Flashing-a-Bootloader.md @@ -1,69 +1,94 @@ -# 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 +# Introduction 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 [[Appendix E: Flashing a Bootloader]] before moving on. +This guide will cover a method for flashing a bootloader onto the Ploopy Nano Trackball. Note, however, that there are alternative methods available; this simply covers one such method. -## Building the Ploopy Trackball firmware +## Before you begin -With your terminal window open and pointed at your QMK build environment, compile the firmware with the following command: +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**. 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. -`qmk compile -kb ploopyco/trackball_nano/rev1_001 -km via` +**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. -Alternatively, you can invoke the Makefile directly with the following: +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. -`make ploopyco/trackball_nano/rev1_001:via` +## Get the necessary tools -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. +- [The Arduino IDE](https://www.arduino.cc/en/main/software) +- [An Arduino Nano](https://store.arduino.cc/usa/arduino-nano) (I get them on Amazon) +- A USB mini-B to USB A cable (something like [this](https://www.amazon.ca/UGREEN-Players-Digital-Navigation-Receiver/dp/B00P0GI68M)) +- Hookup wire (something like [this](https://www.amazon.ca/Elegoo-120pcs-Multicolored-Breadboard-arduino/dp/B01EV70C78); any breadboard jumper wire or 24AWG hookup wire will do fine) +- A 10uF capacitor (something like [this](https://www.amazon.ca/SODIAL-Radial-Aluminum-Electrolytic-Capacitors/dp/B00X3LP44K)) -For more details on building QMK firmware in general, see the [QMK firmware guide](https://docs.qmk.fm/#/newbs_building_firmware). +## Get a copy of the bootloader file -## Putting the Ploopy Nano Trackball into bootloader mode +You can find a copy of the necessary bootloader [here](https://raw.githubusercontent.com/qmk/qmk_firmware/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`. -Putting the Ploopy Trackball into bootloader mode is very easy. +## Install avrdude -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. +`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. -And that's it. While plugged in this way, the Ploopy Nano Trackball will accept new firmware. +Verify that it's installed by opening up a terminal window (`cmd` on Windows machines). Typing in `avrdude` should show that it's installed. -Whenever you want to put new firmware onto the Ploopy Nano, go through these steps again. +## Program the programmer, if necessary -## Flashing the firmware +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. -Use your preferred method of flashing QMK firmware. +**You'll only need to do this step once. If your Arduino Nano is already programmed to be an ArduinoISP, skip this step.** -- QMK Toolbox has been verified as working. -- Using `dfu-programmer` from a terminal window has also been verified as working. +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`. -For more details, see the [QMK guide](https://docs.qmk.fm/#/newbs_flashing) on flashing firmware. +If the Arduino IDE reports that you successfully flashed the firmware onto the Arduino Nano, then you're done. -## And that's it! +## Connect the programmer to the Ploopy PCB -Unplug it, replug it in, and you should be good to go! +The Ploopy PCB ICSP header consists of six holes (or six pins, if you've added a connector). The pins are numbered like this: -Happy customizing! \ No newline at end of file +``` + 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. + +Take a 10uF capacitor and hook it up to the Arduino Nano, between the RST and GND pin. + +## 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:0x5e:m -U hfuse:w:0x99:m -U efuse:w:0xc3: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! + +Once successfully flashed, 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 D: 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