From e84db1c61c5a61f919f90ac464dc279911ee0f65 Mon Sep 17 00:00:00 2001 From: wolfv6 Date: Fri, 4 Nov 2016 00:56:26 -0600 Subject: [PATCH] document --- CONTRIBUTING.md | 15 +++----- doc/PLANNED_FEATURES.md | 8 ++--- src/Scanner_ShiftRegsRead.h | 36 +++++++++++-------- src/Scanner_ShiftRegsReadStrobed.h | 34 +++++++++++------- .../tutorial_4_connecting_split_keyboards.md | 2 +- ..._4b_split_keyboard_with_shift_registers.md | 2 +- 6 files changed, 52 insertions(+), 45 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af65f4d..e794407 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,10 @@ Code contributions Unsure of where to begin contributing to keybrd code? You can start by looking through the improvement suggestions, bug reports, and [planned_features](doc/planned_features.md). +Scratch your own itch. Code for your own need. Then share it with the keybrd community. +* [Tutorial 8b - sharing your keybrd extension library](tutorials/tutorial_8b_sharing_your_keybrd_extension_library.md) +* [Tutorial 8c - sharing your keybrd sketch](tutorials/tutorial_8c_sharing_your_keybrd_sketch.md) + 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 @@ -95,17 +99,6 @@ If you prefer your answers remain confidential, pm the completed Q & A to [wolfv Usability survey results will be used to make improvements to the keybrd library. -### Schematics -The most glaring deficiency is the tutorials' lack of schematics. -Schematics would be easier to read than the current photos. - -Schematics are not my area of expertise. Use what ever would be the best solution for the tutorials: -* schematics -* breadboard drawings -* Arduino simulation software - -Contributions of tutorial schematics would benefit users new to the keybrd library. - ### Documentation Suggest a clarification, simplification, correction, or other improvement. We need the perspective of people new to the project to see these things. diff --git a/doc/PLANNED_FEATURES.md b/doc/PLANNED_FEATURES.md index 7e5b99a..db6bdb0 100644 --- a/doc/PLANNED_FEATURES.md +++ b/doc/PLANNED_FEATURES.md @@ -2,12 +2,12 @@ planned_features is a view of where the keybrd project is headed. Top priority ------------ -* User testing - -Medium priority ---------------- * Add matrix-to-layout mapping (to decouple key matrix from layout) * Add breadboard keyboard schematics to tutorials +Medium priority +--------------- +* Getting user feedback + Low priority ------------ diff --git a/src/Scanner_ShiftRegsRead.h b/src/Scanner_ShiftRegsRead.h index 3ba223c..7f1060f 100644 --- a/src/Scanner_ShiftRegsRead.h +++ b/src/Scanner_ShiftRegsRead.h @@ -1,5 +1,5 @@ -#ifndef ROWSCANNER_SHIFTREGSPISOSINGLEROW_H -#define ROWSCANNER_SHIFTREGSPISOSINGLEROW_H +#ifndef ROWSCANNER_SHIFTREGSREAD_H +#define ROWSCANNER_SHIFTREGSREAD_H #include #include @@ -8,29 +8,33 @@ #include /* Scanner_ShiftRegsRead reads shift registers. -This was tested on 74HC165 shift registers, which are Parallel-In-Serial-Out (PISO). Upto 4 shift registers can be in a daisy chained for a total of 32 read pins. +This was tested on 74HC165 shift registers, which are Parallel-In-Serial-Out (PISO). + +The row is always powered (there is no strobe that turns off). Example instantiation: Row row_R0(scanner_R, 0, ptrsKeys_R0, sizeof(ptrsKeys_R0)/sizeof(*ptrsKeys_R0)); - Scanner_ShiftRegsRead scanner_R(HIGH, SS, 4); + Scanner_ShiftRegsRead scanner_R(HIGH, 6, 4); -The Row "strobePin" parameter is ignored. -In the above example, the "strobePin" argument is 0, but it doesn't matter what value is given. +In the above Row instantiation, argument 0 for "strobePin" is ignored because there is no strobe. There are three Scanner_ShiftRegsRead parameters. -"strobeOn" paramter is ignored, but should be active state HIGH or LOW required by ScannerInterface. - -"slaveSelect" paramter can be any controller pin connected to shift register's SHIFT-LOAD pin. - -"byte_count" is the number of bytes to read from shift registers (1 to 4). -byte_count should cover all the row's keys: - byte_count*8 >= row's keyCount +1. "strobeOn" paramter is ignored, but should be active state HIGH or LOW for ScannerInterface. +2. "slaveSelect" paramter can be any controller pin connected to shift register's SHIFT-LOAD pin. +3. "byte_count" is the number of bytes to read from shift registers (1 to 4). + byte_count should cover all the row's keys: byte_count*8 >= row's keyCount Hardware setup: -There is only one row, and it is permanently active. +The row of keys is connected to a controller by 5 wires: +* GND +* power +* CLK +* Slave Select +* MISO + Switches are connected to shift-register parallel-input pins and row. -Diodes are not needed because there is only one row. +Diodes are not needed if there is only one row. For active low: Shift-register parallel-input pins need 10k Ohm pull-up resistors powered. @@ -41,6 +45,8 @@ For active high: Shift-register parallel-input pins need 10k pull-down resistors grounded. Switches connect grouned row to parallel-input pins. Controller's MISO pin is connected to shift register's serial output (QH) pin + +If multiple rows (or any SPI divice) share a MISO line, the shift registers need to be isolated by a tri-state buffer chip. */ class Scanner_ShiftRegsRead : public ScannerInterface { diff --git a/src/Scanner_ShiftRegsReadStrobed.h b/src/Scanner_ShiftRegsReadStrobed.h index 45d83b8..17db711 100644 --- a/src/Scanner_ShiftRegsReadStrobed.h +++ b/src/Scanner_ShiftRegsReadStrobed.h @@ -1,5 +1,5 @@ -#ifndef ROWSCANNER_SHIFTREGSPISOMULTIROW_H -#define ROWSCANNER_SHIFTREGSPISOMULTIROW_H +#ifndef ROWSCANNER_SHIFTREGSREADSTROBED_H +#define ROWSCANNER_SHIFTREGSREADSTROBED_H #include #include @@ -8,24 +8,30 @@ #include /* Scanner_ShiftRegsReadStrobed reads shift registers. -This was tested on 74HC165 shift registers, which are Parallel-In-Serial-Out (PISO). Shift registers can be daisy chained for a total of 32 read pins. +This was tested on 74HC165 shift registers, which are Parallel-In-Serial-Out (PISO). + +The class works with machanical switches or photointerrupter switches. +A "strobe" powers the IR LEDs for a short time while the shift registers read the photo transistors. +The IR LEDs are off most of the time to preserve IR LED life. Example instantiation: - Scanner_ShiftRegsReadStrobed scanner_R(HIGH, SS, 4); + Scanner_ShiftRegsReadStrobed scanner_R(HIGH, 6, 4); There are three Scanner_ShiftRegsReadStrobed parameters. -"strobeOn" paramter is active state HIGH or LOW. - -"slaveSelect" paramter can be any controller pin connected to shift register's SHIFT-LOAD pin. - -"byte_count" is the number of bytes to read from shift registers (1 to 4). -byte_count should cover all the row's keys: - byte_count*8 >= row's keyCount +1. "strobeOn" paramter is active state HIGH or LOW. +2. "slaveSelect" paramter is controller pin connected to shift register's SHIFT-LOAD pin. +3. "byte_count" is the number of bytes to read from shift registers (1 to 4). + byte_count should cover all the row's keys: byte_count*8 >= row's keyCount Hardware setup: -Each row needs to be connected to a strobe pin from the controller. -Switch and diode in series, connect shift-register parallel-input pins to strobed row. +Each row of keys is connected to a controller by 6 wires: +* GND +* power +* CLK +* Slave Select +* MISO +* strobe For active low: Shift-register parallel-input pins need 10k Ohm pull-up resistors powered. @@ -36,6 +42,8 @@ For active high: Shift-register parallel-input pins need 10k pull-down resistors grounded. Orient diodes with cathode (banded end) towards the read pins. Controller's MISO pin is connected to shift register's serial output (QH) pin + +If multiple rows (or any SPI divice) share a MISO line, the shift registers need to be isolated by a tri-state buffer chip. */ class Scanner_ShiftRegsReadStrobed : public ScannerInterface { diff --git a/tutorials/tutorial_4_connecting_split_keyboards.md b/tutorials/tutorial_4_connecting_split_keyboards.md index c42d811..08adb53 100644 --- a/tutorials/tutorial_4_connecting_split_keyboards.md +++ b/tutorials/tutorial_4_connecting_split_keyboards.md @@ -49,7 +49,7 @@ More scanning options are reviewed at http://www.openmusiclabs.com/learning/digi Only ready-made cables that are widely available are listed. There are hundreds of other connectors listed at http://pinouts.ru/ -There are also wireless options if you don't mind adding complexity and maintaining a battery. +There are also wireless options at the expense of adding complexity and maintaining a battery. The 8-wire "GearIT Cat 6 Ethernet Flat Patch Cable 7 Feet" is very flexible. It's available at Walmart (9/19/16) if you want to feel the merchandise before you buy. diff --git a/tutorials/tutorial_4b_split_keyboard_with_shift_registers.md b/tutorials/tutorial_4b_split_keyboard_with_shift_registers.md index f223ede..f21a653 100644 --- a/tutorials/tutorial_4b_split_keyboard_with_shift_registers.md +++ b/tutorials/tutorial_4b_split_keyboard_with_shift_registers.md @@ -3,7 +3,7 @@ keybrd Tutorial 4b - split keyboard with shift registers When you finish this tutorial you will be able to be able to modify a split keybrd sketch with 10 to 24 keys on the shift registers. Overview of split keyboard with shift registers ------------------------------------------------- +----------------------------------------------- The breadboard in the following picture models a split keyboard. The green rectangle on the left is a Teensy LC micro controller. The black rectangles in the middle are two SN74HC165N shift registers daisy chained together.