Mercurial > louis > kiibohd-controller

changeset 313:a2df35fa4f0b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updating the README to be of a more reasonable length.
author Jacob Alexander <haata@kiibohd.com>
date Sun, 15 Mar 2015 21:37:57 -0700
parents c5f083de1838
children 8325f8c91663 a0ad3a172269
files Keyboards/README.markdown README.markdown README.old.markdown
diffstat 3 files changed, 801 insertions(+), 710 deletions(-) [+]
line wrap: on
line diff
--- a/Keyboards/README.markdown	Sun Mar 15 20:51:23 2015 -0700
+++ b/Keyboards/README.markdown	Sun Mar 15 21:37:57 2015 -0700
@@ -31,3 +31,7 @@
 * template.bash (Example template for new keyboards)
 
 
+**Extra files**
+
+* cmake.bash (Used by the compilation script, does nothing on it's own)
+
--- a/README.markdown	Sun Mar 15 20:51:23 2015 -0700
+++ b/README.markdown	Sun Mar 15 21:37:57 2015 -0700
@@ -1,750 +1,87 @@
 The Kiibohd Controller
 ======================
 
-This README is a bit long, just look at the sections you are interested in.
-You only need to install avr-gcc if you want to build for the Teensy 2.0/2.0++.
-Everything else needs an arm-none-eabi-gcc compiler (e.g. Infinity keyboard,
-Teensy 3.0/3.1, McHCK).
-
-Linux is the ideal build environment (preferably recent'ish). In the near
-future I'll make available an Arch Linux VM for building/manufacturing tests.
-
-Building on Mac should be ok for 99% of users with Macports or Homebrew. For
-Homebrew, use `brew tap PX4/homebrew-px4` to get the arm-none-eabi-gcc installer.
-The dfu Bootloader will not build correctly with the old version of
-arm-none-eabi-gcc that Macports currently has (4.7.3). This is due to a bug
-with lto (link time optimizations) which makes the resulting binary too big to
-fit on the chip (must be less than 4096 Bytes).
-
-Building on Windows should also be fine for 99% of users, but takes a bunch of
-work to setup (because Windows is a crappy dev environment).  Cygwin is
-currently required along with some non-Cygwin compilers and utilities (because
-they are not available for Cygwin).  The dfu Bootloader will not build because
-of a Make 3.81+ bug/feature that removed support for non-Unix (Windows)
-filenames as dependencies of targets.  If you [replace the version of Make in
-Cygwin](http://stackoverflow.com/questions/601516/cygwin-make-error-target-pattern-contains-no)
-it should work.  However, make sure that the flash size is no larger than 4096
-Bytes or the bootloader will not work. Things will likely break if there are
-**SPACES IN YOUR PATHS**. I install cygwin to `C:\cygwin64`.  If you are brave
-and have programming knowledge, I will accept patches to fix any issues
-regarding spaces in paths.
-
-Please give authors credit for modules used if you use in a distributed
-product :D
+This is the main Kiibohd Firmware.
+In general, this should be the **only** git repo you need to clone.
+The [KLL](https://github.com/kiibohd/kll) git repo is automatically cloned during the build process.
 
-
-General Dependencies
---------------------
-
-Below listed are the Arch Linux pacman names, AUR packages may be required.
-
-These depend a bit on which targets you are trying to build, but the general
-one:
-
-- cmake (2.8 and higher)
-- git
-- ctags (recommended, not required)
-- python3
-- libusb1.0 (and -devel)
-- make
+Please refer to the [KLL](https://github.com/kiibohd/kll) repo or [kiibohd.com](http://kiibohd.com) for details on the KLL (Keyboard Layout Language) Spec.
 
-AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested
-versions below)
-
-- avr-gcc      (~4.8.0)
-- avr-binutils (~2.23.2)
-- avr-libc     (~1.8.0)
-
-ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK)
-
-- Arch Linux / Mac Ports
-    - arm-none-eabi-gcc
-    - arm-none-eabi-binutils
-
-- Windows (https://launchpad.net/gcc-arm-embedded/+download)
-    - gcc-arm-none-eabi (win32.zip)
 
 
-Windows Setup
--------------
-
-Compiling on Windows does work, just it's a bunch more work.
-
-First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit
-is fine. Make sure the following are installed:
-
-- make
-- git (needed for some compilation info)
-- cmake
-- gcc-core
-- gcc-g++
-- libusb1.0
-- libusb1.0-devel
-- python3
-- ctags (recommended, not required)
-
-Please note, I use cygwin term exclusively for any command line options.
-Unless mentioned otherwise, use it.  Do NOT use CMD or Powershell.
-
-Also install the [Windows version of CMake](http://cmake.org/cmake/resources/software.html)
-(3+ is ideal) - Select "Do not add CMake to system PATH".  This is in addition
-to the Cygwin version. This is an easier alternative to installing another C
-compiler.  Add the following line to your .bashrc, making sure the CMake path
-is correct:
-
-    echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc
+Official Keyboards
+------------------
 
-Install the [PJRC Virtual Serial Port Driver](http://pjrc.com/teensy/serial_install.exe).
-
-Next, install the compiler(s) you want.
-
-
-### AVR GCC
-
-You just need the
-[Atmel AVR 8-bit Toolchain](http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx).
-The latest should be fine, as of writing it was 3.4.3.
-
-Extract the files to a directory, say `C:\avr8-gnu-toolchain`. Then copy all
-the folders in that directory to the Cygwin `/usr/local` directory.  Mine is
-`C:\cygwin64\usr\local`. (You can also just setup the paths, but this is
-faster/simpler. Might screw up your Cygwin though).
-
-
-### ARM EABI
-
-Download the latest
-[GNU Tools for Embedded Processors
-gcc-arm-none-eabi](https://launchpad.net/gcc-arm-embedded/+download).
-
-Download `gcc-arm-none-eabi*win32.zip`.
-
-Then extract all the folders/files in the zip to the Cygwin `/usr/local`
-directory.  Mine is `C:\cygwin64\usr\local`.  Or, you can setup paths using
-the installer (you have to be more careful, avoid spaces in paths).
+* MD1 (Infinity Keyboard 2014/10/15)
 
 
-CMake Info
-----------
-
-One of the big benefits of using CMake is the ability to build multiple
-configurations (for different microcontrollers) at the same time.  The
-following sections explain in detail what each CMakeLists.txt configuration
-option does and what you can change it to.  However, it is possible to
-configure each of these options using the `-D` command line flag.
-
-For example, to build the Infinity Keyboard default configuration:
-
-```bash
-$ mkdir build_infinity
-$ cd build_infinity
-$ cmake -DCHIP=mk20dx128vlf5 -DScanModule=MD1 -DMacroModule=PartialMap \
-        -DOutputModule=pjrcUSB -DDebugModule=full -DBaseMap=defaultMap \
-        -DDefaultMap="md1Overlay stdFuncMap" -DPartialMaps="hhkbpro2" \
-        ..
-$ make
-```
-
-CMake defaults to the values specified in CMakeLists.txt if not overridden via
-the command line.
-
-> NOTE: On Windows, you will have to use "wincmake" instead of "cmake".
-
+The Kiibohd firmware supports a lot of other keyboards, but these are more obscure/custom/lesser known.
 
-Selecting Microcontroller
--------------------------
-
-This is where you select the chip you want to compile for.  The build system
-will automatically select the compiler needed to compile for your chip.
-
-Open up CMakeLists.txt in your favourite text editor. You are looking for:
-
-```cmake
-###
-# Chip Selection
-#
-
-#| You _MUST_ set this to match the microcontroller you are trying to compile for
-#| You _MUST_ clean the build directory if you change this value
-#|
-set( CHIP
-#	"at90usb162"       # Teensy   1.0 (avr)
-#	"atmega32u4"       # Teensy   2.0 (avr)
-#	"at90usb646"       # Teensy++ 1.0 (avr)
-#	"at90usb1286"      # Teensy++ 2.0 (avr)
-#	"mk20dx128"        # Teensy   3.0 (arm)
-    "mk20dx128vlf5"    # McHCK    mk20dx128vlf5
-#	"mk20dx256"        # Teensy   3.1 (arm)
-    CACHE STRING "Microcontroller Chip" )
-```
-
-Just uncomment the chip you want, and comment out the old one.
-
-> NOTE: If you change this option, you will *need* to delete the build
-> directory that is created in the Building sections below.
 
 
-Selecting Modules
------------------
-
-> WARNING: Not all modules are compatible, and some modules may have
-> dependencies on other modules.
-
-This is where the options start getting interesting.  The Kiibohd Controller
-is designed around a set of 4 types of modules that correspond to different
-functionality:
-
-- Scan Module
-- Macro Module
-- Output Module
-- Debug Module
-
-The Scan Module is where the most interesting stuff happens. These modules
-take in "keypress data".  A converter Scan Module will interpret a protocol
-into key press/releases.  A matrix Scan Module may inherit from the matrix
-module to scan keypress from a matrix This module just has to give
-press/release codes, but does have some callback control to other modules
-depending on the lifecycle for press/release codes (this can be very
-complicated depending on the protocol).  Each Scan Module has it's own default
-keymap/modifier map. (TODO recommend keymap changing in the Macro Module).
-
-Some scan modules have very specialized hardware requirements, each module
-directory should have at least a link to the needed parts and/or schematics
-(TODO!).
-
-The Macro Module takes care of the mapping of the key press/release code into
-an Output (USB) scan code.  Any layering, macros, keypress
-intelligence/reaction is done here.
-
-The Output Module is the module dealing with output from the microcontroller.
-Currently USB is the only output protocol.  Different USB output
-implementations are available, pjrc being the safest/least featureful one.
-Debug capabilities may depend on the module selected.
+Compilation
+-----------
 
-The Debug Module enables various things like the Teensy LED on errors, debug
-terminal output.  (TODO get true UART working in avr, not just arm)
-
-Open up CMakeLists.txt in your favourite text editor.  Look for:
-
-```cmake
-###
-# Project Modules
-#
-
-#| Note: This is the only section you probably want to modify
-#| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module)
-#| All of the modules must be specified, as they generate the sources list of files to compile
-#| Any modifications to this file will cause a complete rebuild of the project
-
-#| Please look at the {Scan,Macro,Output,Debug} for information on the modules and how to create new ones
+Compilation is possible and tested on Windows/Linux/Mac.
+Linux is the easiest using this [VM](https://s3.amazonaws.com/configurator-assets/ArchLinux_kiibohd_2015-02-13.tar.gz).
 
-##| Deals with acquiring the keypress information and turning it into a key index
-set(   ScanModule "MD1"
-    CACHE STRING "Scan Module" )
-
-##| Provides the mapping functions for DefaultMap and handles any macro processing before sending to the OutputModule
-set(  MacroModule "PartialMap"
-    CACHE STRING "Macro Module" )
-
-##| Sends the current list of usb key codes through USB HID
-set( OutputModule "pjrcUSB"
-    CACHE STRING "Output Module" )
+For most people refer [here](https://github.com/kiibohd/controller/tree/master/Keyboards).
 
-##| Debugging source to use, each module has it's own set of defines that it sets
-set(  DebugModule "full"
-    CACHE STRING "Debug Module" )
-```
-
-Look at each module individually for it's requirements. There is
-chip/architecture dependency checking but some permutations of modules may not
-be tested/compile.
-
-There are also CMake options for temporarily selecting modules. But it's
-easier to just edit the file. e.g. `cmake -DScanModuleOverride=<module name>`.
+For the full compilation details, please refer to the [wiki](https://github.com/kiibohd/controller/wiki).
 
 
-Keymap Configuration
---------------------
 
-This is where you define the layout for your keyboard.
-Currently, the only way to define kebyoard layouts is using [KLL](https://www.overleaf.com/read/zzqbdwqjfwwf).
-
-KLL is built up of 3 different kinds of keymaps in total.
-The BaseMap, DefaultMap and PartialMaps.
-
-For each type of keymap, it is possible to combine multiple .kll files together to create new ones using
-the compiler. The order of the files matter, as the right-most file will overwrite any setting in the
-previous files.
-
-> NOTE: Each keymap is done after the entire file is processed. This means that within the file the order
->       of assignment doesa *not* matter (if you assign the same thing twice, then yes the most recent one
->       takes priority).
-
-
-BaseMap defines what the keyboard can do. This includes specific capabilities of the keyboard (such as USB),
-the mapping of Scan Codes to USB Codes and any specific configurations for the keyboard.
-In general, the BaseMap rarely needs to be changed. Usually only when adding a new keyboard to the firmware
-does the Basemap need any modification.
-The BaseMap is what both DefaultMap and PartialMaps are based upon. This allows for a common reference
-when defining custom keymappings.
-
-> NOTE: Don't use defaultMap.kll to change your layouts. This will work, but they will not be portable.
-
-
-The DefaultMap is the normal state of the keyboard, i.e. your default layer.
-Using the BaseMap as a base, the DefaultMap is a modification of the BaseMap to what the keyboard should do.
-Since the DefaultMap uses USB Code to USB Code translations, this means that keymaps used for one keyboard
-will work with another keyboard.
-For example, I use Colemak, so this means I only have to define Colemak once for every keyboard that supports
-the kiibohd firmware. This is possible because every BaseMap defines the keyboard as a US ANSI like keyboard
-layout.
-The DefaultMap can also be thought of as Layer 0.
-
-
-PartialMaps are optional keymaps that can be "stacked" on top of the DefaultMap.
-They can be dynamically swapped out using the layer control capabilities:
-
-- layerLatch( `<layer number>` )
-- layerLock( `<layer number>` )
-- layerShift( `<layer number>` )
-
-layerShift is usually what you want as it works just like a standard shift key.
-layerLock is similar to the CapsLock key. While layerLatch is a latch, where only the next key you press
-will use that layer (e.g. stickykeys).
+Supported Microcontrollers
+--------------------------
 
-A unique aspect of KLL layers is that it's a true stack of layers.
-When a layer is activated, only the keys that are specified by the layer will change.
-This means, if you define a layer that only sets `CapsLock -> LCtrl` and `LCtrl->Capslock` only those keys
-will change when you active the layer. All the other keys will use the layer that is "underneath" to
-lookup the keypress (usually the DefaultMap).
-
-This means that you can combine .kll files statically using the compiler or dynamically using the firmware.
-
-You can set the max number of layers by changing the `stateWordSize` define in one of your kll files.
-By default it is set to 8 in Macro/PartialMap/capabilities.kll. This means you can have up to 256 layers
-total (this includes the DefaultMap).
-You can increase this number to either 16 or 32 (this will use more Flash and RAM btw) which will give you
-2^16 and 2^32 possible layers respectively (65 535 and 4 294 967 295).
-
-
-```cmake
-###
-# Keymap Configuration (do not include the .kll extension)
-#
-
-#| Do not include the .kll extension
-#| * BaseMap maps the native keyboard scan codes to USB Codes so the layout is compatible with all other layouts
-#| * DefaultMap allows the default keymap to be modified from the BaseMap
-#| * PartialMaps is a set of dynamically set layers (there is no limit, but too many may use up too much RAM...)
-#| BaseMap generally does not need to be changed from "defaultMap"
-#|
-#| Syntax:
-#|  myMap
-#|    * defines a single .kll layout file, double-quotes are needed to distinguish between layers
-#|  "myMap specialLayer"
-#|    * defines myMap to be the main layout, then replace specialLayers on top of it
-#|
-#| - Only for PartialMaps -
-#|  "myMap specialLayer" "myMap colemak" dvorak
-#|    * As before, but also generates a second layer at index 2 and third at index 3
-#|
-#| NOTE:  Remember to add key(s) to enable each Partial Layer
-#| NOTE2: Layers are always based up the BaseMap (which should be an ANSI-like mapping)
-#| NOTE3: Compiler looks in kll/layouts and the build directory for layout files (precedence on build directory)
-
-##| Set the base keyboard .kll map, defaults to "defaultMap" if not found
-##| Looks in Scan/<Module Name> for the available BaseMaps
-set(     BaseMap "defaultMap"
-        CACHE STRING "KLL BaseMap/Scancode Keymapping" )
-
-##| Layer additonal .kll maps on the BaseMap, layers are in order from 1st to nth
-##| Can be set to ""
-set(  DefaultMap "md1Overlay stdFuncMap"
-        CACHE STRING "KLL DefaultMap" )
-
-##| ParitalMaps available on top of the BaseMap. See above for syntax on specifying multiple layers vs. layering
-##| Can be set to ""
-set( PartialMaps "hhkbpro2"
-        CACHE STRING "KLL PartialMaps/Layer Definitions" )
-```
+* Teensy 2.0 (Partial)
+* Teensy 2.0++
+* Teesny 3.0
+* Teensy 3.1
+* mk20dx128vlf5
+* mk20dx256vlh7
 
 
-Linux Building
---------------
-
-From this directory.
-
-```bash
-$ mkdir build
-$ cd build
-$ cmake ..
-$ make
-```
-
-Example output:
+Adding support for more microcontrollers is possible.
+Some considerations for minimum specs:
 
-```
-$ cmake ..
--- Compiler Family:
-arm
--- Chip Selected:
-mk20dx128vlf5
--- Chip Family:
-mk20dx
--- CPU Selected:
-cortex-m4
--- Compiler Source Files:
-Lib/mk20dx.c;Lib/delay.c
--- Bootloader Type:
-dfu
--- Detected Scan Module Source Files:
-Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
--- Detected Macro Module Source Files:
-Macro/PartialMap/macro.c
--- Detected Output Module Source Files:
-Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c;
-Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c
--- Detected Debug Module Source Files:
-Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
--- Found Git: /usr/bin/git (found version "2.2.1")
--- Found Ctags: /usr/bin/ctags (found version "5.8")
--- Checking for latest kll version:
-Current branch master is up to date.
--- Detected Layout Files:
-/home/hyatt/Source/controller/Macro/PartialMap/capabilities.kll
-/home/hyatt/Source/controller/Output/pjrcUSB/capabilities.kll
-/home/hyatt/Source/controller/Scan/MD1/defaultMap.kll
-/home/hyatt/Source/controller/kll/layouts/md1Overlay.kll
-/home/hyatt/Source/controller/kll/layouts/stdFuncMap.kll
-/home/hyatt/Source/controller/kll/layouts/hhkbpro2.kll
--- Configuring done
--- Generating done
--- Build files have been written to: /home/hyatt/Source/controller/build
-[master]: make                                [~/Source/controller/build](hyatt@x230mas:pts/6)
-[  5%] Generating KLL Layout
-Scanning dependencies of target kiibohd.elf
-[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
-[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.o
-[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.o
-[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.o
-[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.o
-[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.o
-[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.o
-[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.o
-[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.o
-[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.o
-[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.o
-[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.o
-[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.o
-[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
-[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
-Linking C executable kiibohd.elf
-[ 94%] Built target kiibohd.elf
-Scanning dependencies of target SizeAfter
-[100%] Chip usage for mk20dx128vlf5
-     SRAM:  32%     5384/16384      bytes
-    Flash:  18%     23384/126976    bytes
-[100%] Built target SizeAfter
-```
+* ~8  kB of SRAM
+* ~25 kB of Flash
 
-Linux Loading Firmware
-----------------------
+It's possible to port chips with lower specs, but will be more effort and have fewer features.
 
-First place the keyboard into re-flash mode.  This can be done either by
-pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
-Virtual Serial Port and using the 'reload' command.
-
-The `load` script that is created during the build can load the firmware over
-USB.  Either run it with sudo, or install the `98-kiibohd.rules` to
-`/etc/udev/rules.d` and run: `udevadm control --reload-rules`.
-
-To load the newly built firmware: `./load`.
 
 
-Linux Building Bootloader
--------------------------
-
-> NOTE: Does not apply to Teensy based builds.
-
-From this directory.
+Contributions
+-------------
 
-```bash
-$ cd Bootloader
-$ mkdir build
-$ cd build
-$ cmake ..
-$ make
-```
-
-Example output:
+Contributions welcome!
 
-```bash
-$ cmake ..
--- Compiler Family:
-arm
--- Chip Selected:
-mk20dx128vlf5
--- Chip Family:
-mk20dx
--- CPU Selected:
-cortex-m4
--- Compiler Source Files:
-Lib/mk20dx.c;Lib/delay.c
--- Bootloader Type:
-dfu
--- Bootloader Source Files:
-main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c
--- Found Git: /usr/bin/git (found version "2.2.1")
--- Found Ctags: /usr/bin/ctags (found version "5.8")
--- Configuring done
--- Generating done
--- Build files have been written to: /home/hyatt/Source/controller/Bootloader/build
-[master]: make                                 [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6)
-Scanning dependencies of target kiibohd_bootloader.elf
-[ 11%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/main.c.o
-[ 22%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.c.o
-[ 33%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.desc.c.o
-[ 44%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/flash.c.o
-[ 55%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/kinetis.c.o
-[ 66%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/usb.c.o
-[ 77%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/mk20dx.c.o
-[ 88%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/delay.c.o
-Linking C executable kiibohd_bootloader.elf
-[ 88%] Built target kiibohd_bootloader.elf
-Scanning dependencies of target SizeAfter
-[100%] Chip usage for mk20dx128vlf5
-     SRAM:  19%     3176/16384      bytes
-    Flash:  2%      3736/126976     bytes
-[100%] Built target SizeAfter
-```
+* Bug reports
+* Documentation and Wiki editing
+* Patches (including new features)
 
 
-Linux Loading Bootloader
-------------------------
-
-> NOTE: Does not apply to Teensy based builds.
-
-It's recommended to use an SWD-type flasher like a Bus Pirate.  There is a
-convenience script for loading the firmware once the system is setup.
-
-```bash
-$ cd Bootloader/Scripts
-$ ./swdLoad.bash
-```
-
-The above script requires Ruby, Ruby serial port module, git, and a
-`/dev/buspirate` udev rule.
-
-Additional Notes:
-
-* https://github.com/mchck/mchck/wiki/Getting-Started (See Bus-Pirate section)
-* https://wiki.archlinux.org/index.php/Bus_pirate
-
 
-Windows Building
-----------------
-
-From this directory.
-
-```bash
-$ mkdir build
-$ cd build
-$ wincmake ..
-$ make
-```
-
-Example output:
-
-```bash
-$ wincmake ..
--- Compiler Family:
-arm
--- Chip Selected:
-mk20dx128vlf5
--- Chip Family:
-mk20dx
--- CPU Selected:
-cortex-m4
--- Compiler Source Files:
-Lib/mk20dx.c;Lib/delay.c
--- Bootloader Type:
-dfu
--- Detected Scan Module Source Files:
-Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
--- Detected Macro Module Source Files:
-Macro/PartialMap/macro.c
--- Detected Output Module Source Files:
-Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c;Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c
--- Detected Debug Module Source Files:
-Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
--- Found Git: C:/cygwin64/bin/git.exe (found version "2.1.1")
--- Found Ctags: C:/cygwin64/bin/ctags.exe (found version "5.8")
--- Checking for latest kll version:
-Current branch master is up to date.
--- Detected Layout Files:
-C:/cygwin64/home/Jacob/controller/Macro/PartialMap/capabilities.kll
-C:/cygwin64/home/Jacob/controller/Output/pjrcUSB/capabilities.kll
-C:/cygwin64/home/Jacob/controller/Scan/MD1/defaultMap.kll
-C:/cygwin64/home/Jacob/controller/kll/layouts/md1Overlay.kll
-C:/cygwin64/home/Jacob/controller/kll/layouts/stdFuncMap.kll
-C:/cygwin64/home/Jacob/controller/kll/layouts/hhkbpro2.kll
--- Configuring done
--- Generating done
--- Build files have been written to: C:/cygwin64/home/Jacob/controller/build
+Licensing
+---------
 
-$ make
-[  5%] Generating KLL Layout
-Scanning dependencies of target kiibohd.elf
-[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
-[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.obj
-[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.obj
-[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.obj
-[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.obj
-[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
-[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
-[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.obj
-[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.obj
-[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.obj
-[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.obj
-[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.obj
-[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
-[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
-[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
-Linking C executable kiibohd.elf
-[ 94%] Built target kiibohd.elf
-Scanning dependencies of target SizeAfter
-[100%] Chip usage for mk20dx128vlf5
-     SRAM:  32%     5384/16384      bytes
-    Flash:  18%     23296/126976    bytes
-[100%] Built target SizeAfter
-```
+Licensing is done on a per-file basis.
+Some of the source code is from [PJRC/Teensy](http://pjrc.com), other source code is from the [McHck Project](https://mchck.org).
+Code written specifically for the Kiibohd Controller use the following licenses:
 
-### NOTES:
-
-If you get the following error, you have not setup wincmake correctly:
-
-```bash
-$ make
-[  5%] Generating KLL Layout
-Scanning dependencies of target kiibohd.elf
-[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
-../main.c:28:19: fatal error: macro.h: No such file or directory
- #include <macro.h>
-                   ^
-compilation terminated.
-CMakeFiles/kiibohd.elf.dir/build.make:67: recipe for target 'CMakeFiles/kiibohd.elf.dir/main.c.o' failed
-make[2]: *** [CMakeFiles/kiibohd.elf.dir/main.c.o] Error 1
-CMakeFiles/Makefile2:98: recipe for target 'CMakeFiles/kiibohd.elf.dir/all' failed
-make[1]: *** [CMakeFiles/kiibohd.elf.dir/all] Error 2
-Makefile:75: recipe for target 'all' failed
-make: *** [all] Error 2
-```
-
-If you have already added the line to your `~/.bashrc` try restarting your
-cygwin shell.
+* MIT
+* GPLv3
+* Public Domain
 
 
-Windows Loading Firmware
-------------------------
 
-First place the keyboard into re-flash mode.  This can be done either by
-pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
-Virtual Serial Interface and using the `reload` command.
-
-The `load` script that is created during the build can load the firmware over
-USB.
-
-To load the newly built firmware: `./load`
-
-Be patient the couple of times, Windows is slow at installing drivers...
-
-
-Mac OS X Building
------------------
-
-From this directory.
-
-```bash
-$ mkdir build
-$ cd build
-$ cmake ..
-$ make
-```
-
-Example output:
-
-> TODO
-
-
-Mac OS X Loading Firmware
--------------------------
-
-First place the keyboard into re-flash mode.  This can be done either by
-pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
-Virtual Serial Port and using the `reload` command.
-
-The `load` script that is created during the build can load the firmware over
-USB.
-
-To load the newly built firmware: `./load`.
-
-
-Virtual Serial Port - CLI
--------------------------
-
-Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
-This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
-
+Contact
+-------
 
-### Linux
-
-I generally use screen.  You will need sudo/root priviledges if you haven't
-installed the `98-kiibohd.rules` file to `/etc/udev/rules.d`.
-
-```
-$ screen /dev/ttyACM0
-# (Might be ACM1, ACM2, etc.)
-```
-
-### Windows
-
-Make sure the Teensy Virtual Serial Port driver is installed.  If possible use
-screen (as part of Cygwin).  Check which COM port the virtual serial port has
-been assigned to: `Device Manager->Ports (COM & LPT)->Teensy USB Serial`. In
-brackets it will say which COM port (e.g. COM3)
-
-putty works well when using DTR/DSR or RTS/CTS flow control.
-
-| Setting         | Value                                 |
-| --------------- | ------------------------------------- |
-| Connection type | Serial                                |
-| Serial line     | Your COM port, e.g. COM3              |
-| Speed           | doesn't matter, it's auto-negotiated  |
+If you really need to get a hold of HaaTa, email is best: `haata@kiibohd.com`
 
-Under `Category->Connections->Serial`: `Flow control: DTR/DSR`.
-
-If stuff is hard to read (you have a dumb colour scheme):
-`Category->Window->Colours->Use system color`.  That seems to make text at
-least readable
-
-> I use a custom colour scheme that makes each colour easy to see.
-> -HaaTa.
-
-Unfortunately, screen for Cygwin seems to be broken for serial ports, but you
-can try it...
+IRC is likely faster though.
+`#geekhack@irc.freenode.net`
+`#deskthority@irc.freenode.net`
 
-```bash
-$ screen /dev/ttyS2
-# Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc.
-```
-
-Gnu screen doesn't seem to echo all the characters (it works though).
-I believe it's a problem with stty, but I don't know how to fix it...
-
-### Mac OS X
-
-I recommend screen (can be installed via Macports).
-
-```bash
-$ screen /dev/tty.<usb something>
-```
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.old.markdown	Sun Mar 15 21:37:57 2015 -0700
@@ -0,0 +1,750 @@
+The Kiibohd Controller
+======================
+
+This README is a bit long, just look at the sections you are interested in.
+You only need to install avr-gcc if you want to build for the Teensy 2.0/2.0++.
+Everything else needs an arm-none-eabi-gcc compiler (e.g. Infinity keyboard,
+Teensy 3.0/3.1, McHCK).
+
+Linux is the ideal build environment (preferably recent'ish). In the near
+future I'll make available an Arch Linux VM for building/manufacturing tests.
+
+Building on Mac should be ok for 99% of users with Macports or Homebrew. For
+Homebrew, use `brew tap PX4/homebrew-px4` to get the arm-none-eabi-gcc installer.
+The dfu Bootloader will not build correctly with the old version of
+arm-none-eabi-gcc that Macports currently has (4.7.3). This is due to a bug
+with lto (link time optimizations) which makes the resulting binary too big to
+fit on the chip (must be less than 4096 Bytes).
+
+Building on Windows should also be fine for 99% of users, but takes a bunch of
+work to setup (because Windows is a crappy dev environment).  Cygwin is
+currently required along with some non-Cygwin compilers and utilities (because
+they are not available for Cygwin).  The dfu Bootloader will not build because
+of a Make 3.81+ bug/feature that removed support for non-Unix (Windows)
+filenames as dependencies of targets.  If you [replace the version of Make in
+Cygwin](http://stackoverflow.com/questions/601516/cygwin-make-error-target-pattern-contains-no)
+it should work.  However, make sure that the flash size is no larger than 4096
+Bytes or the bootloader will not work. Things will likely break if there are
+**SPACES IN YOUR PATHS**. I install cygwin to `C:\cygwin64`.  If you are brave
+and have programming knowledge, I will accept patches to fix any issues
+regarding spaces in paths.
+
+Please give authors credit for modules used if you use in a distributed
+product :D
+
+
+General Dependencies
+--------------------
+
+Below listed are the Arch Linux pacman names, AUR packages may be required.
+
+These depend a bit on which targets you are trying to build, but the general
+one:
+
+- cmake (2.8 and higher)
+- git
+- ctags (recommended, not required)
+- python3
+- libusb1.0 (and -devel)
+- make
+
+AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested
+versions below)
+
+- avr-gcc      (~4.8.0)
+- avr-binutils (~2.23.2)
+- avr-libc     (~1.8.0)
+
+ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK)
+
+- Arch Linux / Mac Ports
+    - arm-none-eabi-gcc
+    - arm-none-eabi-binutils
+
+- Windows (https://launchpad.net/gcc-arm-embedded/+download)
+    - gcc-arm-none-eabi (win32.zip)
+
+
+Windows Setup
+-------------
+
+Compiling on Windows does work, just it's a bunch more work.
+
+First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit
+is fine. Make sure the following are installed:
+
+- make
+- git (needed for some compilation info)
+- cmake
+- gcc-core
+- gcc-g++
+- libusb1.0
+- libusb1.0-devel
+- python3
+- ctags (recommended, not required)
+
+Please note, I use cygwin term exclusively for any command line options.
+Unless mentioned otherwise, use it.  Do NOT use CMD or Powershell.
+
+Also install the [Windows version of CMake](http://cmake.org/cmake/resources/software.html)
+(3+ is ideal) - Select "Do not add CMake to system PATH".  This is in addition
+to the Cygwin version. This is an easier alternative to installing another C
+compiler.  Add the following line to your .bashrc, making sure the CMake path
+is correct:
+
+    echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc
+
+Install the [PJRC Virtual Serial Port Driver](http://pjrc.com/teensy/serial_install.exe).
+
+Next, install the compiler(s) you want.
+
+
+### AVR GCC
+
+You just need the
+[Atmel AVR 8-bit Toolchain](http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx).
+The latest should be fine, as of writing it was 3.4.3.
+
+Extract the files to a directory, say `C:\avr8-gnu-toolchain`. Then copy all
+the folders in that directory to the Cygwin `/usr/local` directory.  Mine is
+`C:\cygwin64\usr\local`. (You can also just setup the paths, but this is
+faster/simpler. Might screw up your Cygwin though).
+
+
+### ARM EABI
+
+Download the latest
+[GNU Tools for Embedded Processors
+gcc-arm-none-eabi](https://launchpad.net/gcc-arm-embedded/+download).
+
+Download `gcc-arm-none-eabi*win32.zip`.
+
+Then extract all the folders/files in the zip to the Cygwin `/usr/local`
+directory.  Mine is `C:\cygwin64\usr\local`.  Or, you can setup paths using
+the installer (you have to be more careful, avoid spaces in paths).
+
+
+CMake Info
+----------
+
+One of the big benefits of using CMake is the ability to build multiple
+configurations (for different microcontrollers) at the same time.  The
+following sections explain in detail what each CMakeLists.txt configuration
+option does and what you can change it to.  However, it is possible to
+configure each of these options using the `-D` command line flag.
+
+For example, to build the Infinity Keyboard default configuration:
+
+```bash
+$ mkdir build_infinity
+$ cd build_infinity
+$ cmake -DCHIP=mk20dx128vlf5 -DScanModule=MD1 -DMacroModule=PartialMap \
+        -DOutputModule=pjrcUSB -DDebugModule=full -DBaseMap=defaultMap \
+        -DDefaultMap="md1Overlay stdFuncMap" -DPartialMaps="hhkbpro2" \
+        ..
+$ make
+```
+
+CMake defaults to the values specified in CMakeLists.txt if not overridden via
+the command line.
+
+> NOTE: On Windows, you will have to use "wincmake" instead of "cmake".
+
+
+Selecting Microcontroller
+-------------------------
+
+This is where you select the chip you want to compile for.  The build system
+will automatically select the compiler needed to compile for your chip.
+
+Open up CMakeLists.txt in your favourite text editor. You are looking for:
+
+```cmake
+###
+# Chip Selection
+#
+
+#| You _MUST_ set this to match the microcontroller you are trying to compile for
+#| You _MUST_ clean the build directory if you change this value
+#|
+set( CHIP
+#	"at90usb162"       # Teensy   1.0 (avr)
+#	"atmega32u4"       # Teensy   2.0 (avr)
+#	"at90usb646"       # Teensy++ 1.0 (avr)
+#	"at90usb1286"      # Teensy++ 2.0 (avr)
+#	"mk20dx128"        # Teensy   3.0 (arm)
+    "mk20dx128vlf5"    # McHCK    mk20dx128vlf5
+#	"mk20dx256"        # Teensy   3.1 (arm)
+    CACHE STRING "Microcontroller Chip" )
+```
+
+Just uncomment the chip you want, and comment out the old one.
+
+> NOTE: If you change this option, you will *need* to delete the build
+> directory that is created in the Building sections below.
+
+
+Selecting Modules
+-----------------
+
+> WARNING: Not all modules are compatible, and some modules may have
+> dependencies on other modules.
+
+This is where the options start getting interesting.  The Kiibohd Controller
+is designed around a set of 4 types of modules that correspond to different
+functionality:
+
+- Scan Module
+- Macro Module
+- Output Module
+- Debug Module
+
+The Scan Module is where the most interesting stuff happens. These modules
+take in "keypress data".  A converter Scan Module will interpret a protocol
+into key press/releases.  A matrix Scan Module may inherit from the matrix
+module to scan keypress from a matrix This module just has to give
+press/release codes, but does have some callback control to other modules
+depending on the lifecycle for press/release codes (this can be very
+complicated depending on the protocol).  Each Scan Module has it's own default
+keymap/modifier map. (TODO recommend keymap changing in the Macro Module).
+
+Some scan modules have very specialized hardware requirements, each module
+directory should have at least a link to the needed parts and/or schematics
+(TODO!).
+
+The Macro Module takes care of the mapping of the key press/release code into
+an Output (USB) scan code.  Any layering, macros, keypress
+intelligence/reaction is done here.
+
+The Output Module is the module dealing with output from the microcontroller.
+Currently USB is the only output protocol.  Different USB output
+implementations are available, pjrc being the safest/least featureful one.
+Debug capabilities may depend on the module selected.
+
+The Debug Module enables various things like the Teensy LED on errors, debug
+terminal output.  (TODO get true UART working in avr, not just arm)
+
+Open up CMakeLists.txt in your favourite text editor.  Look for:
+
+```cmake
+###
+# Project Modules
+#
+
+#| Note: This is the only section you probably want to modify
+#| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module)
+#| All of the modules must be specified, as they generate the sources list of files to compile
+#| Any modifications to this file will cause a complete rebuild of the project
+
+#| Please look at the {Scan,Macro,Output,Debug} for information on the modules and how to create new ones
+
+##| Deals with acquiring the keypress information and turning it into a key index
+set(   ScanModule "MD1"
+    CACHE STRING "Scan Module" )
+
+##| Provides the mapping functions for DefaultMap and handles any macro processing before sending to the OutputModule
+set(  MacroModule "PartialMap"
+    CACHE STRING "Macro Module" )
+
+##| Sends the current list of usb key codes through USB HID
+set( OutputModule "pjrcUSB"
+    CACHE STRING "Output Module" )
+
+##| Debugging source to use, each module has it's own set of defines that it sets
+set(  DebugModule "full"
+    CACHE STRING "Debug Module" )
+```
+
+Look at each module individually for it's requirements. There is
+chip/architecture dependency checking but some permutations of modules may not
+be tested/compile.
+
+There are also CMake options for temporarily selecting modules. But it's
+easier to just edit the file. e.g. `cmake -DScanModuleOverride=<module name>`.
+
+
+Keymap Configuration
+--------------------
+
+This is where you define the layout for your keyboard.
+Currently, the only way to define kebyoard layouts is using [KLL](https://www.overleaf.com/read/zzqbdwqjfwwf).
+
+KLL is built up of 3 different kinds of keymaps in total.
+The BaseMap, DefaultMap and PartialMaps.
+
+For each type of keymap, it is possible to combine multiple .kll files together to create new ones using
+the compiler. The order of the files matter, as the right-most file will overwrite any setting in the
+previous files.
+
+> NOTE: Each keymap is done after the entire file is processed. This means that within the file the order
+>       of assignment doesa *not* matter (if you assign the same thing twice, then yes the most recent one
+>       takes priority).
+
+
+BaseMap defines what the keyboard can do. This includes specific capabilities of the keyboard (such as USB),
+the mapping of Scan Codes to USB Codes and any specific configurations for the keyboard.
+In general, the BaseMap rarely needs to be changed. Usually only when adding a new keyboard to the firmware
+does the Basemap need any modification.
+The BaseMap is what both DefaultMap and PartialMaps are based upon. This allows for a common reference
+when defining custom keymappings.
+
+> NOTE: Don't use defaultMap.kll to change your layouts. This will work, but they will not be portable.
+
+
+The DefaultMap is the normal state of the keyboard, i.e. your default layer.
+Using the BaseMap as a base, the DefaultMap is a modification of the BaseMap to what the keyboard should do.
+Since the DefaultMap uses USB Code to USB Code translations, this means that keymaps used for one keyboard
+will work with another keyboard.
+For example, I use Colemak, so this means I only have to define Colemak once for every keyboard that supports
+the kiibohd firmware. This is possible because every BaseMap defines the keyboard as a US ANSI like keyboard
+layout.
+The DefaultMap can also be thought of as Layer 0.
+
+
+PartialMaps are optional keymaps that can be "stacked" on top of the DefaultMap.
+They can be dynamically swapped out using the layer control capabilities:
+
+- layerLatch( `<layer number>` )
+- layerLock( `<layer number>` )
+- layerShift( `<layer number>` )
+
+layerShift is usually what you want as it works just like a standard shift key.
+layerLock is similar to the CapsLock key. While layerLatch is a latch, where only the next key you press
+will use that layer (e.g. stickykeys).
+
+A unique aspect of KLL layers is that it's a true stack of layers.
+When a layer is activated, only the keys that are specified by the layer will change.
+This means, if you define a layer that only sets `CapsLock -> LCtrl` and `LCtrl->Capslock` only those keys
+will change when you active the layer. All the other keys will use the layer that is "underneath" to
+lookup the keypress (usually the DefaultMap).
+
+This means that you can combine .kll files statically using the compiler or dynamically using the firmware.
+
+You can set the max number of layers by changing the `stateWordSize` define in one of your kll files.
+By default it is set to 8 in Macro/PartialMap/capabilities.kll. This means you can have up to 256 layers
+total (this includes the DefaultMap).
+You can increase this number to either 16 or 32 (this will use more Flash and RAM btw) which will give you
+2^16 and 2^32 possible layers respectively (65 535 and 4 294 967 295).
+
+
+```cmake
+###
+# Keymap Configuration (do not include the .kll extension)
+#
+
+#| Do not include the .kll extension
+#| * BaseMap maps the native keyboard scan codes to USB Codes so the layout is compatible with all other layouts
+#| * DefaultMap allows the default keymap to be modified from the BaseMap
+#| * PartialMaps is a set of dynamically set layers (there is no limit, but too many may use up too much RAM...)
+#| BaseMap generally does not need to be changed from "defaultMap"
+#|
+#| Syntax:
+#|  myMap
+#|    * defines a single .kll layout file, double-quotes are needed to distinguish between layers
+#|  "myMap specialLayer"
+#|    * defines myMap to be the main layout, then replace specialLayers on top of it
+#|
+#| - Only for PartialMaps -
+#|  "myMap specialLayer" "myMap colemak" dvorak
+#|    * As before, but also generates a second layer at index 2 and third at index 3
+#|
+#| NOTE:  Remember to add key(s) to enable each Partial Layer
+#| NOTE2: Layers are always based up the BaseMap (which should be an ANSI-like mapping)
+#| NOTE3: Compiler looks in kll/layouts and the build directory for layout files (precedence on build directory)
+
+##| Set the base keyboard .kll map, defaults to "defaultMap" if not found
+##| Looks in Scan/<Module Name> for the available BaseMaps
+set(     BaseMap "defaultMap"
+        CACHE STRING "KLL BaseMap/Scancode Keymapping" )
+
+##| Layer additonal .kll maps on the BaseMap, layers are in order from 1st to nth
+##| Can be set to ""
+set(  DefaultMap "md1Overlay stdFuncMap"
+        CACHE STRING "KLL DefaultMap" )
+
+##| ParitalMaps available on top of the BaseMap. See above for syntax on specifying multiple layers vs. layering
+##| Can be set to ""
+set( PartialMaps "hhkbpro2"
+        CACHE STRING "KLL PartialMaps/Layer Definitions" )
+```
+
+
+Linux Building
+--------------
+
+From this directory.
+
+```bash
+$ mkdir build
+$ cd build
+$ cmake ..
+$ make
+```
+
+Example output:
+
+```
+$ cmake ..
+-- Compiler Family:
+arm
+-- Chip Selected:
+mk20dx128vlf5
+-- Chip Family:
+mk20dx
+-- CPU Selected:
+cortex-m4
+-- Compiler Source Files:
+Lib/mk20dx.c;Lib/delay.c
+-- Bootloader Type:
+dfu
+-- Detected Scan Module Source Files:
+Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
+-- Detected Macro Module Source Files:
+Macro/PartialMap/macro.c
+-- Detected Output Module Source Files:
+Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c;
+Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c
+-- Detected Debug Module Source Files:
+Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
+-- Found Git: /usr/bin/git (found version "2.2.1")
+-- Found Ctags: /usr/bin/ctags (found version "5.8")
+-- Checking for latest kll version:
+Current branch master is up to date.
+-- Detected Layout Files:
+/home/hyatt/Source/controller/Macro/PartialMap/capabilities.kll
+/home/hyatt/Source/controller/Output/pjrcUSB/capabilities.kll
+/home/hyatt/Source/controller/Scan/MD1/defaultMap.kll
+/home/hyatt/Source/controller/kll/layouts/md1Overlay.kll
+/home/hyatt/Source/controller/kll/layouts/stdFuncMap.kll
+/home/hyatt/Source/controller/kll/layouts/hhkbpro2.kll
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /home/hyatt/Source/controller/build
+[master]: make                                [~/Source/controller/build](hyatt@x230mas:pts/6)
+[  5%] Generating KLL Layout
+Scanning dependencies of target kiibohd.elf
+[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
+[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.o
+[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.o
+[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.o
+[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.o
+[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.o
+[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.o
+[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.o
+[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.o
+[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.o
+[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.o
+[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.o
+[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.o
+[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
+[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
+Linking C executable kiibohd.elf
+[ 94%] Built target kiibohd.elf
+Scanning dependencies of target SizeAfter
+[100%] Chip usage for mk20dx128vlf5
+     SRAM:  32%     5384/16384      bytes
+    Flash:  18%     23384/126976    bytes
+[100%] Built target SizeAfter
+```
+
+Linux Loading Firmware
+----------------------
+
+First place the keyboard into re-flash mode.  This can be done either by
+pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
+Virtual Serial Port and using the 'reload' command.
+
+The `load` script that is created during the build can load the firmware over
+USB.  Either run it with sudo, or install the `98-kiibohd.rules` to
+`/etc/udev/rules.d` and run: `udevadm control --reload-rules`.
+
+To load the newly built firmware: `./load`.
+
+
+Linux Building Bootloader
+-------------------------
+
+> NOTE: Does not apply to Teensy based builds.
+
+From this directory.
+
+```bash
+$ cd Bootloader
+$ mkdir build
+$ cd build
+$ cmake ..
+$ make
+```
+
+Example output:
+
+```bash
+$ cmake ..
+-- Compiler Family:
+arm
+-- Chip Selected:
+mk20dx128vlf5
+-- Chip Family:
+mk20dx
+-- CPU Selected:
+cortex-m4
+-- Compiler Source Files:
+Lib/mk20dx.c;Lib/delay.c
+-- Bootloader Type:
+dfu
+-- Bootloader Source Files:
+main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c
+-- Found Git: /usr/bin/git (found version "2.2.1")
+-- Found Ctags: /usr/bin/ctags (found version "5.8")
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /home/hyatt/Source/controller/Bootloader/build
+[master]: make                                 [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6)
+Scanning dependencies of target kiibohd_bootloader.elf
+[ 11%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/main.c.o
+[ 22%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.c.o
+[ 33%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.desc.c.o
+[ 44%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/flash.c.o
+[ 55%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/kinetis.c.o
+[ 66%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/usb.c.o
+[ 77%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/mk20dx.c.o
+[ 88%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/delay.c.o
+Linking C executable kiibohd_bootloader.elf
+[ 88%] Built target kiibohd_bootloader.elf
+Scanning dependencies of target SizeAfter
+[100%] Chip usage for mk20dx128vlf5
+     SRAM:  19%     3176/16384      bytes
+    Flash:  2%      3736/126976     bytes
+[100%] Built target SizeAfter
+```
+
+
+Linux Loading Bootloader
+------------------------
+
+> NOTE: Does not apply to Teensy based builds.
+
+It's recommended to use an SWD-type flasher like a Bus Pirate.  There is a
+convenience script for loading the firmware once the system is setup.
+
+```bash
+$ cd Bootloader/Scripts
+$ ./swdLoad.bash
+```
+
+The above script requires Ruby, Ruby serial port module, git, and a
+`/dev/buspirate` udev rule.
+
+Additional Notes:
+
+* https://github.com/mchck/mchck/wiki/Getting-Started (See Bus-Pirate section)
+* https://wiki.archlinux.org/index.php/Bus_pirate
+
+
+Windows Building
+----------------
+
+From this directory.
+
+```bash
+$ mkdir build
+$ cd build
+$ wincmake ..
+$ make
+```
+
+Example output:
+
+```bash
+$ wincmake ..
+-- Compiler Family:
+arm
+-- Chip Selected:
+mk20dx128vlf5
+-- Chip Family:
+mk20dx
+-- CPU Selected:
+cortex-m4
+-- Compiler Source Files:
+Lib/mk20dx.c;Lib/delay.c
+-- Bootloader Type:
+dfu
+-- Detected Scan Module Source Files:
+Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
+-- Detected Macro Module Source Files:
+Macro/PartialMap/macro.c
+-- Detected Output Module Source Files:
+Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c;Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c
+-- Detected Debug Module Source Files:
+Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
+-- Found Git: C:/cygwin64/bin/git.exe (found version "2.1.1")
+-- Found Ctags: C:/cygwin64/bin/ctags.exe (found version "5.8")
+-- Checking for latest kll version:
+Current branch master is up to date.
+-- Detected Layout Files:
+C:/cygwin64/home/Jacob/controller/Macro/PartialMap/capabilities.kll
+C:/cygwin64/home/Jacob/controller/Output/pjrcUSB/capabilities.kll
+C:/cygwin64/home/Jacob/controller/Scan/MD1/defaultMap.kll
+C:/cygwin64/home/Jacob/controller/kll/layouts/md1Overlay.kll
+C:/cygwin64/home/Jacob/controller/kll/layouts/stdFuncMap.kll
+C:/cygwin64/home/Jacob/controller/kll/layouts/hhkbpro2.kll
+-- Configuring done
+-- Generating done
+-- Build files have been written to: C:/cygwin64/home/Jacob/controller/build
+
+$ make
+[  5%] Generating KLL Layout
+Scanning dependencies of target kiibohd.elf
+[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
+[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.obj
+[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.obj
+[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.obj
+[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.obj
+[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
+[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
+[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.obj
+[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.obj
+[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.obj
+[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.obj
+[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.obj
+[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
+[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
+[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
+Linking C executable kiibohd.elf
+[ 94%] Built target kiibohd.elf
+Scanning dependencies of target SizeAfter
+[100%] Chip usage for mk20dx128vlf5
+     SRAM:  32%     5384/16384      bytes
+    Flash:  18%     23296/126976    bytes
+[100%] Built target SizeAfter
+```
+
+### NOTES:
+
+If you get the following error, you have not setup wincmake correctly:
+
+```bash
+$ make
+[  5%] Generating KLL Layout
+Scanning dependencies of target kiibohd.elf
+[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
+../main.c:28:19: fatal error: macro.h: No such file or directory
+ #include <macro.h>
+                   ^
+compilation terminated.
+CMakeFiles/kiibohd.elf.dir/build.make:67: recipe for target 'CMakeFiles/kiibohd.elf.dir/main.c.o' failed
+make[2]: *** [CMakeFiles/kiibohd.elf.dir/main.c.o] Error 1
+CMakeFiles/Makefile2:98: recipe for target 'CMakeFiles/kiibohd.elf.dir/all' failed
+make[1]: *** [CMakeFiles/kiibohd.elf.dir/all] Error 2
+Makefile:75: recipe for target 'all' failed
+make: *** [all] Error 2
+```
+
+If you have already added the line to your `~/.bashrc` try restarting your
+cygwin shell.
+
+
+Windows Loading Firmware
+------------------------
+
+First place the keyboard into re-flash mode.  This can be done either by
+pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
+Virtual Serial Interface and using the `reload` command.
+
+The `load` script that is created during the build can load the firmware over
+USB.
+
+To load the newly built firmware: `./load`
+
+Be patient the couple of times, Windows is slow at installing drivers...
+
+
+Mac OS X Building
+-----------------
+
+From this directory.
+
+```bash
+$ mkdir build
+$ cd build
+$ cmake ..
+$ make
+```
+
+Example output:
+
+> TODO
+
+
+Mac OS X Loading Firmware
+-------------------------
+
+First place the keyboard into re-flash mode.  This can be done either by
+pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
+Virtual Serial Port and using the `reload` command.
+
+The `load` script that is created during the build can load the firmware over
+USB.
+
+To load the newly built firmware: `./load`.
+
+
+Virtual Serial Port - CLI
+-------------------------
+
+Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
+This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
+
+
+### Linux
+
+I generally use screen.  You will need sudo/root priviledges if you haven't
+installed the `98-kiibohd.rules` file to `/etc/udev/rules.d`.
+
+```
+$ screen /dev/ttyACM0
+# (Might be ACM1, ACM2, etc.)
+```
+
+### Windows
+
+Make sure the Teensy Virtual Serial Port driver is installed.  If possible use
+screen (as part of Cygwin).  Check which COM port the virtual serial port has
+been assigned to: `Device Manager->Ports (COM & LPT)->Teensy USB Serial`. In
+brackets it will say which COM port (e.g. COM3)
+
+putty works well when using DTR/DSR or RTS/CTS flow control.
+
+| Setting         | Value                                 |
+| --------------- | ------------------------------------- |
+| Connection type | Serial                                |
+| Serial line     | Your COM port, e.g. COM3              |
+| Speed           | doesn't matter, it's auto-negotiated  |
+
+Under `Category->Connections->Serial`: `Flow control: DTR/DSR`.
+
+If stuff is hard to read (you have a dumb colour scheme):
+`Category->Window->Colours->Use system color`.  That seems to make text at
+least readable
+
+> I use a custom colour scheme that makes each colour easy to see.
+> -HaaTa.
+
+Unfortunately, screen for Cygwin seems to be broken for serial ports, but you
+can try it...
+
+```bash
+$ screen /dev/ttyS2
+# Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc.
+```
+
+Gnu screen doesn't seem to echo all the characters (it works though).
+I believe it's a problem with stty, but I don't know how to fix it...
+
+### Mac OS X
+
+I recommend screen (can be installed via Macports).
+
+```bash
+$ screen /dev/tty.<usb something>
+```