keybrd/tutorials/tutorial_3a_multi-layer_keyboard.md

Tutorial 3a - multi-layer keyboard

When you finish this tutorial you will be able to be able to modify a multi-layer keybrd sketch to suite your own multi-layer keyboard design.

Multi-layer nomenclature

layers are key bindings provided by the keyboard firmware. For example,

• The full-size IBM PC keyboard has one layer.
• Many compact keyboards have an additional Fn layer.
• The Neo layout has 6 layers.

layer code - is an integer used to identify a layer.

active layer - is the layer currently used by the keyboard.

layer scheme - is a system for changing layers while typing (a single-layer scheme does not change layers).

Pseudo code for simple layer scheme

The following pseudo code has just enough detail to show how layer schemes work.

Layer objects select the active layer. When a Layer object is pressed, it tells StateLayer to update the active layer. There is one Key_Layer object for each layer. Each Key_Layer object has a unique layer Id number.

class Key_Layer
{
    int layer
    StateLayer& refStateLayer
    press() { refStateLayer.setLayer(layer) }
}

A StateLayer's activeLayer is always up to date.

class StateLayer
{
    int activeLayer
    setActiveLayer(int layer) { activeLayer = layer }
    getActiveLayer() { return activeLayer }
}

Layered objects contain an array of Key pointers, one Key pointer for each layer. Layer Id numbers are used as array indexes in the Key_Layered ptrsKeys array. When a Layered object is pressed, it gets the active layer from StateLayer, and then presses the key of the active layer.

class Key_Layered
{
    Key** ptrsKeys          //array of Key pointers, one Key pointer per layer
    StateLayer& refStateLayer
    press() { layer = refStateLayer.getActiveLayer()
              ptrsKeys[layer]->press() }
}

Dependency diagram

     +-----------+
     | Key_Layer |
     +-----------+
          |
          |setLayer()
          |
          v
    +------------+
    | StateLayer |
    +------------+
          ^
          |
          |getLayer()
          |
    +-------------+
    | Key_Layered |
    +-------------+

Layer-scheme classes

There are several layer scheme-classes to choose from. You can view all the class definitions in the keybrd library.

Layer classes include:

• Code_LayerHold
• Code_LayerLock

There is only one StateLayer class:

• StateLayer

Layered classes include:

• Code_LayeredScSc
• Code_LayeredCodeSc
• Code_LayeredCodeCode
• Key_LayeredKeysArray

Single-layer Codes

Most Code objects only have one scancode or code. They are not affected by the active layer. Example single-layer Code classes include:

• Code_Sc
• Code_ScS
• Code_ScNS
• Code_Shift
• Code_LayerHold
• Code_LayerLock

(Future version of keybrd library may change all Code classes to Key classes.)

A simple multi-layer keybrd sketch

The keybrd_3a_multi-layer_annotated.ino sketch uses three layer-scheme classes:

• StateLayers
• Code_LayerHold
• Key_LayeredKeysArray

Annotations in the sketch explain how the multi-layer feature works.

Exercises

1. Modify the keybrd_3_multi-layer_annotated.ino sketch to use two Code_LayerLock objects.

Layout	0	1
0	a 1	b 2
1	layer0	layer1

keybrd tutorial by Wolfram Volpi is licensed under a Creative Commons Attribution 4.0 International License.
Permissions beyond the scope of this license may be available at https://github.com/wolfv6/keybrd/issues/new.