keybrd Library Developer’s Guide

This guide if for maintaining and writing new classes for the keybrd library and its extension libraries. The most common reason for adding new classes are:

• I/O expander classes
• custom layer schemes for multi-layer keyboards
• experimental features

Who this guide is for

This guide is for the maintainers and developers of the keybrd library and it’s extensions. It is assumed the reader is familiar with the C++ language including pointers, objects, classes, static class variables, composition, aggregation, inheritance, polymorphism, and enum. Row, Scanner, and Debouncer classes use bit manipulation.

Class inheritance diagrams

Keybrd library class inheritance diagram

    Row

         ___ ScannerInterface ___
        /          |             \
    Scanner_uC  Scanner_IOE  Scanner_ShiftRegsRead


                PortWriteInterface
                 /           \
           PortInterface   Port_ShiftRegs       (Port class for MOSI shift registers)
             /        \
    Port_PCA9655E  Port_MCP23S17                (one Port class for each IOE type)
 
 
      LEDInterface
       /       \
    LED_uC    LED_Port


    DebouncerInterface
          |
    Debouncer_Samples

    ScanDelay

    LayerStateInterface
         |
    LayerState


    Key
     |____
     |    \
     |   Key_LayeredKeysBase
     |      \____________________
     |      /                    \
     |   Key_LayeredKeys      Key_LayeredKeys1
     |
     |___________________________
     |     \                     \
     |   Key_LayeredScScBase  Key_LayeredCodeScBase
     |      |                     |
     |   Key_LayeredScSc      Key_LayeredCodeSc
     |
    Code
     |_____________________
     |     \               \
     |   Code_LayerLock  Code_LayerHold
     |
      \________________________________________________________
           \           \            \           \              \
         Code_Sc  Code_Shift  Code_AutoShift  Code_LEDLock  Code_Null
                                 /      \
                            Code_ScS  Code_ScNS

Dependency diagrams

Dependency diagram of example single-layer keyboard with LEDs

            ____ Row ______
           /      |        \
    Scanner_uC  Debouncer  Key ___
          |                 |     \
    readPins               Code  Code_LEDLock
                                   |
                                 LED_PinNumber

Dependency diagram of example multi-layer keyboard with layer LEDs

                                              LayerStates
             ___________ Row ________________/__   |     \
            /        /            \         /   \  |      \
    Scanner_uC  Debouncer  Key_LayeredKeys / Code_Layer  LED_PinNumber
           |                           \  /
      readPins                         Code

Dependency diagram of example shift registers Row

                      _______ Row _______
                     /         |         \
    RowScanner_ShiftRegsPISO  Debouncer  Key
                                          |
                                         Code

Dependency diagram of example I/O expander matrix with LEDs

                     _________ Row ________
                    /             \        \
            __ Scanner_IOE __   Debouncer  Key
           /       |         \             /  \
    strobePin  PortWrite  PortRead      Code  Code_LEDLock
                 |   \      /   \              |
                 |    PortIOE  readPins       LED_Port
                  \___________________________/ \
                                                pin

Class naming conventions

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.

Interface class names end with “Interface”. Except for Key, to reduce clutter because sketches define so many Key[] arrays.

Layer-class naming conventions

Layer classes are explained in tutorial_3a_multi-layer_keyboard.md.

Code_Layer class names are concatenations of “Code_“, “Layer” or layer name, and persistence. Example persistences are:

• “Lock” - layer remains active after the layer key is released
• “Hold” - layer is active for as long as layer key is held down

Example Code_Layer class names:

• Code_LayerHold
• Code_LayerLock

LayerState class names start with “LayerState” and end with a descriptive name. Example LayerState class names:

• LayerState - basic LayerState class in keybrd library
• LayerState_DH - main LayerState for the keybrd_DH library
• LayerState_MF - LayerState for Mouse Function sub-layers in the keybrd_DH library

Key_Layered class names start with “Key_Layered” and end with a descriptive name. Example Key_Layered class names:

• Key_LayeredScSc
• Key_LayeredKeys

Style guide

Following the style guide makes it easier for the next programmer to understand your code.

• For class names, see above section “Class naming conventions”.
• Member names use camelCase starting with lowercase letter.
• Use constants rather than macros, except for header guards.
• Global const names and static const names use ALL_CAPS_WITH_UNDERSCORE.
• Header guards have _H suffix e.g. #ifndef FILE_NAME_H
• Pointer names are prefixed with “ptr” e.g. ptrRow = &row;
• Arrays names use the plural of the element name e.g. Row* const = ptrsRows { &row0, &row1 };
• Pass arrays using array notation rather than pointer notation: void printArray(char[] array); not void printArray( char* array);
• In constructor’s initialization list, use same names for fields and constructor parameters.
• Do not use new or malloc (make memory leaks impossible).
• Document class interface in .h file, above the class declaration.
• Code should be self-documenting. A simple function with a good name needs no comment.
• Code is automatically formatted before being pushed to the keybrd repository. The astyle_cpp file specifies the format:
  • Allman style indentation
  • indent 4 spaces
  • replace tabs with spaces
  • maximum code width of 100 columns

Trace of keybrd scan

Arduino does not have a debugger. So here is a list of functions in the order that they are called. The trace is of a one-row single-layer keybrd scan.

    loop()                                      for each row
        Row::process()
            Scanner_uC::scan()                      strobe row on
                                                        for each readPin
                                                            set readState bit
                                                    strobe row off
            Debouncer_Samples::debounce()           debounce
            Row::send()                         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 Arduino libraries

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.