Mercurial > louis > kiibohd-controller

changeset 277:aabd00e4b17b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Convert README to Markdown format. This makes it render nicely on GitHub's website, as well as having a consistent plain-text format that should be familiar to many.
author Mike Cooper <mythmon@gmail.com>
date Wed, 11 Feb 2015 22:22:12 -0800
parents 2a3468f5d8be
children 42e801e0b444
files README README.markdown
diffstat 2 files changed, 643 insertions(+), 632 deletions(-) [+]
line wrap: on
line diff
--- a/README	Mon Feb 09 15:58:07 2015 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,632 +0,0 @@
-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 (haven't tried Brew).
-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 it should work (e.g. http://stackoverflow.com/questions/601516/cygwin-make-error-target-pattern-contains-no).
-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-eaby-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 (3+ is ideal) - http://cmake.org/cmake/resources/software.html
-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. The latest should be fine, as of writing it was 3.4.3.
-
-http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx
-(Atmel AVR 8-bit Toolchain 3.4.3 - Windows)
-
-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:
-
-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:
-
-	###
-	# 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:
-
-	###
-	# 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>
-
-
-
-----------------------
-Linux Building
-----------------------
-
-From this directory.
-mkdir build
-cd build
-cmake ..
-make
-
-
-Example output:
-
-	[master]: cmake ..                            [~/Source/controller/build](hyatt@x230mas:pts/6)
-	-- 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.
-cd Bootloader
-mkdir build
-cd build
-cmake ..
-make
-
-Example output:
-
-	[master]: cmake ..                             [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6)
-	-- 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.
-
-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.
-mkdir build
-cd build
-wincmake ..
-make
-
-
-Example output:
-
-	$ 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
-
-	Jacob@DenPC ~/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:
-
-$ 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.
-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.
-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 colur
-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...
-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).
-screen /dev/tty.<usb something>
-
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.markdown	Wed Feb 11 22:22:12 2015 -0800
@@ -0,0 +1,643 @@
+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 (haven't tried
+Brew). 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-eaby-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>`.
+
+
+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>
+```