diff --git a/Appendix-C:-Firmware-programming.md b/Appendix-C:-Firmware-programming.md new file mode 100644 index 0000000..d3930e5 --- /dev/null +++ b/Appendix-C:-Firmware-programming.md @@ -0,0 +1,111 @@ +# Background +The Arduino Nano is how you're going to program your Ploopy Mouse, whether you're building your own Ploopy Mouse 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 +**TODO PIX** +- The Arduino IDE +- A base PCB with all components soldered +- An Arduino Nano +- A USB mini-B to USB A cable +- Hookup wire +- A 10uF capacitor +- A breadboard + +## Step 2: Hook up the base PCB to the Arduino Nano +**TODO PIX** +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. the microcontroller is visible). + +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) +``` + +## Step 3: Add the Ploopy Mouse board definition to the Arduino IDE +In this step, you'll add the Ploopy Mouse board definition to your install of the Arduino IDE. + +1. Visit the [Ploopy Mouse Github firmware page](https://github.com/ploopyco/mouse/tree/master/firmware) 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 Mouse` (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 Mouse. + +**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. + - The Ploopy Mouse 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. +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 Examples). +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 Mouse +In this step, you'll use the Arduino Nano to program the Ploopy Mouse. + +1. Ensure that a 10uF capacitor is placed between RST and GND on the Arduino Nano. +2. Double-check the hookups between the Arduino Nano and the Ploopy Mouse ICSP header. +3. In the Arduino IDE, set `Tools > Board` to `Ploopy Mouse` and `Tools > Programmer` to `Arduino as ISP`. +4. If necessary, burn the Arduino bootloader onto the Ploopy Mouse by selecting `Tools > Burn Bootloader`. + - You only have to do this once. Don't do this every time you reflash the microcontroller. +5. Go to `Sketch > Upload Using Programmer` to upload a sketch to the Ploopy Mouse. + +If the Arduino IDE reports that you successfully flashed the firmware onto the Ploopy Mouse, then you're done. + +## Step 6: Verify that the Ploopy Mouse 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! +**TODO PIX completed enclosure halves** + +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 `1. Electronics Assembly` to continue assembling your Ploopy Mouse. + +# 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 Mouse, or flash the bootloader to the Ploopy Mouse, 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 Mouse) 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 Mouse board. \ No newline at end of file