improve tutorials
This commit is contained in:
wolfv6
parent
6978b038aa
commit
7293bee03c
@ -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
|
||||
|
||||
Reference in New Issue
Block a user