From c6b7cd1a168fe12bea8ec7020a21e1d4b8e1e8e2 Mon Sep 17 00:00:00 2001 From: wolfv6 Date: Mon, 9 May 2016 13:41:29 -0600 Subject: [PATCH] document --- README.md | 22 +++--- doc/CHANGELOG.md | 8 +-- ...microcontroller.txt => Teensy2_pinout.txt} | 10 +-- doc/keybrd_library_developer_guide.md | 31 +++----- doc/keybrd_library_user_guide.md | 71 ++++++++++--------- doc/planned_features.md | 8 +-- .../keybrd_mapping_bb/keybrd_mapping_bb.ino | 2 +- 7 files changed, 75 insertions(+), 77 deletions(-) rename doc/{Teensy2_microcontroller.txt => Teensy2_pinout.txt} (78%) diff --git a/README.md b/README.md index f0ae1f3..7c61827 100644 --- a/README.md +++ b/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. + +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. diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md index 7e425e3..074b7ec 100644 --- a/doc/CHANGELOG.md +++ b/doc/CHANGELOG.md @@ -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 diff --git a/doc/Teensy2_microcontroller.txt b/doc/Teensy2_pinout.txt similarity index 78% rename from doc/Teensy2_microcontroller.txt rename to doc/Teensy2_pinout.txt index 9f61675..049ccc8 100644 --- a/doc/Teensy2_microcontroller.txt +++ b/doc/Teensy2_pinout.txt @@ -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 diff --git a/doc/keybrd_library_developer_guide.md b/doc/keybrd_library_developer_guide.md index 7475d97..5bf9191 100644 --- a/doc/keybrd_library_developer_guide.md +++ b/doc/keybrd_library_developer_guide.md @@ -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. diff --git a/doc/keybrd_library_user_guide.md b/doc/keybrd_library_user_guide.md index 158fde1..7308d3c 100644 --- a/doc/keybrd_library_user_guide.md +++ b/doc/keybrd_library_user_guide.md @@ -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. + ## 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 diff --git a/doc/planned_features.md b/doc/planned_features.md index 73a7bd5..13b5c81 100644 --- a/doc/planned_features.md +++ b/doc/planned_features.md @@ -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 diff --git a/examples/keybrd_mapping_bb/keybrd_mapping_bb.ino b/examples/keybrd_mapping_bb/keybrd_mapping_bb.ino index 761f069..3c0d7e4 100644 --- a/examples/keybrd_mapping_bb/keybrd_mapping_bb.ino +++ b/examples/keybrd_mapping_bb/keybrd_mapping_bb.ino @@ -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** | |:------:|-------|-------|