Updated Appendix E: Flashing a Bootloader (markdown)
ploopyco
parent
402f4d04fb
commit
cf5a57ce57
|
|
@ -1,106 +1,69 @@
|
|||
# Introduction
|
||||
# Working with QMK
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
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) **TODO fix this**. 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.
|
||||
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).
|
||||
|
||||
**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.
|
||||
QMK was built for keyboards, so you'll see lots of references to code that looks like 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.
|
||||
`-kb <keyboard>`
|
||||
|
||||
## Get the necessary tools
|
||||
Whenever you see that, use the following syntax:
|
||||
|
||||
- [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))
|
||||
`-kb ploopyco/trackball_nano/rev1_001`
|
||||
|
||||
## Get a copy of the bootloader file
|
||||
and you'll be fine.
|
||||
|
||||
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`.
|
||||
## Flashing a bootloader
|
||||
|
||||
## Install avrdude
|
||||
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.
|
||||
|
||||
`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.
|
||||
Follow the steps in [[Appendix E: Flashing a Bootloader]] before moving on.
|
||||
|
||||
Verify that it's installed by opening up a terminal window (`cmd` on Windows machines). Typing in `avrdude` should show that it's installed.
|
||||
## Building the Ploopy Trackball firmware
|
||||
|
||||
## Program the programmer, if necessary
|
||||
With your terminal window open and pointed at your QMK build environment, compile the firmware with the following command:
|
||||
|
||||
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.
|
||||
`qmk compile -kb ploopyco/trackball_nano/rev1_001 -km via`
|
||||
|
||||
**You'll only need to do this step once. If your Arduino Nano is already programmed to be an ArduinoISP, skip this step.**
|
||||
Alternatively, you can invoke the Makefile directly with the following:
|
||||
|
||||
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`.
|
||||
`make ploopyco/trackball_nano/rev1_001:via`
|
||||
|
||||
If the Arduino IDE reports that you successfully flashed the firmware onto the Arduino Nano, then you're done.
|
||||
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.
|
||||
|
||||
## Connect the programmer to the Ploopy PCB
|
||||
For more details on building QMK firmware in general, see the [QMK firmware guide](https://docs.qmk.fm/#/newbs_building_firmware).
|
||||
|
||||
**This next bit is very tricky. Pay very close attention.**
|
||||
## Putting the Ploopy Nano Trackball into bootloader mode
|
||||
|
||||
The Ploopy PCB ICSP header consists of six holes (or six pins, if you've added a connector). The pins are numbered like this:
|
||||
Putting the Ploopy Trackball into bootloader mode is very easy.
|
||||
|
||||
```
|
||||
1 -> ■ o <- 2
|
||||
3 -> o o <- 4
|
||||
5 -> o o <- 6
|
||||
```
|
||||
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.
|
||||
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.
|
||||
|
||||
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) **TODO fix this**.
|
||||
And that's it. While plugged in this way, the Ploopy Nano Trackball will accept new firmware.
|
||||
|
||||
**HOWEVER.** On the Ploopy Nano PCB, the microcontroller actually covers these holes. You'll have to flip the PCB upside-down in order to access the ICSP header. Obviously, if it's upside-down, the header is backwards. So, really, the numbers are like this:
|
||||
Whenever you want to put new firmware onto the Ploopy Nano, go through these steps again.
|
||||
|
||||
```
|
||||
2 -> o ■ <- 1
|
||||
4 -> o o <- 3
|
||||
6 -> o o <- 5
|
||||
```
|
||||
## Flashing the firmware
|
||||
|
||||
Got that?
|
||||
Use your preferred method of flashing QMK firmware.
|
||||
|
||||
Hook up the ICSP connector on the Ploopy PCB to the programmer. If you're using an Arduino Nano, make the following connections:
|
||||
- QMK Toolbox has been verified as working.
|
||||
- Using `dfu-programmer` from a terminal window has also been verified as working.
|
||||
|
||||
```
|
||||
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)
|
||||
```
|
||||
For more details, see the [QMK guide](https://docs.qmk.fm/#/newbs_flashing) on flashing firmware.
|
||||
|
||||
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.
|
||||
## And that's it!
|
||||
|
||||
Take a 10uF capacitor and hook it up to the Arduino Nano, between the RST and GND pin.
|
||||
Unplug it, replug it in, and you should be good to go!
|
||||
|
||||
## 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).
|
||||
Happy customizing!
|
||||
Loading…
Reference in New Issue