@@ -23,22 +23,28 @@ The keybrd library has been tested on the Teensy 2.0 microcontroller, MCP23018 I | |||
Example minimal keybrd sketch | |||
----------------------------- | |||
Here is a [minimal keybrd sketch](keybrd_single-layer_2/keybrd_single-layer_2.ino). | |||
todo after teensy LC bb, copy and remove annotations from keybrd_single-layer_2_annotated.ino | |||
The sketch has about 50 lines of code and runs a 4-key keyboard. | |||
<!-- todo after teensy LC bb, copy and remove annotations from keybrd_single-layer_2_annotated.ino --> | |||
Here is a [minimal keybrd sketch](blob/master/tutorials/keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino). | |||
The sketch has about 50 lines of code and runs on a 4-key keyboard. | |||
It runs on a breadboard with rows, columns, and diodes just like the big keyboards. | |||
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 2 and 3 show how to create custom keybrd firmware. | |||
The keybrd tutorials 2, 3, and 4 show how to create custom keybrd firmware. | |||
Example complex keybrd sketch | |||
----------------------------- | |||
The DodoHand keybrd emulates the DataHand keyboard. | |||
It has 72 keys, 4 layers, 2 sub-layers, 2 matrices, and is loaded with features. | |||
The [DodoHand sketch](todo /sketch.cpp), and its instantiation files, contain about 800 lines of code. | |||
The keybrd_DH emulates the DataHand keyboard. | |||
It has 72 keys, 4 layers, a sub-layers, 2 matrices, and is loaded with features. | |||
The keybrd_DH and its instantiation files, contain about 800 lines of code. | |||
[mainSketch.ino](../keybrd_DH/blob/master/examples/keybrd_DH/mainSketch.cpp) | |||
[instantiations_ports.h](../keybrd_DH/tree/master/src/instantiations_ports.h) | |||
[instantiations_LEDs.h](../keybrd_DH/tree/master/src/instantiations_LEDs.h) | |||
[instantiations_codes.h](../keybrd_DH/tree/master/src/instantiations_codes.h) | |||
[instantiations_matrix.h](../keybrd_DH/tree/master/src/instantiations_matrix.h) | |||
Support | |||
------- | |||
The [doc](doc) folder contains guides and tutorials. | |||
[Guides](tree/master/doc) and [tutorials](/tree/master/tutorials) are provided. | |||
Please ask a questions in [issues](https://github.com/wolfv6/Keybrd/issues) if something is not clear. |
@@ -2,20 +2,20 @@ | |||
All notable changes to the keybrd project will be documented in this file. | |||
This project adheres to [Semantic Versioning 2.0.0](http://semver.org/). | |||
Version 0.x.x is for initial development. The public API should not be considered stable. | |||
Version 1.0.0 will be released when the public API is stable. | |||
keybrd version 0.x.x is for initial development. The public API should not be considered stable. | |||
keybrd version 1.0.0 will be released when the public API is stable. | |||
## [Unreleased][unreleased] | |||
## [0.3.0] - 2016-05-09 | |||
### Changed | |||
* Restructured the project directory to conform to Arduino library manager specifications | |||
* Moved keybrd_DH library extension (DodoHand) to its own repository | |||
* Moved keybrd_DH library extension (for DodoHand) to its own repository | |||
* Moved sketches to examples directory | |||
* Replaced Key_Layered dependency on LayerManager with StateLayers class | |||
### Added | |||
* tutorials | |||
* Tutorials | |||
## [0.2.0] - 2016-02-25 | |||
### Added |
@@ -1,6 +1,5 @@ | |||
Teensy 2.0 Pinout Diagram | |||
------------------------- | |||
------------------------- | |||
USB is on top in the diagram. | |||
Inner columns are pin numbers, outer columns are port+bit pin name. | |||
``` | |||
@@ -18,7 +17,7 @@ SDA D1 6 15 B6 | |||
C7 10 11 D6 Do not use pin D6 for scanning keyboard matrix | |||
LED on pin D6 pulls voltage down and will always return low | |||
BOTTOM (USB on top, left to right) | |||
BOTTOM EDGE (USB on top, pins from left to right) | |||
PIN# port+bit function | |||
23 D5 | |||
VCC 5v power | |||
@@ -26,12 +25,13 @@ PIN# port+bit function | |||
RST reset | |||
22 D4 | |||
MID (below USB, left to right) | |||
MIDDLE (below USB, pins from left to right) | |||
PIN# port+bit function | |||
24 E6 | |||
Ref | |||
``` | |||
Teensy pin out with port names is on http://www.pjrc.com/teensy/td_digital.html | |||
Teensy 2.0 pin assignment on https://www.pjrc.com/teensy/pinout.html | |||
Teensy 2.0 pinout with pin numbers on http://www.pjrc.com/teensy/td_digital.html | |||
Identifying and naming ports is useful when instantiating RowPorts and ColPorts. | |||
Keybrd library was tested on Teensy 2.0 |
@@ -1,21 +1,17 @@ | |||
keybrd Library Developer's Guide | |||
================================ | |||
This guide contains diagrams, naming conventions, and a style guide. | |||
This guide will help you design custom classes to interface with the keybrd library. | |||
The most common need for custom classes are: | |||
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. | |||
The most common reason for new classes are: | |||
* Port classes for micro controller or I/O expanders | |||
* custom layer schemes for multi-layer keyboards | |||
* experimental features | |||
## Who this guide is for | |||
This guide is for the maintainers, developers, and anyone that wants to extend the keybrd library. | |||
This guide is for the maintainers and developers of the keybrd library and it's extensions. | |||
It is assumed the reader is familiar with C++ language including pointers, objects, classes, static class variables, composition, inheritance, polymorphism, and enum. | |||
Some classes use bit manipulation. | |||
## Custom keybrd classes | |||
Please refer to tutorial_7a_using_someone_else's_keybrd_extension_library.md | |||
## Class diagrams | |||
Keybrd library class inheritance diagram | |||
@@ -114,11 +110,11 @@ Most derived-class names start with the base class name followed by "_" and a na | |||
``` | |||
This convention leads to class names that convey information about the classes inheritance. | |||
Underscore delineates base class name and sub name. Capital letters delineate words. | |||
Underscore delineates base class name and sub-class name. Capital letters delineate words. | |||
## Style guide | |||
Following the style guide makes it easier for the next programmer to understand your code. | |||
* For class names, see above section "Class Naming Conventions" | |||
* For class names, see above section "Class naming conventions" | |||
* For member names, use camelCase starting with lowercase letter. | |||
* Use constants rather than macros, except for header guards. | |||
* For constant names that could be macros, use ALL_CAPS_AND_UNDERSCORE. | |||
@@ -126,21 +122,21 @@ Following the style guide makes it easier for the next programmer to understand | |||
* **itemCount** is a variable number of items. | |||
* Use header guards CLASS_NAME_H. | |||
* Prefix pointer name with "ptr" e.g. ptrRow = &row | |||
* Name arrays using the plural of elements e.g. Row* const = ptrsRows { &row0, &row1 }; | |||
* 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 | |||
``` | |||
void printArray(char[] array); | |||
not | |||
void printArray( char* array); | |||
``` | |||
* In constructor's initialization list, use same names for fields and constructor parameters | |||
* Do not use new or malloc (to make memory leaks impossible). | |||
* In constructor's initialization list, use same names for fields and constructor parameters. | |||
* Do not use new or malloc (making memory leaks impossible). | |||
* 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. | |||
http://stackoverflow.com/questions/2198241/best-practice-for-c-function-commenting | |||
<-- http://stackoverflow.com/questions/2198241/best-practice-for-c-function-commenting !--> | |||
* Code is automatically formated before being pushed to the keybrd repository | |||
The options file doc/astyle_cpp specifies the format: | |||
* Allman style indentation | |||
@@ -148,13 +144,6 @@ Following the style guide makes it easier for the next programmer to understand | |||
* replace tabs with spaces | |||
* maximum code width of 100 columns | |||
## keybrd sketches | |||
keybrd sketch naming convention is described in the keybrd_library_user_guide "Sample keybrd sketches". | |||
The head of sketch should contain latest version of keybrd lib that sketch was test on: | |||
tested on keybrd v1.1 by wolfv6 | |||
## 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. |
@@ -15,7 +15,7 @@ Its easy for novice programmers to setup and learn. | |||
This guide is for anyone who wants to use the keybrd library to develop custom-keyboard firmware. | |||
A reader with programming experience, but no C++ experience, would understand the tutorials well enough to modify existing keybrd sketches. | |||
An experienced C++ programmer would be able to write original sketches and classes from scratch. | |||
An experienced C++ programmer would be able to write original sketches and classes. | |||
The library is written in the C++ language and uses pointers, objects, classes, static class variables, composition, inheritance, and enum. | |||
@@ -24,7 +24,7 @@ The keybrd library works with Teensy and Arduino boards. | |||
[Teensy LC](https://www.pjrc.com/teensy/teensyLC.html) has 8K RAM, which is more than enough memory for any keyboard. | |||
keybrd has been tested on the DodoHand keyboard with Teensy 2.0 and PCA9655E I/O expander using the DH_2565 sketch. | |||
keybrd has been tested on the DodoHand keyboard with Teensy 2.0 and PCA9655E I/O expander using the keybrd_DH sketch. | |||
Teensy LC is preferred over the older Teensy 2.0 for it's larger memory capacity and lower price. | |||
@@ -36,10 +36,10 @@ Teensyduino is a software add-on for the Arduino IDE that allows it to compile t | |||
[Teensy Getting Started](http://www.pjrc.com/teensy/first_use.html) is a good way to familiarize yourself with Teensy. | |||
[Arduino Development Environment](http://arduino.cc/en/guide/Environment) is a brief description. | |||
The following steps create an Arduino development environment for keybrd sketches. | |||
The following install and setup steps create an Arduino development environment for keybrd sketches. | |||
### Install Arduino IDE and Teensyduino | |||
Follow the install steps are modified from the [Teensyduino download page](https://www.pjrc.com/teensy/td_download.html) | |||
Following install steps are modified from the [Teensyduino download page](https://www.pjrc.com/teensy/td_download.html) | |||
For Linux: | |||
@@ -64,39 +64,25 @@ For Linux: | |||
4. Launch Arduino IDE from /opt/arduino-1.x.x/arduino | |||
### Setup Arduino IDE for compiling keybrd firmware | |||
From the Arduino IDE tool bar, select: | |||
* Tools > Board > Teensy LC (or whatever board you are using) | |||
* Tools > USB Type > Keyboard + Mouse + Joystick | |||
optional: | |||
* File > Preferences > Compiler warnings: All | |||
* File > Preferences > check: Use external editor | |||
A Sketchbook is a folder that the Arduino IDE uses to store sketches and libraries. | |||
The default location for [Arduino libraries](https://www.arduino.cc/en/Guide/Libraries) is in | |||
~/Documents/Arduino/libraries/ | |||
### Download and unpack keybrd-master.zip into your Arduino directory | |||
todo update after testing Arduino library manager | |||
<-- todo update after testing Arduino library manager | |||
link from tutorial 7 ## Publishing | |||
https://www.arduino.cc/en/Guide/Libraries | |||
> Installing Additional Arduino Libraries | |||
> Using the Library Manager | |||
!--> | |||
Down load keybrd-master.zip from the [Download ZIP](https://github.com/wolfv6/keybrd) button. | |||
Unpack keybrd-master.zip into your Arduino directory on your system (default location is ~/Documents/Arduino/). | |||
### keybrd library and keybrd extension libraries | |||
todo update after testing Arduino library manager | |||
<-- todo update after testing Arduino library manager !--> | |||
The keybrd library contains the foundation classes for creating a keyboard firmware. | |||
For emphasis, it is sometimes referred to as the "core keybrd library". | |||
For emphasis, it is referred to as the "core keybrd library". | |||
keybrd extension libraries contain additional classes that extend the keyboard library. | |||
keybrd extension library names are prefixed by "keybrd_". | |||
keybrd extension library names are prefixed with "keybrd_". | |||
The Arduino IDE looks for libraries in Arduino/libraries/. | |||
For example, the DodoHand keyboard requires that the core keybrd library and the keybrd_DH extension library be installed: | |||
@@ -105,6 +91,20 @@ For example, the DodoHand keyboard requires that the core keybrd library and the | |||
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. | |||
### Setup Arduino IDE for compiling keybrd firmware | |||
From the Arduino IDE tool bar, select: | |||
* Tools > Board > Teensy LC (or whatever board you are using) | |||
* Tools > USB Type > Keyboard + Mouse + Joystick | |||
These are optional: | |||
* File > Preferences > Compiler warnings: All | |||
* File > Preferences > check: Use external editor | |||
A Sketchbook is a folder that the Arduino IDE uses to store sketches and libraries. | |||
The default location for [Arduino libraries](https://www.arduino.cc/en/Guide/Libraries) is in | |||
~/Documents/Arduino/libraries/ | |||
### Compile and load keybrd sketch | |||
If it isn't already plugged in, plug the USB cable into the computer and controller. | |||
@@ -121,22 +121,22 @@ If it isn't already plugged in, plug the USB cable into the computer and control | |||
Compile and load workflow: | |||
1. Open a keybrd sketch in the Arduino IDE (for example Arduino/keybrds/firmware/keybrd_single-layer/keybrd_single-layer_1221_bb/keybrd_single-layer_1221_bb.ino) | |||
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 tiny pushbutton on the Teensy circuit board. | |||
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 keybrd_proj/keybrd/examples/ directory. | |||
Example keybrd sketches are in the [examples](../examples/) directory. | |||
Extension libraries have their example sketches similarly located. | |||
The example sketch names use the following conventions. | |||
keybrd_extension_feature_version.ino | |||
**keybrd_extension_feature_version.ino** | |||
where | |||
* **keybrd** indicates a keybrd sketch | |||
* **extension** is the extension library name e.g. DH, DualMode | |||
* **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 | |||
@@ -146,7 +146,7 @@ The first two fields are mandatory, the remaining fields are optional. | |||
The physical martix rows and columns on a keyboard can be in any direction or shape. | |||
[diode](https://en.wikipedia.org/wiki/Diode) orientation is specified in [Matrix.h](todo) | |||
![Diode](images/120px-Diode_pinout_en_fr.svg.png) | |||
![Diode](../tutorials/images/120px-Diode_pinout_en_fr.svg.png) | |||
Diagram is of typical through-the-hole diode in same alignment as diode symbol. | |||
Cross bar and band depict the cathode. | |||
@@ -156,9 +156,8 @@ The following is a listing of items to check when a new keybrd sketch or keyboar | |||
Development-environment items to check: | |||
* If the keyboard has an I/O expander, power cycle (replug the USB) after loading the HEX file. | |||
* If the keybrd extension library directory name or location was changed, see section | |||
[Populate Arduino/libraries with keybrd library symlinks](todo link) | |||
* If compile error: 'KEY_A' was not declared in this scope | |||
From the Arduino IDE tool bar, select: Tools > USB Type > Keyboard + Mouse + Joystick | |||
Sketch items to check: | |||
@@ -187,6 +186,9 @@ Hardware items to check: | |||
* Diode orientation | |||
* 5 volts across power and ground | |||
* To validate keyboard hardware, modify the simple single-layer keybrd sketch from the tutorial. | |||
<!-- todo after teensy LC bb, linke to minimal keybrd sketch | |||
[minimal keybrd sketch](blob/master/tutorials/keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino). | |||
--> | |||
## Keybrd nomenclature | |||
**[scancode](http://en.wikipedia.org/wiki/Scancode)** - | |||
@@ -208,12 +210,13 @@ The [Neo layout](http://neo-layout.org/index_en.html) has 6 layers. | |||
**[Matrix](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/)** - is a collection of switches connected by rows and columns. | |||
**[bounce](http://en.wikipedia.org/wiki/Switch#Contact_bounce)** - | |||
**[Bounce](http://en.wikipedia.org/wiki/Switch#Contact_bounce)** - | |||
Keyboard switches are made of moving contacts. | |||
When the contacts close, they bounce apart one or more times before making steady contact. | |||
A debouncer removes the bounce so that a key press is sent to the computer only once. | |||
**[Modifier key](http://en.wikipedia.org/wiki/Modifier_key)** - is a special key on a computer keyboard that temporarily modifies the normal action of another key when pressed together. By themselves, modifier keys usually do nothing; that is, pressing any of the Shift, Alt, or Ctrl keys alone does not trigger any action from the computer. | |||
**[Modifier key](http://en.wikipedia.org/wiki/Modifier_key)** - is a special key on a computer keyboard that temporarily modifies the normal action of another key when pressed together e.g. Shift, Alt, or Ctrl. | |||
By themselves, modifier keys usually do nothing; that is, pressing any of the Shift, Alt, or Ctrl keys alone does not trigger any action from the computer. | |||
**Sketch** - is the name that Arduino uses for a program | |||
@@ -1,4 +1,4 @@ | |||
PLANNED FEATURES is a view of where the keybrd project is headed. | |||
planned_features is a view of where the keybrd project is headed. | |||
Top priority | |||
============ | |||
@@ -17,6 +17,6 @@ Add matrix-to-layout transform array (to decouple matrix from layout) | |||
Change tutorial sketches from teensy 2.0 and PCA9655E-D IOE to Teensy LC and MCP23018 IOE | |||
Add more tutorials: | |||
tutorial_5_LEDs.md | |||
tutorial_6_mapping_matrix_to_layout.md | |||
tutorial_9_active_high.md | |||
* tutorial_5_LEDs.md | |||
* tutorial_6_mapping_matrix_to_layout.md | |||
* tutorial_9_active_high.md |
@@ -1,7 +1,7 @@ | |||
/* keybrd_mapping_bb.ino | |||
Runs on DodoHand hardware or breadboard, using the left matrix, first two rows and columns. | |||
Uses the same variable naming convention as DH_2565. | |||
Uses the same variable naming convention as keybrd_DH. | |||
| Layout | **0** | **1** | | |||
|:------:|-------|-------| |