louis/kiibohd-controller: README.markdown comparison

comparison README.markdown @ 309:4f47971c45c2

Merge remote-tracking branch 'upstream/master'

author	Rowan Decker <Smasher816@gmail.com>
date	Sun, 08 Mar 2015 20:17:39 -0700
parents	ab4515606277 b311f387c921
children	a2df35fa4f0b

comparison

equal deleted inserted replaced

-:ab4515606277
+:4f47971c45c2
 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 (haven't tried
+Building on Mac should be ok for 99% of users with Macports or Homebrew. For
-Brew). The dfu Bootloader will not build correctly with the old version of
+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
 ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK)
 - Arch Linux / Mac Ports
 - arm-none-eabi-gcc
-- arm-none-eaby-binutils
+- arm-none-eabi-binutils
 - Windows (https://launchpad.net/gcc-arm-embedded/+download)
 - gcc-arm-none-eabi (win32.zip)
 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
 --------------

Mercurial > louis > kiibohd-controller

comparison README.markdown @ 309:4f47971c45c2