]> git.donarmstrong.com Git - kiibohd-controller.git/blob - README.old.markdown
Adding jump to bootloader key
[kiibohd-controller.git] / README.old.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-eabi-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 Keymap Configuration
267 --------------------
268
269 This is where you define the layout for your keyboard.
270 Currently, the only way to define kebyoard layouts is using [KLL](https://www.overleaf.com/read/zzqbdwqjfwwf).
271
272 KLL is built up of 3 different kinds of keymaps in total.
273 The BaseMap, DefaultMap and PartialMaps.
274
275 For each type of keymap, it is possible to combine multiple .kll files together to create new ones using
276 the compiler. The order of the files matter, as the right-most file will overwrite any setting in the
277 previous files.
278
279 > NOTE: Each keymap is done after the entire file is processed. This means that within the file the order
280 >       of assignment doesa *not* matter (if you assign the same thing twice, then yes the most recent one
281 >       takes priority).
282
283
284 BaseMap defines what the keyboard can do. This includes specific capabilities of the keyboard (such as USB),
285 the mapping of Scan Codes to USB Codes and any specific configurations for the keyboard.
286 In general, the BaseMap rarely needs to be changed. Usually only when adding a new keyboard to the firmware
287 does the Basemap need any modification.
288 The BaseMap is what both DefaultMap and PartialMaps are based upon. This allows for a common reference
289 when defining custom keymappings.
290
291 > NOTE: Don't use defaultMap.kll to change your layouts. This will work, but they will not be portable.
292
293
294 The DefaultMap is the normal state of the keyboard, i.e. your default layer.
295 Using the BaseMap as a base, the DefaultMap is a modification of the BaseMap to what the keyboard should do.
296 Since the DefaultMap uses USB Code to USB Code translations, this means that keymaps used for one keyboard
297 will work with another keyboard.
298 For example, I use Colemak, so this means I only have to define Colemak once for every keyboard that supports
299 the kiibohd firmware. This is possible because every BaseMap defines the keyboard as a US ANSI like keyboard
300 layout.
301 The DefaultMap can also be thought of as Layer 0.
302
303
304 PartialMaps are optional keymaps that can be "stacked" on top of the DefaultMap.
305 They can be dynamically swapped out using the layer control capabilities:
306
307 - layerLatch( `<layer number>` )
308 - layerLock( `<layer number>` )
309 - layerShift( `<layer number>` )
310
311 layerShift is usually what you want as it works just like a standard shift key.
312 layerLock is similar to the CapsLock key. While layerLatch is a latch, where only the next key you press
313 will use that layer (e.g. stickykeys).
314
315 A unique aspect of KLL layers is that it's a true stack of layers.
316 When a layer is activated, only the keys that are specified by the layer will change.
317 This means, if you define a layer that only sets `CapsLock -> LCtrl` and `LCtrl->Capslock` only those keys
318 will change when you active the layer. All the other keys will use the layer that is "underneath" to
319 lookup the keypress (usually the DefaultMap).
320
321 This means that you can combine .kll files statically using the compiler or dynamically using the firmware.
322
323 You can set the max number of layers by changing the `stateWordSize` define in one of your kll files.
324 By default it is set to 8 in Macro/PartialMap/capabilities.kll. This means you can have up to 256 layers
325 total (this includes the DefaultMap).
326 You can increase this number to either 16 or 32 (this will use more Flash and RAM btw) which will give you
327 2^16 and 2^32 possible layers respectively (65 535 and 4 294 967 295).
328
329
330 ```cmake
331 ###
332 # Keymap Configuration (do not include the .kll extension)
333 #
334
335 #| Do not include the .kll extension
336 #| * BaseMap maps the native keyboard scan codes to USB Codes so the layout is compatible with all other layouts
337 #| * DefaultMap allows the default keymap to be modified from the BaseMap
338 #| * PartialMaps is a set of dynamically set layers (there is no limit, but too many may use up too much RAM...)
339 #| BaseMap generally does not need to be changed from "defaultMap"
340 #|
341 #| Syntax:
342 #|  myMap
343 #|    * defines a single .kll layout file, double-quotes are needed to distinguish between layers
344 #|  "myMap specialLayer"
345 #|    * defines myMap to be the main layout, then replace specialLayers on top of it
346 #|
347 #| - Only for PartialMaps -
348 #|  "myMap specialLayer" "myMap colemak" dvorak
349 #|    * As before, but also generates a second layer at index 2 and third at index 3
350 #|
351 #| NOTE:  Remember to add key(s) to enable each Partial Layer
352 #| NOTE2: Layers are always based up the BaseMap (which should be an ANSI-like mapping)
353 #| NOTE3: Compiler looks in kll/layouts and the build directory for layout files (precedence on build directory)
354
355 ##| Set the base keyboard .kll map, defaults to "defaultMap" if not found
356 ##| Looks in Scan/<Module Name> for the available BaseMaps
357 set(     BaseMap "defaultMap"
358         CACHE STRING "KLL BaseMap/Scancode Keymapping" )
359
360 ##| Layer additonal .kll maps on the BaseMap, layers are in order from 1st to nth
361 ##| Can be set to ""
362 set(  DefaultMap "md1Overlay stdFuncMap"
363         CACHE STRING "KLL DefaultMap" )
364
365 ##| ParitalMaps available on top of the BaseMap. See above for syntax on specifying multiple layers vs. layering
366 ##| Can be set to ""
367 set( PartialMaps "hhkbpro2"
368         CACHE STRING "KLL PartialMaps/Layer Definitions" )
369 ```
370
371
372 Linux Building
373 --------------
374
375 From this directory.
376
377 ```bash
378 $ mkdir build
379 $ cd build
380 $ cmake ..
381 $ make
382 ```
383
384 Example output:
385
386 ```
387 $ cmake ..
388 -- Compiler Family:
389 arm
390 -- Chip Selected:
391 mk20dx128vlf5
392 -- Chip Family:
393 mk20dx
394 -- CPU Selected:
395 cortex-m4
396 -- Compiler Source Files:
397 Lib/mk20dx.c;Lib/delay.c
398 -- Bootloader Type:
399 dfu
400 -- Detected Scan Module Source Files:
401 Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
402 -- Detected Macro Module Source Files:
403 Macro/PartialMap/macro.c
404 -- Detected Output Module Source Files:
405 Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c;
406 Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c
407 -- Detected Debug Module Source Files:
408 Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
409 -- Found Git: /usr/bin/git (found version "2.2.1")
410 -- Found Ctags: /usr/bin/ctags (found version "5.8")
411 -- Checking for latest kll version:
412 Current branch master is up to date.
413 -- Detected Layout Files:
414 /home/hyatt/Source/controller/Macro/PartialMap/capabilities.kll
415 /home/hyatt/Source/controller/Output/pjrcUSB/capabilities.kll
416 /home/hyatt/Source/controller/Scan/MD1/defaultMap.kll
417 /home/hyatt/Source/controller/kll/layouts/md1Overlay.kll
418 /home/hyatt/Source/controller/kll/layouts/stdFuncMap.kll
419 /home/hyatt/Source/controller/kll/layouts/hhkbpro2.kll
420 -- Configuring done
421 -- Generating done
422 -- Build files have been written to: /home/hyatt/Source/controller/build
423 [master]: make                                [~/Source/controller/build](hyatt@x230mas:pts/6)
424 [  5%] Generating KLL Layout
425 Scanning dependencies of target kiibohd.elf
426 [ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
427 [ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.o
428 [ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.o
429 [ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.o
430 [ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.o
431 [ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.o
432 [ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.o
433 [ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.o
434 [ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.o
435 [ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.o
436 [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.o
437 [ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.o
438 [ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.o
439 [ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
440 [ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
441 Linking C executable kiibohd.elf
442 [ 94%] Built target kiibohd.elf
443 Scanning dependencies of target SizeAfter
444 [100%] Chip usage for mk20dx128vlf5
445      SRAM:  32%     5384/16384      bytes
446     Flash:  18%     23384/126976    bytes
447 [100%] Built target SizeAfter
448 ```
449
450 Linux Loading Firmware
451 ----------------------
452
453 First place the keyboard into re-flash mode.  This can be done either by
454 pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
455 Virtual Serial Port and using the 'reload' command.
456
457 The `load` script that is created during the build can load the firmware over
458 USB.  Either run it with sudo, or install the `98-kiibohd.rules` to
459 `/etc/udev/rules.d` and run: `udevadm control --reload-rules`.
460
461 To load the newly built firmware: `./load`.
462
463
464 Linux Building Bootloader
465 -------------------------
466
467 > NOTE: Does not apply to Teensy based builds.
468
469 From this directory.
470
471 ```bash
472 $ cd Bootloader
473 $ mkdir build
474 $ cd build
475 $ cmake ..
476 $ make
477 ```
478
479 Example output:
480
481 ```bash
482 $ cmake ..
483 -- Compiler Family:
484 arm
485 -- Chip Selected:
486 mk20dx128vlf5
487 -- Chip Family:
488 mk20dx
489 -- CPU Selected:
490 cortex-m4
491 -- Compiler Source Files:
492 Lib/mk20dx.c;Lib/delay.c
493 -- Bootloader Type:
494 dfu
495 -- Bootloader Source Files:
496 main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c
497 -- Found Git: /usr/bin/git (found version "2.2.1")
498 -- Found Ctags: /usr/bin/ctags (found version "5.8")
499 -- Configuring done
500 -- Generating done
501 -- Build files have been written to: /home/hyatt/Source/controller/Bootloader/build
502 [master]: make                                 [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6)
503 Scanning dependencies of target kiibohd_bootloader.elf
504 [ 11%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/main.c.o
505 [ 22%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.c.o
506 [ 33%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.desc.c.o
507 [ 44%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/flash.c.o
508 [ 55%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/kinetis.c.o
509 [ 66%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/usb.c.o
510 [ 77%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/mk20dx.c.o
511 [ 88%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/delay.c.o
512 Linking C executable kiibohd_bootloader.elf
513 [ 88%] Built target kiibohd_bootloader.elf
514 Scanning dependencies of target SizeAfter
515 [100%] Chip usage for mk20dx128vlf5
516      SRAM:  19%     3176/16384      bytes
517     Flash:  2%      3736/126976     bytes
518 [100%] Built target SizeAfter
519 ```
520
521
522 Linux Loading Bootloader
523 ------------------------
524
525 > NOTE: Does not apply to Teensy based builds.
526
527 It's recommended to use an SWD-type flasher like a Bus Pirate.  There is a
528 convenience script for loading the firmware once the system is setup.
529
530 ```bash
531 $ cd Bootloader/Scripts
532 $ ./swdLoad.bash
533 ```
534
535 The above script requires Ruby, Ruby serial port module, git, and a
536 `/dev/buspirate` udev rule.
537
538 Additional Notes:
539
540 * https://github.com/mchck/mchck/wiki/Getting-Started (See Bus-Pirate section)
541 * https://wiki.archlinux.org/index.php/Bus_pirate
542
543
544 Windows Building
545 ----------------
546
547 From this directory.
548
549 ```bash
550 $ mkdir build
551 $ cd build
552 $ wincmake ..
553 $ make
554 ```
555
556 Example output:
557
558 ```bash
559 $ wincmake ..
560 -- Compiler Family:
561 arm
562 -- Chip Selected:
563 mk20dx128vlf5
564 -- Chip Family:
565 mk20dx
566 -- CPU Selected:
567 cortex-m4
568 -- Compiler Source Files:
569 Lib/mk20dx.c;Lib/delay.c
570 -- Bootloader Type:
571 dfu
572 -- Detected Scan Module Source Files:
573 Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c
574 -- Detected Macro Module Source Files:
575 Macro/PartialMap/macro.c
576 -- Detected Output Module Source Files:
577 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
578 -- Detected Debug Module Source Files:
579 Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c
580 -- Found Git: C:/cygwin64/bin/git.exe (found version "2.1.1")
581 -- Found Ctags: C:/cygwin64/bin/ctags.exe (found version "5.8")
582 -- Checking for latest kll version:
583 Current branch master is up to date.
584 -- Detected Layout Files:
585 C:/cygwin64/home/Jacob/controller/Macro/PartialMap/capabilities.kll
586 C:/cygwin64/home/Jacob/controller/Output/pjrcUSB/capabilities.kll
587 C:/cygwin64/home/Jacob/controller/Scan/MD1/defaultMap.kll
588 C:/cygwin64/home/Jacob/controller/kll/layouts/md1Overlay.kll
589 C:/cygwin64/home/Jacob/controller/kll/layouts/stdFuncMap.kll
590 C:/cygwin64/home/Jacob/controller/kll/layouts/hhkbpro2.kll
591 -- Configuring done
592 -- Generating done
593 -- Build files have been written to: C:/cygwin64/home/Jacob/controller/build
594
595 $ make
596 [  5%] Generating KLL Layout
597 Scanning dependencies of target kiibohd.elf
598 [ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
599 [ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.obj
600 [ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.obj
601 [ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.obj
602 [ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.obj
603 [ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
604 [ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
605 [ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.obj
606 [ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.obj
607 [ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.obj
608 [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.obj
609 [ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.obj
610 [ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
611 [ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
612 [ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
613 Linking C executable kiibohd.elf
614 [ 94%] Built target kiibohd.elf
615 Scanning dependencies of target SizeAfter
616 [100%] Chip usage for mk20dx128vlf5
617      SRAM:  32%     5384/16384      bytes
618     Flash:  18%     23296/126976    bytes
619 [100%] Built target SizeAfter
620 ```
621
622 ### NOTES:
623
624 If you get the following error, you have not setup wincmake correctly:
625
626 ```bash
627 $ make
628 [  5%] Generating KLL Layout
629 Scanning dependencies of target kiibohd.elf
630 [ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
631 ../main.c:28:19: fatal error: macro.h: No such file or directory
632  #include <macro.h>
633                    ^
634 compilation terminated.
635 CMakeFiles/kiibohd.elf.dir/build.make:67: recipe for target 'CMakeFiles/kiibohd.elf.dir/main.c.o' failed
636 make[2]: *** [CMakeFiles/kiibohd.elf.dir/main.c.o] Error 1
637 CMakeFiles/Makefile2:98: recipe for target 'CMakeFiles/kiibohd.elf.dir/all' failed
638 make[1]: *** [CMakeFiles/kiibohd.elf.dir/all] Error 2
639 Makefile:75: recipe for target 'all' failed
640 make: *** [all] Error 2
641 ```
642
643 If you have already added the line to your `~/.bashrc` try restarting your
644 cygwin shell.
645
646
647 Windows Loading Firmware
648 ------------------------
649
650 First place the keyboard into re-flash mode.  This can be done either by
651 pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
652 Virtual Serial Interface and using the `reload` command.
653
654 The `load` script that is created during the build can load the firmware over
655 USB.
656
657 To load the newly built firmware: `./load`
658
659 Be patient the couple of times, Windows is slow at installing drivers...
660
661
662 Mac OS X Building
663 -----------------
664
665 From this directory.
666
667 ```bash
668 $ mkdir build
669 $ cd build
670 $ cmake ..
671 $ make
672 ```
673
674 Example output:
675
676 > TODO
677
678
679 Mac OS X Loading Firmware
680 -------------------------
681
682 First place the keyboard into re-flash mode.  This can be done either by
683 pressing the re-flash button on the PCB/Teensy.  Or by entering the Kiibohd
684 Virtual Serial Port and using the `reload` command.
685
686 The `load` script that is created during the build can load the firmware over
687 USB.
688
689 To load the newly built firmware: `./load`.
690
691
692 Virtual Serial Port - CLI
693 -------------------------
694
695 Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint.
696 This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen)
697
698
699 ### Linux
700
701 I generally use screen.  You will need sudo/root priviledges if you haven't
702 installed the `98-kiibohd.rules` file to `/etc/udev/rules.d`.
703
704 ```
705 $ screen /dev/ttyACM0
706 # (Might be ACM1, ACM2, etc.)
707 ```
708
709 ### Windows
710
711 Make sure the Teensy Virtual Serial Port driver is installed.  If possible use
712 screen (as part of Cygwin).  Check which COM port the virtual serial port has
713 been assigned to: `Device Manager->Ports (COM & LPT)->Teensy USB Serial`. In
714 brackets it will say which COM port (e.g. COM3)
715
716 putty works well when using DTR/DSR or RTS/CTS flow control.
717
718 | Setting         | Value                                 |
719 | --------------- | ------------------------------------- |
720 | Connection type | Serial                                |
721 | Serial line     | Your COM port, e.g. COM3              |
722 | Speed           | doesn't matter, it's auto-negotiated  |
723
724 Under `Category->Connections->Serial`: `Flow control: DTR/DSR`.
725
726 If stuff is hard to read (you have a dumb colour scheme):
727 `Category->Window->Colours->Use system color`.  That seems to make text at
728 least readable
729
730 > I use a custom colour scheme that makes each colour easy to see.
731 > -HaaTa.
732
733 Unfortunately, screen for Cygwin seems to be broken for serial ports, but you
734 can try it...
735
736 ```bash
737 $ screen /dev/ttyS2
738 # Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc.
739 ```
740
741 Gnu screen doesn't seem to echo all the characters (it works though).
742 I believe it's a problem with stty, but I don't know how to fix it...
743
744 ### Mac OS X
745
746 I recommend screen (can be installed via Macports).
747
748 ```bash
749 $ screen /dev/tty.<usb something>
750 ```