From dad142eaa4535bc5ef00f5cade0ddbc83a830c37 Mon Sep 17 00:00:00 2001 From: wolfv6 Date: Sat, 17 Sep 2016 15:47:37 -0600 Subject: [PATCH] reword documentation - bitwise to bit pattern or bits --- doc/keybrd_library_developer_guide.md | 37 ++++++++++--------- src/Code.h | 4 +- src/DebouncerInterface.h | 2 +- src/Debouncer_Not.cpp | 4 +- src/Debouncer_Samples.cpp | 8 ++-- src/Debouncer_Samples.h | 2 +- src/Key_LayeredKeysArray.h | 2 +- src/LED.h | 2 +- src/LED_PCA9655E.h | 2 +- src/PortIOE.h | 2 +- src/PortMCP23S17.cpp | 2 +- src/PortRead_MCP23S17.h | 6 +-- src/PortRead_PCA9655E.h | 4 +- src/PortWrite_MCP23S17.cpp | 2 +- src/PortWrite_PCA9655E.cpp | 2 +- src/Row.cpp | 14 +++---- src/Row.h | 4 +- src/Scanner_IOE.cpp | 4 +- src/Scanner_ShiftRegsPISOMultiRow.cpp | 4 +- src/Scanner_ShiftRegsPISOSingleRow.cpp | 8 ++-- src/Scanner_uC.cpp | 6 +-- .../keybrd_4c_split_with_IOE.ino | 2 +- .../PortRead_MCP23S17/PortRead_MCP23S17.ino | 2 +- 23 files changed, 64 insertions(+), 61 deletions(-) diff --git a/doc/keybrd_library_developer_guide.md b/doc/keybrd_library_developer_guide.md index ff76bec..0876860 100644 --- a/doc/keybrd_library_developer_guide.md +++ b/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 - ___________ Row _______/__ | \ - / / \ / \ | \ - Scanner_uC Debouncer Keys / Code_Layer LED_PinNumber - | \ / - readPins Code + LayerStates + ___________ Row ________________/__ | \ + / / \ / \ | \ + Scanner_uC Debouncer Key_LayeredKeys / Code_Layer LED_PinNumber + | \ / + 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 _________ - / \ \ - __ Scanner_IOE __ Debouncer Keys + _________ Row ________ + / \ \ + __ 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 ------------------------------ diff --git a/src/Code.h b/src/Code.h index f543ac0..30a18a1 100644 --- a/src/Code.h +++ b/src/Code.h @@ -2,8 +2,8 @@ #define CODE_H #include "Key.h" -/* Code is an interface class -It's derived concrete classes send press and release USB scancodes to the computer. +/* Code is an abstract base class. +Each Code object contains one USB scancode and sends the scancode to the computer. */ class Code : public Key { diff --git a/src/DebouncerInterface.h b/src/DebouncerInterface.h index 1c6d56b..0a9d64b 100644 --- a/src/DebouncerInterface.h +++ b/src/DebouncerInterface.h @@ -4,7 +4,7 @@ #include /* -debounce() takes rawSignal and returns debounced signal. Signals are bitwise. +debounce() takes rawSignal and returns debounced signal. Signals are bit paterns. */ class DebouncerInterface { diff --git a/src/Debouncer_Not.cpp b/src/Debouncer_Not.cpp index 7237c58..ecf66ec 100644 --- a/src/Debouncer_Not.cpp +++ b/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; diff --git a/src/Debouncer_Samples.cpp b/src/Debouncer_Samples.cpp index 0bbf7d9..6172494 100644 --- a/src/Debouncer_Samples.cpp +++ b/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 all_1 = ~0; //bitwise - read_pins_t all_0 = 0; //bitwise + read_pins_t previousDebounced; //bits, 1 means pressed, 0 means released + read_pins_t all_1 = ~0; //bits + read_pins_t all_0 = 0; //bits samples[samplesIndex] = rawSignal; //insert rawSignal into samples[] ring buffer diff --git a/src/Debouncer_Samples.h b/src/Debouncer_Samples.h index 99a8b66..1aa62ba 100644 --- a/src/Debouncer_Samples.h +++ b/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) {} diff --git a/src/Key_LayeredKeysArray.h b/src/Key_LayeredKeysArray.h index 66a14af..68c76fa 100644 --- a/src/Key_LayeredKeysArray.h +++ b/src/Key_LayeredKeysArray.h @@ -6,7 +6,7 @@ #include /* 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. diff --git a/src/LED.h b/src/LED.h index d62bbcd..1816aed 100644 --- a/src/LED.h +++ b/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 diff --git a/src/LED_PCA9655E.h b/src/LED_PCA9655E.h index f82588a..7c6096c 100644 --- a/src/LED_PCA9655E.h +++ b/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) diff --git a/src/PortIOE.h b/src/PortIOE.h index 1eec752..ce6ab3c 100644 --- a/src/PortIOE.h +++ b/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) {} diff --git a/src/PortMCP23S17.cpp b/src/PortMCP23S17.cpp index c4bda04..45bac9d 100644 --- a/src/PortMCP23S17.cpp +++ b/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 diff --git a/src/PortRead_MCP23S17.h b/src/PortRead_MCP23S17.h index f49a7b1..5bcd376 100644 --- a/src/PortRead_MCP23S17.h +++ b/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 - const uint8_t readPins; //bitwise, 1 means internal pull-up resistor enabled + uint8_t pullUp; //bits, 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) {} diff --git a/src/PortRead_PCA9655E.h b/src/PortRead_PCA9655E.h index 271f842..87f24ef 100644 --- a/src/PortRead_PCA9655E.h +++ b/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) {} diff --git a/src/PortWrite_MCP23S17.cpp b/src/PortWrite_MCP23S17.cpp index be2d69f..48a2a87 100644 --- a/src/PortWrite_MCP23S17.cpp +++ b/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. */ diff --git a/src/PortWrite_PCA9655E.cpp b/src/PortWrite_PCA9655E.cpp index 687016e..ff6f4d0 100644 --- a/src/PortWrite_PCA9655E.cpp +++ b/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. */ diff --git a/src/Row.cpp b/src/Row.cpp index 965fb34..0db56a5 100644 --- a/src/Row.cpp +++ b/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 debouncedChanged; //bitwise, 1 means debounced changed + read_pins_t readState; //bits, 1 means key is pressed, 0 means released + 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 isRisingEdge; //bitwise, 1 means rising edge - read_pins_t readPosition; //bitwise, active bit is 1 + read_pins_t isFallingEdge; //bits, 1 means falling edge + read_pins_t isRisingEdge; //bits, 1 means rising edge + 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 diff --git a/src/Row.h b/src/Row.h index 4cee19f..281935a 100644 --- a/src/Row.h +++ b/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); diff --git a/src/Scanner_IOE.cpp b/src/Scanner_IOE.cpp index 4c3eb77..a1fa470 100644 --- a/src/Scanner_IOE.cpp +++ b/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); diff --git a/src/Scanner_ShiftRegsPISOMultiRow.cpp b/src/Scanner_ShiftRegsPISOMultiRow.cpp index 34f1a97..81f703d 100644 --- a/src/Scanner_ShiftRegsPISOMultiRow.cpp +++ b/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); diff --git a/src/Scanner_ShiftRegsPISOSingleRow.cpp b/src/Scanner_ShiftRegsPISOSingleRow.cpp index da00687..18d5f31 100644 --- a/src/Scanner_ShiftRegsPISOSingleRow.cpp +++ b/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, HIGH); //shift the data toward a serial output + digitalWrite(slaveSelect, LOW); //load parallel inputs to the register + digitalWrite(slaveSelect, HIGH); //shift the data toward a serial output SPI.transfer(&readState, byte_count); return readState; diff --git a/src/Scanner_uC.cpp b/src/Scanner_uC.cpp index 30d7875..b22c4a6 100644 --- a/src/Scanner_uC.cpp +++ b/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 readMask = 1; //bitwise, active bit is 1 + read_pins_t readState = 0; //bits, 1 means key is pressed, 0 means released + read_pins_t readMask = 1; //bits, active bit is 1 //strobe row on digitalWrite(strobePin, strobeOn); diff --git a/tutorials/keybrd_4c_split_with_IOE/keybrd_4c_split_with_IOE.ino b/tutorials/keybrd_4c_split_with_IOE/keybrd_4c_split_with_IOE.ino index 8131083..4ca0008 100644 --- a/tutorials/keybrd_4c_split_with_IOE/keybrd_4c_split_with_IOE.ino +++ b/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. diff --git a/unit_tests/PortRead_MCP23S17/PortRead_MCP23S17.ino b/unit_tests/PortRead_MCP23S17/PortRead_MCP23S17.ino index 88a3db6..8be8881 100644 --- a/unit_tests/PortRead_MCP23S17/PortRead_MCP23S17.ino +++ b/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);