9 years ago · a3b80b0f2a
--- 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=<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
 --------------