@@ -30,7 +30,7 @@ It runs on a breadboard and has rows, columns, and diodes just like the big keyb | |||
The sketch is small because the keybrd library takes care of the low-level details. | |||
The keybrd tutorial 1 shows how to make a breadboard keyboard. | |||
The [keybrd tutorials](tutorials) 2, 3, and 4 show how to create custom keybrd firmware. | |||
The remaining [keybrd tutorials](tutorials) show how to create custom keybrd firmware. | |||
Example complex keybrd sketch | |||
----------------------------- |
@@ -1,7 +1,6 @@ | |||
keybrd Library Developer's Guide | |||
================================ | |||
This guide contains diagrams, naming conventions, and a style guide, | |||
which are useful when designing new classes for the keybrd library and its extension libraries. | |||
This guide if for maintaining and writing new classes for the keybrd library and its extension libraries. | |||
The most common reason for new classes are: | |||
* Port classes for micro controller or I/O expanders | |||
* custom layer schemes for multi-layer keyboards | |||
@@ -101,7 +100,7 @@ Most derived-class names start with the base class name followed by "_" and a na | |||
``` | |||
Code | |||
| | |||
Code_Sc | |||
Code_LayerLock | |||
``` | |||
This convention leads to class names that convey information about the classes inheritance. | |||
@@ -116,7 +115,7 @@ Following the style guide makes it easier for the next programmer to understand | |||
* **ITEM_COUNT** is a constant number of items. | |||
* **itemCount** is a variable number of items. | |||
* Use header guards CLASS_NAME_H. | |||
* Prefix pointer name with "ptr" e.g. ptrRow = &row | |||
* Prefix pointer name with "ptr" e.g. ptrRow = &row; | |||
* Name arrays using the plural of element name e.g. Row* const = ptrsRows { &row0, &row1 }; | |||
* Pass arrays using array notation rather than pointer notation. Use | |||
``` | |||
@@ -129,8 +128,8 @@ Following the style guide makes it easier for the next programmer to understand | |||
* If class has any non-[POD](http://en.wikipedia.org/wiki/Plain_old_data_structure) data members, [do not inline constructors and destructors](http://www.chromium.org/developers/coding-style/cpp-dos-and-donts). | |||
* Document class interface in .h file, above the class declaration. | |||
* Code should be self-documenting. The only comments should be things that may need clarification. A simple function with a good name needs no comment. | |||
* Code is automatically formated before being pushed to the keybrd repository | |||
The options file doc/astyle_cpp specifies the format: | |||
* Code is automatically formated before being pushed to the keybrd repository. | |||
The [astyle_cpp](astyle_cpp) file specifies the format: | |||
* Allman style indentation | |||
* indent 4 spaces | |||
* replace tabs with spaces |
@@ -29,7 +29,11 @@ keybrd has been tested on the DodoHand keyboard with Teensy 2.0 and PCA9655E I/O | |||
Teensy LC is preferred over the older Teensy 2.0 for it's larger memory capacity and lower price. | |||
## Getting started with Teensy, Arduino IDE, and keybrd | |||
The Arduino IDE is used to edit and compile sketches, and then load them on to the microcontroller. | |||
The Arduino IDE is used to | |||
1. edit sketches | |||
2. compile sketches into HEX files | |||
3. load the HEX file onto the microcontroller | |||
Teensyduino is a software add-on for the Arduino IDE that allows it to compile to Teensy. | |||
@@ -39,7 +43,7 @@ Teensyduino is a software add-on for the Arduino IDE that allows it to compile t | |||
The following install and setup steps create an Arduino development environment for keybrd sketches. | |||
### Install Arduino IDE and Teensyduino | |||
Following install steps are modified from the [Teensyduino download page](https://www.pjrc.com/teensy/td_download.html) | |||
The following install steps are modified from the [Teensyduino download page](https://www.pjrc.com/teensy/td_download.html) | |||
For Linux: | |||
@@ -76,11 +80,11 @@ Down load keybrd-master.zip from the [Download ZIP](https://github.com/wolfv6/ke | |||
Unpack keybrd-master.zip into your Arduino directory on your system (default location is ~/Documents/Arduino/). | |||
### keybrd library and keybrd extension libraries | |||
### Install keybrd library and keybrd extension libraries | |||
<!-- todo update after testing Arduino library manager --> | |||
The keybrd library contains the foundation classes for creating a keyboard firmware. | |||
For emphasis, it is referred to as the "core keybrd library". | |||
For emphasis, it is sometimes referred to as the "core keybrd library". | |||
keybrd extension libraries contain additional classes that extend the keyboard library. | |||
keybrd extension library names are prefixed with "keybrd_". | |||
@@ -90,7 +94,7 @@ For example, the DodoHand keyboard requires that the core keybrd library and the | |||
* Arduino/libraries/keybrd/ | |||
* Arduino/libraries/keybrd_DH/ | |||
A keybrd extension library allows classes to be shared by multiple sketches without polluting the core keybrd library with classes that few other keyboards can use. | |||
A keybrd extension library allows classes to be shared by multiple sketches without polluting the core keybrd library with classes that other keyboards can not use. | |||
### Setup Arduino IDE for compiling keybrd firmware | |||
From the Arduino IDE tool bar, select: | |||
@@ -133,14 +137,14 @@ Extension libraries have their example sketches similarly located. | |||
The example sketch names use the following conventions. | |||
**keybrd_extension_feature_version.ino** | |||
**keybrd_feature_version.ino** | |||
where | |||
* **keybrd_extension** is the extension library name e.g. keybrd_DH | |||
* **feature** is distinguishing feature of keybrd sketch e.g. breadboard, LED, sound, Dvorak | |||
* **version** is version number | |||
* **keybrd** is the library name e.g. keybrd, keybrd_DH | |||
* **feature** is a distinguishing feature of the keybrd sketch e.g. breadboard, LED, sound, Dvorak | |||
* **version** is the sketch's version number | |||
The first two fields are mandatory, the remaining fields are optional. | |||
The first field are mandatory, the remaining fields are optional. | |||
## Diode orientation | |||
The physical martix rows and columns on a keyboard can be in any direction or shape. | |||
@@ -207,7 +211,7 @@ The [Neo layout](http://neo-layout.org/index_en.html) has 6 layers. | |||
**Layer scheme** - is a system for changing layers while typing. | |||
A single-layer scheme does not change layers. | |||
**Layout** - is a grid of keys. Key caps are often labeled to show a keyboard's layout. | |||
**Layout** - is the placement of keys. Key caps are often labeled to show a keyboard's layout. | |||
**[Matrix](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/)** - is a collection of switches connected by rows and columns. | |||
@@ -53,7 +53,7 @@ The CODES section instantiates six codes, one for each item in the layout: | |||
*/ | |||
// ---------------- LAYER CODE ----------------- | |||
/* | |||
enum assings ID numbers to the layers. | |||
enum assings Id numbers to the layers. | |||
*/ | |||
enum layers { NORMAL, FN }; | |||
/* | |||
@@ -61,7 +61,7 @@ stateLayer keeps track of the active layer. The default layer number is 0. | |||
*/ | |||
StateLayers stateLayer; | |||
/* | |||
The Code_LayerHold constructor parameter specifies a layer ID number and a StateLayer. | |||
The Code_LayerHold constructor parameter specifies a layer Id number and a StateLayer. | |||
When l_fn is pressed, it tells stateLayer to change the active layer to 1. | |||
When l_fn is released, it tells stateLayer to restore the normal layer. | |||
*/ | |||
@@ -90,8 +90,8 @@ Key_LayeredKeysArray constructor parameters are: | |||
one array of Code pointers | |||
Key_LayeredKeysArray objects are multi-layered - one Code object per layer. | |||
Layer ID numbers are array indexes for the Key_LayeredKeysArray. | |||
Defining layer ID numbers with enum insures that they are a series of intergers starting at 0. | |||
Layer Id numbers are used as array indexes for the Key_LayeredKeysArray. | |||
Defining layer Id numbers with enum insures that they are a series of intergers starting at 0. | |||
The Key object names in this sketch start with a "k_" followed by matrix-row-column coordinates. | |||
*/ |
@@ -63,7 +63,7 @@ const uint8_t COL_PORT_L_COUNT = sizeof(ptrsColPorts_L)/sizeof(*ptrsColPorts_L); | |||
/* | |||
The right matrix is scanned by an I/O expander. | |||
The micro-controller and I/O expander use address 0x18 to communicate with each other over I2C. | |||
I/O expander I2C address is configured by hardware pins. | |||
ADDR is a static variable of class IOExpanderPort. | |||
*/ | |||
const uint8_t IOExpanderPort::ADDR = 0x18; | |||
@@ -73,7 +73,6 @@ The I/O expander has two ports. Each port has eight pins. | |||
One port is connected to the matrix's rows. The other port is connected to the matrix's columns. | |||
The IOExpanderPort constructor parameters specify the port number and initial output value. | |||
I/O Expander and AVR have similar constructor parameters for RowPort and ColPort. | |||
port1_R is port 1 and has an initial output value of 0. | |||
rowPort1_R uses port1_R. |
@@ -21,6 +21,8 @@ The tutorials assume the reader: | |||
> Some of the pictures do not match the sketches, they will be updated after changing to Teensy LC | |||
> Schematic diagrams are missing from tutorials 2 and 4, they will be added 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. |
@@ -62,10 +62,11 @@ Breadboard keyboard assembly instructions: | |||
* follow pin connections table (below) and consult pinout diagram in | |||
[Teensy2_pinout.txt](../doc/Teensy2_pinout.txt) | |||
<!-- todo replace this table with a schematic | |||
This schematic was written by consulting the micro-controller's datasheet and using the ?? tool. | |||
todo add a schematic | |||
this table might not match the sketches | |||
<!-- This schematic was written by consulting the micro-controller's datasheet and using the ?? tool. | |||
this table might not match the sketches, replace with a schematic | |||
**Teensy 2.0 pin connections table** | |||
@@ -1,7 +1,6 @@ | |||
Tutorial 2 - single-layer keyboard | |||
======================================= | |||
[keybrd_2_single-layer_annotated.ino](keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino) explains how a keybrd sketch works. | |||
You can view the class definitions in the [keybrd library](../src/). | |||
After reading the sketch you will be able to modify it to suite your own single-layer keyboard design. |
@@ -17,19 +17,19 @@ When you finish this tutorial you will be able to be able to modify a multi-laye | |||
## Pseudo code for simple layer scheme | |||
The following pseudo code has just enough detail to show how layer schemes work. | |||
**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. | |||
**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& refState | |||
press() { refState.setLayer(layer) } | |||
StateLayer& refStateLayer | |||
press() { refStateLayer.setLayer(layer) } | |||
} | |||
``` | |||
A **StateLayer** object's activeLayer is always up to date. | |||
A **StateLayer**'s activeLayer is always up to date. | |||
``` | |||
class StateLayer | |||
{ | |||
@@ -39,14 +39,15 @@ class StateLayer | |||
} | |||
``` | |||
**Layered** objects contain one scancode for each layer. | |||
**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 per layer | |||
StateLayer& refState | |||
press() { layer = refState.getLayer() | |||
Key** ptrsKeys //array of Key pointers, one Key pointer per layer | |||
StateLayer& refStateLayer | |||
press() { layer = refStateLayer.getActiveLayer() | |||
ptrsKeys[layer]->press() } | |||
} | |||
``` | |||
@@ -99,6 +100,8 @@ Example single-layer Code classes include: | |||
* Code_LayerHold | |||
* Code_LayerLock | |||
<!-- todo --> | |||
(Future version of keybrd library may change all Code classes to Key classes.) | |||
## A simple multi-layer keybrd sketch |
@@ -4,7 +4,7 @@ Some mulit-layer keyboards have a symbols layer that writes symbols without usin | |||
~ ! @ # $ % ^ & * () _ {} | < > : ? | |||
The keybrd library does this by automatically sending the MODIFIERKEY_SHIFT scancode. | |||
The keybrd library does this by automatically sending a MODIFIERKEY_SHIFT scancode. | |||
The [keybrd_3_autoShift_annotated.ino](keybrd_3_autoShift_annotated/keybrd_3_autoShift_annotated.ino) sketch explains the AutoShift feature. | |||
After reading the sketch you too will be able to automatically shifted characters. |
@@ -20,35 +20,40 @@ The microcontroller and I/O expander are connected by 4 jumper wires: | |||
* Serial CLock signal (SCL) | |||
* Serial DAta signal (SDA) | |||
A capacitor on the power pin smooths power to the I/O expander. | |||
A decoupling capacitor on the power pin dampens noise coming in through the power wire. | |||
The microcontroller and I/O expander communicate via [I2C](http://en.wikipedia.org/wiki/I%C2%B2C) bus, which consists of two signals: SCL and SDA. | |||
Two resistors pull-up voltage on the SCL and SDA. | |||
I/O expander I2C address is configured by three hardware pins (AD0, AD1, AD2). | |||
I/O expander I2C address is configured by hardware pins. | |||
The MCP23018 with all address pins grounded has an I2C address of ?? todo. | |||
The I/O expander has two ports. Each port has eight pins. | |||
One port is connected to the matrix's rows. The other port is connected to the matrix's columns. | |||
## Building a split keyboard with I/O Expander | |||
The split keyboard is built on the basic breadboard keyboard described in [tutorial_1_breadboard_keyboard.md](tutorial_1_breadboard_keyboard.md) | |||
We will build a split keyboard adding parts to the basic breadboard keyboard described in [tutorial_1_breadboard_keyboard.md](tutorial_1_breadboard_keyboard.md) | |||
<!-- todo add schematic with a capacitor to IOE power | |||
todo add schematic | |||
<!-- schematic with IOE power decoupling capacitor | |||
This schematic was written by consulting the I/O expander's datasheet and using the ?? tool. --> | |||
Continuing from the basic breadboard keyboard instructions: | |||
<!-- At some point in the future, Markdown may support starting ordered lists at an arbitrary number. --> | |||
4. Insert the I/O expander | |||
5. Install I/O expander power | |||
* ground | |||
* power | |||
* capacitor | |||
* ground | |||
* power | |||
* capacitor | |||
6. Install I2C bus | |||
* SCL | |||
* SDA | |||
* pull-up resistors on SCL and SDA | |||
* SCL | |||
* SDA | |||
* pull-up resistors on SCL and SDA | |||
7. configure I2C address | |||
@@ -3,7 +3,7 @@ Tutorial 7a - using someone else's keybrd extension library | |||
The keybrd library contains the foundation classes for creating a keyboard firmware. | |||
keybrd extension libraries extend the core keyboard library. | |||
keybrd extension library names are prefixed by "keybrd_" and are listed in: | |||
keybrd extension library names are prefixed by "keybrd_" and are listed in: todo keybrd extension libraries are not listed yet | |||
* [Arduino Playground](http://playground.arduino.cc/Main/InterfacingWithHardware#keyb) > find "keybrd" | |||
* Arduino Library-Manager (Arduino IDE > Sketch > Include Library > Manage Libraries > Filter your search: keybrd) | |||
@@ -2,6 +2,7 @@ Tutorial 7b - creating and publishing your own keybrd extension library | |||
======================================================================= | |||
Publishing and listing your keybrd extension library allows others to find and install your library. | |||
The keybrd extension library name should start with "keybrd_" so that it is easy for people to find. | |||
The directory structure of the library depends on where it will be listed. | |||
## Publishing anywhere with listing on Arduino Playground LibraryList |