improve tutorials
This commit is contained in:
wolfv6
parent
d0ad8ead81
commit
6978b038aa
@ -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>.
|
||||
|
||||
@ -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>.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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.
|
||||
*/
|
||||
|
||||
@ -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.
|
||||
|
||||
An I/O expander used on a matrix 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.
|
||||
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;
|
||||
|
||||
/*
|
||||
port1_R uses port 1 with an initial output value of 0.
|
||||
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.
|
||||
*/
|
||||
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);
|
||||
|
||||
@ -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>.
|
||||
|
||||
@ -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>.
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
|
||||
<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>.
|
||||
|
||||
@ -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>.
|
||||
|
||||
@ -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>.
|
||||
|
||||
@ -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>.
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
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 microcontroller and I/O expander communicate by [I2C](http://en.wikipedia.org/wiki/I%C2%B2C) via 4 jumper wires:
|
||||
* ground
|
||||
* power
|
||||
* Serial CLock input (SCL)
|
||||
* Serial DAta I/O (SDA)
|
||||
|
||||
The two resistors near the microcontroller pull-up voltage on the SCL and SDA pins.
|
||||
|
||||
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 are connected by 4 jumper wires:
|
||||
* ground
|
||||
* power
|
||||
* Serial CLock signal (SCL)
|
||||
* Serial DAta signal (SDA)
|
||||
|
||||
A capacitor on the power pin smooths power to the I/O expander.
|
||||
|
||||
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
|
||||
The split keyboard is built on the basic breadboard keyboard described in [tutorial_1_breadboard_keyboard.md](tutorial_1_breadboard_keyboard.md)
|
||||
|
||||
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 add schematic with a capacitor to IOE power
|
||||
This schematic was written by consulting the I/O expander's datasheet and using the ?? tool. -->
|
||||
|
||||
todo these tables might not match the sketch
|
||||
Continuing from the basic breadboard keyboard instructions:
|
||||
|
||||
**Teensy 2.0 pin connections tables**
|
||||
4. Insert the I/O expander
|
||||
|
||||
| Pin Number | Row Column |
|
||||
|------------|-------------|
|
||||
| 21 | row_R0 |
|
||||
| 20 | row_R1 |
|
||||
| 0 | col_R0 |
|
||||
| 1 | col_R1 |
|
||||
5. Install I/O expander power
|
||||
* ground
|
||||
* power
|
||||
* capacitor
|
||||
|
||||
| Pin Number | I2C |
|
||||
|------------|-------------|
|
||||
| GND | ground |
|
||||
| VCC | power |
|
||||
| 5 | SCL |
|
||||
| 6 | SDA |
|
||||
6. Install I2C bus
|
||||
* SCL
|
||||
* SDA
|
||||
* pull-up resistors on SCL and SDA
|
||||
|
||||
| Pin Number | 4.7K Ohms Pull-up Resistor |
|
||||
|------------|-------------|
|
||||
| 5 | VCC |
|
||||
| 6 | VCC |
|
||||
7. configure I2C address
|
||||
|
||||
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)
|
||||
8. Assemble key matrix as shown in the picture.
|
||||
|
||||
**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
|
||||
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>.
|
||||
|
||||
@ -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>.
|
||||
|
||||
@ -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>.
|
||||
|
||||
@ -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>.
|
||||
|
||||
Reference in New Issue
Block a user