keybrd Library User’s Guide

keybrd is a library for creating custom-keyboard firmware. This guide shows how to:

• set up the Arduino development environment
• install the keybrd library
• compile and load keybrd firmware

The Arduino development environment is free and simple as possible. Its easy for novice programmers to setup and learn.

Who this guide is for

This guide is for anyone who wants to use the keybrd library to develop keyboard firmware.

A reader with programming experience, but no C++ experience, would understand the tutorials well enough to modify existing keybrd sketches. An experienced C++ programmer would be able to write original sketches and classes.

The library is written in the C++ language. keybrd sketches use keybrd classes, objects pointers, aggregation, and static class variables.

Microcontroller board requirements

The keybrd library works with Teensy and Arduino compatible boards.

Teensy LC has 8K RAM, which is more than enough memory for any keyboard.

keybrd has been tested on the DodoHand keyboard with Teensy 2.0 and PCA9655E I/O expander using the keybrd_DH sketch.

Teensy LC is preferred over the older Teensy 2.0 for it’s larger memory capacity and lower price.

Getting started with Teensy, Arduino IDE, and keybrd

The Arduino IDE is used to

1. edit sketches
2. compile sketches into HEX files
3. load the HEX file onto the microcontroller

Teensyduino is a software add-on for the Arduino IDE that allows it to compile to Teensy.

Teensy Getting Started is a good way to familiarize yourself with Teensy. Arduino Development Environment is a brief description.

The following install and setup steps create an Arduino development environment for keybrd sketches.

Install Arduino IDE and Teensyduino

The following install steps are modified from the Teensyduino download page.

For Linux:

1. Download and extract the Arduino software to the /opt directory:

   /opt/arduino-1.x.x

2. The “Linux udev rules” link is at top right of page. Save the teensy.rules file in /etc/udev/rules.d/

3. “Teensyduino Files” installer links are at top of page. Download the installer to your Downloads directory. Make the installer executable:

   $ chmod 755 teensyduino.64bit

Run the teensyduino installer and fill the form fields:

   Arduino location to install Teensyduino: /opt/arduino-1.x.x 
   Libraries to Install: keybrd

1. Launch Arduino IDE from /opt/arduino-1.x.x/arduino

Install keybrd extension libraries

The keybrd library contains the foundation classes for creating a keyboard firmware. For emphasis, it is sometimes referred to as the “core keybrd library”.

keybrd extension libraries contain additional classes that extend the keyboard library. keybrd extension library names are prefixed with “keybrd_“.

Instructions for installing Arduino libraries are at: http://www.arduino.cc/en/Guide/Libraries

A Sketchbook is a folder that the Arduino IDE uses to store sketches and libraries. The default location for Arduino libraries is ~/Documents/Arduino/libraries/.

For example, the DodoHand keyboard requires the core keybrd library and the keybrd_DH extension library. After installing the libraries, my Arduino directory looks like this:

• ~/Documents/Arduino/libraries/keybrd/
• ~/Documents/Arduino/libraries/keybrd_DH/

Setup Arduino IDE for compiling keybrd firmware

From the Arduino IDE tool bar, select:

• Tools > Board > Teensy LC (or whatever board you are using)
• Tools > USB Type > Keyboard + Mouse + Joystick

These are optional:

• File > Preferences > Compiler warnings: All
• File > Preferences > check: Use external editor

Compile and load keybrd sketch

If it isn’t already plugged in, plug the USB cable into the computer and controller.

CAUTION: It is possible to loose control of your keyboard when running a keybrd sketch. If the keybrd sketch has a mouse object, it is possible to loose control of your mouse too. USB keyboard protocol is capable of spewing characters and mouse commands at up to 500 per second. Take the following precautions before uploading an untested keybrd sketch to a controller:

• Save all files and close dangerous applications.
• Park the cursor in an editor opened to a test file. That way you can immediately see if the controller starts spewing characters.
• Be prepared to turn off the controller: turn off Teensy Loader’s green “Auto” button and push Teensy’s reset button or unplug Teensy USB.

Compile and load workflow:

1. Open a keybrd sketch in the Arduino IDE.
2. Prepare for loosing control of keyboard and mouse.
3. On the Arduino IDE, click the Upload button.
4. The Teensy boot loader window opens (you might need to press and release the pushbutton on the Teensy circuit board).

Example keybrd sketches

Example keybrd sketches are in the examples and tutorials directories. Extension libraries have their example sketches similarly located.

The example sketch names use the following conventions.

keybrd_feature_version.ino

where

• keybrd is the library name e.g. keybrd, keybrd_DH
• feature is a distinguishing feature of the keybrd sketch e.g. keyboard name, sound, Dvorak
• version is the sketch’s version number (optional)

Active state and diode orientation

Active state is set in the sketch by variables STROBE_ON and STROBE_OFF. The following instructions are for setting active state for a Scanner_uC class (Scanner_ShiftRegs74HC165 and Scanner_Port classes is similar).

For active low:

• Orient diodes with cathode (banded end) towards the write pins (row)
• Use these two lines in the sketch: const bool Scanner_uC::STROBE_ON = LOW; const bool Scanner_uC::STROBE_OFF = HIGH;

For active high:

• Add an external 10k pull-down resistor to each read pin.
• Orient diodes with cathode (banded end) towards the read pins.
• Use these two lines in the sketch: const bool Scanner_uC::STROBE_ON = HIGH; const bool Scanner_uC::STROBE_OFF = LOW;

Troubleshooting check list

The following is a listing of items to check when a new keybrd sketch or keyboard hardware is having trouble.

Development-environment items to check:

• If the keyboard has an I/O expander, power cycle (replug the USB) after loading the HEX file.
• For compile error: 'KEY_A' was not declared in this scope Where ‘KEY_A’ could be any scan code. Fix this from the Arduino IDE tool bar: Tools > USB Type > Keyboard + Mouse + Joystick

Sketch items to check:

• For each row, number of read pins in Row should equal number of keys. In this example, row_0 has 2 read pins and 2 keys:

  uint8_t readPins[] = {14, 15};
  uint8_t READ_PIN_COUNT = sizeof(readPins)/sizeof(*readPins);
  
  Key* ptrsKeys_0[] = { &s_a, &s_b };
  Row_uC row_0(0, readPins, READ_PIN_COUNT, ptrsKeys_0);
  

• Some of the constructors take array-element-count arguments, make sure that the correct counts are passed to the constructors. Or use sizeof() like the preceding example.

• For multi-layered keyboards, the number of codes in each Key_Layered should equal the number of layers.

Hardware items to check:

• Connections
• Diode orientation
• 3.3 or 5 volts across power and ground
• To validate keyboard hardware, modify the simple keybrd_1_breadboard.ino sketch.

Keybrd nomenclature

scancode - Is a 16-bit integer assigned to a key position on a keyboard. The keyboard sends a scancode to the computer for every key press and release.

layers - are key bindings provided by the keyboard firmware. For example,

• The classic IBM PC keyboard has one layer.
• Many compact keyboards have an additional Fn layer.
• The Neo layout has 6 layers.

Layer id - is an integer assigned to a layer.

Layer scheme - is a system for changing layers while typing.

               A single-layer scheme does not change layers.

Layout - is the placement of keys. Key caps are often labeled to show a keyboard’s layout.

Matrix - is a collection of switches connected by rows and columns.

Bounce - Keyboard switches are made of moving contacts. When the contacts close, they bounce apart one or more times before making steady contact. A debouncer removes the bounce so that a key press is sent to the computer only once.

Modifier key - is a special key on a computer keyboard that temporarily modifies the normal action of another key when pressed together e.g. Shift, Alt, or Ctrl. By themselves, modifier keys usually do nothing; that is, pressing any of the Shift, Alt, or Ctrl keys alone does not trigger any action from the computer.

Sketch - is the name that Arduino uses for a program

keybrd sketch - is an Arduino sketch that uses the keybrd library to define a keyboard firmware.

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.