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).
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.
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).
18 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).
19 Cygwin is currently required along with some non-Cygwin compilers and utilities (because they are not available for Cygwin).
20 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.
21 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).
22 However, make sure that the flash size is no larger than 4096 Bytes or the bootloader will not work.
23 Things will likely break if there are *SPACES IN YOUR PATHS*. I install cygwin to C:\cygwin64.
24 If you are brave and have programming knowledge, I will accept patches to fix any issues regarding spaces in paths.
27 Please give authors credit for modules used if you use in a distributed product :D
31 ----------------------
33 ----------------------
35 Below listed are the Arch Linux pacman names, AUR packages may be required.
37 These depend a bit on which targets you are trying to build, but the general one:
38 - cmake (2.8 and higher)
40 - ctags (recommended, not required)
42 - libusb1.0 (and -devel)
46 AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested versions below)
48 - avr-binutils (~2.23.2)
52 ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK)
54 Arch Linux / Mac Ports
56 - arm-none-eaby-binutils
59 (https://launchpad.net/gcc-arm-embedded/+download)
60 - gcc-arm-none-eabi (win32.zip)
64 ----------------------
66 ----------------------
68 Compiling on Windows does work, just it's a bunch more work.
70 First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit is fine. Make sure the following are installed:
72 - git (needed for some compilation info)
79 - ctags (recommended, not required)
81 Please note, I use cygwin term exclusively for any command line options. Unless mentioned otherwise, use it.
82 Do NOT use CMD or Powershell.
84 Also install the Windows version of CMake (3+ is ideal) - http://cmake.org/cmake/resources/software.html
85 Select "Do not add CMake to system PATH".
86 This is in addition to the Cygwin version. This is an easier alternative to installing another C compiler.
87 Add the following line to your .bashrc, making sure the CMake path is correct:
88 echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc
90 Install the PJRC Virtual Serial Port Driver:
91 (http://pjrc.com/teensy/serial_install.exe)
93 Next, install the compiler(s) you want.
101 You just need the Atmel AVR 8-bit Toolchain. The latest should be fine, as of writing it was 3.4.3.
103 http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx
104 (Atmel AVR 8-bit Toolchain 3.4.3 - Windows)
106 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.
107 Mine is C:\cygwin64\usr\local.
108 (You can also just setup the paths, but this is faster/simpler. Might screw up your Cygwin though).
115 Download the latest GNU Tools for Embedded Processors gcc-arm-none-eabi.
117 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 directory.
122 Mine is C:\cygwin64\usr\local.
123 Or, you can setup paths using the installer (you have to be more careful, avoid spaces in paths).
127 ----------------------
129 ----------------------
131 One of the big benefits of using CMake is the ability to build multiple configurations (for different microcontrollers) at the same time.
132 The following sections explain in detail what each CMakeLists.txt configuration option does and what you can change it to.
133 However, it is possible to configure each of these options using the -D command line flag.
135 For example, to build the Infinity Keyboard default configuration:
139 cmake -DCHIP=mk20dx128vlf5 -DScanModule=MD1 -DMacroModule=PartialMap -DOutputModule=pjrcUSB -DDebugModule=full -DBaseMap=defaultMap -DDefaultMap="md1Overlay stdFuncMap" -DPartialMaps="hhkbpro2" ..
142 CMake defaults to the values specified in CMakeLists.txt if not overridden via the command line.
143 NOTE: On Windows, you will have to use "wincmake" instead of "cmake".
147 ----------------------
148 Selecting Microcontroller
149 ----------------------
151 This is where you select the chip you want to compile for.
152 The build system will automatically select the compiler needed to compile for your chip.
154 Open up CMakeLists.txt in your favourite text editor.
161 #| You _MUST_ set this to match the microcontroller you are trying to compile for
162 #| You _MUST_ clean the build directory if you change this value
165 # "at90usb162" # Teensy 1.0 (avr)
166 # "atmega32u4" # Teensy 2.0 (avr)
167 # "at90usb646" # Teensy++ 1.0 (avr)
168 # "at90usb1286" # Teensy++ 2.0 (avr)
169 # "mk20dx128" # Teensy 3.0 (arm)
170 "mk20dx128vlf5" # McHCK mk20dx128vlf5
171 # "mk20dx256" # Teensy 3.1 (arm)
172 CACHE STRING "Microcontroller Chip" )
174 Just uncomment the chip you want, and comment out the old one.
176 NOTE: If you change this option, you will *need* to delete the build directory that is created in the Building sections below.
180 ----------------------
182 ----------------------
184 WARNING: Not all modules are compatible, and some modules may have dependencies on other modules.
186 This is where the options start getting interesting.
187 The Kiibohd Controller is designed around a set of 4 types of modules that correspond to different functionality:
194 The Scan Module is where the most interesting stuff happens. These modules take in "keypress data".
195 A converter Scan Module will interpret a protocol into key press/releases.
196 A matrix Scan Module may inherit from the matrix module to scan keypress from a matrix
197 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).
198 Each Scan Module has it's own default keymap/modifier map. (TODO recommend keymap changing in the Macro Module).
200 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!).
203 The Macro Module takes care of the mapping of the key press/release code into an Output (USB) scan code.
204 Any layering, macros, keypress intelligence/reaction is done here.
207 The Output Module is the module dealing with output from the microcontroller. Currently USB is the only output protocol.
208 Different USB output implementations are available, pjrc being the safest/least featureful one.
209 Debug capabilities may depend on the module selected.
212 The Debug Module enables various things like the Teensy LED on errors, debug terminal output.
213 (TODO get true UART working in avr, not just arm)
217 Open up CMakeLists.txt in your favourite text editor.
224 #| Note: This is the only section you probably want to modify
225 #| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module)
226 #| All of the modules must be specified, as they generate the sources list of files to compile
227 #| Any modifications to this file will cause a complete rebuild of the project
229 #| Please look at the {Scan,Macro,Output,Debug} for information on the modules and how to create new ones
231 ##| Deals with acquiring the keypress information and turning it into a key index
232 set( ScanModule "MD1"
233 CACHE STRING "Scan Module" )
235 ##| Provides the mapping functions for DefaultMap and handles any macro processing before sending to the OutputModule
236 set( MacroModule "PartialMap"
237 CACHE STRING "Macro Module" )
239 ##| Sends the current list of usb key codes through USB HID
240 set( OutputModule "pjrcUSB"
241 CACHE STRING "Output Module" )
243 ##| Debugging source to use, each module has it's own set of defines that it sets
244 set( DebugModule "full"
245 CACHE STRING "Debug Module" )
248 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.
251 There are also CMake options for temporarily selecting modules. But it's easier to just edit the file.
252 e.g. cmake -DScanModuleOverride=<module name>
256 ----------------------
258 ----------------------
269 [master]: cmake .. [~/Source/controller/build](hyatt@x230mas:pts/6)
278 -- Compiler Source Files:
279 Lib/mk20dx.c;Lib/delay.c
282 -- Detected Scan Module Source Files:
283 Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
284 -- Detected Macro Module Source Files:
285 Macro/PartialMap/macro.c
286 -- Detected Output Module Source Files:
287 Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c;
288 Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c
289 -- Detected Debug Module Source Files:
290 Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
291 -- Found Git: /usr/bin/git (found version "2.2.1")
292 -- Found Ctags: /usr/bin/ctags (found version "5.8")
293 -- Checking for latest kll version:
294 Current branch master is up to date.
295 -- Detected Layout Files:
296 /home/hyatt/Source/controller/Macro/PartialMap/capabilities.kll
297 /home/hyatt/Source/controller/Output/pjrcUSB/capabilities.kll
298 /home/hyatt/Source/controller/Scan/MD1/defaultMap.kll
299 /home/hyatt/Source/controller/kll/layouts/md1Overlay.kll
300 /home/hyatt/Source/controller/kll/layouts/stdFuncMap.kll
301 /home/hyatt/Source/controller/kll/layouts/hhkbpro2.kll
304 -- Build files have been written to: /home/hyatt/Source/controller/build
305 [master]: make [~/Source/controller/build](hyatt@x230mas:pts/6)
306 [ 5%] Generating KLL Layout
307 Scanning dependencies of target kiibohd.elf
308 [ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
309 [ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.o
310 [ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.o
311 [ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.o
312 [ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.o
313 [ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.o
314 [ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.o
315 [ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.o
316 [ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.o
317 [ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.o
318 [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.o
319 [ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.o
320 [ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.o
321 [ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
322 [ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
323 Linking C executable kiibohd.elf
324 [ 94%] Built target kiibohd.elf
325 Scanning dependencies of target SizeAfter
326 [100%] Chip usage for mk20dx128vlf5
327 SRAM: 32% 5384/16384 bytes
328 Flash: 18% 23384/126976 bytes
329 [100%] Built target SizeAfter
333 ----------------------
334 Linux Loading Firmware
335 ----------------------
337 First place the keyboard into re-flash mode.
338 This can be done either by pressing the re-flash button on the PCB/Teensy.
339 Or by entering the Kiibohd Virtual Serial Port and using the 'reload' command.
341 The 'load' script that is created during the build can load the firmware over USB.
342 Either run it with sudo, or install the 98-kiibohd.rules to /etc/udev/rules.d
343 and run: udevadm control --reload-rules
346 To load the newly built firmware:
351 ----------------------
352 Linux Building Bootloader
353 ----------------------
355 *NOTE* Does not apply to Teensy based builds.
366 [master]: cmake .. [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6)
375 -- Compiler Source Files:
376 Lib/mk20dx.c;Lib/delay.c
379 -- Bootloader Source Files:
380 main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c
381 -- Found Git: /usr/bin/git (found version "2.2.1")
382 -- Found Ctags: /usr/bin/ctags (found version "5.8")
385 -- Build files have been written to: /home/hyatt/Source/controller/Bootloader/build
386 [master]: make [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6)
387 Scanning dependencies of target kiibohd_bootloader.elf
388 [ 11%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/main.c.o
389 [ 22%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.c.o
390 [ 33%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.desc.c.o
391 [ 44%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/flash.c.o
392 [ 55%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/kinetis.c.o
393 [ 66%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/usb.c.o
394 [ 77%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/mk20dx.c.o
395 [ 88%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/delay.c.o
396 Linking C executable kiibohd_bootloader.elf
397 [ 88%] Built target kiibohd_bootloader.elf
398 Scanning dependencies of target SizeAfter
399 [100%] Chip usage for mk20dx128vlf5
400 SRAM: 19% 3176/16384 bytes
401 Flash: 2% 3736/126976 bytes
402 [100%] Built target SizeAfter
406 ----------------------
407 Linux Loading Bootloader
408 ----------------------
410 *NOTE* Does not apply to Teensy based builds.
412 It's recommended to use an SWD-type flasher like a Bus Pirate.
413 There is a convenience script for loading the firmware once the system is setup.
415 cd Bootloader/Scripts
418 The above script requires Ruby, Ruby serial port module, git, and a /dev/buspirate udev rule.
421 https://github.com/mchck/mchck/wiki/Getting-Started (See Bus-Pirate section)
422 https://wiki.archlinux.org/index.php/Bus_pirate
426 ----------------------
428 ----------------------
448 -- Compiler Source Files:
449 Lib/mk20dx.c;Lib/delay.c
452 -- Detected Scan Module Source Files:
453 Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
454 -- Detected Macro Module Source Files:
455 Macro/PartialMap/macro.c
456 -- Detected Output Module Source Files:
457 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
458 -- Detected Debug Module Source Files:
459 Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
460 -- Found Git: C:/cygwin64/bin/git.exe (found version "2.1.1")
461 -- Found Ctags: C:/cygwin64/bin/ctags.exe (found version "5.8")
462 -- Checking for latest kll version:
463 Current branch master is up to date.
464 -- Detected Layout Files:
465 C:/cygwin64/home/Jacob/controller/Macro/PartialMap/capabilities.kll
466 C:/cygwin64/home/Jacob/controller/Output/pjrcUSB/capabilities.kll
467 C:/cygwin64/home/Jacob/controller/Scan/MD1/defaultMap.kll
468 C:/cygwin64/home/Jacob/controller/kll/layouts/md1Overlay.kll
469 C:/cygwin64/home/Jacob/controller/kll/layouts/stdFuncMap.kll
470 C:/cygwin64/home/Jacob/controller/kll/layouts/hhkbpro2.kll
473 -- Build files have been written to: C:/cygwin64/home/Jacob/controller/build
475 Jacob@DenPC ~/controller/build
477 [ 5%] Generating KLL Layout
478 Scanning dependencies of target kiibohd.elf
479 [ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
480 [ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.obj
481 [ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.obj
482 [ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.obj
483 [ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.obj
484 [ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
485 [ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
486 [ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.obj
487 [ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.obj
488 [ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.obj
489 [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.obj
490 [ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.obj
491 [ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
492 [ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
493 [ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
494 Linking C executable kiibohd.elf
495 [ 94%] Built target kiibohd.elf
496 Scanning dependencies of target SizeAfter
497 [100%] Chip usage for mk20dx128vlf5
498 SRAM: 32% 5384/16384 bytes
499 Flash: 18% 23296/126976 bytes
500 [100%] Built target SizeAfter
505 If you get the following error, you have not setup wincmake correctly:
508 [ 5%] Generating KLL Layout
509 Scanning dependencies of target kiibohd.elf
510 [ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
511 ../main.c:28:19: fatal error: macro.h: No such file or directory
514 compilation terminated.
515 CMakeFiles/kiibohd.elf.dir/build.make:67: recipe for target 'CMakeFiles/kiibohd.elf.dir/main.c.o' failed
516 make[2]: *** [CMakeFiles/kiibohd.elf.dir/main.c.o] Error 1
517 CMakeFiles/Makefile2:98: recipe for target 'CMakeFiles/kiibohd.elf.dir/all' failed
518 make[1]: *** [CMakeFiles/kiibohd.elf.dir/all] Error 2
519 Makefile:75: recipe for target 'all' failed
520 make: *** [all] Error 2
522 If you have already added the line to your ~/.bashrc try restarting your cygwin shell.
526 ----------------------
527 Windows Loading Firmware
528 ----------------------
530 First place the keyboard into re-flash mode.
531 This can be done either by pressing the re-flash button on the PCB/Teensy.
532 Or by entering the Kiibohd Virtual Serial Interface and using the 'reload' command.
534 The 'load' script that is created during the build can load the firmware over USB.
536 To load the newly built firmware:
539 Be patient the couple of times, Windows is slow at installing drivers...
543 ----------------------
545 ----------------------
559 ----------------------
560 Mac OS X Loading Firmware
561 ----------------------
563 First place the keyboard into re-flash mode.
564 This can be done either by pressing the re-flash button on the PCB/Teensy.
565 Or by entering the Kiibohd Virtual Serial Port and using the 'reload' command.
567 The 'load' script that is created during the build can load the firmware over USB.
570 To load the newly built firmware:
575 ----------------------
576 Virtual Serial Port - CLI
577 ----------------------
579 Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
580 This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
587 I generally use screen.
588 You will need sudo/root priviledges if you haven't installed the 98-kiibohd.rules file to /etc/udev/rules.d
591 (Might be ACM1, ACM2, etc.)
598 Make sure the Teensy Virtual Serial Port driver is installed.
599 If possible use screen (as part of Cygwin).
600 Check which COM port the virtual serial port has been assigned to:
601 Device Manager->Ports (COM & LPT)->Teensy USB Serial
602 In brackets it will say which COM port (e.g. COM3)
605 putty works well when using DTR/DSR or RTS/CTS flow control.
606 Connection type: Serial
607 Serial line: <Your COM port, e.g. COM3>
608 Speed: (doesn't matter, it's auto-negotiated)
610 Under Category->Connections->Serial
611 Flow control: DTR/DSR
613 If stuff is hard to read (you have a dumb colour scheme):
614 Category->Window->Colours->Use system colur
615 That seems to make text at least readable (I use a custom colour scheme that makes each colour easy to see -HaaTa).
618 Unfortunately, screen for Cygwin seems to be broken for serial ports, but you can try it...
620 (Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc.)
622 Gnu screen doesn't seem to echo all the characters (it works though).
623 I believe it's a problem with stty, but I don't know how to fix it...
630 I recommend screen (can be installed via Macports).
631 screen /dev/tty.<usb something>