di0ib/keybrd
Archived
1
0
Fork 0
Code Releases Activity

document

Browse Source
This commit is contained in:
wolfv6 2016-05-09 13:41:29 -06:00
parent 98b6060e7c
commit c6b7cd1a16
7 changed files with 75 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -23,22 +23,28 @@ The keybrd library has been tested on the Teensy 2.0 microcontroller, MCP23018 I
Example minimal keybrd sketch 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 -->
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 a 4-key keyboard. 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. 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 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 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 Example complex keybrd sketch
----------------------------- -----------------------------
The DodoHand keybrd emulates the DataHand keyboard. The keybrd_DH emulates the DataHand keyboard.
It has 72 keys, 4 layers, 2 sub-layers, 2 matrices, and is loaded with features. It has 72 keys, 4 layers, a 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 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 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. Please ask a questions in [issues](https://github.com/wolfv6/Keybrd/issues) if something is not clear.

8
doc/CHANGELOG.md
View File

@ -2,20 +2,20 @@
All notable changes to the keybrd project will be documented in this file. 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/). 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. keybrd 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 1.0.0 will be released when the public API is stable.
## [Unreleased][unreleased] ## [Unreleased][unreleased]
## [0.3.0] - 2016-05-09 ## [0.3.0] - 2016-05-09
### Changed ### Changed
* Restructured the project directory to conform to Arduino library manager specifications * 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 * Moved sketches to examples directory
* Replaced Key_Layered dependency on LayerManager with StateLayers class * Replaced Key_Layered dependency on LayerManager with StateLayers class
### Added ### Added
* tutorials * Tutorials
## [0.2.0] - 2016-02-25 ## [0.2.0] - 2016-02-25
### Added ### Added

8
doc/Teensy2_microcontroller.txt → doc/Teensy2_pinout.txt
View File

@ -1,4 +1,3 @@
Teensy 2.0 Pinout Diagram Teensy 2.0 Pinout Diagram
------------------------- -------------------------
USB is on top in the diagram. USB is on top in the diagram.
@ -18,7 +17,7 @@ SDA D1 6 15 B6
C7 10 11 D6 Do not use pin D6 for scanning keyboard matrix 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 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 PIN# port+bit function
23 D5 23 D5
VCC 5v power VCC 5v power
@ -26,12 +25,13 @@ PIN# port+bit function
RST reset RST reset
22 D4 22 D4
MID (below USB, left to right) MIDDLE (below USB, pins from left to right)
PIN# port+bit function PIN# port+bit function
24 E6 24 E6
Ref 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. Identifying and naming ports is useful when instantiating RowPorts and ColPorts.
Keybrd library was tested on Teensy 2.0 Keybrd library was tested on Teensy 2.0

31
doc/keybrd_library_developer_guide.md
View File

@ -1,21 +1,17 @@
keybrd Library Developer's Guide keybrd Library Developer's Guide
================================ ================================
This guide contains diagrams, naming conventions, and a style 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 will help you design custom classes to interface with the keybrd library. The most common reason for new classes are:
The most common need for custom classes are:
* Port classes for micro controller or I/O expanders * Port classes for micro controller or I/O expanders
* custom layer schemes for multi-layer keyboards * custom layer schemes for multi-layer keyboards
* experimental features * experimental features
## Who this guide is for ## 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. 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. Some classes use bit manipulation.
## Custom keybrd classes
Please refer to tutorial_7a_using_someone_else's_keybrd_extension_library.md
## Class diagrams ## Class diagrams
Keybrd library class inheritance diagram 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. 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 ## Style guide
Following the style guide makes it easier for the next programmer to understand your code. 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. * For member names, use camelCase starting with lowercase letter.
* Use constants rather than macros, except for header guards. * Use constants rather than macros, except for header guards.
* For constant names that could be macros, use ALL_CAPS_AND_UNDERSCORE. * 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. * **itemCount** is a variable number of items.
* Use header guards CLASS_NAME_H. * 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 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 * Pass arrays using array notation rather than pointer notation. Use
``` ```
void printArray(char[] array); void printArray(char[] array);
not not
void printArray( char* array); void printArray( char* array);
``` ```
* In constructor's initialization list, use same names for fields and constructor parameters * In constructor's initialization list, use same names for fields and constructor parameters.
* Do not use new or malloc (to make memory leaks impossible). * 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). * 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. * Document class interface in .h file, above the class declaration.
* Code should be self-documenting. * Code should be self-documenting.
The only comments should be things that may need clarification. The only comments should be things that may need clarification.
A simple function with a good name needs no comment. 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 * Code is automatically formated before being pushed to the keybrd repository
The options file doc/astyle_cpp specifies the format: The options file doc/astyle_cpp specifies the format:
* Allman style indentation * Allman style indentation
@ -148,13 +144,6 @@ Following the style guide makes it easier for the next programmer to understand
* replace tabs with spaces * replace tabs with spaces
* maximum code width of 100 columns * 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 ## 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.

71
doc/keybrd_library_user_guide.md
View File

@ -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. 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. 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. 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. [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. 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. [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. [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 ### 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: For Linux:
@ -64,39 +64,25 @@ For Linux:
4. Launch Arduino IDE from /opt/arduino-1.x.x/arduino 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 ### 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 link from tutorial 7 ## Publishing
https://www.arduino.cc/en/Guide/Libraries https://www.arduino.cc/en/Guide/Libraries
> Installing Additional Arduino Libraries > Installing Additional Arduino Libraries
> Using the Library Manager > Using the Library Manager
!-->
Down load keybrd-master.zip from the [Download ZIP](https://github.com/wolfv6/keybrd) button. 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/). Unpack keybrd-master.zip into your Arduino directory on your system (default location is ~/Documents/Arduino/).
### keybrd library and keybrd extension libraries ### 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. 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 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/. 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: 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. 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 ### Compile and load keybrd sketch
If it isn't already plugged in, plug the USB cable into the computer and controller. 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: 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. 2. Prepare for loosing control of keyboard and mouse.
3. On the Arduino IDE, click the Upload button. 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
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. Extension libraries have their example sketches similarly located.
The example sketch names use the following conventions. The example sketch names use the following conventions.
keybrd_extension_feature_version.ino **keybrd_extension_feature_version.ino**
where where
* **keybrd** indicates a keybrd sketch * **keybrd_extension** is the extension library name e.g. keybrd_DH
* **extension** is the extension library name e.g. DH, DualMode
* **feature** is distinguishing feature of keybrd sketch e.g. breadboard, LED, sound, Dvorak * **feature** is distinguishing feature of keybrd sketch e.g. breadboard, LED, sound, Dvorak
* **version** is version number * **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. 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](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. Diagram is of typical through-the-hole diode in same alignment as diode symbol.
Cross bar and band depict the cathode. 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: 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 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 * If compile error: 'KEY_A' was not declared in this scope
From the Arduino IDE tool bar, select: Tools > USB Type > Keyboard + Mouse + Joystick From the Arduino IDE tool bar, select: Tools > USB Type > Keyboard + Mouse + Joystick
Sketch items to check: Sketch items to check:
@ -187,6 +186,9 @@ Hardware items to check:
* Diode orientation * Diode orientation
* 5 volts across power and ground * 5 volts across power and ground
* To validate keyboard hardware, modify the simple single-layer keybrd sketch from the tutorial. * 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 ## Keybrd nomenclature
**[scancode](http://en.wikipedia.org/wiki/Scancode)** - **[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. **[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. Keyboard switches are made of moving contacts.
When the contacts close, they bounce apart one or more times before making steady contact. 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. 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 **Sketch** - is the name that Arduino uses for a program

8
doc/planned_features.md
View File

@ -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 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 Change tutorial sketches from teensy 2.0 and PCA9655E-D IOE to Teensy LC and MCP23018 IOE
Add more tutorials: Add more tutorials:
tutorial_5_LEDs.md * tutorial_5_LEDs.md
tutorial_6_mapping_matrix_to_layout.md * tutorial_6_mapping_matrix_to_layout.md
tutorial_9_active_high.md * tutorial_9_active_high.md

2
examples/keybrd_mapping_bb/keybrd_mapping_bb.ino
View File

@ -1,7 +1,7 @@
/* keybrd_mapping_bb.ino /* keybrd_mapping_bb.ino
Runs on DodoHand hardware or breadboard, using the left matrix, first two rows and columns. 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** | | Layout | **0** | **1** |
|:------:|-------|-------| |:------:|-------|-------|