updating firmware documentation

joshajohnson · Jun 27, 2020 · 2624028 · 2624028
1 parent db109c2
commit 2624028
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 15 deletions.
diff --git a/Documents/firmware-install.md b/Documents/firmware-install.md
@@ -1,24 +1,30 @@
 # Flashing Firmware
 
-These instructions are for those who are either building their own board from scratch, or have bricked their board and need to bring it back to life. 
+
+## Bootloader
+The bootloader only has to be flashed if you are building your own board from scratch, have a board purchased between June 12 and June 22 2020 which will not enter the bootloader from a software reset, or have bricked your board and need to bring it back to life.
 
 * To make life easy I recommend flashing the Arduino bootloader onto the microcontroller, however if you already have the Atmel DFU bootloader on your device, feel free to change the bootloader in `rules.mk` to `atmel-dfu` and skip the next step. 
 
 * The simplest way to flash the bootloader is to download [Arduino](https://www.arduino.cc/en/main/software) and [follow these instructions](https://learn.sparkfun.com/tutorials/installing-an-arduino-bootloader/all).
-	* You will need to select 'Arduino Leonardo' as your chosen board, and connect to the 6 exposed pads on the back of the keyboard. They follow the standard [AVR pinout](https://www.olimex.com/Products/AVR/Programmers/AVR-ICSP/resources/AVR-ICSP.gif).
+	* You will need to select 'Arduino Leonardo' as your chosen board, and connect to the 6 exposed pads on the back of the keyboard. They follow the standard [AVR pinout](https://www.olimex.com/Products/AVR/Programmers/AVR-ICSP/resources/AVR-ICSP.gif). 
+	* Pressing 2x3 male header against the pins will provide a good way to flash the board without soldering to the programming header.
 
 With the bootloader on the microcontroller, we can now flash the QMK firmware onto the device. 
 
+## QMK
 Precompiled binaries are available at `Firmware/binaries` for the keyboard if you do not want to compile it from source, and can be flashed using [QMK Toolbox](https://github.com/qmk/qmk_toolbox).
 
 To build the firmware from source: 
 
 * Follow the [Getting Started Guide](https://docs.qmk.fm/#/newbs_getting_started) for your OS to install the toolchain and required files.
 
-To confirm all keys / encoders work, we will flash test firmware which does not mask key presses first. 
-* Connect your keyboard and run `make hub16:test:flash`, or flash `hub16_test.bin` with QMK Toolbox.
+If programming theh board for the first time, we want to confirm all keys / encoders work, and will flash firmware which does not wrap the key presses. 
+* Connect your keyboard and run `make hub16:no_mod:flash`, or flash `hub16_no_mod.bin` with QMK Toolbox.
 * Follow the on screen prompts to reset your keyboard when required for the device to be flashed - the reset button is located on the back of the PCB. 
 * You can now use something conductive (tweezers, paperclip) to short out the keyswitch and encoder switch contacts to ensure all keys work, along with pressing a rotary encoder against its three pins to check its function. 
 * You should see each switch / encoder type a unique letter, if there are duplicates or no text, look for bad solder joints on the PCB, in particular the microcontroller pins and resistor packs. 
-* If all of the keys work, flash the real firmware with `make hub16:default:flash` (or `hub16_default.bin` for QMK Toolbox), and your keyboard should be good to go. 
-* If desired, check out the [Test Procedue](test-procedure.md) to confirm everything works as plnned, and the head to the [mechanical assembly](Documents/enclosure-manufacturing.md) instructions to finish your build.
+
+If all of the keys work, flash the real firmware with `make hub16:default:flash` (or `hub16_default.bin` for QMK Toolbox), and your keyboard should be good to go. 
+* If you plan to use it with VIA, run `make hub16:via:flash` (or `hub16_via.bin` for QMK Toolbox), and your keyboard should be good to go. 
+* If desired, check out the [Test Procedue](test-procedure.md) to confirm everything works as planned, and the head to the [mechanical assembly](Documents/enclosure-manufacturing.md) instructions to finish your build.
diff --git a/Documents/firmware-software-config.md b/Documents/firmware-software-config.md
@@ -28,6 +28,7 @@ RGB_VAD, RGB_VAI,  RGB_HUD,  RGB_HUI,
 RGB_SAD, RGB_SAI,  _______,  _______, 
 _______, _______,  RESET,    TD(TOGGLE_LAYER)
 ```
+__NOTE__ if your board resets without going into bootloader mode upon pressing the above reset key, you will need to either reset the board using the physical reset button on the back of the PCB instead, or reflash the bootloader following [these instructions](Documents/firmware-install.md). 
 
 ## Firmware Configuration 
 
@@ -38,21 +39,25 @@ To build your new configuration, you will need to do the following:
 * Download QMK: `git clone https://github.com/qmk/qmk_firmware --recursive`
 * Follow the [build instructions](https://docs.qmk.fm/#/getting_started_build_tools) for your OS to install the toolchain.
 
-QMK configurator / VIA is not supported due to rotary encoders [not yet being supported.](https://github.com/qmk/qmk_configurator/issues/468)
-
-The important sections of the code are oulined below:
+The important sections of the code are outlined below:
 
 | Line(s) | Description |  
 | --- | ----------- |  
 | 19 | Default modifier key |  
-| 32:33 | Behaviour of layer shift key |  
+| 32:33 | behaviour of layer shift key |  
 | 35:51| Keyboard layout and layers|  
 | 56:74| Encoder rotation behaviour|  
 
 If you want to use it without all the strange modifier key stuff, I'd suggest modifying the `no_mod` keymap, as it has all of the modifier code removed. 
 
 If you are wondering how all the layouts / layers / code stuff works, I highly recommend the [QMK Documentation](https://docs.qmk.fm/#/).
 
+## VIA Support 
+
+If you would rather use a GUI to configure the board, flash the board with the [VIA](https://caniusevia.com/) keymap (`make hub16:via:flash` or `hub16_via.bin` for QMK Toolbox), and then you will be able to configure the board in VIA.
+
+Unfortunately the rotary encoders cannot be configured from within VIA, and are set to volume / media controls out of the box. Encoder behaviour can be altered in the `/hub16/keymap/via/keymap.c` file and after flashing the board will be updated, whilst allowing the remaining keys to be programmed in VIA.
+
 ## Software Configuration 
 
 Use of the software requires understanding of whatever scripting language is being used, such as AutoHotKey, or Python if AutoKey is being used on Linux. I have provided my scripts as inspiration, and am more than happy to answer questions on how to implement features if required.

diff --git a/Documents/test-procedure.md b/Documents/test-procedure.md
@@ -6,7 +6,7 @@ This procedure is used to ensure bringup and functionality of a freshly baked PC
 * Measure continuity across C1. If shorted, locate and resolve a VCC - GND short. 
 * Measure continuity across C21. If shorted, locate and reslove a 3V3 - GND short.
 * Using a current limited bench power supply set at 5V 100 mA, connect board through J1 and confirm power draw is approximately 25 mA. If current draw is high, attempt to locate and resolve any shorts on the board. If current draw too low, ensure ICs and crystals are soldered correctly. 
-* Using an AVR programmer, flash the Arduino bootloader through the ISP header J2.
+* Using an AVR programmer, [flash the bootloader](Documents/firmware-install.md) through the ISP header J2.
 	* If unable, common causes are:
 		* Software issues - check if programming a known good device works.
 		* Poor connection - ensure your connections to J2 are good, and if using pogo pins that they operate freely. 
@@ -18,10 +18,12 @@ This procedure is used to ensure bringup and functionality of a freshly baked PC
 * Using tweezers, short pin connections and ensure all keys print a unique key to the computer.
 * Also test the rotary encoder connections by placing an encoder against the three holes and rotating in both directions.
 	* Common issues are with the diodes being installed incorrectly, and resistor networks being shorted. 
-* Flash default firmware and confirm all LEDs light up red. Double tap bottom right key (K19) and then K11 do cycle through LEDs and confirm they all function. 
+* Flash default firmware and confirm all LEDs light up red. Double tap bottom right key (K19) and then K11 (top row, 3rd from left) do cycle through LEDs and confirm they all function. 
 	* LEDs are daisy chained from D2 - D3 - D10 etc around outside of board, ensure good solder connections if LEDs stop working somewhere in the middle.
 	* If solder connections are good but LED still non functioning, ensure is it oriented correctly (triangle on LED near corner marking on PCB, NOT pin 1!)
 	* These LEDs often fail during reflow, so if LED is non functioning and remaining LEDs can be fixed by shorting out LED, replace. 
+* Check fuses have been set correctly by resetting board from software by pressing the "RESET" key on layer two of the board (bottom row, 3rd from left).
+   * With `dmesg-w` or device manager running, ensure "Arduino Leonardo" is seen enumerating before "Hub16" appears. If this fails reflash the bootloader following [these instructions](Documents/firmware-install.md)
 * Confirm all downstream USB ports function by connecting a device to each port, ensuring to rotate 180 degrees, and checking it appears on computer each time. 
 	* Common issues are with shorts on the USB hub, along with data pins on connector.
 	* If device only works in one orientation, check power pins of connector are soldered down well. 

diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ All design files required to manufacture the board and enclosure are located in
 
 ## Key Features
 * 16 Cherry MX compatible switches, along with two switches in the encoders. 
-* Two rotary encoders, bringing an intuitive interface for continous controls such as grid size and volume.
+* Two rotary encoders, bringing an intuitive interface for continuous controls such as grid size and volume.
 * Four port USB 2.0 hub with Type-C connectors, allowing connection to other keyboards, memory sticks, wireless receivers and more! 
 * Designed to interface with host computer to provide a level of interaction / macro control not available on standard keyboards, with examples provided for Windows, macOS, and Linux.
 * Various case designs, allowing the Hub16 to fit in on any desk. 
@@ -28,11 +28,14 @@ All design files required to manufacture the board and enclosure are located in
 * [Firmware Flashing Instructions](Documents/firmware-install.md)
 * [Enclosure Manufacturing](Documents/enclosure-manufacturing.md)
 
-### Errata
-* Some rotary encoders output flipped signals (clockwise instead of counterclockwise), if after assembly your encoders appear to be sending the wrong signals, comment in line 84 in [config.h](Firmware/hub16/config.h), or alter the setting in your [software](Software).
+### Errata / Changelog
+* Boards purchased between June 12 and June 22 2020 will not go into the bootloader upon resting from software. Workaround: reset board with physical reset button under board. Fix: reflash the bootloader following [these instructions](Documents/firmware-install.md).
 
+* Firmware builds prior to 27th June do not continually send characters when the encoders are depressed. Update to the latest firmware to resolve.
 * Firmware builds prior to 9th June have issues with the bottom right key `p` not functioning correctly. Update to the latest firmware to resolve.
 
+* Some rotary encoders output flipped signals (clockwise instead of counterclockwise), if after assembly your encoders appear to be sending the wrong signals, comment in line 84 in [config.h](Firmware/hub16/config.h), or alter the setting in your [software](Software).
+
 * Long USB cables (> 2m) may not work with the keyboard. If the keyboard is not detected, or power cycles (can often be seen by LEDs flashing on and off), please try a shorter cable.
 
 If you have any questions or comments please get in touch. I can be found on Discord as `_joshajohnson#9451`, [Twitter](https://twitter.com/_joshajohnson), and [r/mk](https://www.reddit.com/user/_joshajohnson).