Mercurial > louis > kiibohd-controller
comparison README.old.markdown @ 313:a2df35fa4f0b
Updating the README to be of a more reasonable length.
author | Jacob Alexander <haata@kiibohd.com> |
---|---|
date | Sun, 15 Mar 2015 21:37:57 -0700 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
312:c5f083de1838 | 313:a2df35fa4f0b |
---|---|
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 ``` |