Add 'bootloadHID' flash target (#5587)

* Add 'bootloadHID' flash target

* Prep for flash target

* Add :flash support

* Align bootloader wait messages

Co-Authored-By: Drashna Jaelre <drashna@live.com>

* Update template to suggest use of :flash

docs/flashing.md

@@ -144,6 +144,36 @@ Flashing sequence:
 3. Flash a .hex file
 4. Reset the device into application mode (may be done automatically)
 
+## BootloadHID
+
+BootloadHID is a USB bootloader for AVR microcontrollers. The uploader tool requires no kernel level driver on Windows and can therefore be run without installing any DLLs.
+
+To ensure compatibility with the bootloadHID bootloader, make sure this block is present your `rules.mk`:
+
+    # Bootloader
+    #     This definition is optional, and if your keyboard supports multiple bootloaders of
+    #     different sizes, comment this out, and the correct address will be loaded
+    #     automatically (+60). See bootloader.mk for all options.
+    BOOTLOADER = bootloadHID
+
+Compatible flashers:
+
+* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (recommended Windows GUI)
+* [bootloadhid Command Line](https://www.obdev.at/products/vusb/bootloadhid.html) / `:BootloadHID` in QMK (recommended command line)
+
+Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `RESET` keycode (may not work on all devices)
+    * Hold the salt key while plugging the keyboard in (usually documented within keyboard readme) 
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+or:
+
+    make <keyboard>:<keymap>:bootloadHID
+
 ## STM32
 
 All STM32 chips come preloaded with a factory bootloader that cannot be modified nor deleted. Some STM32 chips have bootloaders that do not come with USB programming (e.g. STM32F103) but the process is still the same.

docs/flashing_bootloadhid.md

@@ -0,0 +1,70 @@
+# BootloadHID Flashing Instructions and Bootloader Information
+
+ps2avr(GB) boards use an ATmega32A microcontroller and a different bootloader. It is not flashable using the regular QMK methods.
+
+General flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `RESET` keycode (may not work on all devices)
+    * Hold the salt key while plugging the keyboard in (usually documented within keyboard readme) 
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+## bootloadHID Flashing Target
+
+Using the QMK installation script, detailed [here](newbs_getting_started.md), the required bootloadHID tools should be automatically installed.
+
+To flash via the command line, use the target `:bootloadHID` by executing the following command:
+
+    make <keyboard>:<keymap>:bootloadHID
+
+## GUI Flashing
+
+### Windows
+1. Download [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash).
+2. Place your keyboard into reset. 
+3. Ensure the configured VendorID is `16c0` and ProductID is `05df`
+4. Press the `Find Device` button and ensure that your keyboard is found.
+5. Press the `Open .hex File` button and locate the `.hex` file you created.
+6. Press the `Flash Device` button and wait for the process to complete.
+
+## Command Line Flashing
+
+1. Place your keyboard into reset. 
+2. Flash the board by typing `bootloadHID -r` followed by the path to your `.hex` file.
+
+### Windows Manual Installation
+For MSYS2:
+1. Download the BootloadHID firmware package from https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz.
+2. Extract contents using a compatible tool, for example 7-Zip.
+3. Add to the MSYS path by copying `commandline/bootloadHID.exe` from the extracted archive to your MSYS2 installation, typically `C:\msys64\usr\bin`.
+
+For native Windows flashing, the `bootloadHID.exe` can be used outside of the MSYS2 environment.
+
+### Linux Manual Installation
+1. Install libusb development dependency:
+    ```bash
+    # This depends on OS - for Debian the following works
+    sudo apt-get install libusb-dev
+    ```
+2. Download the BootloadHID firmware package:
+    ```
+    wget https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz -O - | tar -xz -C /tmp
+    ```
+3. Build the bootloadHID executable:
+    ```
+    cd /tmp/bootloadHID.2012-12-08/commandline/
+    make
+    sudo cp bootloadHID /usr/local/bin
+    ```
+
+### MacOS Manual Installation
+1. Install Homebrew by typing the following:
+    ```
+    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+    ```
+2. Install the following packages:
+    ```
+    brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb
+    ```

docs/getting_started_make_guide.md

@@ -14,7 +14,7 @@ The full syntax of the `make` command is `<keyboard_folder>:<keymap>:<target>`,
 The `<target>` means the following
 * If no target is given, then it's the same as `all` below
 * `all` compiles as many keyboard/revision/keymap combinations as specified. For example, `make planck/rev4:default` will generate a single .hex, while `make planck/rev4:all` will generate a hex for every keymap available to the planck.
-* `dfu`, `teensy`, `avrdude` or `dfu-util`, compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme.
+* `dfu`, `teensy`, `avrdude`, `dfu-util` or `bootloadHID`, compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme.
  * **Note**: some operating systems need root access for these commands to work, so in that case you need to run for example `sudo make planck/rev4:default:dfu`.
 * `clean`, cleans the build output folders to make sure that everything is built from scratch. Run this before normal compilation if you have some unexplainable problems.
 

docs/newbs_flashing.md

@@ -248,6 +248,42 @@ Programming.....................................................................
 Booting
 ```
 
+## BootloadHID
+
+For Bootmapper Client(BMC)/bootloadHID/ATmega32A based boards, when you're ready to compile and flash your firmware, open up your terminal window and run the build command: 
+
+    make <my_keyboard>:<my_keymap>:bootloaderHID
+
+For example, if your keymap is named "xyverz" and you're building a keymap for a jj40, you'll use this command:
+
+    make jj40:xyverz:bootloaderHID
+
+Once the firmware finishes compiling, it will output something like this: 
+
+```
+Linking: .build/jj40_default.elf                                                                   [OK]
+Creating load file for flashing: .build/jj40_default.hex                                           [OK]
+Copying jj40_default.hex to qmk_firmware folder                                                    [OK]
+Checking file size of jj40_default.hex                                                             [OK]
+ * The firmware size is fine - 21920/28672 (6752 bytes free)
+```
+
+After it gets to this point, the build script will look for the DFU bootloader every 5 seconds.  It will repeat the following until the device is found or you cancel it. 
+
+```
+Error opening HIDBoot device: The specified device was not found
+Trying again in 5s.
+```
+
+Once it does this, you'll want to reset the controller.  It should then show output similar to this: 
+
+```
+Page size   = 128 (0x80)
+Device size = 32768 (0x8000); 30720 bytes remaining
+Uploading 22016 (0x5600) bytes starting at 0 (0x0)
+0x05580 ... 0x05600
+```
+
 ## STM32 (ARM)
 
 For a majority of ARM boards (including the Proton C, Planck Rev 6, and Preonic Rev 3), when you're ready to compile and flash your firmware, open up your terminal window and run the build command: 

quantum/template/ps2avrgb/readme.md

@@ -12,35 +12,10 @@ Make example for this keyboard (after setting up your build environment):
 
     make %KEYBOARD%:default
 
-Flashing
+Flashing example for this keyboard ([after setting up the bootloadHID flashing environment](flashing_bootloadhid.md))
 
-ps2avr(GB) boards use an atmega32a microcontroller and a different bootloader. It is not flashable using the regular QMK methods. 
+    make %KEYBOARD%:default:flash
 
-**Reset Key:** Hold down the key located at `K00`, commonly programmed as `Esc` while plugging in the keyboard.
+**Reset Key**: Hold down the key located at *LOCATION*, commonly programmed as *KEY* while plugging in the keyboard.
-
-Windows: 
-1. Download [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash).
-2. Place your keyboard into reset. 
-3. Press the `Find Device` button and ensure that your keyboard is found.
-4. Press the `Open .hex File` button and locate the `.hex` file you created.
-5. Press the `Flash Device` button and wait for the process to complete. 
-
-macOS:
-1. Install homebrew by typing the following:   
-    ```
-    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-    ```
-2. Install `crosspack-avr`.  
-    ```
-    brew cask install crosspack-avr
-    ```
-3. Install the following packages:
-    ```
-    brew install python3
-    pip3 install pyusb
-    brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb
-    ```
-4. Place your keyboard into reset. 
-5. Flash the board by typing `bootloadHID -r` followed by the path to your `.hex` file. 
 
 See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).

tmk_core/avr.mk

@@ -246,6 +246,19 @@ endef
 usbasp: $(BUILD_DIR)/$(TARGET).hex check-size cpfirmware
 	$(call EXEC_USBASP)
 
+BOOTLOADHID_PROGRAMMER ?= bootloadHID
+
+define EXEC_BOOTLOADHID
+	# bootloadHid executable has no cross platform detect methods
+	# so keep running bootloadHid if the output contains "The specified device was not found"
+	until $(BOOTLOADHID_PROGRAMMER) -r $(BUILD_DIR)/$(TARGET).hex 2>&1 | tee /dev/stderr | grep -v "device was not found"; do\
+		echo "Error: Bootloader not found. Trying again in 5s." ;\
+		sleep 5 ;\
+	done
+endef
+
+bootloadHID: $(BUILD_DIR)/$(TARGET).hex check-size cpfirmware
+	$(call EXEC_BOOTLOADHID)
 
 # Convert hex to bin.
 bin: $(BUILD_DIR)/$(TARGET).hex
@@ -331,6 +344,8 @@ else ifeq (dfu,$(findstring dfu,$(BOOTLOADER)))
 	$(call EXEC_DFU)
 else ifeq ($(strip $(BOOTLOADER)), USBasp)
 	$(call EXEC_USBASP)
+else ifeq ($(strip $(BOOTLOADER)), bootloadHID)
+	$(call EXEC_BOOTLOADHID)
 else
 	$(PRINT_OK); $(SILENT) || printf "&(MSG_FLASH_BOOTLOADER)"
 endif