di0ib
/
keybrd
Watch 1
Star 0
Fork 0
Code Releases 7 Activity
Browse Source

document

tags/v0.5.0
wolfv6 8 years ago
parent
da0d5f22ac
commit
4214c51bae
9 changed files with 101 additions and 73 deletions
Split View Show Diff Stats
  1. 1
    1
      doc/keybrd_library_developer_guide.md
  2. 5
    6
      doc/keybrd_library_user_guide.md
  3. BIN
      tutorials/images/breadboard_keyboard_2x5_labeled.jpg
  4. 12
    11
      tutorials/tutorial_0_introduction.md
  5. 15
    19
      tutorials/tutorial_1_breadboard_keyboard.md
  6. 4
    4
      tutorials/tutorial_2_single-layer_keyboard.md
  7. 55
    22
      tutorials/tutorial_3a_multi-layer_keyboard.md
  8. 5
    4
      tutorials/tutorial_3b_autoShift.md
  9. 4
    6
      tutorials/tutorial_4_split_keyboard_with_IOE.md

+ 1
- 1
doc/keybrd_library_developer_guide.md View File

@@ -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.

+ 5
- 6
doc/keybrd_library_user_guide.md View File

@@ -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.

BIN
tutorials/images/breadboard_keyboard_2x5_labeled.jpg View File


+ 12
- 11
tutorials/tutorial_0_introduction.md View File

@@ -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.
<!-- 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.
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")

+ 15
- 19
tutorials/tutorial_1_breadboard_keyboard.md View File

@@ -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")

+ 4
- 4
tutorials/tutorial_2_single-layer_keyboard.md View File

@@ -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.

+ 55
- 22
tutorials/tutorial_3a_multi-layer_keyboard.md View File

@@ -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/).
**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_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.

+ 5
- 4
tutorials/tutorial_3b_autoShift.md View File

@@ -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

+ 4
- 6
tutorials/tutorial_4_split_keyboard_with_IOE.md View File

@@ -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.