diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f30287..3c55311 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md index 6bc6649..0a8539f 100644 --- a/doc/CHANGELOG.md +++ b/doc/CHANGELOG.md @@ -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 diff --git a/doc/PLANNED_FEATURES.md b/doc/PLANNED_FEATURES.md index a469efe..45007f6 100644 --- a/doc/PLANNED_FEATURES.md +++ b/doc/PLANNED_FEATURES.md @@ -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) diff --git a/doc/keybrd_library_developer_guide.md b/doc/keybrd_library_developer_guide.md index 9bf7346..b912204 100644 --- a/doc/keybrd_library_developer_guide.md +++ b/doc/keybrd_library_developer_guide.md @@ -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()
-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.
Row_Ext_uC uses Scanner_uC to scan the primary matrix.
@@ -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 diff --git a/doc/keybrd_library_user_guide.md b/doc/keybrd_library_user_guide.md index c012dd1..7ba0e3d 100644 --- a/doc/keybrd_library_user_guide.md +++ b/doc/keybrd_library_user_guide.md @@ -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 diff --git a/src/Row_uC.h b/src/Row_uC.h index 8e4aa91..d94fe0c 100644 --- a/src/Row_uC.h +++ b/src/Row_uC.h @@ -5,7 +5,7 @@ #include #include -/* Row_uC is a row connected to a micro controller. +/* Row_uC is a row connected to a microcontroller. Instantiation ------------- diff --git a/tutorials/keybrd_2_single-layer/keybrd_2_single-layer.ino b/tutorials/keybrd_2_single-layer/keybrd_2_single-layer.ino index c65dd3e..0c87124 100644 --- a/tutorials/keybrd_2_single-layer/keybrd_2_single-layer.ino +++ b/tutorials/keybrd_2_single-layer/keybrd_2_single-layer.ino @@ -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. diff --git a/tutorials/tutorial_0_introduction.md b/tutorials/tutorial_0_introduction.md index 83ed1b3..2d0da0f 100644 --- a/tutorials/tutorial_0_introduction.md +++ b/tutorials/tutorial_0_introduction.md @@ -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
Creative Commons License
keybrd tutorial by Wolfram Volpi is licensed under a Creative Commons Attribution 4.0 International License.
Permissions beyond the scope of this license may be available at https://github.com/wolfv6/keybrd/issues/new. diff --git a/tutorials/tutorial_10_writing_your_own_port_classes.md b/tutorials/tutorial_10_writing_your_own_port_classes.md index 71824fc..6a1adea 100644 --- a/tutorials/tutorial_10_writing_your_own_port_classes.md +++ b/tutorials/tutorial_10_writing_your_own_port_classes.md @@ -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. diff --git a/tutorials/tutorial_1_breadboard_keyboard.md b/tutorials/tutorial_1_breadboard_keyboard.md index 8a0f8d7..6d0c85d 100644 --- a/tutorials/tutorial_1_breadboard_keyboard.md +++ b/tutorials/tutorial_1_breadboard_keyboard.md @@ -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. diff --git a/tutorials/tutorial_2_single-layer_keyboard.md b/tutorials/tutorial_2_single-layer_keyboard.md index a742203..5284acb 100644 --- a/tutorials/tutorial_2_single-layer_keyboard.md +++ b/tutorials/tutorial_2_single-layer_keyboard.md @@ -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 | +
Creative Commons License
keybrd tutorial by Wolfram Volpi is licensed under a Creative Commons Attribution 4.0 International License.
Permissions beyond the scope of this license may be available at https://github.com/wolfv6/keybrd/issues/new. diff --git a/tutorials/tutorial_3a_multi-layer_keyboard.md b/tutorials/tutorial_3a_multi-layer_keyboard.md index 23922ea..b1789aa 100644 --- a/tutorials/tutorial_3a_multi-layer_keyboard.md +++ b/tutorials/tutorial_3a_multi-layer_keyboard.md @@ -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 ------------------------ diff --git a/tutorials/tutorial_3b_autoShift.md b/tutorials/tutorial_3b_autoShift.md index 9d653b5..c4b36aa 100644 --- a/tutorials/tutorial_3b_autoShift.md +++ b/tutorials/tutorial_3b_autoShift.md @@ -23,7 +23,7 @@ Exercises | Layout | **0** | **1** | |:------:|:-----:|:-----:| | **0** | a ! 6 | b @ 7 | -| **1** |. sym .|. num .| +| **1** | sym |. num .|
Creative Commons License
keybrd tutorial by Wolfram Volpi is licensed under a Creative Commons Attribution 4.0 International License.
Permissions beyond the scope of this license may be available at https://github.com/wolfv6/keybrd/issues/new. diff --git a/tutorials/tutorial_5_LEDs.md b/tutorials/tutorial_5_LEDs.md index 85c1dcb..c23e562 100644 --- a/tutorials/tutorial_5_LEDs.md +++ b/tutorials/tutorial_5_LEDs.md @@ -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 diff --git a/tutorials/tutorial_8b_creating_and_publishing_your_own_keybrd_extension_library.md b/tutorials/tutorial_8b_creating_and_publishing_your_own_keybrd_extension_library.md index c35b4a3..24d52d9 100644 --- a/tutorials/tutorial_8b_creating_and_publishing_your_own_keybrd_extension_library.md +++ b/tutorials/tutorial_8b_creating_and_publishing_your_own_keybrd_extension_library.md @@ -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=* ``` diff --git a/tutorials/tutorial_9_breaking_up_a_sketch_into_smaller_files.md b/tutorials/tutorial_9_breaking_up_a_sketch_into_smaller_files.md index 7236d79..dcfad89 100644 --- a/tutorials/tutorial_9_breaking_up_a_sketch_into_smaller_files.md +++ b/tutorials/tutorial_9_breaking_up_a_sketch_into_smaller_files.md @@ -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
Creative Commons License
keybrd tutorial by Wolfram Volpi is licensed under a Creative Commons Attribution 4.0 International License.
Permissions beyond the scope of this license may be available at https://github.com/wolfv6/keybrd/issues/new.