document

doc/keybrd_library_developer_guide.md

@@ -143,7 +143,7 @@ Following the style guide makes it easier for the next programmer to understand
 
   <!-- http://stackoverflow.com/questions/2198241/best-practice-for-c-function-commenting -->
 
-## trace of keybrd scan
+## Trace of keybrd scan
 Arduino does not have a debugger; so here is a list of functions in the order that they are called.
 Refer to it like a table of contents while reading the keybrd library.
 

doc/keybrd_library_user_guide.md

@@ -121,7 +121,6 @@ If it isn't already plugged in, plug the USB cable into the computer and control
 >   if that fails, unplug Teensy USB
 
 Compile and load workflow:
-
  1. Open a keybrd sketch in the Arduino IDE.
  2. Prepare for loosing control of keyboard and mouse.
  3. On the Arduino IDE, click the Upload button.

tutorials/tutorial_0_introduction.md

@@ -1,25 +1,26 @@
 Tutorial 0 - Introduction
 =========================
+Tutorials 2 through 6 present an example sketch.
+All the example sketches have 2 to 8 keys and run on a breadboard keyboard.
+
 The first two tutorials are intended to be read in sequence:
  1. Breadboard keyboard
  2. Single-layer keybrd
-You can write a keyboard firmware after reading tutorial 2.
+
 Topics covered in tutorial 2 apply to all keybrd sketches.
-The remaining tutorials can be read in any sequence, and highlight topics that may or may not be useful to your keyboard design.
+The remaining tutorials can be read in any order.
 
 The tutorials assume the reader:
 * is familiar with C++
 * is new to Arduino, firmware, controllers, and the internal workings of keyboards
 
-Each tutorial presents an example sketch.
+<!-- todo -->
-All the example sketches have 2 to 8 keys and run on a breadboard keyboard.
+> All the tutorial sketches are tested on teensy 2.0 and PCA9655E-D I/O expander
 
-todo all the tutorial sketches are tested on teensy 2.0 and PCA9655E-D IOE
+> In July, the tutorial sketches will be changed to Teensy LC and MCP23018 I/O expander
-     in July, sketches will be changed to Teensy LC and MCP23018 IOE
+
+> Some of the pictures and table values do not match the sketches, they will be updated after changing to Teensy LC
 
 You will need a breadboard keyboard with a Teensy 2.0 controller to run the tutorial sketches.
 If you use a different controller, you may have to change port classes.
 If you already have a keyboard with an Arduino compatible controller, you can use that instead of a breadboard keyboard.
-
-[breadboard keyboard with 2 rows and 2 columns]
-(images/breadboard_keyboard_2x2_labeled.jpg "2x2 breadboard keyboard")

tutorials/tutorial_1_breadboard_keyboard.md

@@ -1,9 +1,6 @@
-Tutorial 0 - breadboard keyboard
+Tutorial 1 - breadboard keyboard
 ================================
-When you finish this tutorial you will have a working keyboard and understand how its key matrix works.
+When you finish this tutorial you will have a working keyboard and understand how a key matrix works.
-
-[breadboard keyboard with 2 rows and 2 columns]
-(images/breadboard_keyboard_2x2_labeled.jpg "2x2 breadboard keyboard")
 
 ## Why a breadboard keyboard is useful
 A breadboard is the easiest way to learn keyboard electronics.
@@ -11,14 +8,14 @@ Electronics are fickle, you won't get everything right the first time, there is
 Breadboards make the learning electronics faster and fun.
 
 Breadboard keyboards have row-column matrices and diodes just like the big keyboards.
-Compared to full size keyboards on PCBs, breadboard keyboards are easier to work with because:
+Compared to full size keyboards on PCBs, breadboard keyboards are easier to learn on because:
 * Parts can be reused in many different configurations
 * A small keyboard is easier to trouble shoot
 * Mistakes are easily corrected because no desoldering
 
 Breadboard keyboards are useful for:
 * learning keyboard electronics - diodes, micro controllers, I/O expanders
-* learning the firmware development process
+* learning the firmware development workflow
 * prototyping circuits before making a PCB
 * testing firmware concepts before building the keyboard hardware
 
@@ -38,13 +35,12 @@ A multi-meter is useful for trouble shooting.
 ## Building a basic breadboard keyboard
 The basic breadboard has 4 switches and a microcontroller.
 
-[breadboard keyboard with 2 rows and 2 columns of keys]
+![breadboard keyboard with 2 rows and 2 columns](images/breadboard_keyboard_2x2_labeled.jpg "2x2 breadboard keyboard")
-(images/breadboard_keyboard_2x2_labeled.jpg "2x2 breadboard keyboard")
 
 The key matrix has two rows and two columns.
 Breadboard power rails are repurposed as matrix rows.
-Short bare wires connect switches into matrix columns.
+Short bare wires connect terminal strips into matrix columns.
-Diodes connect switches to rows.
+Switch-diode pairs connect rows to columns.
 
 The green rectangle on the right is the Teensy 2.0 microcontroller.
 The matrix rows and columns connect to the microcontroller via jumper wires.
@@ -53,14 +49,14 @@ Breadboard keyboard assembly instructions:
 
 1. Cut leads to length.
  * tactile-switch-lead length 6 to 8 mm
- * diodes 22 to 24 mm total end-to-end length, and save the cut offs, they will be used in steps 2 and 3
+ * diodes 22 to 24 mm total end-to-end length, and save the cut offs for steps 2 and 3
 2. Insert parts into the breadboard as shown in the picture.
- * orient the switches such that the leads are on separate terminal strips
+ * diode cut offs connect terminal strips into columns
- * orient diodes with cathode (banded end) towards the row (power strip)
+ * diodes are orient with cathode (banded end) towards the row (power strip)
- * use the diode cut offs to connect switches into columns
+ * switches connect diode to columns
 3. Insert jumper wires connecting Teensy2 to the matrix rows and columns.
  * follow pin connections table (below) and consult pinout diagram in
-   [Connecting Teensy 2.0 to a Keyboard](connecting_teensy2_to_keyboard.md)
+   [Teensy2_pinout.txt](../doc/Teensy2_pinout.txt)
 
 **Teensy 2.0 pin connections table**
 
@@ -72,7 +68,7 @@ Breadboard keyboard assembly instructions:
 | 1          | col_1       |
 
 ## Compiling and loading the keyboard firmware
-Follow the [keybrd Library User's Guide](todo /doc/keybrd_library_user_guide.md) to set up the Arduino environment and to compile and load keybrd firmware onto the keyboard's controller.
+Follow the [keybrd Library User's Guide](../doc/keybrd_library_user_guide.md) to set up the Arduino environment and to compile and load keybrd firmware onto the keyboard's controller.
 
 ## How a keyboard matrix works
 Now that you have built your first breadboard keyboard, you can dig in and learn how it actually works.
@@ -80,7 +76,7 @@ This excellent article explains how the microcontroller, matrix, switches and di
 [How a Key Matrix Work](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/)
 
 ## Bigger breadboard keyboards
-Sometimes its useful to prototype the full keyboard matrix before designing the PCB.
+Sometimes its useful to prototype a full keyboard matrix before designing the PCB.
 Several breadboards can be tied together into one.
 
-[big breadboard keyboard](breadboard_big.jpg "breadboard_big.jpg")
+![big breadboard keyboard](images/breadboard_big.jpg "breadboard_big.jpg")

tutorials/tutorial_2_single-layer_keyboard.md

@@ -1,11 +1,11 @@
 Tutorial 2 - single-layer keyboard
 =======================================
-This annotated sketch explains how the keybrd library works:
+The [keybrd_2_single-layer_annotated.ino](keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino)
-[keybrd_2_single-layer_annotated.ino](keybrd_proj/keybrd/examples/tutorials/keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino)
+sketch explains how the keybrd library works.
 
-You can view the class definitions in the [keybrd library](keybrd/src/).
+You can view the class definitions in the [keybrd library](../src/).
 
-After reading the sketch you will be to modify it to suite your own single-layer keyboard design.
+After reading the sketch you will be able to modify it to suite your own single-layer keyboard design.
 
 ## Exercises
 1) Add a third column to the breadboard and sketch.

tutorials/tutorial_3a_multi-layer_keyboard.md

@@ -1,6 +1,6 @@
 Tutorial 3a - multi-layer keyboard
 ==================================
-After reading this tutorial you will be able to be able to modify a multi-layer keybrd sketch to suite your own multi-layer keyboard design.
+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](http://deskthority.net/wiki/Layer)** are key bindings provided by the keyboard firmware.  For example,
@@ -14,39 +14,63 @@ After reading this tutorial you will be able to be able to modify a multi-layer
 
 **layer scheme** - is a system for changing layers while typing (a single-layer scheme does not change layers).
 
-## A simple multi-layer keybrd sketch
+## Pseudo code for simple layer scheme
-This annotated sketch demonstrates the multi-layer feature:
+The following pseudo code has just enough detail to show how layer schemes work.
-[keybrd_3_multi-layer_annotated.ino](keybrd_proj/keybrd/examples/tutorials/keybrd_3_multi-layer_annotated/keybrd_3_multi-layer_annotated.ino)
 
-## Layer scheme classes
+**Layer** objects control the active layer.
-The walkthrough example covered the most basic classes.
+There is one Key_Layer object for each layer.  Each Key_Layer object has a unique layer number.
-This section takes a general view of layer scheme classes.
-You can view all the class definitions in the [keybrd library](keybrd/src/).
-
-### StateLayer
-StateLayer object has an active layer.  StateLayer keeps its active layer up to date.
-There is only one StateLayer class:
-* StateLayer
-
-### Layer
-Layer objects control the active layer.  For example, there could be one layer key for each layer.
 When a Layer object is pressed, it tells StateLayer to change the active layer.
-Example Layer classes include:
+```
+class Key_Layer
+{
+    int layer
+    StateLayer& refState
+    press() { refState.setLayer(layer) }
+}
+```
+
+A **StateLayer** object's activeLayer is always up to date.
+```
+class StateLayer
+{
+    int activeLayer
+    setActiveLayer(int layer) { activeLayer = layer }
+    getActiveLayer() { return activeLayer }
+}
+```
+
+**Layered** objects contain one scancode for each layer.
+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 per layer
+    StateLayer& refState
+    press() { layer = refState.getLayer()
+              ptrsKeys[layer]->press() }
+}
+```
+
+## Layer-scheme classes
+There are several layer scheme-classes to choose from.
+You can view all the class definitions in the [keybrd library](../src/).
+
+Layer classes include:
 * Code_LayerHold
 * Code_LayerLock
 
-### Multi-layered
+There is only one StateLayer class:
-Layered objects contain one scancode for each layer.
+* StateLayer
-When a Layered object is pressed, it gets the active layer from StateLayer, and then sends the scancode of the active layer.
+
-Example Layered classes include:
+Layered classes include:
 * Code_LayeredScSc
 * Code_LayeredCodeSc
 * Code_LayeredCodeCode
 * Key_LayeredKeysArray
 
 ## Single-layer Codes
-Most Code objects only have one scancode or one layer code.
+Most Code objects only have one scancode or code.
-They do are not affected by the active layer.
+They are not affected by the active layer.
 Example single-layer Code classes include:
 * Code_Sc
 * Code_ScS
@@ -57,6 +81,15 @@ Example single-layer Code classes include:
 
 (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](keybrd_3a_multi-layer_annotated/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.
 

tutorials/tutorial_3b_autoShift.md

@@ -1,14 +1,15 @@
 Tutorial 3b - autoShift
 =======================
-After reading this tutorial your keyboard will be able to be able to automatically shifted characters.
+When you finish this tutorial your keyboard will be able to automatically shifted characters.
 
 ## AutoShift
-Some mulit-layer keyboards have a symbols layer that writes symbols and numbers without using the shift key:
+Some mulit-layer keyboards have a symbols layer that writes symbols without using the shift key:
 
-    ~ ! @ # $ % ^ & * () _ {} | < > ? 1 2 3 4 5 6 7 8 9 0
+    ~ ! @ # $ % ^ & * () _ {} | < > : ?
 
 The keybrd library does this by automatically sending the MODIFIERKEY_SHIFT scancode.
-This annotated sketch demonstrates the AutoShift feature: [keybrd_3_autoShift_annotated.ino](keybrd_proj/keybrd/examples/keybrd_3_autoShift_annotated/keybrd_3_autoShift_annotated.ino)
+The [keybrd_3_autoShift_annotated.ino](keybrd_proj/keybrd/examples/keybrd_3_autoShift_annotated/keybrd_3_autoShift_annotated.ino)
+sketch explains the AutoShift feature.
 
 Two keybrd classes use AutoShift:
 * Code_ScS

tutorials/tutorial_4_split_keyboard_with_IOE.md

@@ -1,11 +1,10 @@
 keybrd Tutorial 4 - split keyboard with I/O Expander
 ====================================================
-After reading this tutorial you will be able to be able to modify a 2-matrix keybrd sketch to suite your own split keyboard design.
+When you finish this tutorial you will be able to be able to modify a 2-matrix keybrd sketch to suite your own split keyboard design.
 
 ## Overview of split keyboard with I/O Expander
 The breadboard in this picture models a split keyboard.
-![breadboard keyboard with 2 rows and 4 columns of keys]
+![breadboard keyboard with 2 rows and 4 columns of keys](images/breadboard_keyboard_2x5_labeled.jpg "2x5 breadboard keyboard")
-(images/breadboard_keyboard_2x4_labeled.jpg "2x5 breadboard keyboard")
 
 The right matrix is connected to a microcontroller.
 The left matrix is connected to a I/O expander.
@@ -84,6 +83,5 @@ todo these tables might not match the sketch
 todo add capacitor
 
 ## Sketch for split keyboard with I/O Expander
-An annotated sketch for the split keyboard with I/O Expander is on 
+The [keybrd_4_split_with_IOE_annotated.ino](keybrd_4_split_with_IOE_annotated/keybrd_4_split_with_IOE_annotated.ino)
-[keybrd_4_split_with_IOE_annotated.ino](keybrd_4_split_with_IOE_annotated/keybrd_4_split_with_IOE_annotated.ino)
+ sketch explains how the I/O Expander works on a keyboard.
-