README

   1 The Kiibohd Controller
   2 ----------------------
   3
   4 TODO, write some insightful/informative :P
   5
   6 Please give authors credit for modules used if you use in a distributed product :D
   7
   8
   9
  10 ----------------------
  11 Dependencies
  12 ----------------------
  13
  14 Below listed are the Arch Linux pacman names, AUR packages may be required.
  15
  16 These depend a bit on which targets you are trying to build, but the general one:
  17 - cmake (2.8 and higher)
  18 - Teensy Loader (http://pjrc.com/teensy/loader.html)
  19
  20
  21 AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested versions below)
  22 - avr-gcc      (4.8.0)
  23 - avr-binutils (2.23.2)
  24 - avr-libc     (1.8.0)
  25
  26
  27 ARM Specific (Teensy 3.0/3.1) (Sourcery CodeBench Lite for ARM EABI
  28 (http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/)
  29 - arm-none-eabi
  30 OR
  31 - arm-none-eabi-gcc
  32 - arm-none-eaby-binutils
  33
  34
  35
  36 ----------------------
  37 Selecting Architecture
  38 ----------------------
  39
  40 This is where you choose which architecture you want to build for.
  41 The options are:
  42  - Teensy 1.0   (Not tested)
  43  - Teensy 1.0++ (Not tested)
  44  - Teensy 2.0
  45  - Teensy 2.0++
  46  - Teensy 3.0
  47  - Teensy 3.1
  48
  49 Open up CMakeLists.txt in your favourite text editor.
  50 You are looking for:
  51
  52         ###
  53         Compiler Family
  54         #
  55
  56         #| Specify the compiler family to use
  57         #| Currently only supports AVR and ARM
  58         #| "avr"       # Teensy   1.0
  59         #| "avr"       # Teensy   2.0
  60         #| "avr"       # Teensy++ 1.0
  61         #| "avr"       # Teensy++ 2.0
  62         #| "arm"       # Teensy   3.0
  63         #| "arm"       # Teensy   3.1
  64
  65         set( COMPILER_FAMILY "avr" )
  66
  67
  68 Just change the COMPILER_FAMILY variable to whatever you are trying to build for.
  69
  70 NOTE: If you change this option, you will *may* to delete the build directory that is created in the Building sections below.
  71
  72
  73
  74 ----------------------
  75 Selecting Microcontroller
  76 ----------------------
  77
  78 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).
  79
  80 Open up avr.cmake (or arm.cmake) in your favourite text editor.
  81 You are looking for:
  82
  83         ###
  84         # Atmel Defines and Linker Options
  85         #
  86
  87         #| MCU Name
  88         #| You _MUST_ set this to match the board you are using
  89         #| type "make clean" after changing this, so all files will be rebuilt
  90         #|
  91         #| "at90usb162"       # Teensy   1.0
  92         #| "atmega32u4"       # Teensy   2.0
  93         #| "at90usb646"       # Teensy++ 1.0
  94         #| "at90usb1286"      # Teensy++ 2.0
  95
  96         set( MCU "at90usb1286" )
  97
  98 *OR*
  99
 100         ###
 101         # ARM Defines and Linker Options
 102         #
 103
 104         #| Chip Name (Linker)
 105         #| You _MUST_ set this to match the board you are using
 106         #| type "make clean" after changing this, so all files will be rebuilt
 107         #|
 108         #| "mk20dx128"        # Teensy   3.0
 109         #| "mk20dx256"        # Teensy   3.1
 110
 111         set( CHIP "mk20dx128" )
 112
 113
 114 Just change the CHIP variable to the microcontroller you are trying to build for.
 115
 116 NOTE: If you change this option, you will *need* to delete the build directory that is created in the Building sections below.
 117
 118
 119
 120 ----------------------
 121 Selecting Modules
 122 ----------------------
 123
 124 WARNING: Not all modules are compatible, and some modules may have dependencies on other modules.
 125
 126 This is where the options start getting interesting.
 127 The Kiibohd Controller is designed around a set of 4 types of modules that correspond to different functionality:
 128
 129 - Scan Module
 130 - Macro Module
 131 - Output Module
 132 - Debug Module
 133
 134 The Scan Module is where the most interesting stuff happens. These modules take in "keypress data".
 135 A converter Scan Module will interpret a protocol into key press/releases.
 136 A matrix Scan Module may inherit from the matrix module to scan keypress from a matrix
 137 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).
 138 Each Scan Module has it's own default keymap/modifier map. (TODO recommend keymap changing in the Macro Module).
 139
 140 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!).
 141
 142
 143 The Macro Module takes care of the mapping of the key press/release code into an Output (USB) scan code.
 144 Any layering, macros, keypress intelligence/reaction is done here.
 145
 146
 147 The Output Module is the module dealing with output from the microcontroller. Currently USB is the only output protocol.
 148 Different USB output implementations are available, pjrc being the safest/least featureful one.
 149 Debug capabilities may depend on the module selected.
 150
 151
 152 The Debug Module enables various things like the Teensy LED on errors, debug terminal output.
 153 (TODO get true UART working in avr, not just arm)
 154
 155
 156
 157 Open up setup.cmake in your favourite text editor.
 158 Look for:
 159
 160         ###
 161         # Project Modules
 162         #
 163
 164         #| Note: This is the only section you probably want to modify
 165         #| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module)
 166         #| All of the modules must be specified, as they generate the sources list of files to compile
 167         #| Any modifications to this file will cause a complete rebuild of the project
 168
 169         #| Please look at the {Scan,Macro,Output,Debug}/module.txt for information on the modules and how to create new ones
 170
 171         ##| Deals with acquiring the keypress information and turning it into a key index
 172         set(  ScanModule  "avr-capsense" )
 173
 174         ##| Uses the key index and potentially applies special conditions to it, mapping it to a usb key code
 175         set( MacroModule  "buffer"  )
 176
 177         ##| Sends the current list of usb key codes through USB HID
 178         set(   OutputModule  "pjrc"   )
 179
 180         ##| Debugging source to use, each module has it's own set of defines that it sets
 181         set( DebugModule  "full"   )
 182
 183
 184 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.
 185
 186
 187 There are also CMake options for temporarily selecting modules. But it's easier to just edit the file.
 188 e.g. cmake -DScanModuleOverride=<module name>
 189
 190
 191
 192 ----------------------
 193 Linux Building
 194 ----------------------
 195
 196 From this directory.
 197 mkdir build
 198 cd build
 199 cmake ..
 200 make
 201
 202
 203 Example output:
 204
 205         [master]: cmake ..                 [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 206         -- Compiler Family:
 207         avr
 208         -- MCU Selected:
 209         at90usb1286
 210         -- Detected Scan Module Source Files:
 211         Scan/avr-capsense/scan_loop.c
 212         -- Detected Macro Module Source Files:
 213         Macro/buffer/macro.c
 214         -- Detected Output Module Source Files:
 215         Output/pjrc/usb_com.c;Output/pjrc/avr/usb_keyboard_debug.c
 216         -- Detected Debug Module Source Files:
 217         Debug/full/../led/led.c;Debug/full/../print/print.c
 218         -- Configuring done
 219         -- Generating done
 220         -- Build files have been written to: /home/hyatt/Source/Teensy/avr-capsense-haata/build
 221         [master]: make                     [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 222         Scanning dependencies of target kiibohd.elf
 223         [ 12%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
 224         [ 25%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/avr-capsense/scan_loop.c.o
 225         [ 37%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/buffer/macro.c.o
 226         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/usb_com.c.o
 227         [ 62%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/avr/usb_keyboard_debug.c.o
 228         [ 75%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
 229         [ 87%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
 230         Linking C executable kiibohd.elf
 231         Creating load file for Flash:  kiibohd.hex
 232         Creating Extended Listing:     kiibohd.lss
 233         Creating Symbol Table:         kiibohd.sym
 234         [ 87%] Built target kiibohd.elf
 235         Scanning dependencies of target SizeAfter
 236         [100%] Size after generation:
 237            text    data     bss     dec     hex filename
 238               0    6112       0    6112    17e0 kiibohd.hex
 239            5792     320     852    6964    1b34 kiibohd.elf
 240         [100%] Built target SizeAfter
 241
 242
 243
 244 ----------------------
 245 Linux Loading Firmware
 246 ----------------------
 247
 248 The 'load' script that is created during the build can load the firmware over USB.
 249 It uses sudo, so make sure you have the priviledges.
 250
 251 (TODO, not complete, avr and arm are different currently, need to be unified)
 252 ./load
 253
 254
 255
 256 ----------------------
 257 Windows Building
 258 ----------------------
 259
 260 TODO
 261
 262 ----------------------
 263 Windows Loading Firmware
 264 ----------------------
 265
 266 TODO
 267
 268 ----------------------
 269 Mac OS X Building
 270 ----------------------
 271
 272 TODO
 273
 274 ----------------------
 275 Mac OS X Loading Firmware
 276 ----------------------
 277
 278 TODO
 279
 280
 281
 282 ----------------------
 283 Debugging
 284 ----------------------
 285
 286 TODO
 287
 288