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

document

tags/v0.5.0
wolfv6 8 years ago
parent
98b6060e7c
commit
c6b7cd1a16
7 changed files with 75 additions and 77 deletions
Split View Show Diff Stats
  1. 14
    8
      README.md
  2. 4
    4
      doc/CHANGELOG.md
  3. 5
    5
      doc/Teensy2_pinout.txt
  4. 10
    21
      doc/keybrd_library_developer_guide.md
  5. 37
    34
      doc/keybrd_library_user_guide.md
  6. 4
    4
      doc/planned_features.md
  7. 1
    1
      examples/keybrd_mapping_bb/keybrd_mapping_bb.ino

+ 14
- 8
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
-----------------------------
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.

+ 4
- 4
doc/CHANGELOG.md View File

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

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

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

+ 10
- 21
doc/keybrd_library_developer_guide.md View File

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

+ 37
- 34
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.
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

+ 4
- 4
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
============
@@ -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
- 1
examples/keybrd_mapping_bb/keybrd_mapping_bb.ino View File

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