Add a newbie guide for people completely new to QMK (#2480)

docs/_summary.md

@@ -3,9 +3,16 @@
   * [Install Build Tools](getting_started_build_tools.md)
     * Alternative: [Vagrant Guide](getting_started_vagrant.md)
   * [Build/Compile Instructions](getting_started_make_guide.md)
-  * [Flashing Instructions](flashing.md)
+  * [Flashing Firmware](flashing.md)
   * [Contributing to QMK](contributing.md)
   * [How to Use Github](getting_started_github.md)
+  * [Getting Help](getting_started_getting_help.md)
+
+* [Complete Newbs Guide](newbs.md)
+  * [Getting Started](newbs_getting_started.md)
+  * [Building Your First Firmware](newbs_building_firmware.md)
+  * [Flashing Firmware](newbs_flashing.md)
+  * [Testing and Debugging](newbs_testing_debugging.md)
 
 * [FAQ](faq.md)
   * [General FAQ](faq_general.md)

docs/getting_started_getting_help.md

@@ -0,0 +1,21 @@
+# Getting Help
+
+There are a lot of resources for getting help with QMK.
+
+## Realtime Chat
+
+You can find QMK developers and users on our main [gitter chat room](https://gitter.im/qmk/qmk_firmware). We also have other rooms for more specific discussion:
+
+* [Main Firmware Chat](https://gitter.im/qmk/qmk_firmware)
+* [QMK Toolbox](https://gitter.im/qmk/qmk_toolbox)
+* [Hardware Design Discussion](https://gitter.im/qmk/qmk_hardware)
+* [Web Configurator](https://gitter.im/qmk/qmk_configurator)
+* [Compiler API](https://gitter.im/qmk/qmk_compiler_api)
+
+## OLKB Subreddit
+
+The official QMK forum is [/r/olkb](https://reddit.com/r/olkb) on [reddit.com](https://reddit.com).
+
+## Github Issues
+
+You can open an [issue on GitHub](https://github.com/qmk/qmk_firmware/issues). This is especially handy when your issue will require long-term discussion or debugging.

docs/newbs.md

@@ -0,0 +1,21 @@
+# The Compelete Newbs Guide To QMK
+
+QMK is a powerful Open Source firmware for your mechanical keyboard. You can use QMK to customize your keyboard in ways both simple and powerful. People of all skill levels, from complete newbie to master programmer, have successfully used QMK to customize their keyboard. This guide will help you do the same, no matter your skill level.
+
+Not sure if your keyboard can run QMK? If it's a mechanical keyboard you built yourself chances are good it can. We support a [large number of hobbyist boards](http://qmk.fm/keyboards/), so even if your current keyboard can't run QMK you shouldn't have trouble finding one to suit your needs.
+
+We assume you are familiar with the basics of working in a Linux/Unix command line environment. If you are not these resources will teach you enough to work with QMK:
+
+* [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)
+* [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
+
+## Overview
+
+There are 4 main sections to this guide:
+
+* [Getting Started](newbs_getting_started.md)
+* [Building Your First Firmware](newbs_building_firmware.md)
+* [Flashing Firmware](newbs_flashing.md)
+* [Testing and Debugging](newbs_testing_debugging.md)
+
+This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md).

docs/newbs_building_firmware.md

@@ -0,0 +1,49 @@
+# Building Your First Firmware
+
+Now that you have setup your build environment you are ready to start building custom firmware. For this section of the guide we will bounce between 3 programs- your file manager, your text editor, and your terminal window. Keep all 3 open until you are done and happy with your keyboard firmware.
+
+If you have closed and reopened your terminal window since following the first part of the guide, don't forget to `cd qmk_firmware` so that your terminal is in the correct directory.
+
+## Navigate To Your Keymaps Folder
+
+Start by navigating to the `keymaps` folder for your keyboard.
+
+{% hint style='info' %}
+If you are on macOS or Windows there are commands you can use to easily open the `keymaps` folder.
+
+macOS:
+
+    open keyboards/<keyboard_folder>/keymaps
+
+Windows:
+
+    start keyboards/<keyboard_folder>/keymaps
+{% endhint %}
+
+## Create a Copy Of The `default` Keymap
+
+Once you have the `keymaps` folder open you will want to create a copy of the `default` folder. We highly recommend you name your folder the same as your github username, but you can use any name you want as long as it contains only lower case letters, numbers, and the underscore character.
+
+## Open `keymap.c` In Your Favorite Text Editor
+
+Inside the `keymap.c` file you'll find the structure that controls how your keyboard behaves. At the top there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:
+
+    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a that particular layer.
+
+{% hint style='warning' %}
+When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
+{% endhint %}
+
+## Customize The Layout To Your Liking
+
+How to complete this step is entirely up to you. Make the one change that's been bugging you, or completely rework everything. You can remove layers if you don't need all of them, or add layers up to a total of 32. Check the following documentation to find out what you can define here:
+
+* [Keycodes](keycodes.md)
+* [Features](features.md)
+* [FAQ](faq.md)
+
+{% hint style='info' %}
+While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
+{% endhint %}

docs/newbs_flashing.md

@@ -0,0 +1,79 @@
+# Flashing Your Keyboard With QMK Toolbox
+
+Now that you've built a custom firmware file you'll want to flash your keyboard. 
+
+## Load The File Into QMK Toolbox
+
+Begin by opening the QMK Toolbox application. You'll want to locate the firmware file in Finder or Explorer. Your keyboard firmware may be in one of two formats- `.hex` or `.bin`. QMK tries to copy the appropriate one for your keyboard into the root `qmk_firmware` directory.
+
+{% hint style='info' %}
+If you are on Windows or macOS there are commands you can use to easily open the current firmware folder in Explorer or Finder.
+
+Windows:
+
+    start .
+
+macOS:
+
+    open .
+{% endhint %}
+
+The firmware file always follows this naming format:
+
+    <keyboard_name>_<keymap_name>.{bin,hex}
+
+For example, the `plank/rev5` with a `default` keymap will have this filename:
+
+    planck_rev5_default.hex
+
+Once you have located your firmware file drag it into the "Local file" box in QMK Toolbox, or click "Open" and navigate to where your firmware file is stored. 
+
+## Put Your Keyboard Into DFU (Bootloader) Mode
+
+In order to flash your custom firmware you have to put your keyboard into a special flashing mode. While it is in this mode you will not be able to type or otherwise use your keyboard. It is very important that you do not unplug your keyboard or otherwise interrupt the flashing process while the firmware is being written.
+
+Different keyboards have different ways to enter this special mode. If your PCB currently runs QMK or TMK and you have not been given specific instructions try the following, in order:
+
+* Hold down both shift keys and press `Pause`
+* Hold down both shift keys and press `B`
+* Unplug your keyboard, hold down the Spacebar and `B` at the same time, plug in your keyboard and wait a second before releasing the keys
+* Press the physical `RESET` button on the bottom of the PCB
+* Locate header pins on the PCB labeled `BOOT0` or `RESET`, short those together while plugging your PCB in
+
+When you are successful you will see a message similar to this in QMK Toolbox:
+
+```
+*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
+*** DFU device connected
+```
+
+## Flash Your Keyboard
+
+Click the `Flash` button in QMK Toolbox. You will see output similar to the following:
+
+```
+*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
+*** DFU device connected
+*** Attempting to flash, please don't remove device
+>>> dfu-programmer atmega32u4 erase --force
+    Erasing flash...  Success
+    Checking memory from 0x0 to 0x6FFF...  Empty.
+>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
+    Checking memory from 0x0 to 0x55FF...  Empty.
+    0%                            100%  Programming 0x5600 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    0%                            100%  Reading 0x7000 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    Validating...  Success
+    0x5600 bytes written into 0x7000 bytes memory (76.79%).
+>>> dfu-programmer atmega32u4 reset
+    
+*** DFU device disconnected
+*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
+```
+
+## Test It Out!
+
+Congrats! Your custom firmware has been programmed to your keyboard!
+
+Give it a try and make sure everything works the way you want it to. We've written [Testing and Debugging](newbs_testing_debugging.md) to round out this Newbie Guide, so head over there to learn about how to troubleshoot your custom functionality.

docs/newbs_getting_started.md

@@ -0,0 +1,77 @@
+# Introduction
+
+Your computer keyboard has a processor inside of it, not unlike the one inside your computer. This processor runs software that is responsible for detecting button presses and sending reports about the state of the keyboard when they are pressed or released. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom layout you are creating the equivalent of an .exe for your keyboard.
+
+QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful layouts, you only have to follow a few simple syntax rules. 
+
+# Getting Started
+
+Before you can build keymaps you need to setup your build environment. This only has to be done one time no matter how many keyboards you want to compile firmware for.
+
+## Download QMK Toolbox
+
+QMK Toolbox is a Windows and macOS program that allows you to both program and debug your custom keyboard. You will want to install it so that you can easily flash your keyboard and receive the debugging messages that your keyboard will print.
+
+* [Newest Release](https://github.com/qmk/qmk_toolbox/releases/latest)
+* [Source Code](https://github.com/qmk/qmk_toolbox/)
+
+## Environment Setup
+
+We've tried to make QMK as easy to setup as possible. You only have to prepare your Linux or Unix environment and let QMK install the rest.
+
+### Windows
+
+You will need to install msys2 and git.
+
+* Follow the installation instructions on the msys2 homepage: http://www.msys2.org
+* Close any open msys2 terminals, and open a new terminal
+* Install git by running this command: `pacman -S git`
+
+### macOS
+
+You will need to install homebrew. Follow the instructions on the homebrew homepage: https://brew.sh
+
+### Linux
+
+You will need to install git. It's extremely likely you already have it, but if not one of the following commands should install it:
+
+* Debian/Ubuntu/Devuan: `apt-get install git`
+* Fedora/Redhat/Centos: `yum install git`
+* Arch: `pacman -S git`
+
+## Download QMK
+
+Once you have setup your Linux/Unix environment you are ready to download QMK. We will do this by using git to "clone" the QMK repository. Open a Terminal or MSYS2 Console window and leave it open for the remainder of this guide. Inside that window run these two commands:
+
+* `git clone https://github.com/qmk/qmk_firmware.git`
+* `cd qmk_firmware`
+
+{% hint style='info' %}
+If you already know [how to use GitHub](getting_started_github.md) we recommend you create and clone your own fork instead. If you don't know what that means you can safely ignore this message.
+{% endhint %}
+
+## Setup QMK
+
+QMK comes with a script to help you setup the rest of what you'll need. You should run it now:
+
+* `./util/qmk_install.sh`
+
+## Test Your Build Environment
+
+Now that your QMK build environment is setup you can build a firmware for your keyboard. Start by trying to build the default layout for your keyboard. You should be able to do that with a command in this format:
+
+* `make <keyboard>:default`
+
+For example, to build a firmware for a Clueboard 66% use:
+
+* `make clueboard/66:default`
+
+When it is done you should have a lot of output that ends similar to this:
+
+```
+Linking: .build/clueboard_66_rev2_default.elf                                                       [OK]
+Creating load file for flashing: .build/clueboard_66_rev2_default.hex                               [OK]
+Copying clueboard_66_rev2_default.hex to qmk_firmware folder                                        [OK]
+Checking file size of clueboard_66_rev2_default.hex                                                 [OK]
+ * File size is fine - 25174/28672
+```

docs/newbs_testing_debugging.md

@@ -0,0 +1,33 @@
+# Testing and Debugging
+
+Once you've flashed your keyboard with a custom firmware you're ready to test it out. With a little bit of luck everything will work perfectly, but if not this document will help you figure out what's wrong.
+
+## Testing
+
+Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. There are even programs that will help you make sure that no key is missed.
+
+Note: These programs are not provided by or endorsed by QMK.
+
+* [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Windows Only)
+* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Mac Only)
+* [Keyboard Tester](http://www.keyboardtester.com) (Web Based)
+* [Keyboard Checker](http://keyboardchecker.com) (Web Based)
+
+## Debugging With QMK Toolbox
+
+[QMK Toolbox](https://github.com/qmk/qmk_toolbox) will show messages from your keyboard if you have `CONSOLE_ENABLE = yes` in your `rules.mk`. By default the output is very limited, but you can turn on debug mode to increase the amount of debug output. Use the `DEBUG` keycode in your keymap, or use the [Command](feature_command.md) feature to enable debug mode.
+
+<!-- FIXME: Describe the debugging messages here. -->
+
+## Sending Your Own Debug Messages
+
+Sometimes it's useful to print debug messages from within your [custom code](custom_quantum_functions.md). Doing so is pretty simple. Start by including `print.h` at the top of your file:
+
+    #include <print.h>
+
+After that you can use a few different print functions:
+
+* `print("string")`: Print a simple string.
+* `sprintf("%s string", var)`: Print a formatted string
+* `dprint("string")` Print a simple string, but only when debug mode is enabled
+* `dprintf("%s string", var)`: Print a formatted string, but only when debug mode is enabled

docs/redirects.json

@@ -16,6 +16,10 @@
                 "from": "feature_common_shortcuts.html",
                 "to": "feature_advanced_keycodes.html"
             },
+            {
+                "from": "flashing.html",
+                "to": "newbs_flashing.html"
+            },
             {
                 "from": "key_lock.html",
                 "to": "feature_key_lock.html"

util/linux_install.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+if grep ID /etc/os-release | grep -q rhel; then
+	# RPM based OS
+	sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc \
+	    avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs \
+	    arm-none-eabi-binutils-cs arm-none-eabi-newlib
+elif grep ID /etc/os-release | grep -q debian; then
+	sudo apt-get update
+	sudo apt-get install gcc unzip wget zip gcc-avr binutils-avr avr-libc \
+	    dfu-programmer dfu-util gcc-arm-none-eabi binutils-arm-none-eabi \
+	    libnewlib-arm-none-eabi
+else
+	echo "Sorry, we don't recognize your OS. Help us by contributing support!"
+	echo
+	echo "    https://docs.qmk.fm/contributing.html"
+fi

util/macos_install.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+if brew --version 2>&1 > /dev/null; then
+	echo "Error! Homebrew not installed or broken!"
+	echo -n "Would you like to install homebrew now? [y/n] "
+	while read ANSWER; do
+		case $ANSWER in
+			y|Y)
+				/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+				break
+			;;
+			n|N)
+				exit 1
+			;;
+			*)
+				echo -n "Would you like to install homebrew now? [y/n] "
+			;;
+                esac
+	done
+fi
+
+brew tap osx-cross/avr
+brew tap PX4/homebrew-px4
+brew update
+brew install avr-gcc gcc-arm-none-eabi dfu-programmer avrdude

util/qmk_install.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# Pick the correct install script based on the current OS
+
+util_dir=$(dirname "$0")
+
+case $(uname) in
+	Darwin)
+		exec "${util_dir}/macos_install.sh"
+	;;
+	Linux)
+		exec "${util_dir}/linux_install.sh"
+	;;
+	MSYS_NT*)
+		exec "${util_dir}/msys2_install.sh"
+	;;
+esac