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