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