starting to migrate the Arduino setup documentation over from the wiki

docs/images/noun_836336_cc.svg

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 21.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1"
+	 id="Layer_1" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:svg="http://www.w3.org/2000/svg"
+	 xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 150 150"
+	 style="enable-background:new 0 0 150 150;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#F05025;}
+	.st1{enable-background:new    ;}
+</style>
+<g transform="translate(0,-958.61215)">
+	<path class="st0" d="M120.2,998.6c1,0,1.9,0.8,1.9,1.9v80.6c0,1-0.8,1.9-1.9,1.9H99.6c-1,0-1.9-0.8-1.9-1.9v-80.6
+		c0-1,0.8-1.9,1.9-1.9H120.2z M116.8,1010.4h-13.9c-1,0-1.9,0.8-1.9,1.9v6.4c0,1,0.8,1.9,1.9,1.9h13.9c1,0,1.9-0.8,1.9-1.9v-6.4
+		C118.7,1011.2,117.8,1010.4,116.8,1010.4z M116.8,1067.6h-13.9c-1,0-1.9,0.8-1.9,1.9v2.6c0,1,0.8,1.9,1.9,1.9h13.9
+		c1,0,1.9-0.8,1.9-1.9v-2.6C118.7,1068.4,117.8,1067.6,116.8,1067.6z"/>
+	<path class="st0" d="M92.1,998.6c1,0,1.9,0.8,1.9,1.9v80.6c0,1-0.8,1.9-1.9,1.9H71.4c-1,0-1.9-0.8-1.9-1.9v-80.6
+		c0-1,0.8-1.9,1.9-1.9H92.1z M88.7,1010.4H74.8c-1,0-1.9,0.8-1.9,1.9v6.4c0,1,0.8,1.9,1.9,1.9h13.9c1,0,1.9-0.8,1.9-1.9v-6.4
+		C90.6,1011.2,89.7,1010.4,88.7,1010.4z M88.7,1067.6H74.8c-1,0-1.9,0.8-1.9,1.9v2.6c0,1,0.8,1.9,1.9,1.9h13.9c1,0,1.9-0.8,1.9-1.9
+		v-2.6C90.6,1068.4,89.7,1067.6,88.7,1067.6z"/>
+	<path class="st0" d="M65.1,1027.5c1.1,0.2,1.8,1.1,1.6,2.2l-9.6,51.7c-0.2,1-1.2,1.7-2.3,1.5l-15.5-2.6c-1.1-0.2-1.8-1.1-1.6-2.2
+		l9.6-51.7c0.2-1,1.2-1.7,2.3-1.5L65.1,1027.5z M57.8,1034.8l-3.9-0.7c-1.1-0.2-2.1,0.5-2.3,1.5l-6.2,33.2c-0.2,1,0.5,2,1.6,2.2
+		l3.9,0.7c1.1,0.2,2.1-0.5,2.3-1.5l6.2-33.2C59.5,1036,58.8,1035,57.8,1034.8L57.8,1034.8z"/>
+</g>
+<text transform="matrix(1 0 0 1 25.75 159.5)" style="font-family:'HelveticaNeue-Bold'; font-size:5px;">Created by Gonzalo Bravo</text>
+<text transform="matrix(1 0 0 1 25.75 164.5)" style="font-family:'HelveticaNeue-Bold'; font-size:5px;">from the Noun Project</text>
+</svg>

docs/setup_toolchain.md

@@ -1,50 +1,52 @@
-# Installing the Arduino IDE
+# Setting up your development environment
 
 If you'd like to customize your keyboard's layout or functionality, the most robust and flexible option is to use the Arduino IDE. 
 
 Arduino is one of the world's most widely used (and user friendly) platforms for programming "embedded" devices like the chip inside your keyboard. 
 
-The first step is to install the Arduino "Integrated development environment" or IDE:
+
+# Set up the Arduino IDE
+
+Arduino's designers made it to be accessible to people at all skill levels, and Kaleidoscope is built on top of the Arduino platform because we share that goal. The easiest way to customize your keyboard's firmware is to use the Arduino IDE. Even if you expect to use the command line to compile your firmware, you'll still need to install Arduino, as they provide the compilers and libraries Kaleidoscope needs to work. 
+
+Using the IDE is is the easiest process for folks who are new to Arduino, or to programming generally. If you follow the instructions below step by step you should be fine. :-)
+
+
+The right way to install Arduino is a little bit different depending on what operating system you use.
 
 * [Install Arduino on macOS](#Arduino-macOS)
 * [Install Arduino on Linux](#Arduino-Linux)
-* [Install Arduino on Windows](#Arduino-Windows)
+* [Install Arduino on Windows 10](#Arduino-Windows)
 * [Install Arduino on FreeBSD](#Arduino-FreeBSD)
 
 
 ## <a name="Arduino-macOS"/>Install Arduino on macOS
 
-The Arduino system has been designed to be accessible to people at all skill levels, and Keyboardio is built on top of the Arduino platform because we share that goal. There are many ways to set up your system to work with the Keyboardio firmware, the most typical is to use the Arduino Integrated Development Environment (IDE); an application that gives some visual context to the code you want to send to your Arduino device. This is the easiest process for folks who are new to Arduino, or to programming generally. If you follow the instructions below step by step you should be fine. :-)
 
-<h4>Step One: Set up the Arduino IDE</h4>
 
- 1. Download the Arduino IDE install package from https://www.arduino.cc/en/Main/Software
+1. Download the Arduino IDE install package from https://www.arduino.cc/en/Main/Software
 
-As of this writing, the latest version is v1.8.8, which you can download from https://www.arduino.cc/download_handler.php?f=/arduino-1.8.8-macosx.zip
+As of this writing, the latest version is v1.8.13, which you can download from https://www.arduino.cc/download_handler.php?f=/arduino-1.8.13-macosx.zip
 
- 2. Double-click "arduino-1.8.x-macos.zip" to uncompress the Arduino IDE. 
+2. Double-click "arduino-1.8.13-macos.zip" to uncompress the Arduino IDE. 
 
- 3. Move Arduino.app from your `Downloads` folder to your Applications folder.
+3. Move Arduino.app from your `Downloads` folder to your Applications folder.
 
- 4. Double-click on Arduino.app to start it.
+4. Double-click on Arduino.app to start it.
 
-Next step: [Add keyboard support to Arduino](Add-keyboard-support-to-Arduino)
+Next step: [Add keyboard support to Arduino](#Add-keyboard-support-to-Arduino)
 
 
 # <a name="Arduino-Linux"/>Install on Linux
 
-The Arduino system has been designed to be accessible to people at all skill levels, and Keyboardio is built on top of the Arduino platform because we share that goal. There are many ways to set up your system to work with the Keyboardio firmware, the most typical is to use the Arduino Integrated Development Environment (IDE); an application that gives some visual context to the code you want to send to your Arduino device. This is the easiest process for folks who are new to Arduino, or to programming generally. If you follow the instructions below step by step you should be fine. :-)
+1. Install version 1.8.13 or newer of the Arduino IDE from http://arduino.cc/download.  Unfortunately, the version packaged in Ubuntu is too ancient to support Arduino's new way of doing 3rd-party hardware.
-
-<h4>Step One: Set up the Arduino IDE</h4>
-
-1. Install version 1.8.8 or newer of the Arduino IDE from http://arduino.cc/download.  Unfortunately, the version packaged in Ubuntu is too ancient to support Arduino's new way of doing 3rd-party hardware.
 
 2. Assuming you're untarring in the download directory:
 
     ```sh
     $ cd ~/Downloads
-    $ tar xvf arduino-1.8.8-linux64.tar.xz
+    $ tar xvf arduino-1.8.13-linux64.tar.xz
-    $ sudo mv arduino-1.8.8 /usr/local/arduino
+    $ sudo mv arduino-1.8.13 /usr/local/arduino
     $ cd /usr/local/arduino
     $ sudo ./install.sh
     ```
@@ -86,55 +88,44 @@ The Arduino system has been designed to be accessible to people at all skill lev
     export ARDUINO_PATH=/usr/local/arduino
     ```
 
-Next step: [Add keyboard support to Arduino](Add-keyboard-support-to-Arduino)
+Next step: [Add keyboard support to Arduino](#Add-keyboard-support-to-Arduino)
 
-# <a name="Arduino-Windows"/>Install on Windows
+# <a name="Arduino-Windows"/>Install on Windows 10
 
-The Arduino system has been designed to be accessible to people at all skill levels, and Keyboardio is built on top of the Arduino platform because we share that goal. There are many ways to set up your system to work with the Keyboardio firmware, the most typical is to use the Arduino Integrated Development Environment (IDE); an application that gives some visual context to the code you want to send to your Arduino device. This is the easiest process for folks who are new to Arduino, or to programming generally. If you follow the instructions below step by step you should be fine. :-)
 
 _**Note:** This tutorial has been written using Windows 10._
 
 
-<h4>Prerequisite: Install USB Driver (Win 7, 8, & 8.1)</h4>
-
-For Windows 7, 8, and 8.1, please follow the instructions on the [Installing USB Driver on Windows](Installing-USB-Driver-on-Windows) page before proceeding with the instructions on this page.
-
-<h4>Step One: Set up the Arduino IDE</h4>
-
 1. Download the Arduino IDE installation package from https://www.arduino.cc/en/Main/Software
 
-As of this writing, the latest version is v1.8.8, which you can download from this URL:
+As of this writing, the latest version is v1.8.13, which you can download from this URL:
 
-https://www.arduino.cc/download_handler.php?f=/arduino-1.8.8-windows.exe
+https://www.arduino.cc/download_handler.php?f=/arduino-1.8.13-windows.exe
 
 _**Note:** Some users have had difficulties with the Windows store version of the Arduino IDE. Please use the downloadable installation package._
 
 2. Open the installation package and follow the prompts to install the Arduino IDE.
 
-Next step: [Add keyboard support to Arduino](Add-keyboard-support-to-Arduino)
+Next step: [Add keyboard support to Arduino](#Add-keyboard-support-to-Arduino)
 
 ## <a name="Arduino-FreeBSD"/>Install on FreeBSD
 
-The Arduino system has been designed to be accessible to people at all skill levels, and Keyboardio is built on top of the Arduino platform because we share that goal. There are many ways to set up your system to work with the Keyboardio firmware, the most typical is to use the Arduino Integrated Development Environment (IDE); an application that gives some visual context to the code you want to send to your Arduino device. This is the easiest process for folks who are new to Arduino, or to programming generally. If you follow the instructions below step by step you should be fine. :-)
-
-<h4>Step One: installing support packages</h4>
-
 1. Install the following packages required by the build system: `bash`, `gmake`, `perl5`, `avrdude`, and `arduino18`.
 
    ```sh
    $ sudo pkg install bash gmake perl5 avrdude arduino18
    ```
 
-2. Flashing firmware as non-root.
+### Flashing firmware as non-root.
 
-   a. If you want to flash your firmware as non-root, ensure your user has write access to the appropriate USB devices in devfs. By default, the devices are owned by `root`:`operator`, so put yourself in the `operator` group. You will also need to add yourself to the `dialer` group to use the modem device:
+1. If you want to flash your firmware as non-root, ensure your user has write access to the appropriate USB devices in devfs. By default, the devices are owned by `root`:`operator`, so put yourself in the `operator` group. You will also need to add yourself to the `dialer` group to use the modem device:
 
       ```sh
       $ sudo pw groupmod operator -m $USER
       $ sudo pw groupmod dialer -m $USER
       ```
 
-   b. Add devfs rules for write access for operator to USB devices:
+1. Add devfs rules for write access for operator to USB devices:
 
       ```sh
       $ cat << EOM >> /etc/devfs.rules
@@ -148,15 +139,19 @@ The Arduino system has been designed to be accessible to people at all skill lev
       EOM
       ```
 
-   c. Update `/etc/rc.conf` to use the new devfs rule as the system rule:
+1. Update `/etc/rc.conf` to use the new devfs rule as the system rule:
 
       ```sh
       $ sudo sysrc devfs_system_ruleset=operator_usb
       ```
 
-   d. Restart devfs:
+1. Restart devfs:
 
       ```sh
       $ sudo service devfs restart
       ```
 
+Next step: [Add keyboard support to Arduino](#Add-keyboard-support-to-Arduino)
+
+
+# <a name="Add-keyboard-support-to-Arduino"/>Add keyboard support to Arduino