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