This guide if for maintaining and writing new classes for the keybrd library and its extension libraries. The most common reason for new classes are:
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. Debouncer and I/O expander use bit manipulation.
The keybrd library is flexible for designing custom Rows
this example illustrates the custom Row classes for a fictional keybrd_Ext extension library the keybrd_Ext library is for a split keyboard with a matrix on each hand other custom Row classes would have a similar structure
Row_Ext::keyWasPressed() overrides RowBase::keyWasPressed() Row_Ext::keyWasPressed() is used to unstick sticky keys
Row_Ext_uC scans the primary matrix Row_Ext_ShiftRegisters scans the secondary matrix Row_Ext_uC and Row_Ext_ShiftRegisters are a custom classes composed of stock keybrd library classes
Class inheritance diagram
RowBase
|
Row_Ext (override RowBase::keyWasPressed() )
/ \
Row_Ext_uC Row_Ext_ShiftRegisters (inherit Row_Ext::keyWasPressed() )
RowScannerInterface
/ \
RowScanner_PinsArray RowScanner_SPIShiftRegisters
Dependency diagram
________ Row_Ext_uC[1] _______________
/ \ \
RowScanner_PinsArray[1] Debouncer_Samples[1] Key[1..*]
/ \ |
strobePin[1] readPins[1..*] Code[1..*]
_____ Row_Ext_ShiftRegisters[1] ___________
/ \ \
RowScanner_SPIShiftRegisters[1] Debouncer_Samples[1] Key[1..*]
/ \ |
strobePin[1] ROW_END[1] Code[1..*]
Keybrd library class inheritance diagram
_______ RowBase ________
/ | \
Row_uC Row_ShiftRegisters Row_IOE
_____ RowScannerInterface ______
/ | \
RowScanner_PinsArray RowScanner_PinsBitwise RowScanner_SPIShiftRegisters
IOExpanderPort
RowPort
|
RowPort_PCA9655E (one RowPort class for each IOE type)
ColPort
|
ColPort_PCA9655E (one ColPort class for each IOE type)
____ LED ____
/ \
LED_PinNumber LED_PCA9655E
DebouncerInterface
|
Debouncer_4Samples
ScanDelay
LayerStateInterface
|
LayerState
Key __
| \
| Key_LayeredKeysArray
|
Code
|_____________________
| \ \
| Code_LayerLock Code_LayerHold
|
|___________________________
| \ \
| Code_LayeredScScBase Code_LayeredCodeScBase
| | |
| Code_LayeredScSc Code_LayeredCodeSc
|
|__________________________________________
\ \ \ \
Code_Sc Code_Shift Code_AutoShift Code_LEDLock
/ | \
Code_ScS Code_ScNS Code_ScNS_00
Example single-layer dependency diagram with LEDs
___ Row_uC[1..*] ________
/ \ \
RowScanner_PinsArray Debouncer Keys[1..*] __
| \
Code[1..*] Code_LEDLock[1..*]
|
LED_PinNumber[1]
Example multi-layer dependency diagram with layer LEDs
LayerStates[1..*]
________ Row_uC[1..*] _____________________/__ | \
/ \ \ / \ | \
RowScanner_PinsArray[1] Debouncer[1] Keys[1..*] / Code_Layer[1..*] LED_PinNumber[0..*]
| /
Code[1..*]
Example secondary matrix with shift registers dependency diagram
Row_ShiftRegisters[1..*]
/ \ \
RowScanner_ShiftRegisters Debouncer Keys[1..*]
|
Code[1..*]
Example secondary matrix with I/O Expander dependency diagram with LEDs
___ Row_IOE[1..*] _________
/ \ \
RowScanner_PinsBitwise[1] Debouncer[1] Keys[1..*] __
/ | \ | \
RowPort[1] RowPin[1] ColPort[1] Code[1..*] Code_LEDLock[1..*]
\ / \ |
\ / ColPins[1..*] LED[1]
\ /
IOExpanderPort[0..*]
Class names start with upper case letter. Most derived-class names start with the base class name followed by “_” and a name e.g.
Code
|
Code_LayerLock
This convention leads to class names that convey information about the classes inheritance. Underscore delineates base class name and sub-class name. Capital letters delineate words.
Code_Layer class names are concatenations of “Code_“, “Layer” or layer name, and persistence. Example persistences are:
Example Code_Layer class names:
LayerState class names start with “LayerState” and end with a descriptive name. Example LayerState class names:
Code_Layered class names start with “Code_Layered” and end with a descriptive name. Example Code_Layered class names:
Following the style guide makes it easier for the next programmer to understand your code.
void printArray(char[] array);
not
void printArray( char* array);
Arduino does not have a debugger. So here is the next best thing; a list of functions in the order that they are called. The trace is of a single-layer keybrd scan (no LEDs and no I/O expander). Refer to it like a table of contents while reading the keybrd library.
loop() for each row
RowBase::process()
RowScanner_PinsArray::scan() strobe row on
for each readPin
set rowState bit
strobe row off
Debouncer_4Samples::debounce() debounce
RowBase::pressRelease() for each key in row
if falling edge
Key_*::release() scanCode->release()
Code_*::release() Keyboard.release(scancode)
if rising edge
Key_*::press() scanCode->press()
Code_*::press() Keyboard.press(scancode)
scanDelay.delay();
The keybrd libraries compile on the Arduino IDE and make extensive use of the following Arduino libraries:
#include <Arduino.h>
#include <Wire.h>
#include <Keyboard.h>
#include <Mouse.h>
keybrd guide 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.