8 years ago · 6978b038aa
--- a/doc/keybrd_library_developer_guide.md
+++ b/doc/keybrd_library_developer_guide.md
@@ -12,7 +12,7 @@ This guide is for the maintainers and developers of the keybrd library and it's
 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. 
 
 ## Class diagrams 
 ## Class inheritance diagrams 
 
 Keybrd library class inheritance diagram 
 ``` 
@@ -63,12 +63,10 @@ Keybrd library class inheritance diagram
 
 ``` 
 
 ## Association diagrams 
 ## Dependency diagrams 
 
 single-layer Keybrd association diagram with LEDs 
 single-layer dependency diagram with LEDs 
 ``` 
 keybrd[1] 
 | 
 matrix[1..*] 
 | 
 row[1..*]_____________________________ 
@@ -81,11 +79,8 @@ single-layer Keybrd association diagram with LEDs
 
 ``` 
 
 multi-layer Keybrd association diagram with LEDs and I/O Expander 
 multi-layer dependency diagram with LEDs and I/O Expander 
 ``` 
 
 keybrd[1] 
 | 
 matrix[1..*] 
 | stateLayers[1..*] 
 row[1..*]_________________________________________/__ | \ 
@@ -148,7 +143,6 @@ Arduino does not have a debugger; so here is a list of functions in the order th
 Refer to it like a table of contents while reading the keybrd library. 
 
 ``` 
 Keybrd::scan() for each matrix 
 Matrix::scan() for each row 
 Row::process() 
 Row::scan() 
@@ -175,3 +169,5 @@ The keybrd libraries compile on the Arduino IDE and make extensive use of the fo
 #include <Wire.h> 
 #include <Keyboard.h> 
 #include <Mouse.h> 
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>. 
--- a/doc/keybrd_library_user_guide.md
+++ b/doc/keybrd_library_user_guide.md
@@ -222,3 +222,5 @@ By themselves, modifier keys usually do nothing; that is, pressing any of the Sh
 **Sketch** - is the name that Arduino uses for a program 
 
 **keybrd sketch** - is an Arduino sketch that uses the keybrd library to define a keyboard firmware. 
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>. 
--- a/doc/planned_features.md
+++ b/doc/planned_features.md
@@ -20,3 +20,4 @@ Add more tutorials:
 * tutorial_5_LEDs.md 
 * tutorial_6_mapping_matrix_to_layout.md 
 * tutorial_9_active_high.md 
 * add schematics to tutorials 
--- a/tutorials/keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino
+++ b/tutorials/keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino
@@ -54,13 +54,13 @@ const unsigned int Row::DELAY_MICROSECONDS = 1000;
 A micro-controller has one or more ports. Each port has one or more pins.
 These pins are connected to the keyboard's rows and columns.

 The RowPort constructor parameters specify the port's registers.
 rowPortF will strobe PORTF one row at a time.
 */
 RowPort_AVR_Optic rowPortF(DDRF, PORTF);

 /*
 The ColPort constructor parameters specify the port's registers and the port pins to read:
 A number to the right of "1<<" is the pin number to read. 1<<0 reads pin 0, and 1<<1 reads pin 1.
 A number to the right of "1<<" is a pin number to read.
 colPortB will read PORTB's pin 0 and pin 1
 */
 ColPort_AVR colPortB(DDRB, PORTB, PINB, 1<<0 | 1<<1 );

@@ -134,7 +134,8 @@ const uint8_t ROW_COUNT = sizeof(ptrsRows)/sizeof(*ptrsRows);

 /*
 The Matrix constructor parameters are:
 one array of Row pointers, and the number of rows
 one array of Row pointers
 the number of Row pointers
 '0' for active low or '1' for active high
 WARNING: the tutorial sketches all have '1' for active high to be compatible with DH.
 The breadboard keyboard described in tutorial_1 is active low.
--- 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 layer 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 number and the StateLayers it calls.
 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 numbers are array indexes for the Key_LayeredKeysArray.
 Defining layer numbers with enum insures that the layer numbers are a series starting at 0.
 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.

 The Key object names in this sketch start with a "k_" followed by matrix-row-column coordinates.
 */
--- 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,45 +63,33 @@ 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 communicates via I2C bus.
 Three hardware pins (AD0, AD1, AD2) are used to configure the I2C address of the I/O expander.
 ADDR is a static variable of class IOExpanderPort. The I2C address of this I/O expander is 0x18.
 The micro-controller and I/O expander use address 0x18 to communicate with each other over I2C.
 ADDR is a static variable of class IOExpanderPort.
 */
 const uint8_t IOExpanderPort::ADDR = 0x18;

 An I/O expander used on a matrix has two ports. Each port has eight pins.
 /*
 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.
 */
 const uint8_t IOExpanderPort::ADDR = 0x18;

 /*
 port1_R uses port 1 with an initial output value of 0.
 port1_R is port 1 and has an initial output value of 0.
 rowPort1_R uses port1_R.
 */
 IOExpanderPort port1_R(1, 0);

 /*
 The RowPort_PCA9655E constructor parameter specifies the IOExpanderPort.
 */
 RowPort_PCA9655E rowPort1_R(port1_R);

 /*
 port0_R uses port 0 with an initial output value of 0.
 port0_R is port 0 and has an initial output value of 0.
 colPort0_R uses port0_R to read pin 0 and pin 1.
 */
 IOExpanderPort port0_R(0, 0);

 /*
 The ColPort_PCA9655E constructor parameter specifies the IOExpanderPort and the port pins to read:
 A number to the right of "1<<" is the pin number to read. 1<<0 reads pin 0, and 1<<1 reads pin 1.
 */
 ColPort_PCA9655E colPort0_R(port0_R, 1<<0 | 1<<1 );

 /*
 ColPort pointers are placed in an array because some keyboards use multiple column ports.
 This sketch only has one column port.

 sizeof() is used to compute the number of array elements.
 This eliminates the risk of forgetting to update the count after adding or removing an element.
 ColPort pointers are packed into an array.
 */
 ColPort* const ptrsColPorts_R[] = { &colPort0_R };
 const uint8_t COL_PORT_R_COUNT = sizeof(ptrsColPorts_R)/sizeof(*ptrsColPorts_R);
--- a/tutorials/tutorial_0_introduction.md
+++ b/tutorials/tutorial_0_introduction.md
@@ -17,12 +17,12 @@ The tutorials assume the reader:
 <!-- todo -->
 > All the tutorial sketches are tested on teensy 2.0 and PCA9655E-D I/O expander

 > In July, the tutorial sketches will be changed to Teensy LC and MCP23018 I/O expander
 > The tutorial sketches will be changed to Teensy LC and MCP23018 I/O expander

 > Some of the pictures and table values do not match the sketches, they will be updated after changing to Teensy LC
 > Some of the pictures do not match the sketches, they will be updated 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.

 <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/tree/master/tutorials" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.
--- a/tutorials/tutorial_10_writing_your_own_port_classes.md
+++ b/tutorials/tutorial_10_writing_your_own_port_classes.md
@@ -1,6 +1,6 @@
 Tutorial 8 - writing your own port classes
 ==========================================
 Port classes are the keybrd library's interface to microcontoller ports or I/O expander ports.
 Port classes are the keybrd library's interface to microcontoller ports and I/O expander ports.

 To write your own port classes:
 1) Get a copy of the controller or I/O expander datasheet.
@@ -8,10 +8,8 @@ To write your own port classes:
 3) Consider looking for other open-source keyboard code that uses the same IC e.g. TMK keyboard firmware.
 4) Write your RowPort_* class to inherit from RowPort class.
 5) Write your ColPort_* class to inherit from ColPort class.
 6) Consider testing on a breadboard keyboard.

 Writing port classes is the most technically demanding task in the keybrd library.
 If you have not read a controller datasheet or I/O expander datasheet before,
 consider designing your keyboard around one of the controllers or I/O expanders
 that already have port classes in the keybrd library.
 It might be faster to designing your keyboard around one of the controllers or I/O expanders that already have port classes in the keybrd library.

 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.
--- a/tutorials/tutorial_1_breadboard_keyboard.md
+++ b/tutorials/tutorial_1_breadboard_keyboard.md
@@ -10,7 +10,7 @@ A breadboard is the easiest way to learn keyboard electronics.
 Electronics are fickle, and you won't get everything right the first time. 
 There is a learning curve. 
 Compared to PCBs, breadboard keyboards are easier to learn on because: 
 * Mistakes are easily corrected because no desoldering 
 * Mistakes are easily corrected; no soldering and desoldering 
 * Parts can be reused in many different configurations 
 * A small keyboard is easier to trouble shoot 
 
@@ -18,7 +18,12 @@ Breadboard keyboards are useful for:
 * learning keyboard electronics - diodes, micro controllers, I/O expanders 
 * learning the firmware development workflow 
 * prototyping circuits before making a PCB 
 * testing firmware concepts before committing to a keyboard-hardware design 
 
 ## Breadboard keyboard starter kit 
 The parts needed to build all the tutorial Breadboard Keyboards are listed in [breadboard_keyboard_supplies.ods](breadboard_keyboard_supplies.ods). 
 
 Wire cutters (or nail clipper) is the only required tool. 
 A multi-meter is useful for trouble shooting. 
 
 ## How a breadboard works 
 To understand the breadboard keyboard you will need to know the internal parts of a breadboard: 
@@ -27,11 +32,9 @@ To understand the breadboard keyboard you will need to know the internal parts o
 
 These are explained in [How to Use a Breadboard](https://learn.sparkfun.com/tutorials/how-to-use-a-breadboard) 
 
 ## Breadboard keyboard starter kit 
 The parts needed to build all the Breadboard Keyboards in the keybrd tutorials are listed in [breadboard_keyboard_supplies.ods](breadboard_keyboard_supplies.ods). 
 
 Wire cutters (or nail clippers) is the only required tool. 
 A multi-meter is useful for trouble shooting. 
 ## How a keyboard matrix works 
 This excellent article explains how the microcontroller, matrix, switches and diodes work together: 
 [How a Key Matrix Work](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) 
 
 ## Building a basic breadboard keyboard 
 The basic breadboard has 4 switches and a microcontroller. 
@@ -59,25 +62,28 @@ Breadboard keyboard assembly instructions:
 * follow pin connections table (below) and consult pinout diagram in 
 [Teensy2_pinout.txt](../doc/Teensy2_pinout.txt) 
 
 <!-- todo replace this table with a schematic 
 This schematic was written by consulting the micro-controller's datasheet and using the ?? tool. 
 
 this table might not match the sketches 
 
 **Teensy 2.0 pin connections table** 
 
 | Pin number | Row Column | 
 |------------|-------------| 
 | 21 | row_0 | todo this table might not match the sketches 
 | 21 | row_0 | 
 | 20 | row_1 | 
 | 0 | col_0 | 
 | 1 | col_1 | 
 --> 
 
 ## Compiling and loading the keyboard firmware 
 Follow the [keybrd Library User's Guide](../doc/keybrd_library_user_guide.md) to set up the Arduino environment and to compile and load keybrd firmware onto the keyboard's controller. 
 
 ## How a keyboard matrix works 
 Now that you have built your first breadboard keyboard, you can dig in and learn how it actually works. 
 This excellent article explains how the microcontroller, matrix, switches and diodes work together: 
 [How a Key Matrix Work](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) 
 
 ## Bigger breadboard keyboards 
 Sometimes its useful to prototype a full keyboard matrix before designing the PCB. 
 Several breadboards can be tied together into one. 
 
 ![big breadboard keyboard](images/breadboard_big.jpg "breadboard_big.jpg") 
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>. 
--- a/tutorials/tutorial_2_single-layer_keyboard.md
+++ b/tutorials/tutorial_2_single-layer_keyboard.md
@@ -1,7 +1,6 @@
 Tutorial 2 - single-layer keyboard 
 ======================================= 
 The [keybrd_2_single-layer_annotated.ino](keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino) 
 sketch explains how the keybrd library works. 
 [keybrd_2_single-layer_annotated.ino](keybrd_2_single-layer_annotated/keybrd_2_single-layer_annotated.ino) explains how a keybrd sketch works. 
 
 You can view the class definitions in the [keybrd library](../src/). 
 
@@ -14,3 +13,5 @@ After reading the sketch you will be able to modify it to suite your own single-
 |:------:|-------|-------|-------| 
 | **0** | a | b | c | 
 | **1** | 1 | 2 | shift | 
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>. 
--- a/tutorials/tutorial_3a_multi-layer_keyboard.md
+++ b/tutorials/tutorial_3a_multi-layer_keyboard.md
@@ -51,6 +51,26 @@ class Key_Layered
 } 
 ``` 
 
 Dependency diagram 
 ``` 
 +-----------+ 
 | Key_Layer | 
 +-----------+ 
 | 
 |setLayer() 
 | 
 v 
 +------------+ 
 | StateLayer | 
 +------------+ 
 ^ 
 | 
 |getLayer() 
 | 
 +-------------+ 
 | Key_Layered | 
 +-------------+ 
 ``` 
 ## Layer-scheme classes 
 There are several layer scheme-classes to choose from. 
 You can view all the class definitions in the [keybrd library](../src/). 
@@ -97,3 +117,5 @@ Annotations in the sketch explain how the multi-layer feature works.
 |:------:|--------|--------| 
 | **0** | a 1 | b 2 | 
 | **1** | layer0 | layer1 | 
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>. 
--- a/tutorials/tutorial_3b_autoShift.md
+++ b/tutorials/tutorial_3b_autoShift.md
@@ -1,15 +1,13 @@
 Tutorial 3b - autoShift 
 ======================= 
 When you finish this tutorial your keyboard will be able to automatically shifted characters. 
 
 ## AutoShift 
 Some mulit-layer keyboards have a symbols layer that writes symbols without using the shift key: 
 
 ~ ! @ # $ % ^ & * () _ {} | < > : ? 
 
 The keybrd library does this by automatically sending the MODIFIERKEY_SHIFT scancode. 
 The [keybrd_3_autoShift_annotated.ino](keybrd_proj/keybrd/examples/keybrd_3_autoShift_annotated/keybrd_3_autoShift_annotated.ino) 
 sketch explains the AutoShift feature. 
 
 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. 
 
 Two keybrd classes use AutoShift: 
 * Code_ScS 
@@ -22,3 +20,5 @@ Two keybrd classes use AutoShift:
 |:------:|-------|-------| 
 | **0** | a ! 6 | b @ 7 | 
 | **1** | sym | num | 
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>. 
--- a/tutorials/tutorial_4_split_keyboard_with_IOE.md
+++ b/tutorials/tutorial_4_split_keyboard_with_IOE.md
@@ -6,82 +6,58 @@ When you finish this tutorial you will be able to be able to modify a 2-matrix k
 The breadboard in this picture models a split keyboard.
 ![breadboard keyboard with 2 rows and 4 columns of keys](images/breadboard_keyboard_2x5_labeled.jpg "2x5 breadboard keyboard")

 There is a total of 4 matrix rows, each on a breadboard power rail.

 The right matrix is connected to a microcontroller.
 The left matrix is connected to a I/O expander.

 There is a total of 4 matrix rows, each on a dedicated power rail.
 The I/O expander has a small notch on one end, which identifies the end with pin 1.
 In the picture, pin 1 is on the right end.

 The microcontroller and I/O expander communicate by [I2C](http://en.wikipedia.org/wiki/I%C2%B2C) via 4 jumper wires:
 The microcontroller and I/O expander are connected by 4 jumper wires:
 * ground
 * power
 * Serial CLock input (SCL)
 * Serial DAta I/O (SDA)
 * Serial CLock signal (SCL)
 * Serial DAta signal (SDA)

 The two resistors near the microcontroller pull-up voltage on the SCL and SDA pins.
 A capacitor on the power pin smooths power to the I/O expander.

 The I/O expander has a small notch on one end, which identifies the end with pin 1.
 In the picture, pin 1 is on the right end.
 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).

 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_0_keybrd_breadboard.md > Building a Basic Breadboard Keyboard

 Follow these instructions to add a second matrix to the Basic Breadboard Keyboard:
 4. Insert I2C jumper wires and pull-up resistors connecting to Teensy2.
 * follow the I2C and pull-up resistors tables (below) and consult Teensy pinout diagram in
 [Connecting Teensy 2.0 to a Keyboard](connecting_teensy2_to_keyboard.md)

 todo these tables might not match the sketch

 **Teensy 2.0 pin connections tables**

 | Pin Number | Row Column |
 |------------|-------------|
 | 21 | row_R0 |
 | 20 | row_R1 |
 | 0 | col_R0 |
 | 1 | col_R1 |

 | Pin Number | I2C |
 |------------|-------------|
 | GND | ground |
 | VCC | power |
 | 5 | SCL |
 | 6 | SDA |

 | Pin Number | 4.7K Ohms Pull-up Resistor |
 |------------|-------------|
 | 5 | VCC |
 | 6 | VCC |

 5. Insert jumper wires to connect MCP23018 I/O expander
 * follow pin connections tables (below) and consult pinout diagram in
 [Connecting MCP23018 I/O Expander to a Keyboard](connecting_MCP23018_to_keyboard.md)

 **MCP23018 I/O expander pin connections tables**

 | Pin Number | Row Column |
 |------------|-------------|
 | 3 | row_L0 |
 | 4 | row_L1 |
 | 20 | col_L0 |
 | 21 | col_L1 |
 | 22 | col_L2 |

 | Pin Number | I2C |
 |------------|-------------|
 | 1 | ground |
 | 11 | power |
 | 12 | SCL |
 | 13 | SDA |

 | Pin Number | Jump to Pin |
 |------------|-------------|
 | 11 | 16 |
 | 1 | 15 |

 todo add capacitor
 The split keyboard is built on the basic breadboard keyboard described in [tutorial_1_breadboard_keyboard.md](tutorial_1_breadboard_keyboard.md)

 <!-- todo add schematic with a capacitor to IOE power
 This schematic was written by consulting the I/O expander's datasheet and using the ?? tool. -->

 Continuing from the basic breadboard keyboard instructions:

 4. Insert the I/O expander

 5. Install I/O expander power
 * ground
 * power
 * capacitor

 6. Install I2C bus
 * SCL
 * SDA
 * pull-up resistors on SCL and SDA

 7. configure I2C address

 8. Assemble key matrix as shown in the picture.

 9. Connect I/O expander ports to matrix rows and columns

 ## Sketch for split keyboard with I/O Expander
 The [keybrd_4_split_with_IOE_annotated.ino](keybrd_4_split_with_IOE_annotated/keybrd_4_split_with_IOE_annotated.ino)
 sketch explains how the I/O Expander works on a keyboard.

 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.
--- a/tutorials/tutorial_7a_using_someone_else's_keybrd_extension_library.md
+++ b/tutorials/tutorial_7a_using_someone_else's_keybrd_extension_library.md
@@ -1,7 +1,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 main keyboard library.
 keybrd extension libraries extend the core keyboard library.

 keybrd extension library names are prefixed by "keybrd_" and are listed in:
 * [Arduino Playground](http://playground.arduino.cc/Main/InterfacingWithHardware#keyb) > find "keybrd"
@@ -9,3 +9,7 @@ keybrd extension library names are prefixed by "keybrd_" and are listed in:

 Instructions for installing a library are at:
 http://www.arduino.cc/en/Guide/Libraries

 Once a keybrd extension library is installed, it's classes can be included in a sketch.

 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.
--- 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
@@ -1,6 +1,6 @@
 Tutorial 7b - creating and publishing your own keybrd extension library
 =======================================================================
 Listing your keybrd extension library allows others to find and install your 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.

@@ -36,8 +36,8 @@ Add your keybrd library to the Keyboard/Keypads sublist:
 The advantage of using GitHub is that users can submit pull requests.
 The advantage of using Arduino Library-Manager is that users can install your library through the Arduino IDE.

 Arduino Library-Manager is particular about directory structures it accepts.
 The directory structure of your keybrd extension library to look like this:
 Arduino Library-Manager is particular about the directory structures it accepts.
 Your keybrd extension library should have a library.properties file and a src folder, placed like this:

 keybrd_MyKeyboard/
 library.properties
@@ -74,7 +74,9 @@ Example library.properties file:
 Instructions for listing a library on Arduino Library Manager are at:
 https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ

 After it has been accepted into the Arduino IDE Library Manager, add your library to the Arduino Playground LibraryList.
 [Arduino playground](http://playground.arduino.cc/) is a wiki.
 After it has been accepted into the Arduino IDE Library Manager, add your library to the Arduino Playground LibraryList.
 Sign in at http://playground.arduino.cc/Main/LibraryList and add keybrd libraries to Keyboard/Keypads sublist:
 http://playground.arduino.cc/Main/InterfacingWithHardware#keyb

 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.
--- a/tutorials/tutorial_8_breaking_up_a_sketch_into_smaller_files.md
+++ b/tutorials/tutorial_8_breaking_up_a_sketch_into_smaller_files.md
@@ -20,13 +20,15 @@ You have three versions of LED indicators you are experimenting with:
 instantiations_LEDs_3.h

 Example 2.
 You use Colemak and want QWERTY users to to try your keyboard design.
 You use Colemak and want QWERTY users to to try your new keyboard design.
 So you publish your keybrd extension library with two versions of instantiations_matrix.h:
 instantiations_matrix_QWERTY.h
 instantiations_matrix_colemak.h
 instantiations_matrix_QWERTY.h

 Example 3.
 Someone wants to try the layout in your keybrd extension library, but their controller and matrix are different.
 So they replace two of your object instantiation files with their own:
 You want to try someone else's keybrd sketch, but your controller and matrix are different.
 So you replace two of your object instantiation files with your own:
 instantiations_ports.h
 instantiations_matrix.h

 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">keybrd tutorial</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd" property="cc:attributionName" rel="cc:attributionURL">Wolfram Volpi</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.