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 Windows Building
 295 ----------------------
 296
 297 From this directory.
 298 mkdir build
 299 cd build
 300 wincmake -G "Unix Makefiles" ..
 301 make
 302
 303
 304 Example output:
 305
 306         $ cmake -G "Unix Makefiles" ..
 307         -- Compiler Family:
 308         avr
 309         -- MCU Selected:
 310         atmega32u4
 311         -- CPU Selected:
 312         megaAVR
 313         -- Detected Scan Module Source Files:
 314         Scan/SKM67001/../matrix/matrix_scan.c;Scan/SKM67001/../matrix/scan_loop.c
 315         -- Detected Macro Module Source Files:
 316         Macro/PartialMap/macro.c
 317         -- Detected Output Module Source Files:
 318         Output/pjrcUSB/output_com.c;Output/pjrcUSB/avr/usb_keyboard_serial.c
 319         -- Detected Debug Module Source Files:
 320         Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
 321         -- Found Git: C:/cygwin64/bin/git.exe (found version "1.7.9")
 322         -- Configuring done
 323         -- Generating done
 324         -- Build files have been written to: C:/cygwin64/home/jacob.alexander/src/capsense-beta/build
 325
 326         jacob.alexander@JALEXANDER2-LT ~/src/capsense-beta/build
 327         $ make
 328         Scanning dependencies of target kiibohd.elf
 329         [ 10%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
 330         [ 20%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/matrix_scan.c.obj
 331         [ 30%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/scan_loop.c.obj
 332         [ 40%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
 333         [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
 334         [ 60%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/avr/usb_keyboard_serial.c.obj
 335         [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
 336         [ 80%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
 337         [ 90%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
 338         Linking C executable kiibohd.elf
 339         Creating load file for Flash:  kiibohd.hex
 340         Creating Extended Listing:     kiibohd.lss
 341         Creating Symbol Table:         kiibohd.sym
 342         [ 90%] Built target kiibohd.elf
 343         Scanning dependencies of target SizeAfter
 344         [100%] Size after generation
 345                 Flash Usage: data (hex)
 346                   RAM Usage: data (elf)
 347            text    data     bss     dec     hex filename
 348               0    9738       0    9738    260a kiibohd.hex
 349            7982    1756     264   10002    2712 kiibohd.elf
 350         [100%] Built target SizeAfter
 351
 352
 353
 354 ----------------------
 355 Windows Loading Firmware
 356 ----------------------
 357
 358 First place the keyboard into re-flash mode.
 359 This can be done either by pressing the re-flash button on the PCB/Teensy.
 360 Or by entering the Kiibohd Virtual Serial Interface and using the 'reload' command.
 361
 362 The 'load' script that is created during the build can load the firmware over USB.
 363
 364 To load the newly built firmware:
 365 ./load
 366
 367 Be patient the couple of times, Windows is slow at installing drivers...
 368
 369
 370
 371 ----------------------
 372 Mac OS X Building
 373 ----------------------
 374
 375 TODO
 376
 377
 378
 379 ----------------------
 380 Mac OS X Loading Firmware
 381 ----------------------
 382
 383 TODO
 384
 385
 386
 387 ----------------------
 388 Virtual Serial Port - CLI
 389 ----------------------
 390
 391 Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
 392 This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
 393
 394
 395  -------
 396 | Linux |
 397  -------
 398
 399 I generally use screen.
 400 You will need sudo/root priviledges if you haven't installed the 98-kiibohd.rules file to /etc/udev/rules.d
 401
 402 screen /dev/ttyACM0
 403 (Might be ACM1, ACM2, etc.)
 404
 405
 406  ---------
 407 | Windows |
 408  ---------
 409
 410 Make sure the Teensy Virtual Serial Port driver is installed.
 411 If possible use screen (as part of Cygwin).
 412
 413 screen /dev/ttyS3
 414 (Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc.)
 415
 416 Gnu screen doesn't seem to echo all the characters (it works though).
 417 I believe it's a problem with stty, but I don't know how to fix it...
 418
 419 putty works well when using DTR/DSR or RTS/CTS flow control.
 420
 421
 422  ----------
 423 | Mac OS X |
 424  ----------
 425
 426 TODO (What is the usual device name). screen if possible.
 427