Appendix E: Firmware Programming (Non QMK Devices)

IMPORTANT!

This guide is strictly for Ploopy devices that do not come preloaded with QMK. These instructions are for putting the old, non-QMK firmware onto the trackball. If that's what you really want, then go ahead. But if you're going to reprogram the firmware anyways, try mounting QMK at Appendix C: QMK Firmware Programming.

Background

The Arduino Nano is how you're going to program your Ploopy Trackball, whether you're building your own Ploopy Trackball boards, or you're unsatisfied with the firmware that we shipped on your boards when you bought them from us.

The Arduino Nano offers a very simple and easy way of programming the microcontroller, which is why we're going to use it. Let's dive in.

Step 1: Get the necessary tools

• The Arduino IDE
• A base PCB with all components soldered
• An Arduino Nano (I get them on Amazon)
• A USB mini-B to USB A cable (something like this)
• Hookup wire (something like this; any breadboard jumper wire or 24AWG hookup wire will do fine)
• A 10uF capacitor (something like this)
• A breadboard (something like this)

Step 2: Hook up the base PCB to the Arduino Nano

The base PCB has a 6-pin ICSP header. 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.

Make the following connections using hookup wire:

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. See the Q&A at the bottom for more details.

Step 3: Add the Ploopy Trackball board definition to the Arduino IDE

In this step, you'll add the Ploopy Trackball board definition to your install of the Arduino IDE.

1. Visit the Ploopy Trackball Github firmware page and download the entire hardware/ploopy/avr directory onto your computer.
2. Copy the hardware/ploopy/avr directory tree into your Arduino folder.
   • On Windows machines, this could be somewhere like C:\Program Files\Arduino or C:\Program Files (x86)\Arduino.
   • If you're part of the Linux master race, look somewhere like ~/Arduino.
   • Macs should also have Arduino installation locations somewhere around ~/Arduino.
   • Individual installations will differ. If you're having trouble, try Googling where is my arduino hardware folder [your operating system here].
3. Restart your Arduino IDE, if it's running.
4. Verify that the board definition was successfully added. You'll know if you were successful if you open your Arduino IDE and go to Tools > Board and see an option for Ploopy Trackball (you'll have to scroll way down).

Step 4: Set up the Arduino Nano to be a firmware programmer

In this step, we'll program the Arduino Nano with the ArduinoISP sketch so that it can program the Ploopy Trackball.

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.
3. Remove any capacitor between RST and GND on the Nano, and then 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.

Step 5: Program the Ploopy Trackball

In this step, you'll use the Arduino Nano to program the Ploopy Trackball.

1. Visit the Ploopy Trackball Github firmware page and download the entire production directory onto your computer.
   • NOTE THAT not all of the firmware versions will work on all of the boards!
   • First, check to see what kind of main board you have. Look at the board for a revision number (the board containing the sensor, the one that lies flat, not the vertical one). The code should look something like "R1.00X", where X is some number.
   • If that number is R1.004, R1.003 or, very rarely, R1.002, use the firmware in the "r1.004" branch of the code.
   • If R1.005 or higher, use the main branch.
2. If it's not running, start the Arduino IDE.
3. Open the Ploopy firmware by selecting File -> Open and selecting production.ino.
4. Ensure that a 10uF capacitor is placed between RST and GND on the Arduino Nano. (The polarity of the capacitor doesn't matter. So, if you're using an electrolytic capacitor, it doesn't matter which way you plug it in.)
5. Connect the Arduino Nano and the Ploopy PCBs via its ICSP header.
   • The Ploopy Trackball will either be completely dim, or there will be a white LED that is either very dim or very bright. Any of those are normal states.
6. In the Arduino IDE, set Tools > Board to Ploopy Trackball and Tools > Programmer to Arduino as ISP.
7. If necessary, burn the Arduino bootloader onto the Ploopy Trackball by selecting Tools > Burn Bootloader.
   • You only have to do this once. Don't do this every time you reflash the microcontroller.
8. Go to Sketch > Upload Using Programmer to upload a sketch to the Ploopy Trackball.

If the Arduino IDE reports that you successfully flashed the firmware onto the Ploopy Trackball, then you're done.

Step 6: Verify that the Ploopy Trackball is working correctly

Plug the electronics assembly into your computer. The buttons should be clicking, and if you hover your finger over the sensor, it should move the cursor.

Step 7: All done!

Congrats, you finished flashing the firmware! Give yourself a pat on the back.

You're ready to get on with this thing. Head over to 2. Electronics assembly to continue assembling your Ploopy Trackball.

Common Problems

In general, Google is going to be very helpful when trying to discover the causes of problems. That's because we're using Arduino, and Arduino is very popular. If you're having problems, take a quick look here first, then dive into the Net.

Q: When I try to program the ArduinoISP sketch onto the Arduino Nano, it fails. What's going on?

In general, the Arduino boards play very nicely with the Arduino IDE. If you can't program the Nano, there are probably some big problems. Here are a few tips:

• Ensure that the status LEDs illuminate when you plug in the Nano. If they don't, you've got some kind of power issue.
• If you've got an old Arduino Nano, try going to Tools > Board > Boards Manager. Look for the Arduino AVR Boards package, and downgrade it to version 1.6.20 or lower, then restart your IDE and trying programming again. Yes, it's a weird fix, but it fixed something for us.
• Try using a different USB cable. Alternatively, use a multimeter to verify that the connections in the cable are correct and functional.
• Try using a different Nano.
• Make sure that the Arduino Nano has it's own bootloader loaded on to it. There are instructions online for how to do this.
• Double check the IDE settings, making sure that things like Tools > Board are set correctly (should be Arduino Nano).
• Use a magnifying glass to inspect the Nano. Ensure that there aren't any stray solder connections between pins. A multimeter may help.

Q: When I try to program the Ploopy Trackball, or flash the bootloader to the Ploopy Trackball, I get an error that looks something like this:

avrdude: Device signature = 0x000000
avrdude: Yikes! Invalid device signature.
Double check connections and try again, or use -F to override
this check.

What's going on?

Hate to say it, but you probably hooked something up wrong. Generally, Device signature = 0x000000 means that the microcontroller (on the Ploopy Trackball) isn't being powered. So, either you swapped a few of the ICSP pins, or you missed a solder connection somewhere. One thing you could try to do is use a multimeter to verify whether power is being supplied to the Ploopy Trackball board.

Q: Okay, but now I'm getting an error that looks slightly different:

avrdude: Device signature = 0xffffff
avrdude: Yikes! Invalid device signature.
Double check connections and try again, or use -F to override
this check.

Huh?

If this is happening, it's likely that your hookup wire isn't making perfect contact with the header on the Ploopy board. Make sure that all of the wires are touching the holes well, and then try again.