di0ib
/
keybrd
Watch 1
Star 0
Fork 0
Code Releases 7 Activity
Browse Source

document and format

tags/v0.5.0
wolfv6 7 years ago
parent
f5e4c5fd3a
commit
36d0ed3579
16 changed files with 69 additions and 49 deletions
Split View Show Diff Stats
  1. 1
    1
      CONTRIBUTING.md
  2. 2
    2
      doc/CHANGELOG.md
  3. 6
    5
      doc/PLANNED_FEATURES.md
  4. 6
    5
      doc/keybrd_library_developer_guide.md
  5. 10
    15
      doc/keybrd_library_user_guide.md
  6. 1
    1
      src/Row_uC.h
  7. 1
    1
      tutorials/keybrd_2_single-layer/keybrd_2_single-layer.ino
  8. 3
    3
      tutorials/tutorial_0_introduction.md
  9. 1
    0
      tutorials/tutorial_10_writing_your_own_port_classes.md
  10. 25
    8
      tutorials/tutorial_1_breadboard_keyboard.md
  11. 7
    2
      tutorials/tutorial_2_single-layer_keyboard.md
  12. 1
    1
      tutorials/tutorial_3a_multi-layer_keyboard.md
  13. 1
    1
      tutorials/tutorial_3b_autoShift.md
  14. 1
    1
      tutorials/tutorial_5_LEDs.md
  15. 1
    1
      tutorials/tutorial_8b_creating_and_publishing_your_own_keybrd_extension_library.md
  16. 2
    2
      tutorials/tutorial_9_breaking_up_a_sketch_into_smaller_files.md

+ 1
- 1
CONTRIBUTING.md View File

@@ -36,7 +36,7 @@ Git commit message style guide:
* Limit the first line to 72 characters summary
* Second line should be empty, followed by body of the commit message
* Use the imperative present tense (use "Add feature", not "Added feature", not "Adds feature")
* Reference an improvement suggestion or bug report
* Reference an improvement suggestion, bug report, or planned_features
* Sometimes a bulleted list is a good format to convey the changes of a commit
User contributions

+ 2
- 2
doc/CHANGELOG.md View File

@@ -40,7 +40,7 @@ keybrd version 1.0.0 will be released when the public API is stable.
* Backward incompatible changes
* Change uC from scanning port arrays to scanning Arduino pins, thereby adding support for:
* Arduino boards, Teensy 3, and Teensy LC micro controllers
* Arduino boards, Teensy 3, and Teensy LC microcontrollers
* up to 31x31 matrix capability
* Change IOE from scanning port arrays to scanning single ports.
* Move scanner and debouncer into their own classes.
@@ -66,7 +66,7 @@ keybrd version 1.0.0 will be released when the public API is stable.
0.2.0 (2016-02-25)
------------------
* Enhancements
* Add Port classes for micro-controllers and I/O expanders
* Add Port classes for microcontrollers and I/O expanders
* Add DH_2565 sketch with DataHand layout
* Add Sticky mouse button (SMB) for DataHand layout
* Add Supporting documentation

+ 6
- 5
doc/PLANNED_FEATURES.md View File

@@ -1,14 +1,15 @@
planned_features is a view of where the keybrd project is headed.
Top priority
============
------------
* Beta testing
* Schematics for tutorials
* Add breadboard keyboard schematics to tutorials
Medium priority
===============
---------------
* Add matrix-to-layout mapping array (to decouple key matrix from layout)
* Add tutorial_4b_split_keyboard_with_shift_registers
Low priority
============
* MCP23S18 I/O expander with Serial Peripheral Interface (SPI)
------------
* Add MCP23S18 I/O expander with Serial Peripheral Interface (SPI)

+ 6
- 5
doc/keybrd_library_developer_guide.md View File

@@ -9,22 +9,21 @@ The most common reason for adding new classes are:
Who this guide is for
---------------------
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, aggregation, inheritance, polymorphism, and enum.
It is assumed the reader is familiar with the C++ language including pointers, objects, classes, static class variables, composition, aggregation, inheritance, polymorphism, and enum.
Row, Scanner, and Debouncer classes use bit manipulation.
Custom Row classes
------------------
Row classes are central to the keybrd library.
Row is an abstract base class that allows flexibility for designing derived Row classes:
Row is an abstract base class that allows flexibility in designing derived Row classes:
* Row functions can be overridden in a derived class
* choice of Debouncers
* choice of Scanners
This example illustrates the custom Row classes for a fictional keybrd_Ext extension library.
The keybrd_Ext library is for a split keyboard with sticky keys and a matrix on each hand.
The keybrd_Ext library is for a split keyboard with a matrix on each hand and sticky keys.
Row_Ext::keyWasPressed() overrides Row::keyWasPressed()<br>
Row_Ext::keyWasPressed() is used to unstick sticky keys
Row_Ext::keyWasPressed() overrides Row::keyWasPressed() which is used to unstick sticky keys.
Row_Ext_uC and Row_Ext_ShiftRegisters are a custom classes composed of stock keybrd library classes.<br>
Row_Ext_uC uses Scanner_uC to scan the primary matrix.<br>
@@ -189,6 +188,8 @@ Underscore delineates base class name and sub-class name. Capital letters delin
Layer-class naming conventions
------------------------------
Layer classes are explained in [tutorial_3a_multi-layer_keyboard.md](../tutorials/tutorial_3a_multi-layer_keyboard.md).
*Code_Layer* class names are concatenations of "Code_", "Layer" or layer name, and persistence.
Example persistences are:
* "Lock" - layer remains active after the layer key is released

+ 10
- 15
doc/keybrd_library_user_guide.md View File

@@ -21,13 +21,9 @@ keybrd sketches use keybrd classes, objects pointers, aggregation, and static cl
Microcontroller board requirements
----------------------------------
The keybrd library works with Teensy and Arduino compatible boards.
The keybrd library works with Teensy and Arduino compatible boards with at least 2 KB SRAM.
[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 keybrd_DH sketch.
Teensy LC is preferred over the older Teensy 2.0 for it's larger memory capacity and lower price.
[Teensy LC](https://www.pjrc.com/teensy/teensyLC.html) is the preferred board for the keybrd library and is used in the tutorials. Teensy LC has 8 KB SRAM, which is enough memory for any keyboard.
Getting started with Teensy, Arduino IDE, and keybrd
----------------------------------------------------
@@ -42,7 +38,7 @@ 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 install and setup steps create an Arduino development environment for keybrd sketches.
The following steps create an Arduino development environment for keybrd sketches.
### Install Arduino IDE and Teensyduino
The following install steps are modified from the [Teensyduino download page](https://www.pjrc.com/teensy/td_download.html).
@@ -90,10 +86,9 @@ keybrd extension library names are prefixed with "keybrd_".
Instructions for installing Arduino libraries are at: http://www.arduino.cc/en/Guide/Libraries
A Sketchbook is a folder that the Arduino IDE uses to store sketches and libraries.
The default location for Arduino libraries is ~/Documents/Arduino/libraries/.
For example, the DodoHand keyboard requires the core keybrd library and the keybrd_DH extension library.
For example, the DodoHand keyboard requires the core keybrd library and the keybrd_DH extension library be installed.
After installing the libraries, my Arduino directory looks like this:
* ~/Documents/Arduino/libraries/keybrd/
* ~/Documents/Arduino/libraries/keybrd_DH/
@@ -138,7 +133,7 @@ The example sketch names use the following conventions.
where
* **keybrd** is the library name e.g. keybrd, keybrd_DH
* **feature** is a distinguishing feature of the keybrd sketch e.g. keyboard name, sound, Dvorak
* **feature** is a distinguishing feature of the keybrd sketch e.g. keyboard name, sound, layout
* **version** is the sketch's version number (optional)
Active state and diode orientation
@@ -149,7 +144,7 @@ The following instructions are for setting active state for a Scanner_uC class
For active low:
* Orient diodes with cathode (banded end) towards the write pins (row)
* Use these two lines in the sketch:
* Define strobe on and strobe off in the sketch like this:
```
const bool Scanner_uC::STROBE_ON = LOW;
const bool Scanner_uC::STROBE_OFF = HIGH;
@@ -158,7 +153,7 @@ For active low:
For active high:
* Add an external 10k pull-down resistor to each read pin.
* Orient diodes with cathode (banded end) towards the read pins.
* Use these two lines in the sketch:
* Define strobe on and strobe off in the sketch like this:
```
const bool Scanner_uC::STROBE_ON = HIGH;
const bool Scanner_uC::STROBE_OFF = LOW;
@@ -175,7 +170,7 @@ Development-environment items to check:
'KEY_A' was not declared in this scope
```
Where 'KEY_A' could be any scan code.
Fix this from the Arduino IDE tool bar: Tools > USB Type > Keyboard + Mouse + Joystick
Fix this error from the Arduino IDE tool bar: Tools > USB Type > Keyboard + Mouse + Joystick
Sketch items to check:
* For each row, number of read pins in Row should equal number of keys.
@@ -191,9 +186,9 @@ In this example, row_0 has 2 read pins and 2 keys:
* For multi-layered keyboards, the number of codes in each Key_Layered should equal the number of layers.
Hardware items to check:
* Connections
* Diode orientation
* Continuity of connections
* 3.3 or 5 volts across power and ground
* Diode orientation
* To validate keyboard hardware, modify the simple [keybrd_1_breadboard.ino](../tutorials/keybrd_1_breadboard/keybrd_1_breadboard.ino) sketch.
Keybrd nomenclature

+ 1
- 1
src/Row_uC.h View File

@@ -5,7 +5,7 @@
#include <Scanner_uC.h>
#include <Debouncer_Samples.h>

/* Row_uC is a row connected to a micro controller.
/* Row_uC is a row connected to a microcontroller.

Instantiation
-------------

+ 1
- 1
tutorials/keybrd_2_single-layer/keybrd_2_single-layer.ino View File

@@ -46,7 +46,7 @@ const bool Scanner_uC::STROBE_ON = LOW; //set scanner for active low
const bool Scanner_uC::STROBE_OFF = HIGH;

/* ================= PINS =================
Micro-controller 14 and 15 are connected to the matrix columns.
Microcontroller 14 and 15 are connected to the matrix columns.
These readPins detect which keys are pressed while a row is strobed.

sizeof() is used to compute the number of array elements.

+ 3
- 3
tutorials/tutorial_0_introduction.md View File

@@ -1,8 +1,8 @@
Tutorial 0 - Introduction
=========================
The first two tutorials are intended to be read in sequence:
* Tutorial 1 builds a breadboard keyboard
* Tutorial 2 covers basic keyboard knowledge needed to understand the remaining tutorials.
* Tutorial 1 builds a breadboard keyboard and covers basic keyboard-hardware knowledge.
* Tutorial 2 covers basic keybrd sketch knowledge needed to understand the remaining tutorials.

Tutorials from 3 up can be read in any order.
Tutorials 2 through 7 use the keyboard breadboard that was built in tutorial 1.
@@ -10,7 +10,7 @@ Tutorials from 8 up are advance topics about the keybrd library.

The tutorials assume the reader:
* is familiar with C++
* is new to Arduino, firmware, controllers, and the internal workings of keyboards
* is new to Arduino, firmware, microcontrollers, and the internal workings of keyboards

<br>
<a rel="license" href="https://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/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="https://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="https://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="https://creativecommons.org/ns" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.

+ 1
- 0
tutorials/tutorial_10_writing_your_own_port_classes.md View File

@@ -3,6 +3,7 @@ Tutorial 10 - writing your own port classes
Port classes are the keybrd library's interface to I/O expander ports.

To write your own port classes:

1. Get a copy of the controller or I/O expander datasheet.
2. Study other keybrd Port classes.


+ 25
- 8
tutorials/tutorial_1_breadboard_keyboard.md View File

@@ -17,7 +17,7 @@ Compared to PCBs, breadboard keyboards make learning faster because:
* A small keyboard is easier to trouble shoot
Breadboard keyboards are useful for:
* learning keyboard electronics - micro controller, key matrix, diode, shift registers, I/O expander
* learning keyboard electronics - microcontroller, key matrix, diode, shift registers, I/O expander
* learning the firmware development workflow
* prototyping circuits before making a PCB
@@ -25,15 +25,15 @@ Arduino simulation software is an alternative to breadboards; I haven't tried th
Breadboard keyboard starter kit
-------------------------------
The parts needed to build the tutorial Breadboard Keyboards are listed in [breadboard_keyboard_supplies.ods](breadboard_keyboard_supplies.ods).
The parts needed to build the tutorial breadboard keyboards are listed in [breadboard_keyboard_supplies.ods](breadboard_keyboard_supplies.ods).
The tutorials use a Teensy LC controller, but any Arduino-compatible controller with SRAM should work.
The tutorials use a Teensy LC controller, but any Arduino-compatible controller with at least 2 KB SRAM should work.
You will need two tools:
* Wire cutters
* A multi-meter for trouble shooting
Wire striper and lead forming tool are optional.
Wire striper, lead-forming tool, and Anti-static mat are optional.
How a breadboard works
----------------------
@@ -43,13 +43,30 @@ 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)
Electrostatic discharge (ESD) safety
------------------------------------
Static electricity can damage a microcontroller in ways that are hard to trouble shoot.
I live in a desert on a carpeted floor and get zapped by door knobs regularly.
Whenever I handle microcontrollers I:
1. Touch the bare metal on the back of my desktop computer (its grounded).
2. Then while still touching to the computer, touch the metal USB connector case on the microcontroller.
Anti-static mat or anti-static wristband are also effective.
Being tethered by an anti-static wristband can be inconvenient (wireless antistatic wrist straps are a scam).
Not everyone needs to take ESD precautions:
* http://forum.arduino.cc/index.php?topic=4643.0
* https://forums.adafruit.com/viewtopic.php?f=8&t=12128
Building a basic breadboard keyboard
------------------------------------
The basic breadboard keyboard has 4 switches.
![basic breadboard keyboard](keybrd_1_breadboard/breadboard_keyboard_2x2.JPG "basic breadboard keyboard")
A Teensy LC microcontroller in on the left.
A Teensy LC microcontroller is on the left.
A key matrix with 4 switches is to the right.
The key matrix has two two columns.
@@ -82,7 +99,7 @@ Breadboard keyboard assembly instructions:
* Teensy LC is on the left
* switch leads are oriented to connect diodes to columns (pictured below)
* diode cut offs connect terminal strips into columns
* diodes connect switches to blue buses, orient with cathode (banded end) towards the row (bus strip)
* diodes connect switches to blue buses; orient diodes with cathode (banded end) towards the row (bus strip)
![switch orientation](keybrd_1_breadboard/switch_orientation.JPG "switch orientation")
@@ -117,11 +134,11 @@ This excellent article explains how key matrix, diodes, and ghosting work:
In the article:
output pins power columns and input pins detect the power on rows.
> Output pins power columns and input pins detect the power on rows.
The breadboard keyboards in this series of tutorials do it the other way:
output pins power rows and input pins detect the power on columns.
> Output pins power rows and input pins detect the power on columns.
The keybrd library uses the word "strobe".
Strobe pins are output pins connected to rows.

+ 7
- 2
tutorials/tutorial_2_single-layer_keyboard.md View File

@@ -10,10 +10,15 @@ After reading the sketch you will be able to modify it to suite your own single-
Exercises
---------
1) Read some of the class definitions used in the sketch.
The classes are defined in the [keybrd library](../src/).
1) Read the three class definitions #included in the sketch.
Classes are defined in the [keybrd library](../src/).
2) Add a third column to the breadboard keyboard and sketch.
| Layout |**0**|**1**|**2**|
|:------:|:---:|:---:|:---:|
| **0** | k | e | y |
| **1** | b | r | d |
<br>
<a rel="license" href="https://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/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="https://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="https://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="https://creativecommons.org/ns" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.

+ 1
- 1
tutorials/tutorial_3a_multi-layer_keyboard.md View File

@@ -1,6 +1,6 @@
Tutorial 3a - multi-layer keyboard
==================================
When you finish this tutorial you will be able to be able to modify a multi-layer keybrd sketch to write your very own multi-layer keyboard design.
When you finish this tutorial you will be able to be able to modify a multi-layer keybrd sketch to write your very own multi-layer keyboard firmware.
Multi-layer nomenclature
------------------------

+ 1
- 1
tutorials/tutorial_3b_autoShift.md View File

@@ -23,7 +23,7 @@ Exercises
| Layout | **0** | **1** |
|:------:|:-----:|:-----:|
| **0** | a ! 6 | b @ 7 |
| **1** |. sym .|. num .|
| **1** | sym |. num .|
<br>
<a rel="license" href="https://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/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="https://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="https://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="https://creativecommons.org/ns" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.

+ 1
- 1
tutorials/tutorial_5_LEDs.md View File

@@ -79,7 +79,7 @@ Exercises
---------
1) In this exercise you will calculate the minimum current limiting resistance needed for your output pin and LED.

For your micro controller, find:
For your microcontroller, find:
* Supply Voltage coming out of the output pins
* Current (mA) capacity of the output pins


+ 1
- 1
tutorials/tutorial_8b_creating_and_publishing_your_own_keybrd_extension_library.md View File

@@ -73,7 +73,7 @@ Example library.properties file:
sentence=An extension to the keybrd library for the MyKeyboard.
paragraph=This library demonstrates my feature.
category=Device Control
url= (github repo URL for keybrd_MyKeyboard)
url= (instert your github repo URL for keybrd_MyKeyboard)
architectures=*
```


+ 2
- 2
tutorials/tutorial_9_breaking_up_a_sketch_into_smaller_files.md View File

@@ -24,8 +24,8 @@ You have three versions of LED indicators you are experimenting with:
Example 2.
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_colemak.h
* instantiations_matrix_QWERTY.h
* instantiations_rows_colemak.h
* instantiations_rows_QWERTY.h

<br>
<a rel="license" href="https://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/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="https://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="https://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="https://creativecommons.org/ns" href="https://github.com/wolfv6/keybrd/issues/new" rel="cc:morePermissions">https://github.com/wolfv6/keybrd/issues/new</a>.