@@ -31,3 +31,7 @@ Projects | |||
* template.bash (Example template for new keyboards) | |||
**Extra files** | |||
* cmake.bash (Used by the compilation script, does nothing on it's own) | |||
@@ -1,750 +1,87 @@ | |||
The Kiibohd Controller | |||
====================== | |||
This README is a bit long, just look at the sections you are interested in. | |||
You only need to install avr-gcc if you want to build for the Teensy 2.0/2.0++. | |||
Everything else needs an arm-none-eabi-gcc compiler (e.g. Infinity keyboard, | |||
Teensy 3.0/3.1, McHCK). | |||
This is the main Kiibohd Firmware. | |||
In general, this should be the **only** git repo you need to clone. | |||
The [KLL](https://github.com/kiibohd/kll) git repo is automatically cloned during the build process. | |||
Linux is the ideal build environment (preferably recent'ish). In the near | |||
future I'll make available an Arch Linux VM for building/manufacturing tests. | |||
Please refer to the [KLL](https://github.com/kiibohd/kll) repo or [kiibohd.com](http://kiibohd.com) for details on the KLL (Keyboard Layout Language) Spec. | |||
Building on Mac should be ok for 99% of users with Macports or Homebrew. For | |||
Homebrew, use `brew tap PX4/homebrew-px4` to get the arm-none-eabi-gcc installer. | |||
The dfu Bootloader will not build correctly with the old version of | |||
arm-none-eabi-gcc that Macports currently has (4.7.3). 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). | |||
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). Cygwin is | |||
currently required along with some non-Cygwin compilers and utilities (because | |||
they are not available for Cygwin). 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. If you [replace the version of Make in | |||
Cygwin](http://stackoverflow.com/questions/601516/cygwin-make-error-target-pattern-contains-no) | |||
it should work. However, make sure that the flash size is no larger than 4096 | |||
Bytes or the bootloader will not work. Things will likely break if there are | |||
**SPACES IN YOUR PATHS**. I install cygwin to `C:\cygwin64`. If you are brave | |||
and have programming knowledge, I will accept patches to fix any issues | |||
regarding spaces in paths. | |||
Please give authors credit for modules used if you use in a distributed | |||
product :D | |||
Official Keyboards | |||
------------------ | |||
* MD1 (Infinity Keyboard 2014/10/15) | |||
General Dependencies | |||
-------------------- | |||
Below listed are the Arch Linux pacman names, AUR packages may be required. | |||
The Kiibohd firmware supports a lot of other keyboards, but these are more obscure/custom/lesser known. | |||
These depend a bit on which targets you are trying to build, but the general | |||
one: | |||
- cmake (2.8 and higher) | |||
- git | |||
- ctags (recommended, not required) | |||
- python3 | |||
- libusb1.0 (and -devel) | |||
- make | |||
AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested | |||
versions below) | |||
Compilation | |||
----------- | |||
- avr-gcc (~4.8.0) | |||
- avr-binutils (~2.23.2) | |||
- avr-libc (~1.8.0) | |||
Compilation is possible and tested on Windows/Linux/Mac. | |||
Linux is the easiest using this [VM](https://s3.amazonaws.com/configurator-assets/ArchLinux_kiibohd_2015-02-13.tar.gz). | |||
ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK) | |||
For most people refer [here](https://github.com/kiibohd/controller/tree/master/Keyboards). | |||
- Arch Linux / Mac Ports | |||
- arm-none-eabi-gcc | |||
- arm-none-eabi-binutils | |||
For the full compilation details, please refer to the [wiki](https://github.com/kiibohd/controller/wiki). | |||
- Windows (https://launchpad.net/gcc-arm-embedded/+download) | |||
- gcc-arm-none-eabi (win32.zip) | |||
Windows Setup | |||
------------- | |||
Compiling on Windows does work, just it's a bunch more work. | |||
First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit | |||
is fine. Make sure the following are installed: | |||
- make | |||
- git (needed for some compilation info) | |||
- cmake | |||
- gcc-core | |||
- gcc-g++ | |||
- libusb1.0 | |||
- libusb1.0-devel | |||
- python3 | |||
- ctags (recommended, not required) | |||
Please note, I use cygwin term exclusively for any command line options. | |||
Unless mentioned otherwise, use it. Do NOT use CMD or Powershell. | |||
Also install the [Windows version of CMake](http://cmake.org/cmake/resources/software.html) | |||
(3+ is ideal) - Select "Do not add CMake to system PATH". This is in addition | |||
to the Cygwin version. This is an easier alternative to installing another C | |||
compiler. Add the following line to your .bashrc, making sure the CMake path | |||
is correct: | |||
echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc | |||
Install the [PJRC Virtual Serial Port Driver](http://pjrc.com/teensy/serial_install.exe). | |||
Next, install the compiler(s) you want. | |||
### AVR GCC | |||
You just need the | |||
[Atmel AVR 8-bit Toolchain](http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx). | |||
The latest should be fine, as of writing it was 3.4.3. | |||
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. Mine is | |||
`C:\cygwin64\usr\local`. (You can also just setup the paths, but this is | |||
faster/simpler. Might screw up your Cygwin though). | |||
### ARM EABI | |||
Download the latest | |||
[GNU Tools for Embedded Processors | |||
gcc-arm-none-eabi](https://launchpad.net/gcc-arm-embedded/+download). | |||
Download `gcc-arm-none-eabi*win32.zip`. | |||
Then extract all the folders/files in the zip to the Cygwin `/usr/local` | |||
directory. Mine is `C:\cygwin64\usr\local`. Or, you can setup paths using | |||
the installer (you have to be more careful, avoid spaces in paths). | |||
CMake Info | |||
---------- | |||
One of the big benefits of using CMake is the ability to build multiple | |||
configurations (for different microcontrollers) at the same time. The | |||
following sections explain in detail what each CMakeLists.txt configuration | |||
option does and what you can change it to. However, it is possible to | |||
configure each of these options using the `-D` command line flag. | |||
For example, to build the Infinity Keyboard default configuration: | |||
```bash | |||
$ mkdir build_infinity | |||
$ cd build_infinity | |||
$ cmake -DCHIP=mk20dx128vlf5 -DScanModule=MD1 -DMacroModule=PartialMap \ | |||
-DOutputModule=pjrcUSB -DDebugModule=full -DBaseMap=defaultMap \ | |||
-DDefaultMap="md1Overlay stdFuncMap" -DPartialMaps="hhkbpro2" \ | |||
.. | |||
$ make | |||
``` | |||
CMake defaults to the values specified in CMakeLists.txt if not overridden via | |||
the command line. | |||
> NOTE: On Windows, you will have to use "wincmake" instead of "cmake". | |||
Selecting Microcontroller | |||
------------------------- | |||
Supported Microcontrollers | |||
-------------------------- | |||
This is where you select the chip you want to compile for. The build system | |||
will automatically select the compiler needed to compile for your chip. | |||
* Teensy 2.0 (Partial) | |||
* Teensy 2.0++ | |||
* Teesny 3.0 | |||
* Teensy 3.1 | |||
* mk20dx128vlf5 | |||
* mk20dx256vlh7 | |||
Open up CMakeLists.txt in your favourite text editor. You are looking for: | |||
```cmake | |||
### | |||
# Chip Selection | |||
# | |||
Adding support for more microcontrollers is possible. | |||
Some considerations for minimum specs: | |||
#| You _MUST_ set this to match the microcontroller you are trying to compile for | |||
#| You _MUST_ clean the build directory if you change this value | |||
#| | |||
set( CHIP | |||
# "at90usb162" # Teensy 1.0 (avr) | |||
# "atmega32u4" # Teensy 2.0 (avr) | |||
# "at90usb646" # Teensy++ 1.0 (avr) | |||
# "at90usb1286" # Teensy++ 2.0 (avr) | |||
# "mk20dx128" # Teensy 3.0 (arm) | |||
"mk20dx128vlf5" # McHCK mk20dx128vlf5 | |||
# "mk20dx256" # Teensy 3.1 (arm) | |||
CACHE STRING "Microcontroller Chip" ) | |||
``` | |||
* ~8 kB of SRAM | |||
* ~25 kB of Flash | |||
Just uncomment the chip you want, and comment out the old one. | |||
It's possible to port chips with lower specs, but will be more effort and have fewer features. | |||
> NOTE: If you change this option, you will *need* to delete the build | |||
> directory that is created in the Building sections below. | |||
Selecting Modules | |||
----------------- | |||
> WARNING: Not all modules are compatible, and some modules may have | |||
> dependencies on other modules. | |||
This is where the options start getting interesting. The Kiibohd Controller | |||
is designed around a set of 4 types of modules that correspond to different | |||
functionality: | |||
- Scan Module | |||
- Macro Module | |||
- Output Module | |||
- Debug Module | |||
The Scan Module is where the most interesting stuff happens. These modules | |||
take in "keypress data". A converter Scan Module will interpret a protocol | |||
into key press/releases. A matrix Scan Module may inherit from the matrix | |||
module to scan keypress from a matrix 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). Each Scan Module has it's own default | |||
keymap/modifier map. (TODO recommend keymap changing in the Macro Module). | |||
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!). | |||
The Macro Module takes care of the mapping of the key press/release code into | |||
an Output (USB) scan code. Any layering, macros, keypress | |||
intelligence/reaction is done here. | |||
The Output Module is the module dealing with output from the microcontroller. | |||
Currently USB is the only output protocol. Different USB output | |||
implementations are available, pjrc being the safest/least featureful one. | |||
Debug capabilities may depend on the module selected. | |||
The Debug Module enables various things like the Teensy LED on errors, debug | |||
terminal output. (TODO get true UART working in avr, not just arm) | |||
Open up CMakeLists.txt in your favourite text editor. Look for: | |||
```cmake | |||
### | |||
# Project Modules | |||
# | |||
#| Note: This is the only section you probably want to modify | |||
#| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module) | |||
#| All of the modules must be specified, as they generate the sources list of files to compile | |||
#| Any modifications to this file will cause a complete rebuild of the project | |||
#| Please look at the {Scan,Macro,Output,Debug} for information on the modules and how to create new ones | |||
##| Deals with acquiring the keypress information and turning it into a key index | |||
set( ScanModule "MD1" | |||
CACHE STRING "Scan Module" ) | |||
##| Provides the mapping functions for DefaultMap and handles any macro processing before sending to the OutputModule | |||
set( MacroModule "PartialMap" | |||
CACHE STRING "Macro Module" ) | |||
##| Sends the current list of usb key codes through USB HID | |||
set( OutputModule "pjrcUSB" | |||
CACHE STRING "Output Module" ) | |||
##| Debugging source to use, each module has it's own set of defines that it sets | |||
set( DebugModule "full" | |||
CACHE STRING "Debug Module" ) | |||
``` | |||
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. | |||
There are also CMake options for temporarily selecting modules. But it's | |||
easier to just edit the file. e.g. `cmake -DScanModuleOverride=<module name>`. | |||
Keymap Configuration | |||
-------------------- | |||
This is where you define the layout for your keyboard. | |||
Currently, the only way to define kebyoard layouts is using [KLL](https://www.overleaf.com/read/zzqbdwqjfwwf). | |||
KLL is built up of 3 different kinds of keymaps in total. | |||
The BaseMap, DefaultMap and PartialMaps. | |||
For each type of keymap, it is possible to combine multiple .kll files together to create new ones using | |||
the compiler. The order of the files matter, as the right-most file will overwrite any setting in the | |||
previous files. | |||
> NOTE: Each keymap is done after the entire file is processed. This means that within the file the order | |||
> of assignment doesa *not* matter (if you assign the same thing twice, then yes the most recent one | |||
> takes priority). | |||
BaseMap defines what the keyboard can do. This includes specific capabilities of the keyboard (such as USB), | |||
the mapping of Scan Codes to USB Codes and any specific configurations for the keyboard. | |||
In general, the BaseMap rarely needs to be changed. Usually only when adding a new keyboard to the firmware | |||
does the Basemap need any modification. | |||
The BaseMap is what both DefaultMap and PartialMaps are based upon. This allows for a common reference | |||
when defining custom keymappings. | |||
> NOTE: Don't use defaultMap.kll to change your layouts. This will work, but they will not be portable. | |||
The DefaultMap is the normal state of the keyboard, i.e. your default layer. | |||
Using the BaseMap as a base, the DefaultMap is a modification of the BaseMap to what the keyboard should do. | |||
Since the DefaultMap uses USB Code to USB Code translations, this means that keymaps used for one keyboard | |||
will work with another keyboard. | |||
For example, I use Colemak, so this means I only have to define Colemak once for every keyboard that supports | |||
the kiibohd firmware. This is possible because every BaseMap defines the keyboard as a US ANSI like keyboard | |||
layout. | |||
The DefaultMap can also be thought of as Layer 0. | |||
PartialMaps are optional keymaps that can be "stacked" on top of the DefaultMap. | |||
They can be dynamically swapped out using the layer control capabilities: | |||
- layerLatch( `<layer number>` ) | |||
- layerLock( `<layer number>` ) | |||
- layerShift( `<layer number>` ) | |||
layerShift is usually what you want as it works just like a standard shift key. | |||
layerLock is similar to the CapsLock key. While layerLatch is a latch, where only the next key you press | |||
will use that layer (e.g. stickykeys). | |||
A unique aspect of KLL layers is that it's a true stack of layers. | |||
When a layer is activated, only the keys that are specified by the layer will change. | |||
This means, if you define a layer that only sets `CapsLock -> LCtrl` and `LCtrl->Capslock` only those keys | |||
will change when you active the layer. All the other keys will use the layer that is "underneath" to | |||
lookup the keypress (usually the DefaultMap). | |||
This means that you can combine .kll files statically using the compiler or dynamically using the firmware. | |||
You can set the max number of layers by changing the `stateWordSize` define in one of your kll files. | |||
By default it is set to 8 in Macro/PartialMap/capabilities.kll. This means you can have up to 256 layers | |||
total (this includes the DefaultMap). | |||
You can increase this number to either 16 or 32 (this will use more Flash and RAM btw) which will give you | |||
2^16 and 2^32 possible layers respectively (65 535 and 4 294 967 295). | |||
```cmake | |||
### | |||
# Keymap Configuration (do not include the .kll extension) | |||
# | |||
#| Do not include the .kll extension | |||
#| * BaseMap maps the native keyboard scan codes to USB Codes so the layout is compatible with all other layouts | |||
#| * DefaultMap allows the default keymap to be modified from the BaseMap | |||
#| * PartialMaps is a set of dynamically set layers (there is no limit, but too many may use up too much RAM...) | |||
#| BaseMap generally does not need to be changed from "defaultMap" | |||
#| | |||
#| Syntax: | |||
#| myMap | |||
#| * defines a single .kll layout file, double-quotes are needed to distinguish between layers | |||
#| "myMap specialLayer" | |||
#| * defines myMap to be the main layout, then replace specialLayers on top of it | |||
#| | |||
#| - Only for PartialMaps - | |||
#| "myMap specialLayer" "myMap colemak" dvorak | |||
#| * As before, but also generates a second layer at index 2 and third at index 3 | |||
#| | |||
#| NOTE: Remember to add key(s) to enable each Partial Layer | |||
#| NOTE2: Layers are always based up the BaseMap (which should be an ANSI-like mapping) | |||
#| NOTE3: Compiler looks in kll/layouts and the build directory for layout files (precedence on build directory) | |||
##| Set the base keyboard .kll map, defaults to "defaultMap" if not found | |||
##| Looks in Scan/<Module Name> for the available BaseMaps | |||
set( BaseMap "defaultMap" | |||
CACHE STRING "KLL BaseMap/Scancode Keymapping" ) | |||
##| Layer additonal .kll maps on the BaseMap, layers are in order from 1st to nth | |||
##| Can be set to "" | |||
set( DefaultMap "md1Overlay stdFuncMap" | |||
CACHE STRING "KLL DefaultMap" ) | |||
##| ParitalMaps available on top of the BaseMap. See above for syntax on specifying multiple layers vs. layering | |||
##| Can be set to "" | |||
set( PartialMaps "hhkbpro2" | |||
CACHE STRING "KLL PartialMaps/Layer Definitions" ) | |||
``` | |||
Linux Building | |||
-------------- | |||
From this directory. | |||
```bash | |||
$ mkdir build | |||
$ cd build | |||
$ cmake .. | |||
$ make | |||
``` | |||
Example output: | |||
``` | |||
$ cmake .. | |||
arm | |||
mk20dx128vlf5 | |||
mk20dx | |||
cortex-m4 | |||
Lib/mk20dx.c;Lib/delay.c | |||
dfu | |||
Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c | |||
Macro/PartialMap/macro.c | |||
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 | |||
Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c | |||
Current branch master is up to date. | |||
/home/hyatt/Source/controller/Macro/PartialMap/capabilities.kll | |||
/home/hyatt/Source/controller/Output/pjrcUSB/capabilities.kll | |||
/home/hyatt/Source/controller/Scan/MD1/defaultMap.kll | |||
/home/hyatt/Source/controller/kll/layouts/md1Overlay.kll | |||
/home/hyatt/Source/controller/kll/layouts/stdFuncMap.kll | |||
/home/hyatt/Source/controller/kll/layouts/hhkbpro2.kll | |||
[master]: make [~/Source/controller/build](hyatt@x230mas:pts/6) | |||
[ 5%] Generating KLL Layout | |||
Scanning dependencies of target kiibohd.elf | |||
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o | |||
[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.o | |||
[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.o | |||
[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.o | |||
[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.o | |||
[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.o | |||
[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.o | |||
[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.o | |||
[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.o | |||
[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.o | |||
[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.o | |||
[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.o | |||
[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.o | |||
[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o | |||
[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o | |||
Linking C executable kiibohd.elf | |||
[ 94%] Built target kiibohd.elf | |||
Scanning dependencies of target SizeAfter | |||
[100%] Chip usage for mk20dx128vlf5 | |||
SRAM: 32% 5384/16384 bytes | |||
Flash: 18% 23384/126976 bytes | |||
[100%] Built target SizeAfter | |||
``` | |||
Linux Loading Firmware | |||
---------------------- | |||
First place the keyboard into re-flash mode. This can be done either by | |||
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd | |||
Virtual Serial Port and using the 'reload' command. | |||
The `load` script that is created during the build can load the firmware over | |||
USB. Either run it with sudo, or install the `98-kiibohd.rules` to | |||
`/etc/udev/rules.d` and run: `udevadm control --reload-rules`. | |||
To load the newly built firmware: `./load`. | |||
Linux Building Bootloader | |||
------------------------- | |||
> NOTE: Does not apply to Teensy based builds. | |||
From this directory. | |||
```bash | |||
$ cd Bootloader | |||
$ mkdir build | |||
$ cd build | |||
$ cmake .. | |||
$ make | |||
``` | |||
Example output: | |||
```bash | |||
$ cmake .. | |||
arm | |||
mk20dx128vlf5 | |||
mk20dx | |||
cortex-m4 | |||
Lib/mk20dx.c;Lib/delay.c | |||
dfu | |||
main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c | |||
[master]: make [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6) | |||
Scanning dependencies of target kiibohd_bootloader.elf | |||
[ 11%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/main.c.o | |||
[ 22%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.c.o | |||
[ 33%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.desc.c.o | |||
[ 44%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/flash.c.o | |||
[ 55%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/kinetis.c.o | |||
[ 66%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/usb.c.o | |||
[ 77%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/mk20dx.c.o | |||
[ 88%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/delay.c.o | |||
Linking C executable kiibohd_bootloader.elf | |||
[ 88%] Built target kiibohd_bootloader.elf | |||
Scanning dependencies of target SizeAfter | |||
[100%] Chip usage for mk20dx128vlf5 | |||
SRAM: 19% 3176/16384 bytes | |||
Flash: 2% 3736/126976 bytes | |||
[100%] Built target SizeAfter | |||
``` | |||
Linux Loading Bootloader | |||
------------------------ | |||
> NOTE: Does not apply to Teensy based builds. | |||
It's recommended to use an SWD-type flasher like a Bus Pirate. There is a | |||
convenience script for loading the firmware once the system is setup. | |||
```bash | |||
$ cd Bootloader/Scripts | |||
$ ./swdLoad.bash | |||
``` | |||
The above script requires Ruby, Ruby serial port module, git, and a | |||
`/dev/buspirate` udev rule. | |||
Additional Notes: | |||
* https://github.com/mchck/mchck/wiki/Getting-Started (See Bus-Pirate section) | |||
* https://wiki.archlinux.org/index.php/Bus_pirate | |||
Windows Building | |||
---------------- | |||
From this directory. | |||
```bash | |||
$ mkdir build | |||
$ cd build | |||
$ wincmake .. | |||
$ make | |||
``` | |||
Example output: | |||
```bash | |||
$ wincmake .. | |||
arm | |||
mk20dx128vlf5 | |||
mk20dx | |||
cortex-m4 | |||
Lib/mk20dx.c;Lib/delay.c | |||
dfu | |||
Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c | |||
Macro/PartialMap/macro.c | |||
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 | |||
Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c | |||
Current branch master is up to date. | |||
C:/cygwin64/home/Jacob/controller/Macro/PartialMap/capabilities.kll | |||
C:/cygwin64/home/Jacob/controller/Output/pjrcUSB/capabilities.kll | |||
C:/cygwin64/home/Jacob/controller/Scan/MD1/defaultMap.kll | |||
C:/cygwin64/home/Jacob/controller/kll/layouts/md1Overlay.kll | |||
C:/cygwin64/home/Jacob/controller/kll/layouts/stdFuncMap.kll | |||
C:/cygwin64/home/Jacob/controller/kll/layouts/hhkbpro2.kll | |||
$ make | |||
[ 5%] Generating KLL Layout | |||
Scanning dependencies of target kiibohd.elf | |||
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj | |||
[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.obj | |||
[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.obj | |||
[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.obj | |||
[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.obj | |||
[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj | |||
[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj | |||
[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.obj | |||
[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.obj | |||
[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.obj | |||
[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.obj | |||
[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.obj | |||
[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj | |||
[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj | |||
[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj | |||
Linking C executable kiibohd.elf | |||
[ 94%] Built target kiibohd.elf | |||
Scanning dependencies of target SizeAfter | |||
[100%] Chip usage for mk20dx128vlf5 | |||
SRAM: 32% 5384/16384 bytes | |||
Flash: 18% 23296/126976 bytes | |||
[100%] Built target SizeAfter | |||
``` | |||
### NOTES: | |||
If you get the following error, you have not setup wincmake correctly: | |||
```bash | |||
$ make | |||
[ 5%] Generating KLL Layout | |||
Scanning dependencies of target kiibohd.elf | |||
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o | |||
../main.c:28:19: fatal error: macro.h: No such file or directory | |||
#include <macro.h> | |||
^ | |||
compilation terminated. | |||
CMakeFiles/kiibohd.elf.dir/build.make:67: recipe for target 'CMakeFiles/kiibohd.elf.dir/main.c.o' failed | |||
make[2]: *** [CMakeFiles/kiibohd.elf.dir/main.c.o] Error 1 | |||
CMakeFiles/Makefile2:98: recipe for target 'CMakeFiles/kiibohd.elf.dir/all' failed | |||
make[1]: *** [CMakeFiles/kiibohd.elf.dir/all] Error 2 | |||
Makefile:75: recipe for target 'all' failed | |||
make: *** [all] Error 2 | |||
``` | |||
If you have already added the line to your `~/.bashrc` try restarting your | |||
cygwin shell. | |||
Windows Loading Firmware | |||
------------------------ | |||
First place the keyboard into re-flash mode. This can be done either by | |||
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd | |||
Virtual Serial Interface and using the `reload` command. | |||
The `load` script that is created during the build can load the firmware over | |||
USB. | |||
To load the newly built firmware: `./load` | |||
Be patient the couple of times, Windows is slow at installing drivers... | |||
Mac OS X Building | |||
----------------- | |||
From this directory. | |||
```bash | |||
$ mkdir build | |||
$ cd build | |||
$ cmake .. | |||
$ make | |||
``` | |||
Example output: | |||
> TODO | |||
Mac OS X Loading Firmware | |||
------------------------- | |||
First place the keyboard into re-flash mode. This can be done either by | |||
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd | |||
Virtual Serial Port and using the `reload` command. | |||
The `load` script that is created during the build can load the firmware over | |||
USB. | |||
To load the newly built firmware: `./load`. | |||
Virtual Serial Port - CLI | |||
------------------------- | |||
Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint. | |||
This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen) | |||
### Linux | |||
I generally use screen. You will need sudo/root priviledges if you haven't | |||
installed the `98-kiibohd.rules` file to `/etc/udev/rules.d`. | |||
``` | |||
$ screen /dev/ttyACM0 | |||
# (Might be ACM1, ACM2, etc.) | |||
``` | |||
Contributions | |||
------------- | |||
### Windows | |||
Contributions welcome! | |||
Make sure the Teensy Virtual Serial Port driver is installed. If possible use | |||
screen (as part of Cygwin). Check which COM port the virtual serial port has | |||
been assigned to: `Device Manager->Ports (COM & LPT)->Teensy USB Serial`. In | |||
brackets it will say which COM port (e.g. COM3) | |||
* Bug reports | |||
* Documentation and Wiki editing | |||
* Patches (including new features) | |||
putty works well when using DTR/DSR or RTS/CTS flow control. | |||
| Setting | Value | | |||
| --------------- | ------------------------------------- | | |||
| Connection type | Serial | | |||
| Serial line | Your COM port, e.g. COM3 | | |||
| Speed | doesn't matter, it's auto-negotiated | | |||
Under `Category->Connections->Serial`: `Flow control: DTR/DSR`. | |||
Licensing | |||
--------- | |||
If stuff is hard to read (you have a dumb colour scheme): | |||
`Category->Window->Colours->Use system color`. That seems to make text at | |||
least readable | |||
Licensing is done on a per-file basis. | |||
Some of the source code is from [PJRC/Teensy](http://pjrc.com), other source code is from the [McHck Project](https://mchck.org). | |||
Code written specifically for the Kiibohd Controller use the following licenses: | |||
> I use a custom colour scheme that makes each colour easy to see. | |||
> -HaaTa. | |||
* MIT | |||
* GPLv3 | |||
* Public Domain | |||
Unfortunately, screen for Cygwin seems to be broken for serial ports, but you | |||
can try it... | |||
```bash | |||
$ screen /dev/ttyS2 | |||
# Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc. | |||
``` | |||
Gnu screen doesn't seem to echo all the characters (it works though). | |||
I believe it's a problem with stty, but I don't know how to fix it... | |||
Contact | |||
------- | |||
### Mac OS X | |||
If you really need to get a hold of HaaTa, email is best: `[email protected]` | |||
I recommend screen (can be installed via Macports). | |||
IRC is likely faster though. | |||
`#[email protected]` | |||
`#[email protected]` | |||
```bash | |||
$ screen /dev/tty.<usb something> | |||
``` |
@@ -0,0 +1,750 @@ | |||
The Kiibohd Controller | |||
====================== | |||
This README is a bit long, just look at the sections you are interested in. | |||
You only need to install avr-gcc if you want to build for the Teensy 2.0/2.0++. | |||
Everything else needs an arm-none-eabi-gcc compiler (e.g. Infinity keyboard, | |||
Teensy 3.0/3.1, McHCK). | |||
Linux is the ideal build environment (preferably recent'ish). In the near | |||
future I'll make available an Arch Linux VM for building/manufacturing tests. | |||
Building on Mac should be ok for 99% of users with Macports or Homebrew. For | |||
Homebrew, use `brew tap PX4/homebrew-px4` to get the arm-none-eabi-gcc installer. | |||
The dfu Bootloader will not build correctly with the old version of | |||
arm-none-eabi-gcc that Macports currently has (4.7.3). 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). | |||
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). Cygwin is | |||
currently required along with some non-Cygwin compilers and utilities (because | |||
they are not available for Cygwin). 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. If you [replace the version of Make in | |||
Cygwin](http://stackoverflow.com/questions/601516/cygwin-make-error-target-pattern-contains-no) | |||
it should work. However, make sure that the flash size is no larger than 4096 | |||
Bytes or the bootloader will not work. Things will likely break if there are | |||
**SPACES IN YOUR PATHS**. I install cygwin to `C:\cygwin64`. If you are brave | |||
and have programming knowledge, I will accept patches to fix any issues | |||
regarding spaces in paths. | |||
Please give authors credit for modules used if you use in a distributed | |||
product :D | |||
General Dependencies | |||
-------------------- | |||
Below listed are the Arch Linux pacman names, AUR packages may be required. | |||
These depend a bit on which targets you are trying to build, but the general | |||
one: | |||
- cmake (2.8 and higher) | |||
- git | |||
- ctags (recommended, not required) | |||
- python3 | |||
- libusb1.0 (and -devel) | |||
- make | |||
AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested | |||
versions below) | |||
- avr-gcc (~4.8.0) | |||
- avr-binutils (~2.23.2) | |||
- avr-libc (~1.8.0) | |||
ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK) | |||
- Arch Linux / Mac Ports | |||
- arm-none-eabi-gcc | |||
- arm-none-eabi-binutils | |||
- Windows (https://launchpad.net/gcc-arm-embedded/+download) | |||
- gcc-arm-none-eabi (win32.zip) | |||
Windows Setup | |||
------------- | |||
Compiling on Windows does work, just it's a bunch more work. | |||
First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit | |||
is fine. Make sure the following are installed: | |||
- make | |||
- git (needed for some compilation info) | |||
- cmake | |||
- gcc-core | |||
- gcc-g++ | |||
- libusb1.0 | |||
- libusb1.0-devel | |||
- python3 | |||
- ctags (recommended, not required) | |||
Please note, I use cygwin term exclusively for any command line options. | |||
Unless mentioned otherwise, use it. Do NOT use CMD or Powershell. | |||
Also install the [Windows version of CMake](http://cmake.org/cmake/resources/software.html) | |||
(3+ is ideal) - Select "Do not add CMake to system PATH". This is in addition | |||
to the Cygwin version. This is an easier alternative to installing another C | |||
compiler. Add the following line to your .bashrc, making sure the CMake path | |||
is correct: | |||
echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc | |||
Install the [PJRC Virtual Serial Port Driver](http://pjrc.com/teensy/serial_install.exe). | |||
Next, install the compiler(s) you want. | |||
### AVR GCC | |||
You just need the | |||
[Atmel AVR 8-bit Toolchain](http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx). | |||
The latest should be fine, as of writing it was 3.4.3. | |||
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. Mine is | |||
`C:\cygwin64\usr\local`. (You can also just setup the paths, but this is | |||
faster/simpler. Might screw up your Cygwin though). | |||
### ARM EABI | |||
Download the latest | |||
[GNU Tools for Embedded Processors | |||
gcc-arm-none-eabi](https://launchpad.net/gcc-arm-embedded/+download). | |||
Download `gcc-arm-none-eabi*win32.zip`. | |||
Then extract all the folders/files in the zip to the Cygwin `/usr/local` | |||
directory. Mine is `C:\cygwin64\usr\local`. Or, you can setup paths using | |||
the installer (you have to be more careful, avoid spaces in paths). | |||
CMake Info | |||
---------- | |||
One of the big benefits of using CMake is the ability to build multiple | |||
configurations (for different microcontrollers) at the same time. The | |||
following sections explain in detail what each CMakeLists.txt configuration | |||
option does and what you can change it to. However, it is possible to | |||
configure each of these options using the `-D` command line flag. | |||
For example, to build the Infinity Keyboard default configuration: | |||
```bash | |||
$ mkdir build_infinity | |||
$ cd build_infinity | |||
$ cmake -DCHIP=mk20dx128vlf5 -DScanModule=MD1 -DMacroModule=PartialMap \ | |||
-DOutputModule=pjrcUSB -DDebugModule=full -DBaseMap=defaultMap \ | |||
-DDefaultMap="md1Overlay stdFuncMap" -DPartialMaps="hhkbpro2" \ | |||
.. | |||
$ make | |||
``` | |||
CMake defaults to the values specified in CMakeLists.txt if not overridden via | |||
the command line. | |||
> NOTE: On Windows, you will have to use "wincmake" instead of "cmake". | |||
Selecting Microcontroller | |||
------------------------- | |||
This is where you select the chip you want to compile for. The build system | |||
will automatically select the compiler needed to compile for your chip. | |||
Open up CMakeLists.txt in your favourite text editor. You are looking for: | |||
```cmake | |||
### | |||
# Chip Selection | |||
# | |||
#| You _MUST_ set this to match the microcontroller you are trying to compile for | |||
#| You _MUST_ clean the build directory if you change this value | |||
#| | |||
set( CHIP | |||
# "at90usb162" # Teensy 1.0 (avr) | |||
# "atmega32u4" # Teensy 2.0 (avr) | |||
# "at90usb646" # Teensy++ 1.0 (avr) | |||
# "at90usb1286" # Teensy++ 2.0 (avr) | |||
# "mk20dx128" # Teensy 3.0 (arm) | |||
"mk20dx128vlf5" # McHCK mk20dx128vlf5 | |||
# "mk20dx256" # Teensy 3.1 (arm) | |||
CACHE STRING "Microcontroller Chip" ) | |||
``` | |||
Just uncomment the chip you want, and comment out the old one. | |||
> NOTE: If you change this option, you will *need* to delete the build | |||
> directory that is created in the Building sections below. | |||
Selecting Modules | |||
----------------- | |||
> WARNING: Not all modules are compatible, and some modules may have | |||
> dependencies on other modules. | |||
This is where the options start getting interesting. The Kiibohd Controller | |||
is designed around a set of 4 types of modules that correspond to different | |||
functionality: | |||
- Scan Module | |||
- Macro Module | |||
- Output Module | |||
- Debug Module | |||
The Scan Module is where the most interesting stuff happens. These modules | |||
take in "keypress data". A converter Scan Module will interpret a protocol | |||
into key press/releases. A matrix Scan Module may inherit from the matrix | |||
module to scan keypress from a matrix 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). Each Scan Module has it's own default | |||
keymap/modifier map. (TODO recommend keymap changing in the Macro Module). | |||
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!). | |||
The Macro Module takes care of the mapping of the key press/release code into | |||
an Output (USB) scan code. Any layering, macros, keypress | |||
intelligence/reaction is done here. | |||
The Output Module is the module dealing with output from the microcontroller. | |||
Currently USB is the only output protocol. Different USB output | |||
implementations are available, pjrc being the safest/least featureful one. | |||
Debug capabilities may depend on the module selected. | |||
The Debug Module enables various things like the Teensy LED on errors, debug | |||
terminal output. (TODO get true UART working in avr, not just arm) | |||
Open up CMakeLists.txt in your favourite text editor. Look for: | |||
```cmake | |||
### | |||
# Project Modules | |||
# | |||
#| Note: This is the only section you probably want to modify | |||
#| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module) | |||
#| All of the modules must be specified, as they generate the sources list of files to compile | |||
#| Any modifications to this file will cause a complete rebuild of the project | |||
#| Please look at the {Scan,Macro,Output,Debug} for information on the modules and how to create new ones | |||
##| Deals with acquiring the keypress information and turning it into a key index | |||
set( ScanModule "MD1" | |||
CACHE STRING "Scan Module" ) | |||
##| Provides the mapping functions for DefaultMap and handles any macro processing before sending to the OutputModule | |||
set( MacroModule "PartialMap" | |||
CACHE STRING "Macro Module" ) | |||
##| Sends the current list of usb key codes through USB HID | |||
set( OutputModule "pjrcUSB" | |||
CACHE STRING "Output Module" ) | |||
##| Debugging source to use, each module has it's own set of defines that it sets | |||
set( DebugModule "full" | |||
CACHE STRING "Debug Module" ) | |||
``` | |||
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. | |||
There are also CMake options for temporarily selecting modules. But it's | |||
easier to just edit the file. e.g. `cmake -DScanModuleOverride=<module name>`. | |||
Keymap Configuration | |||
-------------------- | |||
This is where you define the layout for your keyboard. | |||
Currently, the only way to define kebyoard layouts is using [KLL](https://www.overleaf.com/read/zzqbdwqjfwwf). | |||
KLL is built up of 3 different kinds of keymaps in total. | |||
The BaseMap, DefaultMap and PartialMaps. | |||
For each type of keymap, it is possible to combine multiple .kll files together to create new ones using | |||
the compiler. The order of the files matter, as the right-most file will overwrite any setting in the | |||
previous files. | |||
> NOTE: Each keymap is done after the entire file is processed. This means that within the file the order | |||
> of assignment doesa *not* matter (if you assign the same thing twice, then yes the most recent one | |||
> takes priority). | |||
BaseMap defines what the keyboard can do. This includes specific capabilities of the keyboard (such as USB), | |||
the mapping of Scan Codes to USB Codes and any specific configurations for the keyboard. | |||
In general, the BaseMap rarely needs to be changed. Usually only when adding a new keyboard to the firmware | |||
does the Basemap need any modification. | |||
The BaseMap is what both DefaultMap and PartialMaps are based upon. This allows for a common reference | |||
when defining custom keymappings. | |||
> NOTE: Don't use defaultMap.kll to change your layouts. This will work, but they will not be portable. | |||
The DefaultMap is the normal state of the keyboard, i.e. your default layer. | |||
Using the BaseMap as a base, the DefaultMap is a modification of the BaseMap to what the keyboard should do. | |||
Since the DefaultMap uses USB Code to USB Code translations, this means that keymaps used for one keyboard | |||
will work with another keyboard. | |||
For example, I use Colemak, so this means I only have to define Colemak once for every keyboard that supports | |||
the kiibohd firmware. This is possible because every BaseMap defines the keyboard as a US ANSI like keyboard | |||
layout. | |||
The DefaultMap can also be thought of as Layer 0. | |||
PartialMaps are optional keymaps that can be "stacked" on top of the DefaultMap. | |||
They can be dynamically swapped out using the layer control capabilities: | |||
- layerLatch( `<layer number>` ) | |||
- layerLock( `<layer number>` ) | |||
- layerShift( `<layer number>` ) | |||
layerShift is usually what you want as it works just like a standard shift key. | |||
layerLock is similar to the CapsLock key. While layerLatch is a latch, where only the next key you press | |||
will use that layer (e.g. stickykeys). | |||
A unique aspect of KLL layers is that it's a true stack of layers. | |||
When a layer is activated, only the keys that are specified by the layer will change. | |||
This means, if you define a layer that only sets `CapsLock -> LCtrl` and `LCtrl->Capslock` only those keys | |||
will change when you active the layer. All the other keys will use the layer that is "underneath" to | |||
lookup the keypress (usually the DefaultMap). | |||
This means that you can combine .kll files statically using the compiler or dynamically using the firmware. | |||
You can set the max number of layers by changing the `stateWordSize` define in one of your kll files. | |||
By default it is set to 8 in Macro/PartialMap/capabilities.kll. This means you can have up to 256 layers | |||
total (this includes the DefaultMap). | |||
You can increase this number to either 16 or 32 (this will use more Flash and RAM btw) which will give you | |||
2^16 and 2^32 possible layers respectively (65 535 and 4 294 967 295). | |||
```cmake | |||
### | |||
# Keymap Configuration (do not include the .kll extension) | |||
# | |||
#| Do not include the .kll extension | |||
#| * BaseMap maps the native keyboard scan codes to USB Codes so the layout is compatible with all other layouts | |||
#| * DefaultMap allows the default keymap to be modified from the BaseMap | |||
#| * PartialMaps is a set of dynamically set layers (there is no limit, but too many may use up too much RAM...) | |||
#| BaseMap generally does not need to be changed from "defaultMap" | |||
#| | |||
#| Syntax: | |||
#| myMap | |||
#| * defines a single .kll layout file, double-quotes are needed to distinguish between layers | |||
#| "myMap specialLayer" | |||
#| * defines myMap to be the main layout, then replace specialLayers on top of it | |||
#| | |||
#| - Only for PartialMaps - | |||
#| "myMap specialLayer" "myMap colemak" dvorak | |||
#| * As before, but also generates a second layer at index 2 and third at index 3 | |||
#| | |||
#| NOTE: Remember to add key(s) to enable each Partial Layer | |||
#| NOTE2: Layers are always based up the BaseMap (which should be an ANSI-like mapping) | |||
#| NOTE3: Compiler looks in kll/layouts and the build directory for layout files (precedence on build directory) | |||
##| Set the base keyboard .kll map, defaults to "defaultMap" if not found | |||
##| Looks in Scan/<Module Name> for the available BaseMaps | |||
set( BaseMap "defaultMap" | |||
CACHE STRING "KLL BaseMap/Scancode Keymapping" ) | |||
##| Layer additonal .kll maps on the BaseMap, layers are in order from 1st to nth | |||
##| Can be set to "" | |||
set( DefaultMap "md1Overlay stdFuncMap" | |||
CACHE STRING "KLL DefaultMap" ) | |||
##| ParitalMaps available on top of the BaseMap. See above for syntax on specifying multiple layers vs. layering | |||
##| Can be set to "" | |||
set( PartialMaps "hhkbpro2" | |||
CACHE STRING "KLL PartialMaps/Layer Definitions" ) | |||
``` | |||
Linux Building | |||
-------------- | |||
From this directory. | |||
```bash | |||
$ mkdir build | |||
$ cd build | |||
$ cmake .. | |||
$ make | |||
``` | |||
Example output: | |||
``` | |||
$ cmake .. | |||
-- Compiler Family: | |||
arm | |||
-- Chip Selected: | |||
mk20dx128vlf5 | |||
-- Chip Family: | |||
mk20dx | |||
-- CPU Selected: | |||
cortex-m4 | |||
-- Compiler Source Files: | |||
Lib/mk20dx.c;Lib/delay.c | |||
-- Bootloader Type: | |||
dfu | |||
-- Detected Scan Module Source Files: | |||
Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c | |||
-- Detected Macro Module Source Files: | |||
Macro/PartialMap/macro.c | |||
-- Detected Output Module Source Files: | |||
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 | |||
-- Detected Debug Module Source Files: | |||
Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c | |||
-- Found Git: /usr/bin/git (found version "2.2.1") | |||
-- Found Ctags: /usr/bin/ctags (found version "5.8") | |||
-- Checking for latest kll version: | |||
Current branch master is up to date. | |||
-- Detected Layout Files: | |||
/home/hyatt/Source/controller/Macro/PartialMap/capabilities.kll | |||
/home/hyatt/Source/controller/Output/pjrcUSB/capabilities.kll | |||
/home/hyatt/Source/controller/Scan/MD1/defaultMap.kll | |||
/home/hyatt/Source/controller/kll/layouts/md1Overlay.kll | |||
/home/hyatt/Source/controller/kll/layouts/stdFuncMap.kll | |||
/home/hyatt/Source/controller/kll/layouts/hhkbpro2.kll | |||
-- Configuring done | |||
-- Generating done | |||
-- Build files have been written to: /home/hyatt/Source/controller/build | |||
[master]: make [~/Source/controller/build](hyatt@x230mas:pts/6) | |||
[ 5%] Generating KLL Layout | |||
Scanning dependencies of target kiibohd.elf | |||
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o | |||
[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.o | |||
[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.o | |||
[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.o | |||
[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.o | |||
[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.o | |||
[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.o | |||
[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.o | |||
[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.o | |||
[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.o | |||
[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.o | |||
[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.o | |||
[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.o | |||
[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o | |||
[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o | |||
Linking C executable kiibohd.elf | |||
[ 94%] Built target kiibohd.elf | |||
Scanning dependencies of target SizeAfter | |||
[100%] Chip usage for mk20dx128vlf5 | |||
SRAM: 32% 5384/16384 bytes | |||
Flash: 18% 23384/126976 bytes | |||
[100%] Built target SizeAfter | |||
``` | |||
Linux Loading Firmware | |||
---------------------- | |||
First place the keyboard into re-flash mode. This can be done either by | |||
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd | |||
Virtual Serial Port and using the 'reload' command. | |||
The `load` script that is created during the build can load the firmware over | |||
USB. Either run it with sudo, or install the `98-kiibohd.rules` to | |||
`/etc/udev/rules.d` and run: `udevadm control --reload-rules`. | |||
To load the newly built firmware: `./load`. | |||
Linux Building Bootloader | |||
------------------------- | |||
> NOTE: Does not apply to Teensy based builds. | |||
From this directory. | |||
```bash | |||
$ cd Bootloader | |||
$ mkdir build | |||
$ cd build | |||
$ cmake .. | |||
$ make | |||
``` | |||
Example output: | |||
```bash | |||
$ cmake .. | |||
-- Compiler Family: | |||
arm | |||
-- Chip Selected: | |||
mk20dx128vlf5 | |||
-- Chip Family: | |||
mk20dx | |||
-- CPU Selected: | |||
cortex-m4 | |||
-- Compiler Source Files: | |||
Lib/mk20dx.c;Lib/delay.c | |||
-- Bootloader Type: | |||
dfu | |||
-- Bootloader Source Files: | |||
main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c | |||
-- Found Git: /usr/bin/git (found version "2.2.1") | |||
-- Found Ctags: /usr/bin/ctags (found version "5.8") | |||
-- Configuring done | |||
-- Generating done | |||
-- Build files have been written to: /home/hyatt/Source/controller/Bootloader/build | |||
[master]: make [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6) | |||
Scanning dependencies of target kiibohd_bootloader.elf | |||
[ 11%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/main.c.o | |||
[ 22%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.c.o | |||
[ 33%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.desc.c.o | |||
[ 44%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/flash.c.o | |||
[ 55%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/kinetis.c.o | |||
[ 66%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/usb.c.o | |||
[ 77%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/mk20dx.c.o | |||
[ 88%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/delay.c.o | |||
Linking C executable kiibohd_bootloader.elf | |||
[ 88%] Built target kiibohd_bootloader.elf | |||
Scanning dependencies of target SizeAfter | |||
[100%] Chip usage for mk20dx128vlf5 | |||
SRAM: 19% 3176/16384 bytes | |||
Flash: 2% 3736/126976 bytes | |||
[100%] Built target SizeAfter | |||
``` | |||
Linux Loading Bootloader | |||
------------------------ | |||
> NOTE: Does not apply to Teensy based builds. | |||
It's recommended to use an SWD-type flasher like a Bus Pirate. There is a | |||
convenience script for loading the firmware once the system is setup. | |||
```bash | |||
$ cd Bootloader/Scripts | |||
$ ./swdLoad.bash | |||
``` | |||
The above script requires Ruby, Ruby serial port module, git, and a | |||
`/dev/buspirate` udev rule. | |||
Additional Notes: | |||
* https://github.com/mchck/mchck/wiki/Getting-Started (See Bus-Pirate section) | |||
* https://wiki.archlinux.org/index.php/Bus_pirate | |||
Windows Building | |||
---------------- | |||
From this directory. | |||
```bash | |||
$ mkdir build | |||
$ cd build | |||
$ wincmake .. | |||
$ make | |||
``` | |||
Example output: | |||
```bash | |||
$ wincmake .. | |||
-- Compiler Family: | |||
arm | |||
-- Chip Selected: | |||
mk20dx128vlf5 | |||
-- Chip Family: | |||
mk20dx | |||
-- CPU Selected: | |||
cortex-m4 | |||
-- Compiler Source Files: | |||
Lib/mk20dx.c;Lib/delay.c | |||
-- Bootloader Type: | |||
dfu | |||
-- Detected Scan Module Source Files: | |||
Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c | |||
-- Detected Macro Module Source Files: | |||
Macro/PartialMap/macro.c | |||
-- Detected Output Module Source Files: | |||
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 | |||
-- Detected Debug Module Source Files: | |||
Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c | |||
-- Found Git: C:/cygwin64/bin/git.exe (found version "2.1.1") | |||
-- Found Ctags: C:/cygwin64/bin/ctags.exe (found version "5.8") | |||
-- Checking for latest kll version: | |||
Current branch master is up to date. | |||
-- Detected Layout Files: | |||
C:/cygwin64/home/Jacob/controller/Macro/PartialMap/capabilities.kll | |||
C:/cygwin64/home/Jacob/controller/Output/pjrcUSB/capabilities.kll | |||
C:/cygwin64/home/Jacob/controller/Scan/MD1/defaultMap.kll | |||
C:/cygwin64/home/Jacob/controller/kll/layouts/md1Overlay.kll | |||
C:/cygwin64/home/Jacob/controller/kll/layouts/stdFuncMap.kll | |||
C:/cygwin64/home/Jacob/controller/kll/layouts/hhkbpro2.kll | |||
-- Configuring done | |||
-- Generating done | |||
-- Build files have been written to: C:/cygwin64/home/Jacob/controller/build | |||
$ make | |||
[ 5%] Generating KLL Layout | |||
Scanning dependencies of target kiibohd.elf | |||
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj | |||
[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.obj | |||
[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.obj | |||
[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.obj | |||
[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.obj | |||
[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj | |||
[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj | |||
[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.obj | |||
[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.obj | |||
[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.obj | |||
[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.obj | |||
[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.obj | |||
[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj | |||
[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj | |||
[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj | |||
Linking C executable kiibohd.elf | |||
[ 94%] Built target kiibohd.elf | |||
Scanning dependencies of target SizeAfter | |||
[100%] Chip usage for mk20dx128vlf5 | |||
SRAM: 32% 5384/16384 bytes | |||
Flash: 18% 23296/126976 bytes | |||
[100%] Built target SizeAfter | |||
``` | |||
### NOTES: | |||
If you get the following error, you have not setup wincmake correctly: | |||
```bash | |||
$ make | |||
[ 5%] Generating KLL Layout | |||
Scanning dependencies of target kiibohd.elf | |||
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o | |||
../main.c:28:19: fatal error: macro.h: No such file or directory | |||
#include <macro.h> | |||
^ | |||
compilation terminated. | |||
CMakeFiles/kiibohd.elf.dir/build.make:67: recipe for target 'CMakeFiles/kiibohd.elf.dir/main.c.o' failed | |||
make[2]: *** [CMakeFiles/kiibohd.elf.dir/main.c.o] Error 1 | |||
CMakeFiles/Makefile2:98: recipe for target 'CMakeFiles/kiibohd.elf.dir/all' failed | |||
make[1]: *** [CMakeFiles/kiibohd.elf.dir/all] Error 2 | |||
Makefile:75: recipe for target 'all' failed | |||
make: *** [all] Error 2 | |||
``` | |||
If you have already added the line to your `~/.bashrc` try restarting your | |||
cygwin shell. | |||
Windows Loading Firmware | |||
------------------------ | |||
First place the keyboard into re-flash mode. This can be done either by | |||
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd | |||
Virtual Serial Interface and using the `reload` command. | |||
The `load` script that is created during the build can load the firmware over | |||
USB. | |||
To load the newly built firmware: `./load` | |||
Be patient the couple of times, Windows is slow at installing drivers... | |||
Mac OS X Building | |||
----------------- | |||
From this directory. | |||
```bash | |||
$ mkdir build | |||
$ cd build | |||
$ cmake .. | |||
$ make | |||
``` | |||
Example output: | |||
> TODO | |||
Mac OS X Loading Firmware | |||
------------------------- | |||
First place the keyboard into re-flash mode. This can be done either by | |||
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd | |||
Virtual Serial Port and using the `reload` command. | |||
The `load` script that is created during the build can load the firmware over | |||
USB. | |||
To load the newly built firmware: `./load`. | |||
Virtual Serial Port - CLI | |||
------------------------- | |||
Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint. | |||
This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen) | |||
### Linux | |||
I generally use screen. You will need sudo/root priviledges if you haven't | |||
installed the `98-kiibohd.rules` file to `/etc/udev/rules.d`. | |||
``` | |||
$ screen /dev/ttyACM0 | |||
# (Might be ACM1, ACM2, etc.) | |||
``` | |||
### Windows | |||
Make sure the Teensy Virtual Serial Port driver is installed. If possible use | |||
screen (as part of Cygwin). Check which COM port the virtual serial port has | |||
been assigned to: `Device Manager->Ports (COM & LPT)->Teensy USB Serial`. In | |||
brackets it will say which COM port (e.g. COM3) | |||
putty works well when using DTR/DSR or RTS/CTS flow control. | |||
| Setting | Value | | |||
| --------------- | ------------------------------------- | | |||
| Connection type | Serial | | |||
| Serial line | Your COM port, e.g. COM3 | | |||
| Speed | doesn't matter, it's auto-negotiated | | |||
Under `Category->Connections->Serial`: `Flow control: DTR/DSR`. | |||
If stuff is hard to read (you have a dumb colour scheme): | |||
`Category->Window->Colours->Use system color`. That seems to make text at | |||
least readable | |||
> I use a custom colour scheme that makes each colour easy to see. | |||
> -HaaTa. | |||
Unfortunately, screen for Cygwin seems to be broken for serial ports, but you | |||
can try it... | |||
```bash | |||
$ screen /dev/ttyS2 | |||
# Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc. | |||
``` | |||
Gnu screen doesn't seem to echo all the characters (it works though). | |||
I believe it's a problem with stty, but I don't know how to fix it... | |||
### Mac OS X | |||
I recommend screen (can be installed via Macports). | |||
```bash | |||
$ screen /dev/tty.<usb something> | |||
``` |