diff --git a/doc/keybrd_library_developer_guide.md b/doc/keybrd_library_developer_guide.md index 45343e1..5e30960 100644 --- a/doc/keybrd_library_developer_guide.md +++ b/doc/keybrd_library_developer_guide.md @@ -143,7 +143,7 @@ Following the style guide makes it easier for the next programmer to understand -## 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. diff --git a/doc/keybrd_library_user_guide.md b/doc/keybrd_library_user_guide.md index 67e4fe3..724b65e 100644 --- a/doc/keybrd_library_user_guide.md +++ b/doc/keybrd_library_user_guide.md @@ -121,12 +121,11 @@ 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. - 4. The Teensy boot loader window opens; - you might need to press and release the pushbutton on the Teensy circuit board. + 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. + 4. The Teensy boot loader window opens; + you might need to press and release the pushbutton on the Teensy circuit board. ## Example keybrd sketches Example keybrd sketches are in the [examples](../examples/) directory. diff --git a/tutorials/images/breadboard_keyboard_2x5_labeled.jpg b/tutorials/images/breadboard_keyboard_2x5_labeled.jpg new file mode 100644 index 0000000..cfd9ce4 Binary files /dev/null and b/tutorials/images/breadboard_keyboard_2x5_labeled.jpg differ diff --git a/tutorials/tutorial_0_introduction.md b/tutorials/tutorial_0_introduction.md index e62eeee..9c0d654 100644 --- a/tutorials/tutorial_0_introduction.md +++ b/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 +* is familiar with C++ +* is new to Arduino, firmware, controllers, and the internal workings of keyboards -Each tutorial presents an example sketch. -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, sketches will be changed to Teensy LC and MCP23018 IOE +> In July, the tutorial sketches will be changed to Teensy LC and MCP23018 I/O expander + +> 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") diff --git a/tutorials/tutorial_1_breadboard_keyboard.md b/tutorials/tutorial_1_breadboard_keyboard.md index 4c6dc3d..a16c50c 100644 --- a/tutorials/tutorial_1_breadboard_keyboard.md +++ b/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. - -[breadboard keyboard with 2 rows and 2 columns] -(images/breadboard_keyboard_2x2_labeled.jpg "2x2 breadboard keyboard") +When you finish this tutorial you will have a working keyboard and understand how a key matrix works. ## 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] -(images/breadboard_keyboard_2x2_labeled.jpg "2x2 breadboard keyboard") +![breadboard keyboard with 2 rows and 2 columns](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. -Diodes connect switches to rows. +Short bare wires connect terminal strips into matrix columns. +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 - * orient diodes with cathode (banded end) towards the row (power strip) - * use the diode cut offs to connect switches into columns + * diode cut offs connect terminal strips into columns + * diodes are orient with cathode (banded end) towards the row (power strip) + * 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") diff --git a/tutorials/tutorial_2_single-layer_keyboard.md b/tutorials/tutorial_2_single-layer_keyboard.md index dbe93b6..bf24a69 100644 --- a/tutorials/tutorial_2_single-layer_keyboard.md +++ b/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: -[keybrd_2_single-layer_annotated.ino](keybrd_proj/keybrd/examples/tutorials/keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino) +The [keybrd_2_single-layer_annotated.ino](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. diff --git a/tutorials/tutorial_3a_multi-layer_keyboard.md b/tutorials/tutorial_3a_multi-layer_keyboard.md index 7518dc7..f4ea4ea 100644 --- a/tutorials/tutorial_3a_multi-layer_keyboard.md +++ b/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 -This annotated sketch demonstrates the multi-layer feature: -[keybrd_3_multi-layer_annotated.ino](keybrd_proj/keybrd/examples/tutorials/keybrd_3_multi-layer_annotated/keybrd_3_multi-layer_annotated.ino) +## Pseudo code for simple layer scheme +The following pseudo code has just enough detail to show how layer schemes work. -## Layer scheme classes -The walkthrough example covered the most basic classes. -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. +**Layer** objects control the active layer. +There is one Key_Layer object for each layer. Each Key_Layer object has a unique layer number. 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 -Layered objects contain one scancode for each layer. -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: +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 one layer code. -They do are not affected by the active layer. +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 @@ -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. diff --git a/tutorials/tutorial_3b_autoShift.md b/tutorials/tutorial_3b_autoShift.md index 8a138e9..367064e 100644 --- a/tutorials/tutorial_3b_autoShift.md +++ b/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 diff --git a/tutorials/tutorial_4_split_keyboard_with_IOE.md b/tutorials/tutorial_4_split_keyboard_with_IOE.md index 34594f1..2ef27ec 100644 --- a/tutorials/tutorial_4_split_keyboard_with_IOE.md +++ b/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] -(images/breadboard_keyboard_2x4_labeled.jpg "2x5 breadboard keyboard") +![breadboard keyboard with 2 rows and 4 columns of keys](images/breadboard_keyboard_2x5_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 -[keybrd_4_split_with_IOE_annotated.ino](keybrd_4_split_with_IOE_annotated/keybrd_4_split_with_IOE_annotated.ino) - +The [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.