README.markdown

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