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