docs/isp_flashing_guide.md

   1 # ISP Flashing Guide
   2
   3 If you're having trouble flashing/erasing your board, and running into cryptic error messages like any of the following:
   4
   5     libusb: warning [darwin_transfer_status] transfer error: timed out
   6     dfu.c:844: -ETIMEDOUT: Transfer timed out, NAK 0xffffffc4 (-60)
   7     atmel.c:1627: atmel_flash: flash data dfu_download failed.
   8     atmel.c:1629: Expected message length of 1072, got -60.
   9     atmel.c:1434: Error flashing the block: err -2.
  10     ERROR
  11     Memory write error, use debug for more info.
  12     commands.c:360: Error writing memory data. (err -4)
  13
  14     dfu.c:844: -EPIPE: a) Babble detect or b) Endpoint stalled 0xffffffe0 (-32)
  15     Device is write protected.
  16     dfu.c:252: dfu_clear_status( 0x7fff4fc2ea80 )
  17     atmel.c:1434: Error flashing the block: err -2.
  18     ERROR
  19     Memory write error, use debug for more info.
  20     commands.c:360: Error writing memory data. (err -4)
  21
  22 You're likely going to need to ISP flash your board/device to get it working again. Luckily, this process is pretty straight-forward, provided you have any extra programmable keyboard, Pro Micro, or Teensy 2.0/Teensy 2.0++. There are also dedicated ISP flashers available for this, but most cost >$15, and it's assumed that if you are googling this error, this is the first you've heard about ISP flashing, and don't have one readily available (whereas you might have some other AVR board). __We'll be using a Teensy 2.0 or Pro Micro with Windows 10 in this guide__ - if you are comfortable doing this on another system, please consider editing this guide and contributing those instructions!
  23
  24 ## Software Needed
  25
  26 * [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (if using a Teensy)
  27 * QMK Toolbox (flash as usual - be sure to select the correct MCU) or `avrdude` via [WinAVR](http://www.ladyada.net/learn/avr/setup-win.html) (for Teensy & Pro Micro)
  28
  29 ## Wiring
  30
  31 This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner:
  32
  33 ### Teensy 2.0
  34
  35     Teensy B0  <-> Keyboard RESET
  36     Teensy B1  <-> Keyboard B1 (SCLK)
  37     Teensy B2  <-> Keyboard B2 (MOSI)
  38     Teensy B3  <-> Keyboard B3 (MISO)
  39     Teensy VCC <-> Keyboard VCC
  40     Teensy GND <-> Keyboard GND
  41
  42 ### Pro Micro
  43
  44     Pro Micro 10 (B6)  <-> Keyboard RESET
  45     Pro Micro 15 (B1)  <-> Keyboard B1 (SCLK)
  46     Pro Micro 16 (B2)  <-> Keyboard B2 (MOSI)
  47     Pro Micro 14 (B3)  <-> Keyboard B3 (MISO)
  48     Pro Micro VCC      <-> Keyboard VCC
  49     Pro Micro GND      <-> Keyboard GND
  50
  51 ## The ISP Firmware (now pre-compiled)
  52
  53 The only difference between the .hex files below is which pin is connected to RESET. You can use them on other boards as well, as long as you're aware of the pins being used. If for some reason neither of these pins are available, [create an issue](https://github.com/qmk/qmk_firmware/issues/new), and we can generate one for you!
  54
  55 * Teensy 2.0: [`util/teensy_2.0_ISP_B0.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) (`B0`)
  56 * Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_mico_ISP_B6_10.hex) (`B6/10`)
  57
  58 **Flash your Teenys/Pro Micro with one of these and continue - you won't need the file after flashing your ISP device.**
  59
  60 ## Just the Bootloader File
  61
  62 If you just want to get things back to normal, you can flash only a bootloader from [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util), and use your normal process to flash the firmware afterwards. Be sure to flash the correct bootloader for your chip:
  63
  64 * [`atmega32u4`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) - Most keyboards, Planck Rev 1-5, Preonic Rev 1-2
  65 * [`at90usb1286`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128x_1_0_1.hex) - Planck Light Rev 1
  66
  67 If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU =` line will have the value you need. It may differ between different versions of the board.
  68
  69 ### Advanced/Production Techniques
  70
  71 If you'd like to flash both the bootloader **and** the regular firmware at the same time, you need to combine the files.
  72
  73 1. Open the original firmware .hex file in a text editor
  74 2. Remove the last line (which should be `:00000001FF` - this is an EOF message)
  75 3. Copy the entire bootloader's contents onto a new line (with no empty lines between) and paste it at the end of the original file
  76 4. Save it as a new file by naming it `<keyboard>_<keymap>_production.hex`
  77
  78 It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to use ISP again to write new firmware to your keyboard.
  79
  80 ## Flashing Your Bootloader/Production File
  81
  82 Make sure your keyboard is unplugged from any device, and plug in your Teensy.
  83
  84 ### QMK Toolbox
  85
  86 1. `AVRISP device connected` will show up in yellow
  87 2. Select the correct bootloader/production .hex file with the `Open` dialog (spaces can't be in the path)
  88 3. Be sure the correct `Microcontroller` option is selected
  89 4. Hit `Flash`
  90 5. Wait, as nothing will output for a while, especially with production files
  91
  92 If the verification and fuse checks are ok, you're done! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
  93
  94 ### Command Line
  95
  96 Open `cmd` and navigate to your where your modified .hex file is. We'll pretend this file is called `main.hex`, and that your Teensy 2.0 is on the `COM3` port - if you're unsure, you can open your Device Manager, and look for `Ports > USB Serial Device`. Use that COM port here. You can confirm it's the right port with:
  97
  98     avrdude -c avrisp -P COM3 -p atmega32u4
  99
 100 and you should get something like the following output:
 101
 102     avrdude: AVR device initialized and ready to accept instructions
 103
 104     Reading | ################################################## | 100% 0.02s
 105
 106     avrdude: Device signature = 0x1e9587
 107
 108     avrdude: safemode: Fuses OK
 109
 110     avrdude done.  Thank you.
 111
 112 Since our keyboard uses an `atmega32u4` (common), that is the chip we'll specify. This is the full command:
 113
 114     avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i
 115
 116 You should see a couple of progress bars, then you should see:
 117
 118     avrdude: verifying ...
 119     avrdude: 32768 bytes of flash verified
 120
 121     avrdude: safemode: Fuses OK
 122
 123     avrdude done.  Thank you.
 124
 125 Which means everything should be ok! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
 126
 127 If you have any questions/problems, feel free to [open an issue](https://github.com/qmk/qmk_firmware/issues/new)!