From 34685d73feae06bf70851e27deb46790c0873f32 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Wed, 21 Aug 2019 23:46:31 +1000 Subject: [PATCH 1/8] Add Zadig 101 to docs --- docs/driver_installation_zadig.md | 38 +++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/driver_installation_zadig.md diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md new file mode 100644 index 000000000000..04cbe29e499c --- /dev/null +++ b/docs/driver_installation_zadig.md @@ -0,0 +1,38 @@ +# Bootloader Driver Installation with Zadig + +QMK presents itself to the host as a regular HID keyboard device, and as such requires no special drivers. However, in order to flash your keyboard on Windows, the bootloader device that appears when you reset the board often *does*. There is one notable exception: the Caterina bootloader, usually seen on Pro Micros, appears as a serial port instead, and does not require a driver. + +We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with Msys2 or WSL, the `qmk_install.sh` script will have asked if you want it to install the drivers for you. + +## Installation + +Place your keyboard into the bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch usually located on the underside of the board. If your keyboard has neither, try holding Escape, or Space+`B`, as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). + +Zadig will automatically detect the bootloader device: + - For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`. + - AVR keyboards flashed with the QMK-DFU bootloader will be named ` Bootloader`. + - For most ARM keyboards, it will be called `STM32 BOOTLOADER`. + +!> If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case! + +If the arrow appears green, select the driver, and click **Install Driver**. The `libusb-win32` driver will usually work for AVR, and `WinUSB` for ARM, but if you still cannot flash the board, try installing a different driver from the list. + +![Zadig with a bootloader driver correctly installed](https://i.imgur.com/b8VgXzx.png) + +Finally, unplug and replug the keyboard to make sure the new driver has been loaded. If you are using the QMK Toolbox to flash, exit and restart it too, as it can sometimes fail to recognize the driver change. + +## Recovering from Installation to Wrong Device + +If you find that you can no longer type with the keyboard, you may have installed the driver onto the keyboard itself instead of the bootloader. You can easily confirm this in Zadig - a healthy keyboard has the `HidUsb` driver installed on all of its interfaces: + +![A healthy keyboard as seen by Zadig](https://i.imgur.com/Hx0E5kC.png) + +Open the Device Manager and look for a device that looks like your keyboard. + +![The board with the wrong driver installed, in Device Manager](https://i.imgur.com/L3wvX8f.png) + +Right-click it and hit **Uninstall device**. Make sure to tick **Delete the driver software for this device** first. + +![The Device Uninstall dialog, with the "delete driver" checkbox ticked](https://i.imgur.com/aEs2RuA.png) + +Click **Action -> Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again! From ba4a0e9f00ad432e903afa7cb85f4e8c46dfc2f6 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 22 Aug 2019 00:19:23 +1000 Subject: [PATCH 2/8] Add USBasp bootloader name --- docs/driver_installation_zadig.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index 04cbe29e499c..8b5e0900cc27 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -10,6 +10,7 @@ Place your keyboard into the bootloader mode, either by hitting the `RESET` keyc Zadig will automatically detect the bootloader device: - For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`. + - USBasp bootloaders will appear as `USBasp`. - AVR keyboards flashed with the QMK-DFU bootloader will be named ` Bootloader`. - For most ARM keyboards, it will be called `STM32 BOOTLOADER`. From 041e20c035d6da621f0763b91d0366f0207e7be2 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 22 Aug 2019 02:13:26 +1000 Subject: [PATCH 3/8] Add links to the page --- docs/_summary.md | 1 + docs/faq_build.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/docs/_summary.md b/docs/_summary.md index 56184f44deb1..95286ff46ccb 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -18,6 +18,7 @@ * [Build/Compile QMK](faq_build.md) * [Debugging/Troubleshooting QMK](faq_debug.md) * [Keymap](faq_keymap.md) + * [Driver Installation with Zadig](driver_installation_zadig.md) * Detailed Guides * [Install Build Tools](getting_started_build_tools.md) diff --git a/docs/faq_build.md b/docs/faq_build.md index 3fe358edaf2e..2a6aefdce152 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -83,6 +83,8 @@ If that doesn't work, then you may need to grab the [Zadig Utility](https://zadi From here, you will need to know what type of controller the board is using. You may see it listed in the Device Manager as `ATmega32U4` device (which is an AVR board), or an `STM32` device (Which is an ARM board). For AVR boards, use `libusb-win32` for the driver. For ARM boards, use the `WinUSB` driver. Once the correct driver type has been selected, click on the `Replace Driver` button, unplug your board, plug it back in, and reset it again. +See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information. + ## WINAVR is Obsolete It is no longer recommended and may cause some problem. From 661784df208e47e642450a16285efe06b744b0f0 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 22 Aug 2019 09:40:58 +1000 Subject: [PATCH 4/8] Note the usual VIDs and PIDs for the bootloaders --- docs/driver_installation_zadig.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index 8b5e0900cc27..ec590568dd54 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -9,10 +9,10 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have Place your keyboard into the bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch usually located on the underside of the board. If your keyboard has neither, try holding Escape, or Space+`B`, as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). Zadig will automatically detect the bootloader device: - - For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`. - - USBasp bootloaders will appear as `USBasp`. - - AVR keyboards flashed with the QMK-DFU bootloader will be named ` Bootloader`. - - For most ARM keyboards, it will be called `STM32 BOOTLOADER`. + - For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`, and have a Vendor ID of `03EB`. + - USBasp bootloaders will appear as `USBasp`, with a VID/PID of `16C0:05DC`. + - AVR keyboards flashed with the QMK-DFU bootloader will be named ` Bootloader` and will also have the VID `03EB`. + - For most ARM keyboards, it will be called `STM32 BOOTLOADER`, and have a VID/PID of `0483:DF11`. !> If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case! From f9bec6ea1b08c52b3e487faf56407d811baec1ca Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 22 Aug 2019 09:43:42 +1000 Subject: [PATCH 5/8] Add "List All Devices" note, just in case --- docs/driver_installation_zadig.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index ec590568dd54..0cc87f03bf22 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -8,7 +8,7 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have Place your keyboard into the bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch usually located on the underside of the board. If your keyboard has neither, try holding Escape, or Space+`B`, as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). -Zadig will automatically detect the bootloader device: +Zadig will automatically detect the bootloader device. You may sometimes need to check **Options -> List All Devices**. - For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`, and have a Vendor ID of `03EB`. - USBasp bootloaders will appear as `USBasp`, with a VID/PID of `16C0:05DC`. - AVR keyboards flashed with the QMK-DFU bootloader will be named ` Bootloader` and will also have the VID `03EB`. From 64ef0600ae8decb0208b9bd8a0b0271caa1ae17d Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 22 Aug 2019 09:49:28 +1000 Subject: [PATCH 6/8] Talk about keyboard-specific bootloader procedures --- docs/driver_installation_zadig.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index 0cc87f03bf22..e8e368507fa2 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -7,6 +7,7 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have ## Installation Place your keyboard into the bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch usually located on the underside of the board. If your keyboard has neither, try holding Escape, or Space+`B`, as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). +Some keyboards may have specific instructions for entering the bootloader, for example the [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite) key (Escape) might be on a different key, such as Left Control. Refer to the board's README if you are unsure. Zadig will automatically detect the bootloader device. You may sometimes need to check **Options -> List All Devices**. - For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`, and have a Vendor ID of `03EB`. From 2ba6af89b65359d9bec7534a200a1ab055a578dc Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 22 Aug 2019 11:13:00 +1000 Subject: [PATCH 7/8] Send users to the new page in "Unknown Device for DFU Bootloader" section --- docs/faq_build.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/faq_build.md b/docs/faq_build.md index 2a6aefdce152..f11cb76aa2bd 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -75,16 +75,11 @@ Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices m ## Unknown Device for DFU Bootloader -Issues encountered when flashing keyboards on Windows are most often due to having the wrong drivers installed for the bootloader. +Issues encountered when flashing keyboards on Windows are most often due to having the wrong drivers installed for the bootloader, or none at all. -Re-running the installation script for MSYS2 may help (eg run `util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package. - -If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, and run it on the system. Then, you will need to reset your board into bootloader mode. After that, locate the device in question. If the device doesn't show up in the list (or nothing shows up in the list), you may need to enable the `List all devices` option in the `Options` menu. - -From here, you will need to know what type of controller the board is using. You may see it listed in the Device Manager as `ATmega32U4` device (which is an AVR board), or an `STM32` device (Which is an ARM board). For AVR boards, use `libusb-win32` for the driver. For ARM boards, use the `WinUSB` driver. Once the correct driver type has been selected, click on the `Replace Driver` button, unplug your board, plug it back in, and reset it again. - -See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information. +Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_firmware` directory in MSYS2 or WSL) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually. +If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information. ## WINAVR is Obsolete It is no longer recommended and may cause some problem. From 75c4c42042be551481b35d3327a6c7a8e351047e Mon Sep 17 00:00:00 2001 From: fauxpark Date: Fri, 23 Aug 2019 23:54:04 +1000 Subject: [PATCH 8/8] Halfkay bootloaders are also an exception here --- docs/driver_installation_zadig.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index e8e368507fa2..ccee7008ebac 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -1,6 +1,8 @@ # Bootloader Driver Installation with Zadig -QMK presents itself to the host as a regular HID keyboard device, and as such requires no special drivers. However, in order to flash your keyboard on Windows, the bootloader device that appears when you reset the board often *does*. There is one notable exception: the Caterina bootloader, usually seen on Pro Micros, appears as a serial port instead, and does not require a driver. +QMK presents itself to the host as a regular HID keyboard device, and as such requires no special drivers. However, in order to flash your keyboard on Windows, the bootloader device that appears when you reset the board often *does*. + +There are two notable exceptions: the Caterina bootloader, usually seen on Pro Micros, and the Halfkay bootloader shipped with PJRC Teensys, appear as a serial port and a generic HID device respectively, and so do not require a driver. We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with Msys2 or WSL, the `qmk_install.sh` script will have asked if you want it to install the drivers for you.