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 (I've actually had some issues with Sourcery CodeBench on Linux, so I often just use these)
  34
  35
  36
  37 ----------------------
  38 Windows Setup
  39 ----------------------
  40
  41 Compiling on Windows does work, just it's a bunch more work.
  42
  43 First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit is fine. Make sure the following are installed:
  44 - make
  45 - git (needed for some compilation info)
  46 - cmake
  47 - gcc-core
  48 - gcc-g++ or gcc-c++
  49
  50 And make sure CMake is *NOT* installed through Cygwin. This is extremely important.
  51 If this is not possible, you'll have to play with your paths in Cygwin to prioritize the Windows version of CMake.
  52
  53 Also install the Windows version of CMake - http://cmake.org/cmake/resources/software.html
  54 This is in addition to the Cygwin version. This is an easier alternative to installing another C compiler.
  55 Add the following line to your .bashrc, making sure the CMake path is correct:
  56   alias wincmake="PATH='/cygdrive/c/Program Files (x86)/CMake 2.8'/bin:\"${PATH}\" cmake"
  57
  58 Next, install the compiler(s) you want.
  59
  60  ---------
  61 | AVR GCC |
  62  ---------
  63
  64 You just need the Atmel AVR 8-bit Toolchain. The latest should be fine, as of writing it was 3.4.3.
  65
  66 http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx
  67
  68 Extract the files to a directory, say C:\avr8-gnu-toolchain. Then copy all the folders in that directory to the Cygwin directory.
  69 Mine is C:\cygwin64.
  70 (You can also just setup the paths, but this is faster/simpler. Might screw up your Cygwin though).
  71
  72
  73  ----------
  74 | ARM EABI |
  75  ----------
  76
  77 Download the latest version of Mentor Graphics Sourcery CodeBench ARM EABI.
  78
  79 http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/
  80
  81 Use the installer and make sure you add the binaries to your path within the installer.
  82
  83
  84
  85 ----------------------
  86 Selecting Architecture
  87 ----------------------
  88
  89 This is where you choose which architecture you want to build for.
  90 The options are:
  91  - Teensy 1.0   (Not tested)
  92  - Teensy 1.0++ (Not tested)
  93  - Teensy 2.0
  94  - Teensy 2.0++
  95  - Teensy 3.0
  96  - Teensy 3.1
  97
  98 Open up CMakeLists.txt in your favourite text editor.
  99 You are looking for:
 100
 101         ###
 102         Compiler Family
 103         #
 104
 105         #| Specify the compiler family to use
 106         #| Currently only supports AVR and ARM
 107         #| "avr"       # Teensy   1.0
 108         #| "avr"       # Teensy   2.0
 109         #| "avr"       # Teensy++ 1.0
 110         #| "avr"       # Teensy++ 2.0
 111         #| "arm"       # Teensy   3.0
 112         #| "arm"       # Teensy   3.1
 113
 114         set( COMPILER_FAMILY "avr" )
 115
 116
 117 Just change the COMPILER_FAMILY variable to whatever you are trying to build for.
 118
 119 NOTE: If you change this option, you will *may* to delete the build directory that is created in the Building sections below.
 120
 121
 122
 123 ----------------------
 124 Selecting Microcontroller
 125 ----------------------
 126
 127 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).
 128
 129 Open up avr.cmake (or arm.cmake) in your favourite text editor.
 130 You are looking for:
 131
 132         ###
 133         # Atmel Defines and Linker Options
 134         #
 135
 136         #| MCU Name
 137         #| You _MUST_ set this to match the board you are using
 138         #| type "make clean" after changing this, so all files will be rebuilt
 139         #|
 140         #| "at90usb162"       # Teensy   1.0
 141         #| "atmega32u4"       # Teensy   2.0
 142         #| "at90usb646"       # Teensy++ 1.0
 143         #| "at90usb1286"      # Teensy++ 2.0
 144
 145         set( MCU "at90usb1286" )
 146
 147 *OR*
 148
 149         ###
 150         # ARM Defines and Linker Options
 151         #
 152
 153         #| Chip Name (Linker)
 154         #| You _MUST_ set this to match the board you are using
 155         #| type "make clean" after changing this, so all files will be rebuilt
 156         #|
 157         #| "mk20dx128"        # Teensy   3.0
 158         #| "mk20dx256"        # Teensy   3.1
 159
 160         set( CHIP "mk20dx128" )
 161
 162
 163 Just change the CHIP variable to the microcontroller you are trying to build for.
 164
 165 NOTE: If you change this option, you will *need* to delete the build directory that is created in the Building sections below.
 166
 167
 168
 169 ----------------------
 170 Selecting Modules
 171 ----------------------
 172
 173 WARNING: Not all modules are compatible, and some modules may have dependencies on other modules.
 174
 175 This is where the options start getting interesting.
 176 The Kiibohd Controller is designed around a set of 4 types of modules that correspond to different functionality:
 177
 178 - Scan Module
 179 - Macro Module
 180 - Output Module
 181 - Debug Module
 182
 183 The Scan Module is where the most interesting stuff happens. These modules take in "keypress data".
 184 A converter Scan Module will interpret a protocol into key press/releases.
 185 A matrix Scan Module may inherit from the matrix module to scan keypress from a matrix
 186 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).
 187 Each Scan Module has it's own default keymap/modifier map. (TODO recommend keymap changing in the Macro Module).
 188
 189 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!).
 190
 191
 192 The Macro Module takes care of the mapping of the key press/release code into an Output (USB) scan code.
 193 Any layering, macros, keypress intelligence/reaction is done here.
 194
 195
 196 The Output Module is the module dealing with output from the microcontroller. Currently USB is the only output protocol.
 197 Different USB output implementations are available, pjrc being the safest/least featureful one.
 198 Debug capabilities may depend on the module selected.
 199
 200
 201 The Debug Module enables various things like the Teensy LED on errors, debug terminal output.
 202 (TODO get true UART working in avr, not just arm)
 203
 204
 205
 206 Open up setup.cmake in your favourite text editor.
 207 Look for:
 208
 209         ###
 210         # Project Modules
 211         #
 212
 213         #| Note: This is the only section you probably want to modify
 214         #| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module)
 215         #| All of the modules must be specified, as they generate the sources list of files to compile
 216         #| Any modifications to this file will cause a complete rebuild of the project
 217
 218         #| Please look at the {Scan,Macro,Output,Debug}/module.txt for information on the modules and how to create new ones
 219
 220         ##| Deals with acquiring the keypress information and turning it into a key index
 221         set(  ScanModule  "avr-capsense" )
 222
 223         ##| Uses the key index and potentially applies special conditions to it, mapping it to a usb key code
 224         set( MacroModule  "buffer"  )
 225
 226         ##| Sends the current list of usb key codes through USB HID
 227         set(   OutputModule  "pjrc"   )
 228
 229         ##| Debugging source to use, each module has it's own set of defines that it sets
 230         set( DebugModule  "full"   )
 231
 232
 233 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.
 234
 235
 236 There are also CMake options for temporarily selecting modules. But it's easier to just edit the file.
 237 e.g. cmake -DScanModuleOverride=<module name>
 238
 239
 240
 241 ----------------------
 242 Linux Building
 243 ----------------------
 244
 245 From this directory.
 246 mkdir build
 247 cd build
 248 cmake ..
 249 make
 250
 251
 252 Example output:
 253
 254         [master]: cmake ..                 [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 255         -- Compiler Family:
 256         avr
 257         -- MCU Selected:
 258         at90usb1286
 259         -- Detected Scan Module Source Files:
 260         Scan/avr-capsense/scan_loop.c
 261         -- Detected Macro Module Source Files:
 262         Macro/buffer/macro.c
 263         -- Detected Output Module Source Files:
 264         Output/pjrc/usb_com.c;Output/pjrc/avr/usb_keyboard_debug.c
 265         -- Detected Debug Module Source Files:
 266         Debug/full/../led/led.c;Debug/full/../print/print.c
 267         -- Configuring done
 268         -- Generating done
 269         -- Build files have been written to: /home/hyatt/Source/Teensy/avr-capsense-haata/build
 270         [master]: make                     [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 271         Scanning dependencies of target kiibohd.elf
 272         [ 12%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
 273         [ 25%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/avr-capsense/scan_loop.c.o
 274         [ 37%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/buffer/macro.c.o
 275         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/usb_com.c.o
 276         [ 62%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/avr/usb_keyboard_debug.c.o
 277         [ 75%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
 278         [ 87%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
 279         Linking C executable kiibohd.elf
 280         Creating load file for Flash:  kiibohd.hex
 281         Creating Extended Listing:     kiibohd.lss
 282         Creating Symbol Table:         kiibohd.sym
 283         [ 87%] Built target kiibohd.elf
 284         Scanning dependencies of target SizeAfter
 285         [100%] Size after generation:
 286            text    data     bss     dec     hex filename
 287               0    6112       0    6112    17e0 kiibohd.hex
 288            5792     320     852    6964    1b34 kiibohd.elf
 289         [100%] Built target SizeAfter
 290
 291
 292
 293 ----------------------
 294 Linux Loading Firmware
 295 ----------------------
 296
 297 The 'load' script that is created during the build can load the firmware over USB.
 298 It uses sudo, so make sure you have the priviledges.
 299
 300 ./load
 301
 302
 303
 304 ----------------------
 305 Windows Building
 306 ----------------------
 307
 308 From this directory.
 309 mkdir build
 310 cd build
 311 wincmake -G "Unix Makefiles" ..
 312
 313
 314 Example output:
 315
 316         $ cmake -G "Unix Makefiles" ..
 317         -- Compiler Family:
 318         avr
 319         -- MCU Selected:
 320         atmega32u4
 321         -- CPU Selected:
 322         megaAVR
 323         -- Detected Scan Module Source Files:
 324         Scan/SKM67001/../matrix/matrix_scan.c;Scan/SKM67001/../matrix/scan_loop.c
 325         -- Detected Macro Module Source Files:
 326         Macro/PartialMap/macro.c
 327         -- Detected Output Module Source Files:
 328         Output/pjrcUSB/output_com.c;Output/pjrcUSB/avr/usb_keyboard_serial.c
 329         -- Detected Debug Module Source Files:
 330         Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
 331         -- Found Git: C:/cygwin64/bin/git.exe (found version "1.7.9")
 332         -- Configuring done
 333         -- Generating done
 334         -- Build files have been written to: C:/cygwin64/home/jacob.alexander/src/capsense-beta/build
 335
 336         jacob.alexander@JALEXANDER2-LT ~/src/capsense-beta/build
 337         $ make
 338         Scanning dependencies of target kiibohd.elf
 339         [ 10%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
 340         [ 20%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/matrix_scan.c.obj
 341         [ 30%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/scan_loop.c.obj
 342         [ 40%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
 343         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
 344         [ 60%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/avr/usb_keyboard_serial.c.obj
 345         [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
 346         [ 80%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
 347         [ 90%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
 348         Linking C executable kiibohd.elf
 349         Creating load file for Flash:  kiibohd.hex
 350         Creating Extended Listing:     kiibohd.lss
 351         Creating Symbol Table:         kiibohd.sym
 352         [ 90%] Built target kiibohd.elf
 353         Scanning dependencies of target SizeAfter
 354         [100%] Size after generation
 355                 Flash Usage: data (hex)
 356                   RAM Usage: data (elf)
 357            text    data     bss     dec     hex filename
 358               0    9738       0    9738    260a kiibohd.hex
 359            7982    1756     264   10002    2712 kiibohd.elf
 360         [100%] Built target SizeAfter
 361
 362
 363
 364 ----------------------
 365 Windows Loading Firmware
 366 ----------------------
 367
 368 TODO
 369
 370 ----------------------
 371 Mac OS X Building
 372 ----------------------
 373
 374 TODO
 375
 376 ----------------------
 377 Mac OS X Loading Firmware
 378 ----------------------
 379
 380 TODO
 381
 382
 383 ----------------------
 384 Virtual Serial Port - CLI
 385 ----------------------
 386
 387 Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
 388 This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
 389
 390  -------
 391 | Linux |
 392  -------
 393
 394 I generally use screen.
 395
 396 sudo screen /dev/ttyACM0
 397
 398
 399  ---------
 400 | Windows |
 401  ---------
 402
 403 TODO Probably COM1, but not exactly sure. Tera Term.
 404
 405
 406  ----------
 407 | Mac OS X |
 408  ----------
 409
 410 TODO (What is the usual device name). screen if possible.
 411