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