[jackhill/qmk/firmware.git] / docs / isp_flashing_guide.md

# ISP Flashing Guide

If you're having trouble flashing/erasing your board, and running into cryptic error messages like any of the following:

    libusb: warning [darwin_transfer_status] transfer error: timed out
    dfu.c:844: -ETIMEDOUT: Transfer timed out, NAK 0xffffffc4 (-60)
    atmel.c:1627: atmel_flash: flash data dfu_download failed.
    atmel.c:1629: Expected message length of 1072, got -60.
    atmel.c:1434: Error flashing the block: err -2.
    ERROR
    Memory write error, use debug for more info.
    commands.c:360: Error writing memory data. (err -4)

    dfu.c:844: -EPIPE: a) Babble detect or b) Endpoint stalled 0xffffffe0 (-32)
    Device is write protected.
    dfu.c:252: dfu_clear_status( 0x7fff4fc2ea80 )
    atmel.c:1434: Error flashing the block: err -2.
    ERROR
    Memory write error, use debug for more info.
    commands.c:360: Error writing memory data. (err -4)

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!   

## Software Needed

* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (if using a Teensy)
* 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)

## Wiring

This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner:

### Teensy 2.0

    Teensy B0  <-> Keyboard RESET
    Teensy B1  <-> Keyboard B1 (SCLK)
    Teensy B2  <-> Keyboard B2 (MOSI)
    Teensy B3  <-> Keyboard B3 (MISO)
    Teensy VCC <-> Keyboard VCC
    Teensy GND <-> Keyboard GND
    
### Pro Micro

    Pro Micro 10 (B6)  <-> Keyboard RESET
    Pro Micro 15 (B1)  <-> Keyboard B1 (SCLK)
    Pro Micro 16 (B2)  <-> Keyboard B2 (MOSI)
    Pro Micro 14 (B3)  <-> Keyboard B3 (MISO)
    Pro Micro VCC      <-> Keyboard VCC
    Pro Micro GND      <-> Keyboard GND

## The ISP Firmware (now pre-compiled)

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!

* 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`)
* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`B6/10`)

**Flash your Teenys/Pro Micro with one of these and continue - you won't need the file after flashing your ISP device.**

## Just the Bootloader File

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:

* [`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
* [`at90usb1286`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128x_1_0_1.hex) - Planck Light Rev 1
* [`atmega32a`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32a_1_0_0.hex) - jj40

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.

### Advanced/Production Techniques

If you'd like to flash both the bootloader **and** the regular firmware at the same time, you need to combine the files. 

1. Open the original firmware .hex file in a text editor
2. Remove the last line (which should be `:00000001FF` - this is an EOF message)
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
4. Save it as a new file by naming it `<keyboard>_<keymap>_production.hex`

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.

## Flashing Your Bootloader/Production File

Make sure your keyboard is unplugged from any device, and plug in your Teensy.

### QMK Toolbox

1. `AVRISP device connected` will show up in yellow
2. Select the correct bootloader/production .hex file with the `Open` dialog (spaces can't be in the path)
3. Be sure the correct `Microcontroller` option is selected
4. Hit `Flash`
5. Wait, as nothing will output for a while, especially with production files

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.

### Command Line

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:

    avrdude -c avrisp -P COM3 -p atmega32u4

and you should get something like the following output:

    avrdude: AVR device initialized and ready to accept instructions

    Reading | ################################################## | 100% 0.02s

    avrdude: Device signature = 0x1e9587

    avrdude: safemode: Fuses OK

    avrdude done.  Thank you.

Since our keyboard uses an `atmega32u4` (common), that is the chip we'll specify. This is the full command:

    avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i

If your board uses an `atmega32a` (e.g. on a jj40), the command is this (the extra code at the end sets the fuses correctly):

	avrdude -c avrisp -P COM3 -p atmega32 -U flash:w:main.hex:i -U hfuse:w:0xD0:m -U lfuse:w:0x0F:m

You should see a couple of progress bars, then you should see:

    avrdude: verifying ...
    avrdude: 32768 bytes of flash verified

    avrdude: safemode: Fuses OK

    avrdude done.  Thank you.

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.

If you have any questions/problems, feel free to [open an issue](https://github.com/qmk/qmk_firmware/issues/new)!
Commit	Line	Data
b4f2f44a JH	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.
bb53635f	20	commands.c:360: Error writing memory data. (err -4)
bb53635f	21
ac46378a	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!
b4f2f44a	23
7b0356d1	24	## Software Needed
b4f2f44a	25
ac46378a JH	26	* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (if using a Teensy)
ac46378a JH	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)
b4f2f44a JH	28
	29	## Wiring
	30
	31	This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner:
	32
ac46378a	33	### Teensy 2.0
bb53635f	34
ac46378a JH	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
b4f2f44a	43
ac46378a JH	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)
b4f2f44a	52
ac46378a	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!
b4f2f44a	54
ac46378a	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`)
5dcb1114	56	* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`B6/10`)
b4f2f44a	57
ac46378a	58	Flash your Teenys/Pro Micro with one of these and continue - you won't need the file after flashing your ISP device.
b4f2f44a	59
ac46378a	60	## Just the Bootloader File
b4f2f44a	61
ac46378a	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:
b4f2f44a	63
ac46378a JH	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
ac46378a JH	65	* [`at90usb1286`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128x_1_0_1.hex) - Planck Light Rev 1
1dda671e	66	* [`atmega32a`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32a_1_0_0.hex) - jj40
bb53635f	67
ac46378a	68	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.
b4f2f44a	69
ac46378a	70	### Advanced/Production Techniques
b4f2f44a	71
ac46378a	72	If you'd like to flash both the bootloader and the regular firmware at the same time, you need to combine the files.
b4f2f44a	73
ac46378a JH	74	1. Open the original firmware .hex file in a text editor
	75	2. Remove the last line (which should be `:00000001FF` - this is an EOF message)
	76	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
	77	4. Save it as a new file by naming it `<keyboard>_<keymap>_production.hex`
b4f2f44a	78
ac46378a JH	79	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.
	80
	81	## Flashing Your Bootloader/Production File
b4f2f44a JH	82
	83	Make sure your keyboard is unplugged from any device, and plug in your Teensy.
	84
ac46378a JH	85	### QMK Toolbox
	86
	87	1. `AVRISP device connected` will show up in yellow
	88	2. Select the correct bootloader/production .hex file with the `Open` dialog (spaces can't be in the path)
	89	3. Be sure the correct `Microcontroller` option is selected
	90	4. Hit `Flash`
	91	5. Wait, as nothing will output for a while, especially with production files
	92
	93	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.
	94
	95	### Command Line
	96
b4f2f44a JH	97	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:
	98
	99	avrdude -c avrisp -P COM3 -p atmega32u4
bb53635f	100
b4f2f44a JH	101	and you should get something like the following output:
	102
	103	avrdude: AVR device initialized and ready to accept instructions
	104
	105	Reading \| ################################################## \| 100% 0.02s
	106
	107	avrdude: Device signature = 0x1e9587
	108
	109	avrdude: safemode: Fuses OK
	110
	111	avrdude done. Thank you.
	112
	113	Since our keyboard uses an `atmega32u4` (common), that is the chip we'll specify. This is the full command:
	114
bb53635f	115	avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i
bb53635f	116
1dda671e	117	If your board uses an `atmega32a` (e.g. on a jj40), the command is this (the extra code at the end sets the fuses correctly):
	118
	119	avrdude -c avrisp -P COM3 -p atmega32 -U flash:w:main.hex:i -U hfuse:w:0xD0:m -U lfuse:w:0x0F:m
	120
b4f2f44a JH	121	You should see a couple of progress bars, then you should see:
	122
	123	avrdude: verifying ...
	124	avrdude: 32768 bytes of flash verified
	125
	126	avrdude: safemode: Fuses OK
	127
	128	avrdude done. Thank you.
bb53635f	129
b4f2f44a JH	130	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.
	131
	132	If you have any questions/problems, feel free to [open an issue](https://github.com/qmk/qmk_firmware/issues/new)!