<!-- http://stackoverflow.com/questions/2198241/best-practice-for-c-function-commenting --> | <!-- 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. | 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. | Refer to it like a table of contents while reading the keybrd library. | ||||
> if that fails, unplug Teensy USB | > if that fails, unplug Teensy USB | ||||
Compile and load workflow: | 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 | ||||
Example keybrd sketches are in the [examples](../examples/) directory. | Example keybrd sketches are in the [examples](../examples/) directory. |
Tutorial 0 - Introduction | 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: | The first two tutorials are intended to be read in sequence: | ||||
1. Breadboard keyboard | 1. Breadboard keyboard | ||||
2. Single-layer keybrd | 2. Single-layer keybrd | ||||
You can write a keyboard firmware after reading tutorial 2. | |||||
Topics covered in tutorial 2 apply to all keybrd sketches. | 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: | 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. | |||||
<!-- todo --> | |||||
> All the tutorial sketches are tested on teensy 2.0 and PCA9655E-D I/O expander | |||||
> In July, the tutorial sketches will be changed to Teensy LC and MCP23018 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 | |||||
> 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. | 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 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. | 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") |
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 | ## Why a breadboard keyboard is useful | ||||
A breadboard is the easiest way to learn keyboard electronics. | A breadboard is the easiest way to learn keyboard electronics. | ||||
Breadboards make the learning electronics faster and fun. | Breadboards make the learning electronics faster and fun. | ||||
Breadboard keyboards have row-column matrices and diodes just like the big keyboards. | 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 | * Parts can be reused in many different configurations | ||||
* A small keyboard is easier to trouble shoot | * A small keyboard is easier to trouble shoot | ||||
* Mistakes are easily corrected because no desoldering | * Mistakes are easily corrected because no desoldering | ||||
Breadboard keyboards are useful for: | Breadboard keyboards are useful for: | ||||
* learning keyboard electronics - diodes, micro controllers, I/O expanders | * 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 | * prototyping circuits before making a PCB | ||||
* testing firmware concepts before building the keyboard hardware | * testing firmware concepts before building the keyboard hardware | ||||
## Building a basic breadboard keyboard | ## Building a basic breadboard keyboard | ||||
The basic breadboard has 4 switches and a microcontroller. | 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. | The key matrix has two rows and two columns. | ||||
Breadboard power rails are repurposed as matrix rows. | 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 green rectangle on the right is the Teensy 2.0 microcontroller. | ||||
The matrix rows and columns connect to the microcontroller via jumper wires. | The matrix rows and columns connect to the microcontroller via jumper wires. | ||||
1. Cut leads to length. | 1. Cut leads to length. | ||||
* tactile-switch-lead length 6 to 8 mm | * 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. | 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. | 3. Insert jumper wires connecting Teensy2 to the matrix rows and columns. | ||||
* follow pin connections table (below) and consult pinout diagram in | * 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** | **Teensy 2.0 pin connections table** | ||||
| 1 | col_1 | | | 1 | col_1 | | ||||
## Compiling and loading the keyboard firmware | ## 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 | ## How a keyboard matrix works | ||||
Now that you have built your first breadboard keyboard, you can dig in and learn how it actually works. | Now that you have built your first breadboard keyboard, you can dig in and learn how it actually works. | ||||
[How a Key Matrix Work](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) | [How a Key Matrix Work](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) | ||||
## Bigger breadboard keyboards | ## 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. | 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") |
Tutorial 2 - single-layer keyboard | 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 | ## Exercises | ||||
1) Add a third column to the breadboard and sketch. | 1) Add a third column to the breadboard and sketch. |
Tutorial 3a - multi-layer keyboard | 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 | ## Multi-layer nomenclature | ||||
**[layers](http://deskthority.net/wiki/Layer)** are key bindings provided by the keyboard firmware. For example, | **[layers](http://deskthority.net/wiki/Layer)** are key bindings provided by the keyboard firmware. For example, | ||||
**layer scheme** - is a system for changing layers while typing (a single-layer scheme does not change layers). | **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/). | |||||
**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. | |||||
``` | |||||
class Key_Layer | |||||
{ | |||||
int layer | |||||
StateLayer& refState | |||||
press() { refState.setLayer(layer) } | |||||
} | |||||
``` | |||||
### StateLayer | |||||
StateLayer object has an active layer. StateLayer keeps its active layer up to date. | |||||
There is only one StateLayer class: | |||||
* StateLayer | |||||
A **StateLayer** object's activeLayer is always up to date. | |||||
``` | |||||
class StateLayer | |||||
{ | |||||
int activeLayer | |||||
setActiveLayer(int layer) { activeLayer = layer } | |||||
getActiveLayer() { return activeLayer } | |||||
} | |||||
``` | |||||
### 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: | |||||
**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_LayerHold | ||||
* Code_LayerLock | * 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_LayeredScSc | ||||
* Code_LayeredCodeSc | * Code_LayeredCodeSc | ||||
* Code_LayeredCodeCode | * Code_LayeredCodeCode | ||||
* Key_LayeredKeysArray | * Key_LayeredKeysArray | ||||
## Single-layer Codes | ## 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: | Example single-layer Code classes include: | ||||
* Code_Sc | * Code_Sc | ||||
* Code_ScS | * Code_ScS | ||||
(Future version of keybrd library may change all Code classes to Key classes.) | (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 | ## Exercises | ||||
1) Modify the keybrd_3_multi-layer_annotated.ino sketch to use two Code_LayerLock objects. | 1) Modify the keybrd_3_multi-layer_annotated.ino sketch to use two Code_LayerLock objects. | ||||
Tutorial 3b - autoShift | 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 | ## 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. | 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: | Two keybrd classes use AutoShift: | ||||
* Code_ScS | * Code_ScS |
keybrd Tutorial 4 - split keyboard with I/O Expander | 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 | ## Overview of split keyboard with I/O Expander | ||||
The breadboard in this picture models a split keyboard. | 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 right matrix is connected to a microcontroller. | ||||
The left matrix is connected to a I/O expander. | The left matrix is connected to a I/O expander. | ||||
todo add capacitor | todo add capacitor | ||||
## Sketch for split keyboard with I/O Expander | ## 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. |