controller/README

The Kiibohd Controller
----------------------

TODO, write some insightful/informative :P

Please give authors credit for modules used if you use in a distributed product :D



----------------------
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)
- Teensy Loader (http://pjrc.com/teensy/loader.html)


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) (Sourcery CodeBench Lite for ARM EABI
(http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/)
- arm-none-eabi
OR
- arm-none-eabi-gcc
- arm-none-eaby-binutils
(I've actually had some issues with Sourcery CodeBench on Linux, so I often just use these)



----------------------
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)

And make sure CMake is *NOT* installed through Cygwin. This is extremely important.
If this is not possible, you'll have to play with your paths in Cygwin to prioritize the Windows version of CMake.

Install the latest version of CMake - http://cmake.org/cmake/resources/software.html
Make sure to have CMake add itself to at least your PATH in the installer.
(If this errors out, you'll have to add CMake to your .bashrc path).

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

Extract the files to a directory, say C:\avr8-gnu-toolchain. Then copy all the folders in that directory to the Cygwin directory.
Mine is C:\cygwin64.
(You can also just setup the paths, but this is faster/simpler. Might screw up your Cygwin though).


 ----------
| ARM EABI |
 ----------

Download the latest version of Mentor Graphics Sourcery CodeBench ARM EABI.

http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/

Use the installer and make sure you add the binaries to your path within the installer.



----------------------
Selecting Architecture
----------------------

This is where you choose which architecture you want to build for.
The options are:
 - Teensy 1.0   (Not tested)
 - Teensy 1.0++ (Not tested)
 - Teensy 2.0
 - Teensy 2.0++
 - Teensy 3.0
 - Teensy 3.1

Open up CMakeLists.txt in your favourite text editor.
You are looking for:

	###
	Compiler Family
	#

	#| Specify the compiler family to use
	#| Currently only supports AVR and ARM
	#| "avr"       # Teensy   1.0
	#| "avr"       # Teensy   2.0
	#| "avr"       # Teensy++ 1.0
	#| "avr"       # Teensy++ 2.0
	#| "arm"       # Teensy   3.0
	#| "arm"       # Teensy   3.1

	set( COMPILER_FAMILY "avr" )


Just change the COMPILER_FAMILY variable to whatever you are trying to build for.

NOTE: If you change this option, you will *may* to delete the build directory that is created in the Building sections below.



----------------------
Selecting Microcontroller
----------------------

Even if you selected the "avr" family of microcontroller architectures, you will still need to specify a target microcontroller (or once more ARM microcontrollers are supported).

Open up avr.cmake (or arm.cmake) in your favourite text editor.
You are looking for:

	###
	# Atmel Defines and Linker Options
	#

	#| MCU Name
	#| You _MUST_ set this to match the board you are using
	#| type "make clean" after changing this, so all files will be rebuilt
	#|
	#| "at90usb162"       # Teensy   1.0
	#| "atmega32u4"       # Teensy   2.0
	#| "at90usb646"       # Teensy++ 1.0
	#| "at90usb1286"      # Teensy++ 2.0

	set( MCU "at90usb1286" )

*OR*

	###
	# ARM Defines and Linker Options
	#

	#| Chip Name (Linker)
	#| You _MUST_ set this to match the board you are using
	#| type "make clean" after changing this, so all files will be rebuilt
	#|
	#| "mk20dx128"        # Teensy   3.0
	#| "mk20dx256"        # Teensy   3.1

	set( CHIP "mk20dx128" )


Just change the CHIP variable to the microcontroller you are trying to build for.

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 setup.cmake 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}/module.txt 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  "avr-capsense" )

	##| Uses the key index and potentially applies special conditions to it, mapping it to a usb key code
	set( MacroModule  "buffer"  )

	##| Sends the current list of usb key codes through USB HID
	set(   OutputModule  "pjrc"   )

	##| Debugging source to use, each module has it's own set of defines that it sets
	set( DebugModule  "full"   )


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 ..                 [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
	-- Compiler Family:
	avr
	-- MCU Selected:
	at90usb1286
	-- Detected Scan Module Source Files:
	Scan/avr-capsense/scan_loop.c
	-- Detected Macro Module Source Files:
	Macro/buffer/macro.c
	-- Detected Output Module Source Files:
	Output/pjrc/usb_com.c;Output/pjrc/avr/usb_keyboard_debug.c
	-- Detected Debug Module Source Files:
	Debug/full/../led/led.c;Debug/full/../print/print.c
	-- Configuring done
	-- Generating done
	-- Build files have been written to: /home/hyatt/Source/Teensy/avr-capsense-haata/build
	[master]: make                     [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
	Scanning dependencies of target kiibohd.elf
	[ 12%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
	[ 25%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/avr-capsense/scan_loop.c.o
	[ 37%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/buffer/macro.c.o
	[ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/usb_com.c.o
	[ 62%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/avr/usb_keyboard_debug.c.o
	[ 75%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
	[ 87%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
	Linking C executable kiibohd.elf
	Creating load file for Flash:  kiibohd.hex
	Creating Extended Listing:     kiibohd.lss
	Creating Symbol Table:         kiibohd.sym
	[ 87%] Built target kiibohd.elf
	Scanning dependencies of target SizeAfter
	[100%] Size after generation:
	   text    data     bss     dec     hex filename
	      0    6112       0    6112    17e0 kiibohd.hex
	   5792     320     852    6964    1b34 kiibohd.elf
	[100%] Built target SizeAfter



----------------------
Linux Loading Firmware
----------------------

The 'load' script that is created during the build can load the firmware over USB.
It uses sudo, so make sure you have the priviledges.

./load



----------------------
Windows Building
----------------------

From this directory.
mkdir build
cd build
cmake -G "Unix Makefiles" ..


Example output:

	$ cmake -G "Unix Makefiles" ..
	-- Compiler Family:
	avr
	-- MCU Selected:
	atmega32u4
	-- CPU Selected:
	megaAVR
	-- Detected Scan Module Source Files:
	Scan/SKM67001/../matrix/matrix_scan.c;Scan/SKM67001/../matrix/scan_loop.c
	-- Detected Macro Module Source Files:
	Macro/PartialMap/macro.c
	-- Detected Output Module Source Files:
	Output/pjrcUSB/output_com.c;Output/pjrcUSB/avr/usb_keyboard_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 "1.7.9")
	-- Configuring done
	-- Generating done
	-- Build files have been written to: C:/cygwin64/home/jacob.alexander/src/capsense-beta/build

	jacob.alexander@JALEXANDER2-LT ~/src/capsense-beta/build
	$ make
	Scanning dependencies of target kiibohd.elf
	[ 10%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
	[ 20%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/matrix_scan.c.obj
	[ 30%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/scan_loop.c.obj
	[ 40%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
	[ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
	[ 60%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/avr/usb_keyboard_serial.c.obj
	[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
	[ 80%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
	[ 90%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
	Linking C executable kiibohd.elf
	Creating load file for Flash:  kiibohd.hex
	Creating Extended Listing:     kiibohd.lss
	Creating Symbol Table:         kiibohd.sym
	[ 90%] Built target kiibohd.elf
	Scanning dependencies of target SizeAfter
	[100%] Size after generation
		Flash Usage: data (hex)
		  RAM Usage: data (elf)
	   text    data     bss     dec     hex filename
	      0    9738       0    9738    260a kiibohd.hex
	   7982    1756     264   10002    2712 kiibohd.elf
	[100%] Built target SizeAfter



----------------------
Windows Loading Firmware
----------------------

TODO

----------------------
Mac OS X Building
----------------------

TODO

----------------------
Mac OS X Loading Firmware
----------------------

TODO


----------------------
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.

sudo screen /dev/ttyACM0


 ---------
| Windows |
 ---------

TODO Probably COM1, but not exactly sure. Tera Term.


 ----------
| Mac OS X |
 ----------

TODO (What is the usual device name). screen if possible.