reword documentation - bitwise to bit pattern or bits

doc/keybrd_library_developer_guide.md

@@ -26,11 +26,11 @@ Keybrd library class inheritance diagram
 
     PortIOE
 
-	              PortWrite
+	           PortWriteInterface
 	              /        \
 	PortWrite_PCA9655E  PortWrite_MCP23S17            (one PortWrite class for each IOE type)
  
-                  PortRead
+              PortReadInterface
 	             /        \
 	PortRead_PCA9655E  PortRead_MCP23S17              (one PortRead class for each IOE type)
  
@@ -50,12 +50,10 @@ Keybrd library class inheritance diagram
 	LayerState
 
 
-	Key __
+	Key
+	 |____
 	 |    \
 	 |   Key_LayeredKeysArray
-	 |_____________________
-	 |     \               \
-	 |   Code_LayerLock  Code_LayerHold
 	 |
 	 |___________________________
 	 |     \                     \
@@ -64,6 +62,10 @@ Keybrd library class inheritance diagram
 	 |   Key_LayeredScSc      Key_LayeredCodeSc
 	 |
 	Code
+	 |_____________________
+	 |     \               \
+	 |   Code_LayerLock  Code_LayerHold
+	 |
 	  \________________________________________________________
 	       \           \            \           \              \
 	     Code_Sc  Code_Shift  Code_AutoShift  Code_LEDLock  Code_Null
@@ -79,7 +81,7 @@ Dependency diagram of example single-layer keyboard with LEDs
 ```
 	        ____ Row ______
 	       /      |        \
-	Scanner_uC  Debouncer  Keys __
+	Scanner_uC  Debouncer  Key ___
 	      |                 |     \
 	readPins               Code  Code_LEDLock
 	                               |
@@ -89,12 +91,12 @@ Dependency diagram of example single-layer keyboard with LEDs
 
 Dependency diagram of example multi-layer keyboard with layer LEDs
 ```
-	                                 LayerStates
+	                                          LayerStates
-	         ___________ Row _______/__   |     \
+	         ___________ Row ________________/__   |     \
-	        /           /  \       /   \  |      \
+	        /        /            \         /   \  |      \
-	Scanner_uC  Debouncer  Keys   / Code_Layer  LED_PinNumber
+	Scanner_uC  Debouncer  Key_LayeredKeys / Code_Layer  LED_PinNumber
-	       |                 \   /
+	       |                           \  /
-	  readPins                Code
+	  readPins                         Code
 
 ```
 
@@ -102,7 +104,7 @@ Dependency diagram of example shift registers Row
 ```
 	                  _______ Row _______
 	                 /         |         \
-	RowScanner_ShiftRegsPISO  Debouncer  Keys
+	RowScanner_ShiftRegsPISO  Debouncer  Key
 	                                      |
 	                                     Code
 
@@ -110,9 +112,9 @@ Dependency diagram of example shift registers Row
 
 Dependency diagram of example I/O expander matrix with LEDs
 ```
-	                 _________ Row _________
+	                 _________ Row ________
-	                /             \         \
+	                /             \        \
-	        __ Scanner_IOE __   Debouncer  Keys 
+	        __ Scanner_IOE __   Debouncer  Key
 	       /       |         \             /  \
 	strobePin  PortWrite  PortRead      Code  Code_LEDLock
 	             |   \      /   \              |
@@ -136,6 +138,7 @@ This convention leads to class names that convey information about the classes i
 Underscore delineates base class name and sub-class name.  Capital letters delineate words.
 
 Interface class names end with "Interface".
+Except for Key, because sketches look nicer with short names defining Key[] arrays.
 
 Layer-class naming conventions
 ------------------------------

src/Code.h

@@ -2,8 +2,8 @@
 #define CODE_H
 #include "Key.h"
 
-/* Code is an interface class
+/* Code is an abstract base class.
-It's derived concrete classes send press and release USB scancodes to the computer.
+Each Code object contains one USB scancode and sends the scancode to the computer.
 */
 class Code : public Key
 {

src/DebouncerInterface.h

@@ -4,7 +4,7 @@
 #include <config_keybrd.h>
 
 /* 
-debounce() takes rawSignal and returns debounced signal.  Signals are bitwise.
+debounce() takes rawSignal and returns debounced signal.  Signals are bit paterns.
 */
 class DebouncerInterface
 {

src/Debouncer_Not.cpp

@@ -1,13 +1,13 @@
 #include "Debouncer_Not.h"
 
 /* debounce() sets debounced and returns debouncedChanged.
-All parameters and variables are bitwise.
+All parameters and variables are bit patterns.
 For parameters, 1 means pressed, 0 means released.
 For return, 1 means debounced changed.
 */
 read_pins_t Debouncer_Not::debounce(const read_pins_t rawSignal, read_pins_t& debounced)
 {
-    read_pins_t previousDebounced;              //bitwise, 1 means pressed, 0 means released
+    read_pins_t previousDebounced;              //bits, 1 means pressed, 0 means released
 
     previousDebounced = debounced;
     debounced = rawSignal;

src/Debouncer_Samples.cpp

@@ -32,15 +32,15 @@ strong electromagnetic interference (EMI) may need a larger SAMPLE_COUNT_MACRO f
 #include "Debouncer_Samples.h"
 
 /* debounce() sets debounced and returns debouncedChanged.
-All parameters and variables are bitwise.
+All parameters and variables are bit patterns.
 For parameters, 1 means pressed, 0 means released.
 For return, 1 means debounced changed.
 */
 read_pins_t Debouncer_Samples::debounce(const read_pins_t rawSignal, read_pins_t& debounced)
 {
-    read_pins_t previousDebounced;              //bitwise, 1 means pressed, 0 means released
+    read_pins_t previousDebounced;              //bits, 1 means pressed, 0 means released
-    read_pins_t all_1 = ~0;                     //bitwise
+    read_pins_t all_1 = ~0;                     //bits
-    read_pins_t all_0 = 0;                      //bitwise
+    read_pins_t all_0 = 0;                      //bits
 
     samples[samplesIndex] = rawSignal;          //insert rawSignal into samples[] ring buffer
 

src/Debouncer_Samples.h

@@ -12,7 +12,7 @@ Configuration: #define SAMPLE_COUNT_MACRO in config_keybrd.h
 class Debouncer_Samples : public DebouncerInterface
 {
     private:
-        read_pins_t samples[SAMPLE_COUNT_MACRO]; //bitwise, one bit per key, most recent readings
+        read_pins_t samples[SAMPLE_COUNT_MACRO]; //bits, one bit per key, most recent readings
         uint8_t samplesIndex;                   //samples[] current write index
     public:
         Debouncer_Samples(): samplesIndex(0) {}

src/Key_LayeredKeysArray.h

@@ -6,7 +6,7 @@
 #include <Key.h>
 
 /* Class Key_LayeredKeysArray contains an array of Key pointers, one pointer per layer.
-Codes are a kind of Key, so the Key pointers can point to Codes as well.
+Codes are a kind of Key, so the Key pointers can point to Codes or Keys.
 
 When the key is pressed, active layer is retreived from refLayerState and
 the Key object of the active layer is called.

src/LED.h

@@ -1,7 +1,7 @@
 #ifndef LED_H
 #define LED_H
 
-/* LED is an abstract base class
+/* LED is an interface class
 Each LED object is an IC pin that is used to power an LED on and off.
 */
 class LED

src/LED_PCA9655E.h

@@ -15,7 +15,7 @@ class LED_PCA9655E: public LED
         //PortIOE& port;
         //const uint8_t outputByteCommand;        //General Purpose Input/Ouput register address
         PortWrite_PCA9655E& refPort;
-        const uint8_t pin;                      //bitwise IOE pin to LED
+        const uint8_t pin;                      //bit pattern, IOE pin to LED
 
     public:
         LED_PCA9655E(PortWrite_PCA9655E& refPort, const uint8_t pin)

src/PortIOE.h

@@ -30,7 +30,7 @@ struct PortIOE
 {
     static const uint8_t DEVICE_ADDR;
     const uint8_t num;                          //port identification number
-    uint8_t outputVal;                          //bitwise value of output register for LEDs
+    uint8_t outputVal;                          //bit value of output register for LEDs
 
     PortIOE(const uint8_t portNumber)
         : num(portNumber), outputVal(0) {}

src/PortMCP23S17.cpp

@@ -4,7 +4,7 @@
 */
 uint8_t PortMCP23S17::transfer(const uint8_t command, const uint8_t registerAddr, const uint8_t data)
 {
-    uint8_t portState;                          //bitwise
+    uint8_t portState;                          //bit pattern
 
     digitalWrite(SS, LOW);                      //enable Slave Select
       SPI.transfer(command);                    //write or read command

src/PortRead_MCP23S17.h

@@ -15,7 +15,7 @@ Arduino Pin 10 avoids the speed penalty of digitalWrite.
 
 Instantiation
  ------------
-readPins parameter is port's bitwise pin configuration
+readPins parameter is port's bit pattern pin configuration
     1=configure as input (for read pins connected to column)
     0=configure as output (for LED or not connected to a column)
 readPins are read from pin 0 on up.
@@ -37,8 +37,8 @@ class PortRead_MCP23S17 : public PortReadInterface, public PortMCP23S17
 {
     private:
         PortIOE& port;
-        uint8_t pullUp;                         //bitwise, 1 means internal pull-up resistor enabled
+        uint8_t pullUp;                         //bits, 1 means internal pull-up resistor enabled
-        const uint8_t readPins;                 //bitwise, 1 means internal pull-up resistor enabled
+        const uint8_t readPins;                 //bits, 1 means internal pull-up resistor enabled
     public:
         PortRead_MCP23S17(PortIOE& port, const uint8_t readPins)
             : port(port), readPins(readPins) {}

src/PortRead_PCA9655E.h

@@ -11,7 +11,7 @@ PCA9655E does not have internal pull-up resistors (PCA9535E does).
 
 Instantiation
  ------------
-readPins parameter is port's bitwise pin configuration
+readPins parameter is bit pattern for port's pin configuration
     1=configure as input (for pins connected to column)
     0=configure as output (for LED or not connected to a column)
 readPins are read from pin 0 on up.
@@ -33,7 +33,7 @@ class PortRead_PCA9655E : public PortReadInterface
 {
     private:
         PortIOE& port;
-        const uint8_t readPins;                  //bitwise pin configuration, 1 means read pin
+        const uint8_t readPins;                  //bit pattern, pin configuration, 1 means read pin
     public:
         PortRead_PCA9655E (PortIOE& port, const uint8_t readPins)
             : port(port), readPins(readPins) {}

src/PortWrite_MCP23S17.cpp

@@ -18,7 +18,7 @@ void PortWrite_MCP23S17::begin()
 }
 
 /* write() sets pin output to logicLevel.
-pin is bitwise, where pin being set is 1.
+pin is bit pattern, where pin being set is 1.
 logicLevel is HIGH or LOW.
 write() does not overwrite the other pins.
 */

src/PortWrite_PCA9655E.cpp

@@ -19,7 +19,7 @@ void PortWrite_PCA9655E::begin()
 }
 
 /* write() sets pin output to logicLevel.
-pin is bitwise, where pin being strobed is 1.
+pin is bit pattern, where pin being strobed is 1.
 logicLevel is HIGH or LOW.
 write() does not overwrite the other pins.
 */

src/Row.cpp

@@ -12,12 +12,12 @@ Row::Row(ScannerInterface& refScanner, const uint8_t strobePin,
 }
 
 /* process() scans the row and calls any newly pressed or released keys.
-Bitwise variables are 1 bit per key.
+Bit pattern variables are 1 bit per key.
 */
 void Row::process()
 {
-    read_pins_t readState;                      //bitwise, 1 means key is pressed, 0 means released
+    read_pins_t readState;                      //bits, 1 means key is pressed, 0 means released
-    read_pins_t debouncedChanged;               //bitwise, 1 means debounced changed
+    read_pins_t debouncedChanged;               //bits, 1 means debounced changed
 
     readState = refScanner.scan(strobePin);
     debouncedChanged = debouncer.debounce(readState, debounced);
@@ -26,13 +26,13 @@ void Row::process()
 
 /*
 send() calls key's press() or release() function if key was pressed or released.
-Parameter debouncedChanged is bitwise.
+Parameter debouncedChanged is bit a pattern.
 */
 void Row::send(const uint8_t keyCount, const read_pins_t debouncedChanged)
 {
-    read_pins_t isFallingEdge;                  //bitwise, 1 means falling edge
+    read_pins_t isFallingEdge;                  //bits, 1 means falling edge
-    read_pins_t isRisingEdge;                   //bitwise, 1 means rising edge
+    read_pins_t isRisingEdge;                   //bits, 1 means rising edge
-    read_pins_t readPosition;                   //bitwise, active bit is 1
+    read_pins_t readPosition;                   //bits, active bit is 1
     uint8_t i;                                  //index for ptrsKeys[i] array
 
     //bit=1 if last debounced changed from 1 to 0, else bit=0

src/Row.h

@@ -12,7 +12,7 @@
 /*
 strobePin has one of two formats:
  * if refScanner a Scanner_uC, then strobePin is an Arduino pin number connected to this row
- * otherwise strobePin is bitwise, 1 indicating an IC pin connected to this row
+ * otherwise strobePin is bit pattern, 1 indicating an IC pin connected to this row
 */
 class Row
 {
@@ -28,7 +28,7 @@ class Row
         const uint8_t keyCount;                 //number of read pins
         //Debouncer_Samples debouncer;
         Debouncer_Not debouncer; //todo
-        read_pins_t debounced;                  //bitwise state of keys after debouncing, 1=pressed, 0=released
+        read_pins_t debounced; //bit pattern, state of keys after debouncing, 1=pressed, 0=released
     public:
         Row(ScannerInterface& refScanner, const uint8_t strobePin,
                 Key* const ptrsKeys[], const uint8_t keyCount);

src/Scanner_IOE.cpp

@@ -17,12 +17,12 @@ void Scanner_IOE::begin()
 }
 
 /* scan() is called on every iteration of sketch loop().
-strobePin is bitwise, 1 means that row pin is active.
+strobePin is a bit pattern, 1 means that row pin is active.
 scan() strobes the row's strobePin and retuns state of port's input pins.
 */
 read_pins_t Scanner_IOE::scan(const uint8_t strobePin)
 {
-    uint8_t readState;                          //bitwise, 1 means key is pressed, 0 means released
+    uint8_t readState;                          //bits, 1 means key is pressed, 0 means released
 
     //strobe on
     refPortWrite.write(strobePin, strobeOn);

src/Scanner_ShiftRegsPISOMultiRow.cpp

@@ -28,11 +28,11 @@ void Scanner_ShiftRegsPISOMultiRow::begin()
 
 /* scan() strobes the row's strobePin and returns state of the shift register's input pins.
 strobePin is Arduino pin number connected to this row.
-Bitwise variables are 1 bit per key.
+Bit patterns are 1 bit per key.
 */
 read_pins_t Scanner_ShiftRegsPISOMultiRow::scan(const uint8_t strobePin)
 {
-    read_pins_t readState = 0;                  //bitwise, 1 means key is pressed, 0 means released
+    read_pins_t readState = 0;                  //bits, 1 means key is pressed, 0 means released
 
     //strobe row on
     digitalWrite(strobePin, strobeOn);

src/Scanner_ShiftRegsPISOSingleRow.cpp

@@ -26,15 +26,15 @@ void Scanner_ShiftRegsPISOSingleRow::begin()
 
 /* scan() returns state of the shift register's input pins.
 No strobe pin is needed, the shift register is wired so the strobe is effectivley always "on".
-Bitwise variables are 1 bit per key.
+Bit patterns are 1 bit per key.
 */
 read_pins_t Scanner_ShiftRegsPISOSingleRow::scan(const uint8_t strobePin)
 {
-    read_pins_t readState = 0;                  //bitwise, 1 means key is pressed, 0 means released
+    read_pins_t readState = 0;                  //bits, 1 means key is pressed, 0 means released
 
     //read all the column pins
-    digitalWrite(slaveSelect, LOW);              //load parallel inputs to the register
+    digitalWrite(slaveSelect, LOW);             //load parallel inputs to the register
-    digitalWrite(slaveSelect, HIGH);             //shift the data toward a serial output
+    digitalWrite(slaveSelect, HIGH);            //shift the data toward a serial output
     SPI.transfer(&readState, byte_count);
 
     return readState;

src/Scanner_uC.cpp

@@ -41,12 +41,12 @@ void Scanner_uC::init(const uint8_t strobePin)
 
 /* scan() is called on every iteration of sketch loop().
 scan() strobes the row's strobePin and retuns state of readPins.
-Bitwise variables are 1 bit per key.
+Bit patterns are 1 bit per key.
 */
 read_pins_t Scanner_uC::scan(const uint8_t strobePin)
 {
-    read_pins_t readState = 0;                  //bitwise, 1 means key is pressed, 0 means released
+    read_pins_t readState = 0;                  //bits, 1 means key is pressed, 0 means released
-    read_pins_t readMask = 1;                   //bitwise, active bit is 1
+    read_pins_t readMask = 1;                   //bits, active bit is 1
 
     //strobe row on
     digitalWrite(strobePin, strobeOn);

tutorials/keybrd_4c_split_with_IOE/keybrd_4c_split_with_IOE.ino

@@ -89,7 +89,7 @@ The first parameteer of a Row constructor specifies the scanner.
 The second parameter of the Row constructor specifies the Row's strobePin.
 strobePin has one of two formats:
  * if refScanner a Scanner_uC, then strobePin is an Arduino pin number connected to this row
- * otherwise strobePin is bitwise, 1 indicating an IC pin connected to this row
+ * otherwise strobePin is a bit pattern, 1 indicating an IC pin connected to this row
 */
 // ---------------- LEFT ROWS ------------------
 /* The left rows have a Scanner_uC and Arduino pin numbers to strobe.

unit_tests/PortRead_MCP23S17/PortRead_MCP23S17.ino

@@ -17,7 +17,7 @@ PortRead_MCP23S17 portBRead(portB, ~0);
 
 void setup()
 {
-    uint8_t portBState;                         //bit wise
+    uint8_t portBState;                         //bit pattern
 
     delay(6000);
     portBRead.begin(LOW);