From 7293bee03c2567abe2d2eabe60875e8bebbe8cf3 Mon Sep 17 00:00:00 2001 From: wolfv6 Date: Wed, 11 May 2016 12:46:53 -0600 Subject: [PATCH] improve tutorials --- README.md | 2 +- doc/keybrd_library_developer_guide.md | 11 ++++---- doc/keybrd_library_user_guide.md | 26 +++++++++++-------- .../keybrd_3a_multi-layer_annotated.ino | 8 +++--- .../keybrd_4_split_with_IOE_annotated.ino | 3 +-- tutorials/tutorial_0_introduction.md | 2 ++ tutorials/tutorial_1_breadboard_keyboard.md | 7 ++--- tutorials/tutorial_2_single-layer_keyboard.md | 1 - tutorials/tutorial_3a_multi-layer_keyboard.md | 23 +++++++++------- tutorials/tutorial_3b_autoShift.md | 2 +- .../tutorial_4_split_keyboard_with_IOE.md | 25 +++++++++++------- ...someone_else's_keybrd_extension_library.md | 2 +- ...shing_your_own_keybrd_extension_library.md | 1 + 13 files changed, 63 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index fd3944c..3aae7a5 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ It runs on a breadboard and has rows, columns, and diodes just like the big keyb 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](tutorials) 2, 3, and 4 show how to create custom keybrd firmware. +The remaining [keybrd tutorials](tutorials) show how to create custom keybrd firmware. Example complex keybrd sketch ----------------------------- diff --git a/doc/keybrd_library_developer_guide.md b/doc/keybrd_library_developer_guide.md index 940fff8..d3e78e7 100644 --- a/doc/keybrd_library_developer_guide.md +++ b/doc/keybrd_library_developer_guide.md @@ -1,7 +1,6 @@ keybrd Library Developer's 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 if for maintaining and writing 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 @@ -101,7 +100,7 @@ Most derived-class names start with the base class name followed by "_" and a na ``` Code | - Code_Sc + Code_LayerLock ``` This convention leads to class names that convey information about the classes inheritance. @@ -116,7 +115,7 @@ Following the style guide makes it easier for the next programmer to understand * **ITEM_COUNT** is a constant number of items. * **itemCount** is a variable number of items. * 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 element name e.g. Row* const = ptrsRows { &row0, &row1 }; * Pass arrays using array notation rather than pointer notation. Use ``` @@ -129,8 +128,8 @@ Following the style guide makes it easier for the next programmer to understand * 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. -* Code is automatically formated before being pushed to the keybrd repository - The options file doc/astyle_cpp specifies the format: +* Code is automatically formated before being pushed to the keybrd repository. + The [astyle_cpp](astyle_cpp) file specifies the format: * Allman style indentation * indent 4 spaces * replace tabs with spaces diff --git a/doc/keybrd_library_user_guide.md b/doc/keybrd_library_user_guide.md index c9d6d7b..87f8923 100644 --- a/doc/keybrd_library_user_guide.md +++ b/doc/keybrd_library_user_guide.md @@ -29,7 +29,11 @@ keybrd has been tested on the DodoHand keyboard with Teensy 2.0 and PCA9655E I/O Teensy LC is preferred over the older Teensy 2.0 for it's larger memory capacity and lower price. ## Getting started with Teensy, Arduino IDE, and keybrd -The Arduino IDE is used to edit and compile sketches, and then load them on to the microcontroller. +The Arduino IDE is used to + +1. edit sketches +2. compile sketches into HEX files +3. load the HEX file onto the microcontroller Teensyduino is a software add-on for the Arduino IDE that allows it to compile to Teensy. @@ -39,7 +43,7 @@ Teensyduino is a software add-on for the Arduino IDE that allows it to compile t The following install and setup steps create an Arduino development environment for keybrd sketches. ### Install Arduino IDE and Teensyduino -Following install steps are modified from the [Teensyduino download page](https://www.pjrc.com/teensy/td_download.html) +The following install steps are modified from the [Teensyduino download page](https://www.pjrc.com/teensy/td_download.html) For Linux: @@ -76,11 +80,11 @@ Down load keybrd-master.zip from the [Download ZIP](https://github.com/wolfv6/ke Unpack keybrd-master.zip into your Arduino directory on your system (default location is ~/Documents/Arduino/). -### keybrd library and keybrd extension libraries +### Install keybrd library and keybrd extension libraries The keybrd library contains the foundation classes for creating a keyboard firmware. -For emphasis, it is referred to as the "core keybrd library". +For emphasis, it is sometimes referred to as the "core keybrd library". keybrd extension libraries contain additional classes that extend the keyboard library. keybrd extension library names are prefixed with "keybrd_". @@ -90,7 +94,7 @@ For example, the DodoHand keyboard requires that the core keybrd library and the * Arduino/libraries/keybrd/ * Arduino/libraries/keybrd_DH/ -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 other keyboards can not use. ### Setup Arduino IDE for compiling keybrd firmware From the Arduino IDE tool bar, select: @@ -133,14 +137,14 @@ Extension libraries have their example sketches similarly located. The example sketch names use the following conventions. - **keybrd_extension_feature_version.ino** + **keybrd_feature_version.ino** where -* **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 +* **keybrd** is the library name e.g. keybrd, keybrd_DH +* **feature** is a distinguishing feature of the keybrd sketch e.g. breadboard, LED, sound, Dvorak +* **version** is the sketch's version number -The first two fields are mandatory, the remaining fields are optional. +The first field are mandatory, the remaining fields are optional. ## Diode orientation The physical martix rows and columns on a keyboard can be in any direction or shape. @@ -207,7 +211,7 @@ The [Neo layout](http://neo-layout.org/index_en.html) has 6 layers. **Layer scheme** - is a system for changing layers while typing. A single-layer scheme does not change layers. -**Layout** - is a grid of keys. Key caps are often labeled to show a keyboard's layout. +**Layout** - is the placement of keys. Key caps are often labeled to show a keyboard's layout. **[Matrix](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/)** - is a collection of switches connected by rows and columns. diff --git a/tutorials/keybrd_3a_multi-layer_annotated/keybrd_3a_multi-layer_annotated.ino b/tutorials/keybrd_3a_multi-layer_annotated/keybrd_3a_multi-layer_annotated.ino index 662a7e5..c7d90e4 100644 --- a/tutorials/keybrd_3a_multi-layer_annotated/keybrd_3a_multi-layer_annotated.ino +++ b/tutorials/keybrd_3a_multi-layer_annotated/keybrd_3a_multi-layer_annotated.ino @@ -53,7 +53,7 @@ The CODES section instantiates six codes, one for each item in the layout: */ // ---------------- LAYER CODE ----------------- /* -enum assings ID numbers to the layers. +enum assings Id numbers to the layers. */ enum layers { NORMAL, FN }; /* @@ -61,7 +61,7 @@ stateLayer keeps track of the active layer. The default layer number is 0. */ StateLayers stateLayer; /* -The Code_LayerHold constructor parameter specifies a layer ID number and a StateLayer. +The Code_LayerHold constructor parameter specifies a layer Id number and a StateLayer. When l_fn is pressed, it tells stateLayer to change the active layer to 1. When l_fn is released, it tells stateLayer to restore the normal layer. */ @@ -90,8 +90,8 @@ Key_LayeredKeysArray constructor parameters are: one array of Code pointers Key_LayeredKeysArray objects are multi-layered - one Code object per layer. -Layer ID numbers are array indexes for the Key_LayeredKeysArray. -Defining layer ID numbers with enum insures that they are a series of intergers starting at 0. +Layer Id numbers are used as array indexes for the Key_LayeredKeysArray. +Defining layer Id numbers with enum insures that they are a series of intergers starting at 0. The Key object names in this sketch start with a "k_" followed by matrix-row-column coordinates. */ diff --git a/tutorials/keybrd_4_split_with_IOE_annotated/keybrd_4_split_with_IOE_annotated.ino b/tutorials/keybrd_4_split_with_IOE_annotated/keybrd_4_split_with_IOE_annotated.ino index 5e0b55a..54ea9c8 100644 --- a/tutorials/keybrd_4_split_with_IOE_annotated/keybrd_4_split_with_IOE_annotated.ino +++ b/tutorials/keybrd_4_split_with_IOE_annotated/keybrd_4_split_with_IOE_annotated.ino @@ -63,7 +63,7 @@ const uint8_t COL_PORT_L_COUNT = sizeof(ptrsColPorts_L)/sizeof(*ptrsColPorts_L); /* The right matrix is scanned by an I/O expander. -The micro-controller and I/O expander use address 0x18 to communicate with each other over I2C. +I/O expander I2C address is configured by hardware pins. ADDR is a static variable of class IOExpanderPort. */ const uint8_t IOExpanderPort::ADDR = 0x18; @@ -73,7 +73,6 @@ The I/O expander has two ports. Each port has eight pins. One port is connected to the matrix's rows. The other port is connected to the matrix's columns. The IOExpanderPort constructor parameters specify the port number and initial output value. -I/O Expander and AVR have similar constructor parameters for RowPort and ColPort. port1_R is port 1 and has an initial output value of 0. rowPort1_R uses port1_R. diff --git a/tutorials/tutorial_0_introduction.md b/tutorials/tutorial_0_introduction.md index 17a1957..a80e6d4 100644 --- a/tutorials/tutorial_0_introduction.md +++ b/tutorials/tutorial_0_introduction.md @@ -21,6 +21,8 @@ The tutorials assume the reader: > Some of the pictures do not match the sketches, they will be updated after changing to Teensy LC +> Schematic diagrams are missing from tutorials 2 and 4, they will be added after changing to Teensy LC + You will need a breadboard keyboard with a Teensy 2.0 controller to run the tutorial sketches. If you use a different controller, you may have to change port classes. If you already have a keyboard with an Arduino compatible controller, you can use that instead of a breadboard keyboard. diff --git a/tutorials/tutorial_1_breadboard_keyboard.md b/tutorials/tutorial_1_breadboard_keyboard.md index 644ce63..ac968ae 100644 --- a/tutorials/tutorial_1_breadboard_keyboard.md +++ b/tutorials/tutorial_1_breadboard_keyboard.md @@ -62,10 +62,11 @@ Breadboard keyboard assembly instructions: * follow pin connections table (below) and consult pinout diagram in [Teensy2_pinout.txt](../doc/Teensy2_pinout.txt) - + (Future version of keybrd library may change all Code classes to Key classes.) ## A simple multi-layer keybrd sketch diff --git a/tutorials/tutorial_3b_autoShift.md b/tutorials/tutorial_3b_autoShift.md index 13c4ca2..2475563 100644 --- a/tutorials/tutorial_3b_autoShift.md +++ b/tutorials/tutorial_3b_autoShift.md @@ -4,7 +4,7 @@ Some mulit-layer keyboards have a symbols layer that writes symbols without usin ~ ! @ # $ % ^ & * () _ {} | < > : ? -The keybrd library does this by automatically sending the MODIFIERKEY_SHIFT scancode. +The keybrd library does this by automatically sending a MODIFIERKEY_SHIFT scancode. The [keybrd_3_autoShift_annotated.ino](keybrd_3_autoShift_annotated/keybrd_3_autoShift_annotated.ino) sketch explains the AutoShift feature. After reading the sketch you too will be able to automatically shifted characters. diff --git a/tutorials/tutorial_4_split_keyboard_with_IOE.md b/tutorials/tutorial_4_split_keyboard_with_IOE.md index 0285caa..68110f5 100644 --- a/tutorials/tutorial_4_split_keyboard_with_IOE.md +++ b/tutorials/tutorial_4_split_keyboard_with_IOE.md @@ -20,35 +20,40 @@ The microcontroller and I/O expander are connected by 4 jumper wires: * Serial CLock signal (SCL) * Serial DAta signal (SDA) -A capacitor on the power pin smooths power to the I/O expander. +A decoupling capacitor on the power pin dampens noise coming in through the power wire. The microcontroller and I/O expander communicate via [I2C](http://en.wikipedia.org/wiki/I%C2%B2C) bus, which consists of two signals: SCL and SDA. Two resistors pull-up voltage on the SCL and SDA. -I/O expander I2C address is configured by three hardware pins (AD0, AD1, AD2). +I/O expander I2C address is configured by hardware pins. +The MCP23018 with all address pins grounded has an I2C address of ?? todo. The I/O expander has two ports. Each port has eight pins. One port is connected to the matrix's rows. The other port is connected to the matrix's columns. ## Building a split keyboard with I/O Expander -The split keyboard is built on the basic breadboard keyboard described in [tutorial_1_breadboard_keyboard.md](tutorial_1_breadboard_keyboard.md) +We will build a split keyboard adding parts to the basic breadboard keyboard described in [tutorial_1_breadboard_keyboard.md](tutorial_1_breadboard_keyboard.md) - Continuing from the basic breadboard keyboard instructions: + + 4. Insert the I/O expander 5. Install I/O expander power -* ground -* power -* capacitor + * ground + * power + * capacitor 6. Install I2C bus -* SCL -* SDA -* pull-up resistors on SCL and SDA + * SCL + * SDA + * pull-up resistors on SCL and SDA 7. configure I2C address diff --git a/tutorials/tutorial_7a_using_someone_else's_keybrd_extension_library.md b/tutorials/tutorial_7a_using_someone_else's_keybrd_extension_library.md index aaad3c2..4b5ff59 100644 --- a/tutorials/tutorial_7a_using_someone_else's_keybrd_extension_library.md +++ b/tutorials/tutorial_7a_using_someone_else's_keybrd_extension_library.md @@ -3,7 +3,7 @@ Tutorial 7a - using someone else's keybrd extension library The keybrd library contains the foundation classes for creating a keyboard firmware. keybrd extension libraries extend the core keyboard library. -keybrd extension library names are prefixed by "keybrd_" and are listed in: +keybrd extension library names are prefixed by "keybrd_" and are listed in: todo keybrd extension libraries are not listed yet * [Arduino Playground](http://playground.arduino.cc/Main/InterfacingWithHardware#keyb) > find "keybrd" * Arduino Library-Manager (Arduino IDE > Sketch > Include Library > Manage Libraries > Filter your search: keybrd) diff --git a/tutorials/tutorial_7b_creating_and_publishing_your_own_keybrd_extension_library.md b/tutorials/tutorial_7b_creating_and_publishing_your_own_keybrd_extension_library.md index b41e3fa..16a905f 100644 --- a/tutorials/tutorial_7b_creating_and_publishing_your_own_keybrd_extension_library.md +++ b/tutorials/tutorial_7b_creating_and_publishing_your_own_keybrd_extension_library.md @@ -2,6 +2,7 @@ Tutorial 7b - creating and publishing your own keybrd extension library ======================================================================= Publishing and listing your keybrd extension library allows others to find and install your library. The keybrd extension library name should start with "keybrd_" so that it is easy for people to find. + The directory structure of the library depends on where it will be listed. ## Publishing anywhere with listing on Arduino Playground LibraryList