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).
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.
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).
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.
31 Please give authors credit for modules used if you use in a distributed
38 Below listed are the Arch Linux pacman names, AUR packages may be required.
40 These depend a bit on which targets you are trying to build, but the general
43 - cmake (2.8 and higher)
45 - ctags (recommended, not required)
47 - libusb1.0 (and -devel)
50 AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested
54 - avr-binutils (~2.23.2)
57 ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK)
59 - Arch Linux / Mac Ports
61 - arm-none-eaby-binutils
63 - Windows (https://launchpad.net/gcc-arm-embedded/+download)
64 - gcc-arm-none-eabi (win32.zip)
70 Compiling on Windows does work, just it's a bunch more work.
72 First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit
73 is fine. Make sure the following are installed:
76 - git (needed for some compilation info)
83 - ctags (recommended, not required)
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.
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
94 echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc
96 Install the [PJRC Virtual Serial Port Driver](http://pjrc.com/teensy/serial_install.exe).
98 Next, install the compiler(s) you want.
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.
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).
116 [GNU Tools for Embedded Processors
117 gcc-arm-none-eabi](https://launchpad.net/gcc-arm-embedded/+download).
119 Download `gcc-arm-none-eabi*win32.zip`.
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).
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.
135 For example, to build the Infinity Keyboard default configuration:
138 $ mkdir build_infinity
140 $ cmake -DCHIP=mk20dx128vlf5 -DScanModule=MD1 -DMacroModule=PartialMap \
141 -DOutputModule=pjrcUSB -DDebugModule=full -DBaseMap=defaultMap \
142 -DDefaultMap="md1Overlay stdFuncMap" -DPartialMaps="hhkbpro2" \
147 CMake defaults to the values specified in CMakeLists.txt if not overridden via
150 > NOTE: On Windows, you will have to use "wincmake" instead of "cmake".
153 Selecting Microcontroller
154 -------------------------
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.
159 Open up CMakeLists.txt in your favourite text editor. You are looking for:
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
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" )
180 Just uncomment the chip you want, and comment out the old one.
182 > NOTE: If you change this option, you will *need* to delete the build
183 > directory that is created in the Building sections below.
189 > WARNING: Not all modules are compatible, and some modules may have
190 > dependencies on other modules.
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
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).
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
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.
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.
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)
226 Open up CMakeLists.txt in your favourite text editor. Look for:
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
238 #| Please look at the {Scan,Macro,Output,Debug} for information on the modules and how to create new ones
240 ##| Deals with acquiring the keypress information and turning it into a key index
241 set( ScanModule "MD1"
242 CACHE STRING "Scan Module" )
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" )
248 ##| Sends the current list of usb key codes through USB HID
249 set( OutputModule "pjrcUSB"
250 CACHE STRING "Output Module" )
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" )
257 Look at each module individually for it's requirements. There is
258 chip/architecture dependency checking but some permutations of modules may not
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>`.
289 -- Compiler Source Files:
290 Lib/mk20dx.c;Lib/delay.c
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
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
343 Linux Loading Firmware
344 ----------------------
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.
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`.
354 To load the newly built firmware: `./load`.
357 Linux Building Bootloader
358 -------------------------
360 > NOTE: Does not apply to Teensy based builds.
384 -- Compiler Source Files:
385 Lib/mk20dx.c;Lib/delay.c
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")
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
415 Linux Loading Bootloader
416 ------------------------
418 > NOTE: Does not apply to Teensy based builds.
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.
424 $ cd Bootloader/Scripts
428 The above script requires Ruby, Ruby serial port module, git, and a
429 `/dev/buspirate` udev rule.
433 * https://github.com/mchck/mchck/wiki/Getting-Started (See Bus-Pirate section)
434 * https://wiki.archlinux.org/index.php/Bus_pirate
461 -- Compiler Source Files:
462 Lib/mk20dx.c;Lib/delay.c
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
486 -- Build files have been written to: C:/cygwin64/home/Jacob/controller/build
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
517 If you get the following error, you have not setup wincmake correctly:
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
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
536 If you have already added the line to your `~/.bashrc` try restarting your
540 Windows Loading Firmware
541 ------------------------
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.
547 The `load` script that is created during the build can load the firmware over
550 To load the newly built firmware: `./load`
552 Be patient the couple of times, Windows is slow at installing drivers...
572 Mac OS X Loading Firmware
573 -------------------------
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.
579 The `load` script that is created during the build can load the firmware over
582 To load the newly built firmware: `./load`.
585 Virtual Serial Port - CLI
586 -------------------------
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)
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`.
598 $ screen /dev/ttyACM0
599 # (Might be ACM1, ACM2, etc.)
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)
609 putty works well when using DTR/DSR or RTS/CTS flow control.
612 | --------------- | ------------------------------------- |
613 | Connection type | Serial |
614 | Serial line | Your COM port, e.g. COM3 |
615 | Speed | doesn't matter, it's auto-negotiated |
617 Under `Category->Connections->Serial`: `Flow control: DTR/DSR`.
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
623 > I use a custom colour scheme that makes each colour easy to see.
626 Unfortunately, screen for Cygwin seems to be broken for serial ports, but you
631 # Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc.
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...
639 I recommend screen (can be installed via Macports).
642 $ screen /dev/tty.<usb something>