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 Microcontroller
  85 ----------------------
  86
  87 This is where you select the chip you want to compile for.
  88 The build system will automatically select the compiler needed to compile for your chip.
  89
  90 Open up CMakeLists.txt in your favourite text editor.
  91 You are looking for:
  92
  93         ###
  94         # Chip Selection
  95         #
  96
  97         #| You _MUST_ set this to match the microcontroller you are trying to compile for
  98         #| You _MUST_ clean the build directory if you change this value
  99         #|
 100         set( CHIP
 101         #       "at90usb162"       # Teensy   1.0 (avr)
 102         #       "atmega32u4"       # Teensy   2.0 (avr)
 103         #       "at90usb646"       # Teensy++ 1.0 (avr)
 104                 "at90usb1286"      # Teensy++ 2.0 (avr)
 105         #       "mk20dx128"        # Teensy   3.0 (arm)
 106         #       "mk20dx256"        # Teensy   3.1 (arm)
 107         )
 108
 109 Just uncomment the chip you want, and comment out the old one.
 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 - Output 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 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!).
 136
 137
 138 The Macro Module takes care of the mapping of the key press/release code into an Output (USB) scan code.
 139 Any layering, macros, keypress intelligence/reaction is done here.
 140
 141
 142 The Output Module is the module dealing with output from the microcontroller. Currently USB is the only output protocol.
 143 Different USB output implementations are available, pjrc being the safest/least featureful one.
 144 Debug capabilities may depend on the module selected.
 145
 146
 147 The Debug Module enables various things like the Teensy LED on errors, debug terminal output.
 148 (TODO get true UART working in avr, not just arm)
 149
 150
 151
 152 Open up CMakeLists.txt in your favourite text editor.
 153 Look for:
 154
 155         ###
 156         # Project Modules
 157         #
 158
 159         #| Note: This is the only section you probably want to modify
 160         #| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module)
 161         #| All of the modules must be specified, as they generate the sources list of files to compile
 162         #| Any modifications to this file will cause a complete rebuild of the project
 163
 164         #| Please look at the {Scan,Macro,Output,Debug}/module.txt for information on the modules and how to create new ones
 165
 166         ##| Deals with acquiring the keypress information and turning it into a key index
 167         set(  ScanModule  "avr-capsense" )
 168
 169         ##| Uses the key index and potentially applies special conditions to it, mapping it to a usb key code
 170         set( MacroModule  "buffer"  )
 171
 172         ##| Sends the current list of usb key codes through USB HID
 173         set(   OutputModule  "pjrc"   )
 174
 175         ##| Debugging source to use, each module has it's own set of defines that it sets
 176         set( DebugModule  "full"   )
 177
 178
 179 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.
 180
 181
 182 There are also CMake options for temporarily selecting modules. But it's easier to just edit the file.
 183 e.g. cmake -DScanModuleOverride=<module name>
 184
 185
 186
 187 ----------------------
 188 Linux Building
 189 ----------------------
 190
 191 From this directory.
 192 mkdir build
 193 cd build
 194 cmake ..
 195 make
 196
 197
 198 Example output:
 199
 200         [master]: cmake ..                 [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 201         -- Compiler Family:
 202         avr
 203         -- MCU Selected:
 204         at90usb1286
 205         -- Detected Scan Module Source Files:
 206         Scan/avr-capsense/scan_loop.c
 207         -- Detected Macro Module Source Files:
 208         Macro/buffer/macro.c
 209         -- Detected Output Module Source Files:
 210         Output/pjrc/usb_com.c;Output/pjrc/avr/usb_keyboard_debug.c
 211         -- Detected Debug Module Source Files:
 212         Debug/full/../led/led.c;Debug/full/../print/print.c
 213         -- Configuring done
 214         -- Generating done
 215         -- Build files have been written to: /home/hyatt/Source/Teensy/avr-capsense-haata/build
 216         [master]: make                     [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 217         Scanning dependencies of target kiibohd.elf
 218         [ 12%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
 219         [ 25%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/avr-capsense/scan_loop.c.o
 220         [ 37%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/buffer/macro.c.o
 221         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/usb_com.c.o
 222         [ 62%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/avr/usb_keyboard_debug.c.o
 223         [ 75%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
 224         [ 87%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
 225         Linking C executable kiibohd.elf
 226         Creating load file for Flash:  kiibohd.hex
 227         Creating Extended Listing:     kiibohd.lss
 228         Creating Symbol Table:         kiibohd.sym
 229         [ 87%] Built target kiibohd.elf
 230         Scanning dependencies of target SizeAfter
 231         [100%] Size after generation:
 232            text    data     bss     dec     hex filename
 233               0    6112       0    6112    17e0 kiibohd.hex
 234            5792     320     852    6964    1b34 kiibohd.elf
 235         [100%] Built target SizeAfter
 236
 237
 238
 239 ----------------------
 240 Linux Loading Firmware
 241 ----------------------
 242
 243 The 'load' script that is created during the build can load the firmware over USB.
 244 It uses sudo, so make sure you have the priviledges.
 245
 246 ./load
 247
 248
 249
 250 ----------------------
 251 Windows Building
 252 ----------------------
 253
 254 From this directory.
 255 mkdir build
 256 cd build
 257 wincmake -G "Unix Makefiles" ..
 258
 259
 260 Example output:
 261
 262         $ cmake -G "Unix Makefiles" ..
 263         -- Compiler Family:
 264         avr
 265         -- MCU Selected:
 266         atmega32u4
 267         -- CPU Selected:
 268         megaAVR
 269         -- Detected Scan Module Source Files:
 270         Scan/SKM67001/../matrix/matrix_scan.c;Scan/SKM67001/../matrix/scan_loop.c
 271         -- Detected Macro Module Source Files:
 272         Macro/PartialMap/macro.c
 273         -- Detected Output Module Source Files:
 274         Output/pjrcUSB/output_com.c;Output/pjrcUSB/avr/usb_keyboard_serial.c
 275         -- Detected Debug Module Source Files:
 276         Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
 277         -- Found Git: C:/cygwin64/bin/git.exe (found version "1.7.9")
 278         -- Configuring done
 279         -- Generating done
 280         -- Build files have been written to: C:/cygwin64/home/jacob.alexander/src/capsense-beta/build
 281
 282         jacob.alexander@JALEXANDER2-LT ~/src/capsense-beta/build
 283         $ make
 284         Scanning dependencies of target kiibohd.elf
 285         [ 10%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
 286         [ 20%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/matrix_scan.c.obj
 287         [ 30%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/scan_loop.c.obj
 288         [ 40%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
 289         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
 290         [ 60%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/avr/usb_keyboard_serial.c.obj
 291         [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
 292         [ 80%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
 293         [ 90%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
 294         Linking C executable kiibohd.elf
 295         Creating load file for Flash:  kiibohd.hex
 296         Creating Extended Listing:     kiibohd.lss
 297         Creating Symbol Table:         kiibohd.sym
 298         [ 90%] Built target kiibohd.elf
 299         Scanning dependencies of target SizeAfter
 300         [100%] Size after generation
 301                 Flash Usage: data (hex)
 302                   RAM Usage: data (elf)
 303            text    data     bss     dec     hex filename
 304               0    9738       0    9738    260a kiibohd.hex
 305            7982    1756     264   10002    2712 kiibohd.elf
 306         [100%] Built target SizeAfter
 307
 308
 309
 310 ----------------------
 311 Windows Loading Firmware
 312 ----------------------
 313
 314 TODO
 315
 316 ----------------------
 317 Mac OS X Building
 318 ----------------------
 319
 320 TODO
 321
 322 ----------------------
 323 Mac OS X Loading Firmware
 324 ----------------------
 325
 326 TODO
 327
 328
 329 ----------------------
 330 Virtual Serial Port - CLI
 331 ----------------------
 332
 333 Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
 334 This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
 335
 336  -------
 337 | Linux |
 338  -------
 339
 340 I generally use screen.
 341
 342 sudo screen /dev/ttyACM0
 343
 344
 345  ---------
 346 | Windows |
 347  ---------
 348
 349 TODO Probably COM1, but not exactly sure. Tera Term.
 350
 351
 352  ----------
 353 | Mac OS X |
 354  ----------
 355
 356 TODO (What is the usual device name). screen if possible.
 357