README

   1 The Kiibohd Controller
   2 ----------------------
   3
   4 This README is a bit long, just look at the sections you are interested in.
   5 Linux is the ideal build environment (preferably recent'ish).
   6
   7
   8 Building on Mac should be ok for 99% of users with Macports (haven't tried Brew).
   9 The dfu Bootloader will not build correctly with the old version of arm-none-eabi-gcc that Macports currently has (4.7.3).
  10 This is due to a bug with lto (link time optimizations) which makes the resulting binary too big to fit on the chip (must be less than 4096 Bytes).
  11
  12 Building on Windows should also be fine for 99% of users, but takes a bunch of work to setup (because Windows is a crappy dev environment).
  13 Cygwin is currently required along with some non-Cygwin compilers and utilities (because they are not available for Cygwin).
  14 The dfu Bootloader will not build because of a Make 3.81+ bug/feature that removed support for non-Unix (Windows) filenames as dependencies of targets.
  15 If you replace the version of Make in Cygwin it should work (e.g. http://stackoverflow.com/questions/601516/cygwin-make-error-target-pattern-contains-no).
  16 However, make sure that the flash size is no larger than 4096 Bytes or the bootloader will not work.
  17
  18
  19 Please give authors credit for modules used if you use in a distributed product :D
  20
  21
  22
  23 ----------------------
  24 Dependencies
  25 ----------------------
  26
  27 Below listed are the Arch Linux pacman names, AUR packages may be required.
  28
  29 These depend a bit on which targets you are trying to build, but the general one:
  30 - cmake (2.8 and higher)
  31 - git
  32 - ctags (recommended, not required)
  33 - python3
  34 - libusb1.0 (and -devel)
  35 - make
  36
  37
  38 AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested versions below)
  39 - avr-gcc      (~4.8.0)
  40 - avr-binutils (~2.23.2)
  41 - avr-libc     (~1.8.0)
  42
  43
  44 ARM Specific (Teensy 3.0/3.1) (Sourcery CodeBench Lite for ARM EABI
  45 (http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/)
  46 - arm-none-eabi
  47 OR
  48 - arm-none-eabi-gcc
  49 - arm-none-eaby-binutils
  50 (I've actually had some issues with Sourcery CodeBench on Linux, so I often just use these)
  51
  52
  53
  54 ----------------------
  55 Windows Setup
  56 ----------------------
  57
  58 Compiling on Windows does work, just it's a bunch more work.
  59
  60 First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit is fine. Make sure the following are installed:
  61 - make
  62 - git (needed for some compilation info)
  63 - cmake
  64 - gcc-core
  65 - gcc-g++
  66 - libusb1.0
  67 - libusb1.0-devel
  68 - python3
  69 - ctags (recommended, not required)
  70
  71 Please note, I use cygwin term exclusively for any command line options. Unless mentioned otherwise use it.
  72 Do NOT use CMD or Powershell.
  73
  74 Also install the Windows version of CMake (3+ is ideal) - http://cmake.org/cmake/resources/software.html
  75 This is in addition to the Cygwin version. This is an easier alternative to installing another C compiler.
  76 Add the following line to your .bashrc, making sure the CMake path is correct:
  77   echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc
  78
  79 Install the PJRC Virtual Serial Port Driver:
  80 (http://pjrc.com/teensy/serial_install.exe)
  81
  82 Next, install the compiler(s) you want.
  83
  84
  85
  86  ---------
  87 | AVR GCC |
  88  ---------
  89
  90 You just need the Atmel AVR 8-bit Toolchain. The latest should be fine, as of writing it was 3.4.3.
  91
  92 http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx
  93 (Atmel AVR 8-bit Toolchain 3.4.3 - Windows)
  94
  95 Extract the files to a directory, say C:\avr8-gnu-toolchain. Then copy all the folders in that directory to the Cygwin /usr/local directory.
  96 Mine is C:\cygwin64\usr\local.
  97 (You can also just setup the paths, but this is faster/simpler. Might screw up your Cygwin though).
  98
  99
 100  ----------
 101 | ARM EABI |
 102  ----------
 103
 104 Download the latest version of Mentor Graphics Sourcery CodeBench ARM EABI.
 105
 106 http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/
 107
 108 Look for "Download the EABI Release".
 109 Enter your info to get the download link.
 110 Select the most recent download.
 111 Then download the "IA32 Windows Installer".
 112
 113 Then copy all the folders/files installed (e.g. C:\Users\Haata\MentorGraphics\Sourcery_CodeBench_Lite_for_ARM_EABI\) to Cygwin /usr/local directory.
 114 Mine is C:\cygwin64\usr\local.
 115 Or, you can setup paths using the installer (you have to be more careful though).
 116
 117
 118
 119 ----------------------
 120 Selecting Microcontroller
 121 ----------------------
 122
 123 This is where you select the chip you want to compile for.
 124 The build system will automatically select the compiler needed to compile for your chip.
 125
 126 Open up CMakeLists.txt in your favourite text editor.
 127 You are looking for:
 128
 129         ###
 130         # Chip Selection
 131         #
 132
 133         #| You _MUST_ set this to match the microcontroller you are trying to compile for
 134         #| You _MUST_ clean the build directory if you change this value
 135         #|
 136         set( CHIP
 137         #       "at90usb162"       # Teensy   1.0 (avr)
 138         #       "atmega32u4"       # Teensy   2.0 (avr)
 139         #       "at90usb646"       # Teensy++ 1.0 (avr)
 140                 "at90usb1286"      # Teensy++ 2.0 (avr)
 141         #       "mk20dx128"        # Teensy   3.0 (arm)
 142         #       "mk20dx256"        # Teensy   3.1 (arm)
 143         )
 144
 145 Just uncomment the chip you want, and comment out the old one.
 146
 147 NOTE: If you change this option, you will *need* to delete the build directory that is created in the Building sections below.
 148
 149
 150
 151 ----------------------
 152 Selecting Modules
 153 ----------------------
 154
 155 WARNING: Not all modules are compatible, and some modules may have dependencies on other modules.
 156
 157 This is where the options start getting interesting.
 158 The Kiibohd Controller is designed around a set of 4 types of modules that correspond to different functionality:
 159
 160 - Scan Module
 161 - Macro Module
 162 - Output Module
 163 - Debug Module
 164
 165 The Scan Module is where the most interesting stuff happens. These modules take in "keypress data".
 166 A converter Scan Module will interpret a protocol into key press/releases.
 167 A matrix Scan Module may inherit from the matrix module to scan keypress from a matrix
 168 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).
 169 Each Scan Module has it's own default keymap/modifier map. (TODO recommend keymap changing in the Macro Module).
 170
 171 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!).
 172
 173
 174 The Macro Module takes care of the mapping of the key press/release code into an Output (USB) scan code.
 175 Any layering, macros, keypress intelligence/reaction is done here.
 176
 177
 178 The Output Module is the module dealing with output from the microcontroller. Currently USB is the only output protocol.
 179 Different USB output implementations are available, pjrc being the safest/least featureful one.
 180 Debug capabilities may depend on the module selected.
 181
 182
 183 The Debug Module enables various things like the Teensy LED on errors, debug terminal output.
 184 (TODO get true UART working in avr, not just arm)
 185
 186
 187
 188 Open up CMakeLists.txt in your favourite text editor.
 189 Look for:
 190
 191         ###
 192         # Project Modules
 193         #
 194
 195         #| Note: This is the only section you probably want to modify
 196         #| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module)
 197         #| All of the modules must be specified, as they generate the sources list of files to compile
 198         #| Any modifications to this file will cause a complete rebuild of the project
 199
 200         #| Please look at the {Scan,Macro,Output,Debug}/module.txt for information on the modules and how to create new ones
 201
 202         ##| Deals with acquiring the keypress information and turning it into a key index
 203         set(  ScanModule  "avr-capsense" )
 204
 205         ##| Uses the key index and potentially applies special conditions to it, mapping it to a usb key code
 206         set( MacroModule  "buffer"  )
 207
 208         ##| Sends the current list of usb key codes through USB HID
 209         set(   OutputModule  "pjrc"   )
 210
 211         ##| Debugging source to use, each module has it's own set of defines that it sets
 212         set( DebugModule  "full"   )
 213
 214
 215 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.
 216
 217
 218 There are also CMake options for temporarily selecting modules. But it's easier to just edit the file.
 219 e.g. cmake -DScanModuleOverride=<module name>
 220
 221
 222
 223 ----------------------
 224 Linux Building
 225 ----------------------
 226
 227 From this directory.
 228 mkdir build
 229 cd build
 230 cmake ..
 231 make
 232
 233
 234 Example output:
 235
 236         [master]: cmake ..                 [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 237         -- Compiler Family:
 238         avr
 239         -- MCU Selected:
 240         at90usb1286
 241         -- Detected Scan Module Source Files:
 242         Scan/avr-capsense/scan_loop.c
 243         -- Detected Macro Module Source Files:
 244         Macro/buffer/macro.c
 245         -- Detected Output Module Source Files:
 246         Output/pjrc/usb_com.c;Output/pjrc/avr/usb_keyboard_debug.c
 247         -- Detected Debug Module Source Files:
 248         Debug/full/../led/led.c;Debug/full/../print/print.c
 249         -- Configuring done
 250         -- Generating done
 251         -- Build files have been written to: /home/hyatt/Source/Teensy/avr-capsense-haata/build
 252         [master]: make                     [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 253         Scanning dependencies of target kiibohd.elf
 254         [ 12%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
 255         [ 25%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/avr-capsense/scan_loop.c.o
 256         [ 37%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/buffer/macro.c.o
 257         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/usb_com.c.o
 258         [ 62%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/avr/usb_keyboard_debug.c.o
 259         [ 75%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
 260         [ 87%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
 261         Linking C executable kiibohd.elf
 262         Creating load file for Flash:  kiibohd.hex
 263         Creating Extended Listing:     kiibohd.lss
 264         Creating Symbol Table:         kiibohd.sym
 265         [ 87%] Built target kiibohd.elf
 266         Scanning dependencies of target SizeAfter
 267         [100%] Size after generation:
 268            text    data     bss     dec     hex filename
 269               0    6112       0    6112    17e0 kiibohd.hex
 270            5792     320     852    6964    1b34 kiibohd.elf
 271         [100%] Built target SizeAfter
 272
 273
 274
 275 ----------------------
 276 Linux Loading Firmware
 277 ----------------------
 278
 279 First place the keyboard into re-flash mode.
 280 This can be done either by pressing the re-flash button on the PCB/Teensy.
 281 Or by entering the Kiibohd Virtual Serial Port and using the 'reload' command.
 282
 283 The 'load' script that is created during the build can load the firmware over USB.
 284 Either run it with sudo, or install the 98-kiibohd.rules to /etc/udev/rules.d
 285  and run: udevadm control --reload-rules
 286
 287
 288 To load the newly built firmware:
 289 ./load
 290
 291
 292
 293 ----------------------
 294 Linux Building Bootloader
 295 ----------------------
 296
 297 *NOTE* Does not apply to Teensy based builds.
 298
 299 From this directory.
 300 cd Bootloader
 301 mkdir build
 302 cd build
 303 cmake ..
 304 make
 305
 306 Example output:
 307 TODO
 308
 309
 310
 311 ----------------------
 312 Linux Loading Bootloader
 313 ----------------------
 314
 315 *NOTE* Does not apply to Teensy based builds.
 316
 317 It's recommended to use an SWD-type flasher like a Bus Pirate.
 318 TODO
 319 (Guidelines here https://github.com/mchck/mchck/wiki/Getting-Started)
 320
 321
 322
 323 ----------------------
 324 Windows Building
 325 ----------------------
 326
 327 From this directory.
 328 mkdir build
 329 cd build
 330 wincmake ..
 331 make
 332
 333
 334 Example output:
 335
 336         $ cmake -G "Unix Makefiles" ..
 337         -- Compiler Family:
 338         avr
 339         -- MCU Selected:
 340         atmega32u4
 341         -- CPU Selected:
 342         megaAVR
 343         -- Detected Scan Module Source Files:
 344         Scan/SKM67001/../matrix/matrix_scan.c;Scan/SKM67001/../matrix/scan_loop.c
 345         -- Detected Macro Module Source Files:
 346         Macro/PartialMap/macro.c
 347         -- Detected Output Module Source Files:
 348         Output/pjrcUSB/output_com.c;Output/pjrcUSB/avr/usb_keyboard_serial.c
 349         -- Detected Debug Module Source Files:
 350         Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
 351         -- Found Git: C:/cygwin64/bin/git.exe (found version "1.7.9")
 352         -- Configuring done
 353         -- Generating done
 354         -- Build files have been written to: C:/cygwin64/home/jacob.alexander/src/capsense-beta/build
 355
 356         jacob.alexander@JALEXANDER2-LT ~/src/capsense-beta/build
 357         $ make
 358         Scanning dependencies of target kiibohd.elf
 359         [ 10%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
 360         [ 20%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/matrix_scan.c.obj
 361         [ 30%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/scan_loop.c.obj
 362         [ 40%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
 363         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
 364         [ 60%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/avr/usb_keyboard_serial.c.obj
 365         [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
 366         [ 80%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
 367         [ 90%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
 368         Linking C executable kiibohd.elf
 369         Creating load file for Flash:  kiibohd.hex
 370         Creating Extended Listing:     kiibohd.lss
 371         Creating Symbol Table:         kiibohd.sym
 372         [ 90%] Built target kiibohd.elf
 373         Scanning dependencies of target SizeAfter
 374         [100%] Size after generation
 375                 Flash Usage: data (hex)
 376                   RAM Usage: data (elf)
 377            text    data     bss     dec     hex filename
 378               0    9738       0    9738    260a kiibohd.hex
 379            7982    1756     264   10002    2712 kiibohd.elf
 380         [100%] Built target SizeAfter
 381
 382
 383
 384 ----------------------
 385 Windows Loading Firmware
 386 ----------------------
 387
 388 First place the keyboard into re-flash mode.
 389 This can be done either by pressing the re-flash button on the PCB/Teensy.
 390 Or by entering the Kiibohd Virtual Serial Interface and using the 'reload' command.
 391
 392 The 'load' script that is created during the build can load the firmware over USB.
 393
 394 To load the newly built firmware:
 395 ./load
 396
 397 Be patient the couple of times, Windows is slow at installing drivers...
 398
 399
 400
 401 ----------------------
 402 Mac OS X Building
 403 ----------------------
 404
 405 From this directory.
 406 mkdir build
 407 cd build
 408 cmake ..
 409 make
 410
 411
 412 Example output:
 413 TODO
 414
 415
 416
 417 ----------------------
 418 Mac OS X Loading Firmware
 419 ----------------------
 420
 421 First place the keyboard into re-flash mode.
 422 This can be done either by pressing the re-flash button on the PCB/Teensy.
 423 Or by entering the Kiibohd Virtual Serial Port and using the 'reload' command.
 424
 425 The 'load' script that is created during the build can load the firmware over USB.
 426
 427
 428 To load the newly built firmware:
 429 ./load
 430
 431
 432
 433 ----------------------
 434 Virtual Serial Port - CLI
 435 ----------------------
 436
 437 Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
 438 This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
 439
 440
 441  -------
 442 | Linux |
 443  -------
 444
 445 I generally use screen.
 446 You will need sudo/root priviledges if you haven't installed the 98-kiibohd.rules file to /etc/udev/rules.d
 447
 448 screen /dev/ttyACM0
 449 (Might be ACM1, ACM2, etc.)
 450
 451
 452  ---------
 453 | Windows |
 454  ---------
 455
 456 Make sure the Teensy Virtual Serial Port driver is installed.
 457 If possible use screen (as part of Cygwin).
 458 Check which COM port the virtual serial port has been assigned to:
 459    Device Manager->Ports (COM & LPT)->Teensy USB Serial
 460    In brackets it will say which COM port (e.g. COM3)
 461
 462
 463 putty works well when using DTR/DSR or RTS/CTS flow control.
 464 Connection type: Serial
 465 Serial line:     <Your COM port, e.g. COM3>
 466 Speed:           (doesn't matter, it's auto-negotiated)
 467
 468 Under Category->Connections->Serial
 469 Flow control:    DTR/DSR
 470
 471 If stuff is hard to read (you have a dumb colour scheme):
 472 Category->Window->Colours->Use system colur
 473 That seems to make text at least readable (I use a custom colour scheme that makes each colour easy to see -HaaTa).
 474
 475
 476 Unfortunately, screen for Cygwin seems to be broken for serial ports, but you can try it...
 477 screen /dev/ttyS2
 478 (Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc.)
 479
 480 Gnu screen doesn't seem to echo all the characters (it works though).
 481 I believe it's a problem with stty, but I don't know how to fix it...
 482
 483
 484  ----------
 485 | Mac OS X |
 486  ----------
 487
 488 I recommend screen (can be installed via Macports).
 489 screen /dev/tty.<usb something>