keybrd/tutorials/tutorial_1_breadboard_keyboard.md

Tutorial 1 - breadboard keyboard
================================
In this tutorial, you will build a breadboard keyboard with 4 keys.
The keyboad will be used in tutorials 2 through 7.

When you finish this tutorial you will have a working keyboard and an understanding of how a key matrix works.

Why a solderless breadboard keyboard is useful
----------------------------------------------
Breadboard keyboards have key matrices and diodes just like the big keyboards.

A breadboard is the easiest way to learn keyboard electronics.
Learning is fun when mistakes are easily corrected.
Compared to PCBs, breadboard keyboards make learning faster because:
* Mistakes are easily corrected; no soldering and desoldering
* Parts can be reused in many different configurations
* A small keyboard is easier to trouble shoot

Breadboard keyboards are useful for:
* learning keyboard electronics - microcontroller, key matrix, diode, shift registers, I/O expander
* learning the keyboard-development workflow
* prototyping circuits before making a PCB

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 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, lead-forming tool, and Anti-static mat are optional.

How a breadboard works
----------------------
To understand the breadboard keyboard you will need to know the internal parts of a breadboard:
* bus strip
* terminal strip

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 ICs in ways that are hard to trouble shoot.

Here is a ESD precaution for handling ICs:

1. Touch the bare metal on the back of my desktop computer (its grounded).
2. Then touch the IC or circuit (if its a micro-controller, touch the metal USB connector case).

I take these ESD precaution because I live in a dry environment on a carpeted floor.
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

Anti-static mat or anti-static wristband are also effective.
But being tethered by an anti-static wristband can be inconvenient (wireless antistatic wrist straps are a scam).

Building a basic breadboard keyboard
------------------------------------
The basic breadboard keyboard has 4 switches.

![basic breadboard keyboard](keybrd_1_breadboard/basic_breadboard_keyboard_front.JPG "basic breadboard keyboard")

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.
Short wires connect terminal strips into matrix columns.
Jumper wires connect the columns to the microcontroller.

Two bus strips are used as matrix rows.
A jumper connects the top row to the microcontroller.
A short wire connects the bottom row to the microcontroller.

A switches and diodes connect rows to columns.

Tutorials 2 and 3 use the same basic breadboard keyboard pictured above.
Tutorials 4, 5, and 6 add more components to the basic breadboard keyboard.
Positioning components as shown in the picture will provide space for those components.

Breadboard keyboard assembly instructions:

1. Shape leads to fit breadboard.
  * cut tactile-switch leads to length
  * bend and cut diode leads (save the cut offs for steps 2, 3, and tutorial 4)

 ![bend diodes](keybrd_1_breadboard/diodes_bend_en_masse.JPG "bend diodes")

 ![cut diodes](keybrd_1_breadboard/diodes_cut.JPG "cut diodes")

2. Insert parts into the breadboard as shown in the picture.
  * The breadboard is oriented with the red bus strips on top and blue bus strips on the bottom
   (this is important because tutorials will refer to the "red bus" and the "blue bus")
  * 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 rows; orient diodes with cathode (banded end) towards the rows (blue bus)

 ![switch orientation](keybrd_1_breadboard/switch_orientation.JPG "switch orientation")

 ![basic breadboard keyboard overhead](keybrd_1_breadboard/basic_breadboard_keyboard_overhead.JPG "basic breadboard keyboard overhead")

3. Insert jumper wires to connect Arduino pins to the matrix rows and columns.
  * refer to the [Teensy LC pinout diagram](https://www.pjrc.com/teensy/card6a_rev2.png).
  * row_0 is the top row, and col_0 is the left column

| Pin number | Connects to |
|------------|-------------|
|  0         | row_0       |
|  1         | row_1       |
| 14         | col_0       |
| 15         | 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.

Compile and load the [keybrd_1_breadboard.ino](/tutorials/keybrd_1_breadboard/keybrd_1_breadboard.ino) sketch into the keyboard's controller.
The operating system will take 1 to 6 seconds to recognize the USB keyboard.
Then pressing the keys should type the characters 1, 2, a, b.
Congratulations, you have a working keyboard.

How a key matrix works
----------------------
Now we fill in some details of how it all works.

This excellent article explains how key matrix, diodes, and ghosting work:
[How a Key Matrix Work](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/)

In the article:

> 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.

The keybrd library uses the word "strobe", which means powering one row for a very short time.
Strobe pins are output pins connected to rows.
One row at a time is strobed.
While a row is strobed, input pins connected to the columns sense which buttons are pressed.

Exercises
---------
1) replace the diodes with wires (cutoffs) and intentionally cause ghosting.

<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>.
document 2016-05-10 15:05:25 +00:00			`Tutorial 1 - breadboard keyboard`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00			`================================`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`In this tutorial, you will build a breadboard keyboard with 4 keys.`
			`The keyboad will be used in tutorials 2 through 7.`

update diagrams and tutorials: 0 1 2 3a 2016-09-17 05:45:12 +00:00			`When you finish this tutorial you will have a working keyboard and an understanding of how a key matrix works.`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`Why a solderless breadboard keyboard is useful`
			`----------------------------------------------`
			`Breadboard keyboards have key matrices and diodes just like the big keyboards.`
document 2016-05-10 17:15:47 +00:00
			`A breadboard is the easiest way to learn keyboard electronics.`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`Learning is fun when mistakes are easily corrected.`
			`Compared to PCBs, breadboard keyboards make learning faster because:`
improve tutorials 2016-05-11 15:25:48 +00:00			`* Mistakes are easily corrected; no soldering and desoldering`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00			`* Parts can be reused in many different configurations`
			`* A small keyboard is easier to trouble shoot`

			`Breadboard keyboards are useful for:`
document and format 2016-07-22 08:11:38 +00:00			`* learning keyboard electronics - microcontroller, key matrix, diode, shift registers, I/O expander`
rename LED_IOE to LED_Port, update tutorials and sketches 2016-09-28 19:56:10 +00:00			`* learning the keyboard-development workflow`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00			`* prototyping circuits before making a PCB`
improve tutorials 2016-05-11 15:25:48 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`Breadboard keyboard starter kit`
			`-------------------------------`
document and format 2016-07-22 08:11:38 +00:00			`The parts needed to build the tutorial breadboard keyboards are listed in [breadboard_keyboard_supplies.ods](breadboard_keyboard_supplies.ods).`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00
document and format 2016-07-22 08:11:38 +00:00			`The tutorials use a Teensy LC controller, but any Arduino-compatible controller with at least 2 KB SRAM should work.`
improve tutorials 2016-05-11 15:25:48 +00:00
change activeHigh to static, add LED_PinNumber, RowScanner_SPI-ShiftRegisters, keybrd regression tests, remove MCP23018::begin() 2016-06-18 22:32:21 +00:00			`You will need two tools:`
move Debug variables to static 2016-07-18 02:26:00 +00:00			`* Wire cutters`
change activeHigh to static, add LED_PinNumber, RowScanner_SPI-ShiftRegisters, keybrd regression tests, remove MCP23018::begin() 2016-06-18 22:32:21 +00:00			`* A multi-meter for trouble shooting`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
document and format 2016-07-22 08:11:38 +00:00			`Wire striper, lead-forming tool, and Anti-static mat are optional.`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`How a breadboard works`
			`----------------------`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00			`To understand the breadboard keyboard you will need to know the internal parts of a breadboard:`
change activeHigh to static, add LED_PinNumber, RowScanner_SPI-ShiftRegisters, keybrd regression tests, remove MCP23018::begin() 2016-06-18 22:32:21 +00:00			`* bus strip`
document 2016-05-10 17:15:47 +00:00			`* terminal strip`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
			`These are explained in [How to Use a Breadboard](https://learn.sparkfun.com/tutorials/how-to-use-a-breadboard)`

document and format 2016-07-22 08:11:38 +00:00			`Electrostatic discharge (ESD) safety`
			`------------------------------------`
add sr0_LED_shiftRegs.ino, LED_shiftRegs, LED_shiftRegs 2016-10-30 08:30:13 +00:00			`Static electricity can damage a ICs in ways that are hard to trouble shoot.`
document and format 2016-07-22 08:11:38 +00:00
add sr0_LED_shiftRegs.ino, LED_shiftRegs, LED_shiftRegs 2016-10-30 08:30:13 +00:00			`Here is a ESD precaution for handling ICs:`
document and format 2016-07-22 08:11:38 +00:00
			`1. Touch the bare metal on the back of my desktop computer (its grounded).`
add sr0_LED_shiftRegs.ino, LED_shiftRegs, LED_shiftRegs 2016-10-30 08:30:13 +00:00			`2. Then touch the IC or circuit (if its a micro-controller, touch the metal USB connector case).`
document and format 2016-07-22 08:11:38 +00:00
add sr0_LED_shiftRegs.ino, LED_shiftRegs, LED_shiftRegs 2016-10-30 08:30:13 +00:00			`I take these ESD precaution because I live in a dry environment on a carpeted floor.`
document and format 2016-07-22 08:11:38 +00:00			`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`

add sr0_LED_shiftRegs.ino, LED_shiftRegs, LED_shiftRegs 2016-10-30 08:30:13 +00:00			`Anti-static mat or anti-static wristband are also effective.`
			`But being tethered by an anti-static wristband can be inconvenient (wireless antistatic wrist straps are a scam).`

move Debug variables to static 2016-07-18 02:26:00 +00:00			`Building a basic breadboard keyboard`
			`------------------------------------`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`The basic breadboard keyboard has 4 switches.`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
rename LED_IOE to LED_Port, update tutorials and sketches 2016-09-28 19:56:10 +00:00			`![basic breadboard keyboard](keybrd_1_breadboard/basic_breadboard_keyboard_front.JPG "basic breadboard keyboard")`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
document and format 2016-07-22 08:11:38 +00:00			`A Teensy LC microcontroller is on the left.`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`A key matrix with 4 switches is to the right.`

			`The key matrix has two two columns.`
document 2016-07-15 05:15:38 +00:00			`Short wires connect terminal strips into matrix columns.`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`Jumper wires connect the columns to the microcontroller.`

move Debug variables to static 2016-07-18 02:26:00 +00:00			`Two bus strips are used as matrix rows.`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`A jumper connects the top row to the microcontroller.`
			`A short wire connects the bottom row to the microcontroller.`

rename LED_IOE to LED_Port, update tutorials and sketches 2016-09-28 19:56:10 +00:00			`A switches and diodes connect rows to columns.`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
update diagrams and tutorials: 0 1 2 3a 2016-09-17 05:45:12 +00:00			`Tutorials 2 and 3 use the same basic breadboard keyboard pictured above.`
			`Tutorials 4, 5, and 6 add more components to the basic breadboard keyboard.`
move Debug variables to static 2016-07-18 02:26:00 +00:00			`Positioning components as shown in the picture will provide space for those components.`
document 2016-06-05 20:43:53 +00:00
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00			`Breadboard keyboard assembly instructions:`

update diagrams and tutorials: 0 1 2 3a 2016-09-17 05:45:12 +00:00			`1. Shape leads to fit breadboard.`
			`* cut tactile-switch leads to length`
			`* bend and cut diode leads (save the cut offs for steps 2, 3, and tutorial 4)`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`![bend diodes](keybrd_1_breadboard/diodes_bend_en_masse.JPG "bend diodes")`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`![cut diodes](keybrd_1_breadboard/diodes_cut.JPG "cut diodes")`
improve tutorials 2016-05-11 15:25:48 +00:00
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`2. Insert parts into the breadboard as shown in the picture.`
move Debug variables to static 2016-07-18 02:26:00 +00:00			`* The breadboard is oriented with the red bus strips on top and blue bus strips on the bottom`
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`(this is important because tutorials will refer to the "red bus" and the "blue bus")`
move Debug variables to static 2016-07-18 02:26:00 +00:00			`* 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`
rename LED_IOE to LED_Port, update tutorials and sketches 2016-09-28 19:56:10 +00:00			`* diodes connect switches to rows; orient diodes with cathode (banded end) towards the rows (blue bus)`
move Debug variables to static 2016-07-18 02:26:00 +00:00
			`![switch orientation](keybrd_1_breadboard/switch_orientation.JPG "switch orientation")`
improve tutorials 2016-05-11 18:46:53 +00:00
rename LED_IOE to LED_Port, update tutorials and sketches 2016-09-28 19:56:10 +00:00			`![basic breadboard keyboard overhead](keybrd_1_breadboard/basic_breadboard_keyboard_overhead.JPG "basic breadboard keyboard overhead")`
improve tutorials 2016-05-11 15:25:48 +00:00
update tutorials 0 to 6 2016-07-18 02:03:03 +00:00			`3. Insert jumper wires to connect Arduino pins to the matrix rows and columns.`
fix broken link and formatting 2016-09-28 21:44:44 +00:00			`* refer to the [Teensy LC pinout diagram](https://www.pjrc.com/teensy/card6a_rev2.png).`
move Debug variables to static 2016-07-18 02:26:00 +00:00			`* row_0 is the top row, and col_0 is the left column`

			`\| Pin number \| Connects to \|`
			`\|------------\|-------------\|`
			`\| 0 \| row_0 \|`
			`\| 1 \| row_1 \|`
			`\| 14 \| col_0 \|`
			`\| 15 \| 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.`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`Compile and load the [keybrd_1_breadboard.ino](/tutorials/keybrd_1_breadboard/keybrd_1_breadboard.ino) sketch into the keyboard's controller.`
			`The operating system will take 1 to 6 seconds to recognize the USB keyboard.`
update diagrams and tutorials: 0 1 2 3a 2016-09-17 05:45:12 +00:00			`Then pressing the keys should type the characters 1, 2, a, b.`
			`Congratulations, you have a working keyboard.`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`How a key matrix works`
			`----------------------`
			`Now we fill in some details of how it all works.`

			`This excellent article explains how key matrix, diodes, and ghosting work:`
			`[How a Key Matrix Work](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/)`

			`In the article:`

document and format 2016-07-22 08:11:38 +00:00			`> Output pins power columns and input pins detect the power on rows.`
move Debug variables to static 2016-07-18 02:26:00 +00:00
			`The breadboard keyboards in this series of tutorials do it the other way:`

document and format 2016-07-22 08:11:38 +00:00			`> Output pins power rows and input pins detect the power on columns.`
move Debug variables to static 2016-07-18 02:26:00 +00:00
update diagrams and tutorials: 0 1 2 3a 2016-09-17 05:45:12 +00:00			`The keybrd library uses the word "strobe", which means powering one row for a very short time.`
move Debug variables to static 2016-07-18 02:26:00 +00:00			`Strobe pins are output pins connected to rows.`
rename LED_IOE to LED_Port, update tutorials and sketches 2016-09-28 19:56:10 +00:00			`One row at a time is strobed.`
			`While a row is strobed, input pins connected to the columns sense which buttons are pressed.`
initial commit keybrd version 0.3.0 2016-05-09 14:05:08 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`Exercises`
			`---------`
			`1) replace the diodes with wires (cutoffs) and intentionally cause ghosting.`
improve tutorials 2016-05-11 15:25:48 +00:00
move Debug variables to static 2016-07-18 02:26:00 +00:00			`<br>`
fix broken links 2016-07-21 20:20:07 +00:00			<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>.