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