From a3b80b0f2ac852a8940072bc4161261f20fa84fe Mon Sep 17 00:00:00 2001 From: Jacob Alexander Date: Sun, 22 Feb 2015 14:14:55 -0800 Subject: [PATCH] Adding keymap configuration section to the README. --- README.markdown | 108 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) diff --git a/README.markdown b/README.markdown index 2823893..566d17f 100644 --- a/README.markdown +++ b/README.markdown @@ -9,7 +9,7 @@ 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 +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 @@ -263,6 +263,112 @@ There are also CMake options for temporarily selecting modules. But it's easier to just edit the file. e.g. `cmake -DScanModuleOverride=`. +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( `` ) +- layerLock( `` ) +- layerShift( `` ) + +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/ 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 --------------