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