document
This commit is contained in:
wolfv6
parent
98b6060e7c
commit
c6b7cd1a16
22
README.md
22
README.md
@ -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)
|
||||
|
||||
|
||||
|
||||
|
||||
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** |
|
||||
|:------:|-------|-------|
|
||||
|
||||
Reference in New Issue
Block a user