README

   1 The Kiibohd Controller
   2 ----------------------
   3
   4 This README is a bit long, just look at the sections you are interested in.
   5 You only need to install avr-gcc if you want to build for the Teensy 2.0/2.0++.
   6 Everything else needs an arm-none-eabi-gcc compiler (e.g. Infinity keyboard, Teensy 3.0/3.1, McHCK).
   7
   8
   9 Linux is the ideal build environment (preferably recent'ish).
  10 In the near future I'll make available an Arch Linux VM for building/manufacturing tests.
  11
  12
  13 Building on Mac should be ok for 99% of users with Macports (haven't tried Brew).
  14 The dfu Bootloader will not build correctly with the old version of arm-none-eabi-gcc that Macports currently has (4.7.3).
  15 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).
  16
  17 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).
  18 Cygwin is currently required along with some non-Cygwin compilers and utilities (because they are not available for Cygwin).
  19 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.
  20 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).
  21 However, make sure that the flash size is no larger than 4096 Bytes or the bootloader will not work.
  22 Things will likely break if there are *SPACES IN YOUR PATHS*. I install cygwin to C:\cygwin64.
  23 If you are brave and have programming knowledge, I will accept patches to fix any issues regarding spaces in paths.
  24
  25
  26 Please give authors credit for modules used if you use in a distributed product :D
  27
  28
  29
  30 ----------------------
  31 General Dependencies
  32 ----------------------
  33
  34 Below listed are the Arch Linux pacman names, AUR packages may be required.
  35
  36 These depend a bit on which targets you are trying to build, but the general one:
  37 - cmake (2.8 and higher)
  38 - git
  39 - ctags (recommended, not required)
  40 - python3
  41 - libusb1.0 (and -devel)
  42 - make
  43
  44
  45 AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested versions below)
  46 - avr-gcc      (~4.8.0)
  47 - avr-binutils (~2.23.2)
  48 - avr-libc     (~1.8.0)
  49
  50
  51 ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK)
  52
  53 Arch Linux / Mac Ports
  54 - arm-none-eabi-gcc
  55 - arm-none-eaby-binutils
  56
  57 Windows
  58 (https://launchpad.net/gcc-arm-embedded/+download)
  59 - gcc-arm-none-eabi (win32.zip)
  60
  61
  62
  63 ----------------------
  64 Windows Setup
  65 ----------------------
  66
  67 Compiling on Windows does work, just it's a bunch more work.
  68
  69 First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit is fine. Make sure the following are installed:
  70 - make
  71 - git (needed for some compilation info)
  72 - cmake
  73 - gcc-core
  74 - gcc-g++
  75 - libusb1.0
  76 - libusb1.0-devel
  77 - python3
  78 - ctags (recommended, not required)
  79
  80 Please note, I use cygwin term exclusively for any command line options. Unless mentioned otherwise, use it.
  81 Do NOT use CMD or Powershell.
  82
  83 Also install the Windows version of CMake (3+ is ideal) - http://cmake.org/cmake/resources/software.html
  84 Select "Do not add CMake to system PATH".
  85 This is in addition to the Cygwin version. This is an easier alternative to installing another C compiler.
  86 Add the following line to your .bashrc, making sure the CMake path is correct:
  87   echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc
  88
  89 Install the PJRC Virtual Serial Port Driver:
  90 (http://pjrc.com/teensy/serial_install.exe)
  91
  92 Next, install the compiler(s) you want.
  93
  94
  95
  96  ---------
  97 | AVR GCC |
  98  ---------
  99
 100 You just need the Atmel AVR 8-bit Toolchain. The latest should be fine, as of writing it was 3.4.3.
 101
 102 http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx
 103 (Atmel AVR 8-bit Toolchain 3.4.3 - Windows)
 104
 105 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.
 106 Mine is C:\cygwin64\usr\local.
 107 (You can also just setup the paths, but this is faster/simpler. Might screw up your Cygwin though).
 108
 109
 110  ----------
 111 | ARM EABI |
 112  ----------
 113
 114 Download the latest GNU Tools for Embedded Processors gcc-arm-none-eabi.
 115
 116 https://launchpad.net/gcc-arm-embedded/+download
 117
 118 Download "gcc-arm-none-eabi*win32.zip".
 119
 120 Then extract all the folders/files in the zip to the Cygwin /usr/local directory.
 121 Mine is C:\cygwin64\usr\local.
 122 Or, you can setup paths using the installer (you have to be more careful, avoid spaces in paths).
 123
 124
 125
 126 ----------------------
 127 CMake Info
 128 ----------------------
 129
 130 One of the big benefits of using CMake is the ability to build multiple configurations (for different microcontrollers) at the same time.
 131 The following sections explain in detail what each CMakeLists.txt configuration option does and what you can change it to.
 132 However, it is possible to configure each of these options using the -D command line flag.
 133
 134 For example, to build the Infinity Keyboard default configuration:
 135
 136 mkdir build_infinity
 137 cd build_infinity
 138 cmake -DCHIP=mk20dx128vlf5 -DScanModule=MD1 -DMacroModule=PartialMap -DOutputModule=pjrcUSB -DDebugModule=full -DBaseMap=defaultMap -DDefaultMap="md1Overlay stdFuncMap" -DPartialMaps="hhkbpro2" ..
 139 make
 140
 141 CMake defaults to the values specified in CMakeLists.txt if not overridden via the command line.
 142 NOTE: On Windows, you will have to use "wincmake" instead of "cmake".
 143
 144
 145
 146 ----------------------
 147 Selecting Microcontroller
 148 ----------------------
 149
 150 This is where you select the chip you want to compile for.
 151 The build system will automatically select the compiler needed to compile for your chip.
 152
 153 Open up CMakeLists.txt in your favourite text editor.
 154 You are looking for:
 155
 156         ###
 157         # Chip Selection
 158         #
 159
 160         #| You _MUST_ set this to match the microcontroller you are trying to compile for
 161         #| You _MUST_ clean the build directory if you change this value
 162         #|
 163         set( CHIP
 164         #       "at90usb162"       # Teensy   1.0 (avr)
 165         #       "atmega32u4"       # Teensy   2.0 (avr)
 166         #       "at90usb646"       # Teensy++ 1.0 (avr)
 167         #       "at90usb1286"      # Teensy++ 2.0 (avr)
 168         #       "mk20dx128"        # Teensy   3.0 (arm)
 169                 "mk20dx128vlf5"    # McHCK    mk20dx128vlf5
 170         #       "mk20dx256"        # Teensy   3.1 (arm)
 171                 CACHE STRING "Microcontroller Chip" )
 172
 173 Just uncomment the chip you want, and comment out the old one.
 174
 175 NOTE: If you change this option, you will *need* to delete the build directory that is created in the Building sections below.
 176
 177
 178
 179 ----------------------
 180 Selecting Modules
 181 ----------------------
 182
 183 WARNING: Not all modules are compatible, and some modules may have dependencies on other modules.
 184
 185 This is where the options start getting interesting.
 186 The Kiibohd Controller is designed around a set of 4 types of modules that correspond to different functionality:
 187
 188 - Scan Module
 189 - Macro Module
 190 - Output Module
 191 - Debug Module
 192
 193 The Scan Module is where the most interesting stuff happens. These modules take in "keypress data".
 194 A converter Scan Module will interpret a protocol into key press/releases.
 195 A matrix Scan Module may inherit from the matrix module to scan keypress from a matrix
 196 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).
 197 Each Scan Module has it's own default keymap/modifier map. (TODO recommend keymap changing in the Macro Module).
 198
 199 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!).
 200
 201
 202 The Macro Module takes care of the mapping of the key press/release code into an Output (USB) scan code.
 203 Any layering, macros, keypress intelligence/reaction is done here.
 204
 205
 206 The Output Module is the module dealing with output from the microcontroller. Currently USB is the only output protocol.
 207 Different USB output implementations are available, pjrc being the safest/least featureful one.
 208 Debug capabilities may depend on the module selected.
 209
 210
 211 The Debug Module enables various things like the Teensy LED on errors, debug terminal output.
 212 (TODO get true UART working in avr, not just arm)
 213
 214
 215
 216 Open up CMakeLists.txt in your favourite text editor.
 217 Look for:
 218
 219         ###
 220         # Project Modules
 221         #
 222
 223         #| Note: This is the only section you probably want to modify
 224         #| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module)
 225         #| All of the modules must be specified, as they generate the sources list of files to compile
 226         #| Any modifications to this file will cause a complete rebuild of the project
 227
 228         #| Please look at the {Scan,Macro,Output,Debug} for information on the modules and how to create new ones
 229
 230         ##| Deals with acquiring the keypress information and turning it into a key index
 231         set(   ScanModule "MD1"
 232                 CACHE STRING "Scan Module" )
 233
 234         ##| Provides the mapping functions for DefaultMap and handles any macro processing before sending to the OutputModule
 235         set(  MacroModule "PartialMap"
 236                 CACHE STRING "Macro Module" )
 237
 238         ##| Sends the current list of usb key codes through USB HID
 239         set( OutputModule "pjrcUSB"
 240                 CACHE STRING "Output Module" )
 241
 242         ##| Debugging source to use, each module has it's own set of defines that it sets
 243         set(  DebugModule "full"
 244                 CACHE STRING "Debug Module" )
 245
 246
 247 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.
 248
 249
 250 There are also CMake options for temporarily selecting modules. But it's easier to just edit the file.
 251 e.g. cmake -DScanModuleOverride=<module name>
 252
 253
 254
 255 ----------------------
 256 Linux Building
 257 ----------------------
 258
 259 From this directory.
 260 mkdir build
 261 cd build
 262 cmake ..
 263 make
 264
 265
 266 Example output:
 267
 268         [master]: cmake ..                 [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 269         -- Compiler Family:
 270         avr
 271         -- MCU Selected:
 272         at90usb1286
 273         -- Detected Scan Module Source Files:
 274         Scan/avr-capsense/scan_loop.c
 275         -- Detected Macro Module Source Files:
 276         Macro/buffer/macro.c
 277         -- Detected Output Module Source Files:
 278         Output/pjrc/usb_com.c;Output/pjrc/avr/usb_keyboard_debug.c
 279         -- Detected Debug Module Source Files:
 280         Debug/full/../led/led.c;Debug/full/../print/print.c
 281         -- Configuring done
 282         -- Generating done
 283         -- Build files have been written to: /home/hyatt/Source/Teensy/avr-capsense-haata/build
 284         [master]: make                     [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
 285         Scanning dependencies of target kiibohd.elf
 286         [ 12%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
 287         [ 25%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/avr-capsense/scan_loop.c.o
 288         [ 37%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/buffer/macro.c.o
 289         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/usb_com.c.o
 290         [ 62%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/avr/usb_keyboard_debug.c.o
 291         [ 75%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
 292         [ 87%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
 293         Linking C executable kiibohd.elf
 294         Creating load file for Flash:  kiibohd.hex
 295         Creating Extended Listing:     kiibohd.lss
 296         Creating Symbol Table:         kiibohd.sym
 297         [ 87%] Built target kiibohd.elf
 298         Scanning dependencies of target SizeAfter
 299         [100%] Size after generation:
 300            text    data     bss     dec     hex filename
 301               0    6112       0    6112    17e0 kiibohd.hex
 302            5792     320     852    6964    1b34 kiibohd.elf
 303         [100%] Built target SizeAfter
 304
 305
 306
 307 ----------------------
 308 Linux Loading Firmware
 309 ----------------------
 310
 311 First place the keyboard into re-flash mode.
 312 This can be done either by pressing the re-flash button on the PCB/Teensy.
 313 Or by entering the Kiibohd Virtual Serial Port and using the 'reload' command.
 314
 315 The 'load' script that is created during the build can load the firmware over USB.
 316 Either run it with sudo, or install the 98-kiibohd.rules to /etc/udev/rules.d
 317  and run: udevadm control --reload-rules
 318
 319
 320 To load the newly built firmware:
 321 ./load
 322
 323
 324
 325 ----------------------
 326 Linux Building Bootloader
 327 ----------------------
 328
 329 *NOTE* Does not apply to Teensy based builds.
 330
 331 From this directory.
 332 cd Bootloader
 333 mkdir build
 334 cd build
 335 cmake ..
 336 make
 337
 338 Example output:
 339 TODO
 340
 341
 342
 343 ----------------------
 344 Linux Loading Bootloader
 345 ----------------------
 346
 347 *NOTE* Does not apply to Teensy based builds.
 348
 349 It's recommended to use an SWD-type flasher like a Bus Pirate.
 350 There is a convenience script for loading the firmware once the system is setup.
 351
 352 cd Bootloader/Scripts
 353 ./swdLoad.bash
 354
 355 The above script requires Ruby, Ruby serial port module, git, and a /dev/buspirate udev rule.
 356
 357 Additional Notes:
 358 https://github.com/mchck/mchck/wiki/Getting-Started
 359 https://wiki.archlinux.org/index.php/Bus_pirate
 360
 361
 362
 363 ----------------------
 364 Windows Building
 365 ----------------------
 366
 367 From this directory.
 368 mkdir build
 369 cd build
 370 wincmake ..
 371 make
 372
 373
 374 Example output:
 375
 376         $ wincmake ..
 377         -- Compiler Family:
 378         arm
 379         -- Chip Selected:
 380         mk20dx128vlf5
 381         -- Chip Family:
 382         mk20dx
 383         -- CPU Selected:
 384         cortex-m4
 385         -- Compiler Source Files:
 386         Lib/mk20dx.c;Lib/delay.c
 387         -- Bootloader Type:
 388         dfu
 389         -- Detected Scan Module Source Files:
 390         Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
 391         -- Detected Macro Module Source Files:
 392         Macro/PartialMap/macro.c
 393         -- Detected Output Module Source Files:
 394         Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c;Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c
 395         -- Detected Debug Module Source Files:
 396         Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
 397         -- Found Git: C:/cygwin64/bin/git.exe (found version "2.1.1")
 398         -- Found Ctags: C:/cygwin64/bin/ctags.exe (found version "5.8")
 399         -- Checking for latest kll version:
 400         Current branch master is up to date.
 401         -- Detected Layout Files:
 402         C:/cygwin64/home/Jacob/controller/Macro/PartialMap/capabilities.kll
 403         C:/cygwin64/home/Jacob/controller/Output/pjrcUSB/capabilities.kll
 404         C:/cygwin64/home/Jacob/controller/Scan/MD1/defaultMap.kll
 405         C:/cygwin64/home/Jacob/controller/kll/layouts/md1Overlay.kll
 406         C:/cygwin64/home/Jacob/controller/kll/layouts/stdFuncMap.kll
 407         C:/cygwin64/home/Jacob/controller/kll/layouts/hhkbpro2.kll
 408         -- Configuring done
 409         -- Generating done
 410         -- Build files have been written to: C:/cygwin64/home/Jacob/controller/build
 411
 412         Jacob@DenPC ~/controller/build
 413         $ make
 414         [  5%] Generating KLL Layout
 415         Scanning dependencies of target kiibohd.elf
 416         [ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
 417         [ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.obj
 418         [ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.obj
 419         [ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.obj
 420         [ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.obj
 421         [ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
 422         [ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
 423         [ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.obj
 424         [ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.obj
 425         [ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.obj
 426         [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.obj
 427         [ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.obj
 428         [ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
 429         [ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
 430         [ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
 431         Linking C executable kiibohd.elf
 432         [ 94%] Built target kiibohd.elf
 433         Scanning dependencies of target SizeAfter
 434         [100%] Chip usage for mk20dx128vlf5
 435                  SRAM:  32%     5384/16384      bytes
 436                 Flash:  18%     23296/126976    bytes
 437         [100%] Built target SizeAfter
 438
 439 NOTES:
 440
 441 If you get the following error, you have not setup wincmake correctly:
 442
 443 $ make
 444 [  5%] Generating KLL Layout
 445 Scanning dependencies of target kiibohd.elf
 446 [ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
 447 ../main.c:28:19: fatal error: macro.h: No such file or directory
 448  #include <macro.h>
 449                    ^
 450 compilation terminated.
 451 CMakeFiles/kiibohd.elf.dir/build.make:67: recipe for target 'CMakeFiles/kiibohd.elf.dir/main.c.o' failed
 452 make[2]: *** [CMakeFiles/kiibohd.elf.dir/main.c.o] Error 1
 453 CMakeFiles/Makefile2:98: recipe for target 'CMakeFiles/kiibohd.elf.dir/all' failed
 454 make[1]: *** [CMakeFiles/kiibohd.elf.dir/all] Error 2
 455 Makefile:75: recipe for target 'all' failed
 456 make: *** [all] Error 2
 457
 458 If you have already added the line to your ~/.bashrc try restarting your cygwin shell.
 459
 460
 461
 462 ----------------------
 463 Windows Loading Firmware
 464 ----------------------
 465
 466 First place the keyboard into re-flash mode.
 467 This can be done either by pressing the re-flash button on the PCB/Teensy.
 468 Or by entering the Kiibohd Virtual Serial Interface and using the 'reload' command.
 469
 470 The 'load' script that is created during the build can load the firmware over USB.
 471
 472 To load the newly built firmware:
 473 ./load
 474
 475 Be patient the couple of times, Windows is slow at installing drivers...
 476
 477
 478
 479 ----------------------
 480 Mac OS X Building
 481 ----------------------
 482
 483 From this directory.
 484 mkdir build
 485 cd build
 486 cmake ..
 487 make
 488
 489
 490 Example output:
 491 TODO
 492
 493
 494
 495 ----------------------
 496 Mac OS X Loading Firmware
 497 ----------------------
 498
 499 First place the keyboard into re-flash mode.
 500 This can be done either by pressing the re-flash button on the PCB/Teensy.
 501 Or by entering the Kiibohd Virtual Serial Port and using the 'reload' command.
 502
 503 The 'load' script that is created during the build can load the firmware over USB.
 504
 505
 506 To load the newly built firmware:
 507 ./load
 508
 509
 510
 511 ----------------------
 512 Virtual Serial Port - CLI
 513 ----------------------
 514
 515 Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
 516 This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
 517
 518
 519  -------
 520 | Linux |
 521  -------
 522
 523 I generally use screen.
 524 You will need sudo/root priviledges if you haven't installed the 98-kiibohd.rules file to /etc/udev/rules.d
 525
 526 screen /dev/ttyACM0
 527 (Might be ACM1, ACM2, etc.)
 528
 529
 530  ---------
 531 | Windows |
 532  ---------
 533
 534 Make sure the Teensy Virtual Serial Port driver is installed.
 535 If possible use screen (as part of Cygwin).
 536 Check which COM port the virtual serial port has been assigned to:
 537    Device Manager->Ports (COM & LPT)->Teensy USB Serial
 538    In brackets it will say which COM port (e.g. COM3)
 539
 540
 541 putty works well when using DTR/DSR or RTS/CTS flow control.
 542 Connection type: Serial
 543 Serial line:     <Your COM port, e.g. COM3>
 544 Speed:           (doesn't matter, it's auto-negotiated)
 545
 546 Under Category->Connections->Serial
 547 Flow control:    DTR/DSR
 548
 549 If stuff is hard to read (you have a dumb colour scheme):
 550 Category->Window->Colours->Use system colur
 551 That seems to make text at least readable (I use a custom colour scheme that makes each colour easy to see -HaaTa).
 552
 553
 554 Unfortunately, screen for Cygwin seems to be broken for serial ports, but you can try it...
 555 screen /dev/ttyS2
 556 (Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc.)
 557
 558 Gnu screen doesn't seem to echo all the characters (it works though).
 559 I believe it's a problem with stty, but I don't know how to fix it...
 560
 561
 562  ----------
 563 | Mac OS X |
 564  ----------
 565
 566 I recommend screen (can be installed via Macports).
 567 screen /dev/tty.<usb something>
 568