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