Featured

Building a custom keyboard – intro

A custom keyboard? Why? How?

I use keyboards all day, every day. Work computer, work laptop, home computer, home laptop, phone, tablet… even my Nintendo Switch has a virtual keyboard. And cavemen everywhere will tell you that for comfort and feeling, nothing beats a good old mechanical keyboard.

There are plenty of mechanical keyboards on the market, but there is always a problem with every one of them. It could be the size, the shape, the key layout on 60% or TKL, the keycaps, the LED color, the extras… For example, I really like typing on a full 104-key keyboard, but recently I’ve felt the need for a smaller alternative. For reference, this is the keyboard that I use both at work and at home: the Das Keyboard 4 (Ultimate and Professional).

daskeyboard-4-ultimate-front-view-carousel

And here’s what I need to consider when choosing a new keyboard:

  • I like having arrow keys, the page up/down keys from time to time, the home/end key when programming, and I always use the keypad when more than 2 digits are needed. So I need to keep these in a smaller set of keys.
  • I game a decent amount. Game boards are a good alternative but choices are few and are far from perfect.
  • I don’t touch type correctly. I have built my muscle memory over the years, so I don’t use the right fingers, even though I don’t have to look at the keyboard.
  • I like professional-looking keyboards, but a bit of whimsy with LEDs is welcome, especially for the home keyboard.
  • “Form follows function” is a good principle for such an accessory, where productivity is paramount, whether it is for typing or gaming. Key layout and extras may be different depending on what task is performed.
  • While I type in several languages, I’ve become accustomed to the ANSI layout and prefer it over the ISO layout.

Because of all this, I decided that I would build my own, custom keyboard.

It turns out that this is a more common hobby than I imagined, and many things that one needs have ready-made solutions which makes the whole process relatively easy, even for people without electronics or programming experience. This post will follow the progress of my research and experiments with custom keyboards, as I try my hand as “making” for the first time.

The choices, and options

There is a whole world of choices behind the perfect keyboard. Personal taste plays a large role in that, as well as the purpose behind the keyboard. I’ll try to outline as many of them as I can. In the next post I will add ideas for experimentation and my choices.

The layout

This is the most fundamental part, as it will influence the rest of the design. There are already many alternatives out there:

The 104-key ANSI layout

This is the standard one we know and use. It has remained unchanged for decades and is the one that all new computers come with.

filco-standard-layout

The tenkeyless layout

What if you never use the keypad? Just remove it! This is the Ducky keyboard, a very popular alternative.

du4bkyb

The 60% layout

The smallest standard layout. With this one, keys are lost (the `~ key is replaced with Esc, F keys are gone, and there are no arrow keys). To remedy this, the keyboard supports “layers”. A single key press will have different effects depending on which layer is active. The Fn key is an example of key that will determine which layer is active. Layers are the solution to smaller layouts, but can be extended to turn keyboards into multi-purpose peripherals.

Smaller keyboards reduce the travel distance for your hand to use the mouse, which relieves tension in the shoulder and neck.

poker2.jpg

Non-standard (but still recognizable) layouts

After that, one can add or remove keys, or even move them around. This really depends on how you use the keyboard. One of my inspirations for building a custom KB was to find the Whitefox by Matt3o (a reference and an inspiration on the subject). The layout can be customized, and the firmware can be modified if you are familiar with C.

whitefox

whitefox-programmable-mechanical-keyboard-07

I like that this keyboard looks like a 60% layout but adds another column of keys to provide some of the lost functionality. The `~ key was moved from its original place to the right side. This is definitely my main inspiration for this project.

Ergonomic layouts

You know this, but the idea behind the ergonomic keyboard is to bring the hands to a more natural angle, reducing wrist stress and the possibility of getting carpal tunnel after long bouts of typing. For this, the layout is split in two sections, one for each hand. Unfortunately, ergonomic keyboards usually assume that their owners can touch type correctly.

We have all seen the classic Microsoft ergonomic keyboard, which adds a bit of curvature. But there are more “extreme” examples:

7332059_sa

maxresdefault

The Ultimate Hacking Keyboard can be used as a normal, one-piece keyboard or separate in two pieces for ergonomic placement.

Ortholinear layouts

The ortholinear keyboards simply form a matrix of keys.

t1qqfad.jpg

This is a cool-looking keyboard, but it apparently takes time to adjust and get back the typing speed one has learned to get on a regular layout. However, a programmable keyboard with this layout can become anything: a soundboard, a map of specialized macros for software, etc.

While it can be difficult to adjust one’s typing method with it, some gamepads use this layout, so it may be useful for this purpose.

Fully ergonomic

These keyboards break a few conventions we’ve seen in the examples above: the keys are neither vertically nor horizontally aligned, they are not arranged on a flat plane, and the layout can be completely different. The idea is to respect each finger’s length and travel distance, which results in little to no wrist movement, further reducing stress and possible injuries. These keyboards are not solving the space issue though, see for yourselves:

The Kinesis Advantage is the first example I’ve seen of this.

kinesis20advantage201.jpg

Other examples include this keyboard, which seems to add even more curves by adding thumb wells, and a full pad of keys in the center.

ergonomic-keyboard1

The switches

There are many different types of mechanical switches out there.

The most famous and wide-spread switches are built by Cherry and are known as Cherry MX ; they come in various flavors, depending on whether one likes to feel and/or hear the actuation, how much force one likes to exert on the switch for it to register. It comes down to feel and purpose (many people love the brown switches for typing but the red switches for gaming, some love the “clickyness” of blue switches but people who work in the same open space may disagree).

Other types of switches include Topre, which many enthusiasts prefer for its feel and simpler mechanism. Alps switches are also popular and praised for their feel.

The micro-controller, software and electronics

Once we picked the switches, we need to add the electronics for them to become a keyboard. On the surface, this looks complex, as:

  • The circuit must register on the computer as a keyboard, i.e. as a human interface device (HID) and communicate as such
  • The system must be able to register potentially 100+ keys and send the correct data over the USB (or Bluetooth)

Fortunately, smarter people than I have figured out those things and prepared the work for us.

The most popular micro-controllers for electronics enthusiasts and makers are ATMega controllers and ARM controllers. ARM controllers usually offer higher computing power, support more peripherals and I/O protocols, and have more pins to work with.

Arduino boards are extremely popular, and feature either an ATMega or an ARM chip.

Another popular pre-made board is the Teensy.  It is particularly popular for custom keyboards for the reason we will see below.

The appeal of pre-made boards with ATMega or ARM chips is that they connect via USB, usually come with a development environment and with software to easily upload firmware onto the boards. They also benefit from very large communities which have been extremely productive and make most of their code open source for us to use as is or customize.

The reason why Teensy is popular for keyboards is that there is such a firmware: TMK, or its variant, QMK. The firmware takes care of the USB registration and communication, of processing the data in and out of the micro-controller pins, and of converting those inputs into key presses the computer can understand. Usually, the most “programming” one needs to do is configure the keys and layers along rows and columns, also called the key matrix (more about this later).

The materials

The physical build for this project is rather simple: you need a plate onto which the switches will be attached, and a case. If you choose a standard key layout (104-key, TKL, 60%), you will easily find pre-cut plates and cases for sale on the internet.

Plates are usually made from aluminium, steel or plastic. Rigidity is necessary so the plate doesn’t cave and bend on keystrokes. The case can be made out of anything.

For home enthusiasts, there are a few options, depending on the tools available to you and the money you’re willing to shell out.

3D printing is a great tool to build the case. It doesn’t quite provide the strength needed to avoid deformation though, making it a poor choice for the plate if not reinforced.

Laser-cut acrylic is stronger than 3D-printed plastics, but does not offer the design flexibility that 3D printing offers, and it also requires reinforcement to be used for the plate.

Aluminum and steel can be cut by many consumer-grade laser cutters, and are great materials for the plate.

The features

After doing some research, I have found many different features for keyboards, some of it we take for granted, some that are a bit less common. I’ll list the ones I have in mind, and add the questions they got me thinking about.

USB outlets/USB hub

xarmoru9bl_39

This is particularly interested for those with a Bluetooth mouse, or as a thumb drive outlet, or for other peripherals.

How does that work? Is the cable sticking out from the keyboard the USB hub input, and the keyboard itself is only one of the peripherals plugged into the hub? Can the hub be powered (with a thicker cable containing USB and power)? How would that work with USB-C? Can we have high-amperage USB-C outlets on a keyboard?

Headphones and microphone jacks

See photo above. Is this just a jack-to-USB device that uses the USB hub? I don’t expect the keyboard cable to include more lines for these.

Trackball, trackpoint or mouse by keys

To further reduce hand travel distance from keyboard to mouse, the keyboard itself can feature a trackball, a trackpoint, or even emulate the mouse with keypresses. The Ultimate Hacking Keyboard (UHK, see above) for example has a mouse layer, and the QMK firmware supports mouse outputs.

Usually mice are different devices for the computer, is it once again a hidden USB hub where one device is a keyboard and the other is a mouse? Can one HID device send both keyboard and mouse signals (from the QMK software support, it looks like it might be the case).

LEDs

How to personalize your keyboard? Add LEDs, and rotate colors and patterns by typing a set sequence of keys. LEDs backlight under the keycaps, LEDs around the case, there are so many possibilities!

RGB patterns quite probably need an extra MC to control them, but for simple, one-color backlight with just levels of brightness, would the Teensy or Arduino suffice?

Case buttons

When typing, I find it instinctive to find spots on the side of the case. Adding buttons on these spots would be an easy way to add functionality without expanding the keyboard surface area. The UHK features case buttons, and I have seen other custom keyboards with flat buttons on the side of the case.

uhk-merged-photo-1024x425

Volume wheel

Wheels are so much more practical than buttons for volume control in my opinion. More precise, faster, and just more intuitive. Usually easier to find as well. I love the volume wheel on my Das Keyboard 4, but drum roller wheels have a smaller footprint.

 

Is this part of the usual HID device control features?

Extra storage

If we build a USB hub inside a keyboard, why not make one of the USB peripherals a storage peripheral? Some people have managed to add hidden storage, which only appear when a given sequence of keystrokes is performed (like a password).

This is done by programming a MC so the USB storage’s power pin is only up if the correct sequence is entered.

LED/LCD screens

Screens are also a common feature on gaming keyboards. It can display information about the computer (CPU/GPU temperature, music track being played, etc) or information about the keyboard (the UHK’s three 7-segment displays indicate which layer is active).

Custom keyboard – The problem of power, and backlight

In the previous post, I explained how the backlight can easily be added to our keyboard by using the built-in feature of QMK, and built a prototype that could even change the backlight level based on the active layer by using on single LED – resistor pair on the signal pin.
This setup will not work with a full backlight however. To understand why, we need to do a bit of basic electronics.

Take a 70-key board, with one LED per key. There are many kinds of LEDs out there, but most of the common ones have a 20mA forward current, which means that they reach their maximum brightness at 20mA. If we wanted 70 LEDs at 20mA, we would need 1.4A, which is way more than what the Teensy can deliver on a single pin (60mA at the most).

It actually exceeds the maximum current a USB 2.0 port can deliver (500mA) by a factor of 3! Even USB 3.1 will struggle, as it delivers 1.5A but the Teensy itself will need some current to function. We need to solve for those two issues.

The power issue

But this led me (pun intended?) to a fact I hadn’t considered before: if I want to build a high-end keyboard will a screen, a trackball, case and backlight RGB LEDs etc, each of those features will consume current, so I need to make sure that I don’t exceed 500mA for a USB 2.0 port or 900mA for a USB 3.0 port. Each feature will have to be designed in a way that doesn’t consume too much energy.

Usually, this is the kind of consumption one can expect:

  • A normal keyboard: 50 – 100mA
  • A mouse: 15 – 50mA
  • Backlight LEDs (single color): to be discussed further
  • Backlight LEDs (RGB): to be discussed further
  • A USB hub (nothing plugged in): 10-50mA
  • A small LCD screen, backlit: 20-150mA

And then there is anything plugged in to the other ports of the USB hub. 500mA is quickly reached! Many devices, such as webcams, register directly as 500mA devices on the computer.

For every iteration of the keyboard, and for each feature added, we’ll have to take the current consumption into account. If we need higher currents, we will have to:

  • Have two USB 2.0 plugs in one cable
  • Make sure that the keyboard is plugged into USB 3.0, or 3.1

For now, we can simply make sure that we’re not using too much current.

Back to LEDs

Armed with this knowledge, we can now define what power we will give the LEDs. It will probably be higher than what the Teensy can deliver, but we’ll find a way around this.

How much should they consume?

I decided that my 70 LEDs (it will depend on the keyboard) will consume 100mA. This means that each LED will have an allowance of 1.43mA. We’re well below the 20mA many common LEDs can use!

About brightness

A bit of research showed me a few interesting things:

  • LEDs vary greatly in their intensity (measured in millicandelas, or mcd). For example, for T-1 package, through-hole LEDs (the ones that fit our switches), Mouser lists LEDs going from 1 mcd to 15000 mcd
  • The listed intensity is reached at the forward current rating
  • They also vary greatly in their forward current rating (If), the same search yields results from 1mA to 100mA (40% have the 20mA forward current rating)
  • The brightness is proportional to the current fed into the LED

From that, we can see that a 20mA, 10000 mcd LED and a 2mA, 500 mcd LED will have the same brightness if we give them both 1mA.
So it looks like brightness is the real question here, and is also a matter of taste. But for a keyboard, we will have to find LEDs which have a decent intensity at the maximum current we want to give them, since QMK supports brightness levels via PWM.

Experiment

I want to experiment with this, try different LEDs with different ratings, and test the brightness. So I ordered 10 of the Kingbright WP710A10SEC/J4  (20mA, 10000 mcd) and 10 of their WP710A10LSECK/J4 (2mA, 550 mcd).

A quick application of Ohm’s law: I want 1.43mA in 10 LEDs, or 14.3mA total, and the Teensy has a 5V pin.

\displaystyle R = \frac{U}{I} = \frac{5}{0.0143} = 349.65 \Omega.

We will round it up to 350Ω.

And let’s build this simple circuit.

LEDs

Result: both kinds of LEDs produce very similar brightness with the given current. The assumption was right: we can severely under-feed the LEDs and still get a great result.

Full backlight power

Ok now we have a way to have good backlight with just 100mA of current. This is still to much for just one Teensy pin. We could drop the current even more, but it would limit our choices for LEDs later, and it is generally discouraged to drive power-hungry payloads with a MC pin.

What we need is a way to power the LEDs directly via the USB power line, and have the pin activate a switch that would complete the circuit when we want light. The PWM aspect would still work. Something like this:

LEDs-2

Luckily, this kind of thing is pretty common, it’s a simple transistor. There is a very particular kind of transistor that is popular for logic-level voltages with relatively high payloads: MOSFETs. Metal Oxyde Semiconductor Field-Effect Transistors, especially N-channel ones (for reasons I won’t get into in this post, it took some learning), are very simple to use and work perfectly for us. I chose to buy the ON FQP30N06L, a popular model, which is activated by a 5V signal and can handle large payload currents and voltages.

For N-channel MOSFETs, the drain is connected to the payload, and the source is grounded. Our circuit becomes this:

LEDs-3

Now we have a LED backlight completely disconnected from the logic circuit. We can easily handle 100mA this way, and have our bright backlight!

This is a good solution for a single-color backlight. In the future, we’ll think about RGB versions.

Custom keyboard – More software features – layers and backlight

Layers!

As I mentioned in the intro article, layers are the main reason small layout keyboards can retain as much functionality as full, 104-key keyboards. So naturally, I wanted to experiment with layers first.

This time, I had to start reading up material, because the code surrounding layers is rather obscure. I found this and this pages which explain them fully.

Basically, QMK supports up to 32 layers. Each layer can be active or inactive. When a key is pressed, the keycode associated with this key on the topmost active layer is sent. Unless that keycode is KC_TRNS (transparent), in which case the keycode from the first active layer under it is sent. The default, bottom-most layer is always active.

Let’s see a few examples with a simple keyboard of six keys in a row, and 4 layers.

  ________________________
 /_A_/_B_/_C_/_D_/_E_/_F_/  -- 3
  ________________________
 /_G_/_H_/_I_/_J_/_K_/_L_/  -- 2
  ________________________
 /_M_/_N_/_O_/_P_/_Q_/_R_/  -- 1
  ________________________
 /_S_/_T_/_U_/_V_/_W_/_X_/  -- 0, active


Only the default, bottom layer is active. If the first key is pressed, ‘S’ is sent. If the third key is pressed, ‘U’ is sent, etc.

Now, let’s see what happens if we activate a few layers.

  ________________________
 /_A_/_B_/_C_/_D_/NO_/TRS/  -- 3, active, with KC_NO and KC_TRNS keycodes
  ________________________
 /_G_/_H_/_I_/_J_/_K_/_L_/  -- 2, active
  ________________________
 /_M_/_N_/_O_/_P_/_Q_/_R_/  -- 1
  ________________________
 /_S_/_T_/_U_/_V_/_W_/_X_/  -- 0, active

Pressing the first key will send ‘A’. Pressing the 5th one will not return anything, and pressing the last one with send ‘L’.

KC_TRNS is particularly important when switching layers. We’ll see why soon.

There are several ways to switch layers in QMK , these are the codes to be used in the keymap:

  • MO(layer): if “layer” is higher than the current layer, switch to “layer” as long as key is pressed.
  • LT(layer, kc): if the key is tapped, keycode “kc” is sent. If the key is pressed, it behaves like MO
  • TG(layer): if “layer” is higher, toggle the layer’s active status ON/OFF
  • TO(layer): go to “layer”, whether it is higher of lower, on key down
  • TT(layer): if “layer” is higher and the key is pressed, behave like MO, or if the key is tapped X times (configurable), toggle “layer”

So basically, for all but one command, layers can only be manipulated from under them. And this is where the KC_TRNS key comes in. Imagine the following setup:

  ________________________
 /_M_/_N_/_O_/_P_/_Q_/_R_/   -- 1
  __________________________
 /_S_/_T_/_U_/_V_/_W_/TG(1)/ -- 0, active

Pressing the last key will toggle layer 1:

  ________________________
 /_M_/_N_/_O_/_P_/_Q_/_R_/   -- 1, active
  __________________________
 /_S_/_T_/_U_/_V_/_W_/TG(1)/ -- 0, active

But now, pressing the last key will register as ‘R’, there is no way to deactivate layer 1. We lost access to the default layer. Using MO or LT or TT will not solve the issue, once layer 1 is active, the keycode has changed, so we can’t go back to layer 0. Even using TG(1) instead of ‘R’ will not work, since layers can only be (de)activated from below.

KC_TRNS solves the issue.

  _________________________
 /_M_/_N_/_O_/_P_/_Q_/TRNS/    -- 1, active
  __________________________
 /_S_/_T_/_U_/_V_/_W_/TG(1)/   -- 0, active

Now, layer is active, but the key is “transparent”, so pressing it again will register as the keycode for layer 0, which will deactivate layer 1.

Applying layers to our example

Let’s try several layer-switching techniques. We will define 2 more layers for our keyboard in our keymap.c file.

#define _QW 0    // QWERTY layer, QWEASDZXC keys
#define _QR 1    // QWERTY right, or IOPJKLBNM
#define _NB 2    // Number pad, 789456123

We already predict that we will not be able to use all those keycodes, since some keys will be used for layer switching. And here are the keycodes:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
/* Qwerty
 * ,-----------------.
 * |  Q  |  W  |  E  |
 * |-----+-----+-----|
 * |  A  |  S  |  D  |
 * |-----+-----+-----|
 * |  QR |  X  |Numbr|
 * `-----------------'
 */
[_QW] = KEYMAP(
 KC_Q, KC_W, KC_E,
 KC_A, KC_S, KC_D,
 TG(_QR), LT(_QR, KC_X), MO(_NB)
),

/* Qwerty right
* ,-----------------.
* |  I  |  O  |  P  |
* |-----+-----+-----|
* |  J  |  K  |  L  |
* |-----+-----+-----|
* |     |     |  C  |
* `-----------------'
*/
[_QR] = KEYMAP(
 KC_I, KC_O, KC_P,
 KC_J, KC_TRNS, KC_L,
 KC_TRNS, KC_TRNS, KC_C
),

/* Numbers
* ,-----------------.
* |  7  |  8  |  9  |
* |-----+-----+-----|
* |  4  |  5  |  6  |
* |-----+-----+-----|
* |  1  |  2  |     |
* `-----------------'
*/
[_NB] = KEYMAP(
KC_7, KC_8, KC_9,
KC_4, KC_5, KC_6,
KC_1, KC_2, KC_TRNS
)
};

So we have two ways of accessing layer _QR: either tap the lower left key, or hold the lower middle key. Tapping that key should send ‘X’ instead. But as we saw earlier, we need to keep those two keys transparent to be able to switch back to the bottom layer. The _NB layer can only be accessed by holding the lower right key. That key must also be transparent on that layer.
– But wait! If it is transparent, shouldn’t we still switch to the _QR layer?
– No, the _QR layer is never activated by pressing that key. So we can only be on layer _QW or _NB.

We also see that there is no way to go from layer _QR to layer _NB or vice versa. We could have added this, by replacing ‘C’ with TG(_NB) for example. Since we already have a transparent key on _NB at this place, it would make sense.

And this is all we need! Flashing this to the Teensy transforms our 9 keys into a much more complex system. At the end of this article we can have fun and look into how many keycodes we could emulate if we wanted to maximize their number on just 9 keys.

Backlight control

In the previous article, we connected an LED and resistor to pin B7 that we designated as the backlight key. Let’s try and add a backlight control layer to our keyboard.

This page provides the full list of “quantum” keycodes, i.e. all the non-trivial KC_A, KC_B, KC_1, etc. It tells us that there exists:

  • BL_ON to turn on the backlight to full brightness.
  • BL_OFF to turn off the backlight
  • BL_INC to increase the brightness
  • BL_DEC yes, you guessed it

We also decided that we would support 5 levels of brightness when we configured our code. So let’s add this.

First, in 9pad.h, we need to include the header file

#include "backlight.h"

and add our new layer!

We’ll modify our base layer to add access to the backlight layer:

#define _BL 3

/* Qwerty
 * ,-----------------.
 * |  Q  |  W  |  E  |
 * |-----+-----+-----|
 * |  A  |  S  |  D  |
 * |-----+-----+-----|
 * |  BL |  X  |Numbr|
 * `-----------------'
 */
[_QW] = KEYMAP(
 KC_Q, KC_W, KC_E,
 KC_A, KC_S, KC_D,
 TG(_BL), LT(_QR, KC_X), MO(_NB)
),

...

/* Backlight
* ,---------------.
* | ON |  +  |    |
* |----+-----+----|
* | OFF|  -  |    |
* |----+-----+----|
* |    |     |    |
* `---------------'
*/
[_BL] = KEYMAP(
BL_ON, BL_INC, KC_NO,      // We add KC_NO for keys with no keycode
BL_OFF, BL_DEC, KC_NO,
KC_TRNS, KC_NO, KC_NO
)
};

Then, we need to initialize the backlight library, so in 9pad.c, we add, in matrix_init_kb:

void matrix_init_kb(void) {
  matrix_init_user();
  backlight_init();
}

Still pretty simple. For now, we only control one LED, but we will see later how to control an entire matrix of LEDs.

Let’s flash the firmware!

We see that, upon startup, the LED is turned on bright. Tapping the lower left key switches the keyboard to the _BL layer. Tapping the center key lowers the brightness on key up. Tapping the top middle key does indeed increase the brightness! Awesome! Lowering the brightness down a couple of levels and tapping the top left key makes it fully bright again. For some reason though, BL_OFF does not seem to work for me. Not sure why yet.

img_20170813_202421.jpg

Look closely, the LED is on, but dim.

img_20170813_202435.jpg

Layers and backlighting – together

Looking back at some of the code that we deleted before, we can see that the Traveller keyboard was changing the RGB color depending on which layer was on. Let’s adapt this code to set a brightness level based on which layer is active.

We can define a function that sets the backlight level, using the “backlight” library:

void layer_led_set(uint8_t layr) {
  switch (layr) {
    case _QW:
      backlight_set(4);
      break;
    case _QR:
      backlight_set(3);
      break; 
    case _NB:
      backlight_set(2);
      break; 
    default:
      backlight_set(1);
      break;
  }
  return;
}

And we can add some logic to the matrix_scan_user hook to detect layer changes and call this new function.

uint8_t old_layer=_QW;

void matrix_scan_user(void) {
  uint8_t layer = biton32(layer_state);
  if (old_layer != layer) {
    layer_led_set(layer);
    old_layer = layer;
  }
}

Flash the firmware, and now there are different LED backlight level for each layer! We’re making progress!

 

Addendum: how many keycodes can we fit?

Now for a bit of a brain-tease, let’s see what is the most efficient way to arrange layers so up to 32 of them are accessible, and how many keycodes our 9-key pad could pack.

It seems like just 2 layer-switching keys are necessary to access any layer of the stack:

  ____________               ______
 /_____/_   _/  -- 4        /_   _/  = transparent key
  ____________
 /_   _/TG(4)/  -- 3
 ____________
 /TG(3)/_   _/  -- 2
  ____________
 /_   _/TG(2)/  -- 1
  ____________
 /TG(1)/_____/  -- 0

Alternating the left and right keys allows us to move up and down the layers.

So for our 9-key pad, 2 keys are used for transparent keys (except on the topmost and bottom-most layers), and 7 are used for keycodes.

So 32 * 7 + 2 = 226 keycodes! We could fit two full keyboards and have 2+ layers to control the backlight and the mouse!

Yeah, layers are powerful!

But I believe that for most purposes, all possible layers should be accessible from the default layer with just one keypress. Intermediate layers are not practical, but could be used for rarely used keycodes, or exotic uses (music, etc).

Custom keyboard: code for 9-key prototype

Layers, backlighting, etc.

Now we have everything we need for the prototype to work, we just need to adapt existing QMK code for our needs.

QMK is an open-source firmware written to be used on Arduino or Teensy boards. It has a wide range of features for keyboards, many of which I have yet to discover. The ones that caught my attention and that I wanted to experiment with are:

  • Layers. The same key could have different effects depending on which layer is active. QMK offers very cool features with layers.
  • LED backlighting. QMK offers support for a single-color backlighting with multiple brightness levels. RGB backlighting (all keys illuminated with the same color) is also possible with an extra IC (more when we need RGB backlighting)
  • Simple macros with shift, control, GUI (command for Mac, Windows key for Windows, etc) and/or alt.

Setting up the compilation environment

I do have a dual-boot Windows/Ubuntu, but I didn’t want to have to switch from one to the other regularly with this irregular project. And while there are instructions to set up the compilation environment on Windows, they require too many software installations and vague settings that did not work for me. So I opted for a virtual machine.

I installed VirtualBox by Oracle, and installed the latest Ubuntu version. I also shared the code folder with my host machine so I could use Visual Studio Express to write code.  Once this was done, set up was a breeze. Only one command to run, and I was on my way.
A simple “make” call confirmed that the setup was complete.

For the firmware upload software, to flash the Teensy, I tried using the Ubuntu Teensy Loader, but it didn’t work as well as the Windows version to me, so while it is bit clunky, I decided that I would: write code on Windows, compile the code in Ubuntu on the VM, then upload the new binary on Windows.

The Teensy Loader is very easy to use. Connect the Teensy to the computer via a mini-USB to USB cable, press the button on the board, open the .hex file that is your binary, click upload and reset, and that’s it!

First discovery of QMK

Because I’m a caveman, I don’t read manuals. I dove directly into the code, trying to find whether it made sense quickly. And if you can read C, then I had the pleasure to discover that it did!

First, I assumed that I could just look at existing keyboards, and ignore the core logic. Maybe I could just copy one of them, and just tweak it.
I found the model-specific code in the keyboards/ folder, and saw that there was a whole list of handwired/ folders. I copied the last one, traveller/.

traveller/
|--+ keymaps/
|  |--+ default/
|     |-- keymap.c
|     |-- readme.md
|-- config.h
|-- Makefile
|-- readme.md
|-- rules.mk

First thing I found: there are not many files, and they are not very long. With two README files and a makefile, only 5 files had actual logic. Second thing I noticed: QMK seems to work via macros. The logic seems to be buried deep into the core code, and predefined macros provide hooks for the user to add their own code.

Looking around, I could see that the rules.mk file does not contain actual code (not a .h or .c), but seems to define the values of global variables for features and aspects of the build. Let’s see the main values, and how I modified them:

MCU = at90usb1286   # The chip. Teensy and Arduino are based on the
                    # ATMega32u4, but the Teensy++ is based on the
                    # ATMega90USB1286
F_CPU = 16000000    # The chip's frequency: 16MHz for the Teensy++
ARCH = AVR8         # ATMega
F_USB = $(F_CPU)    # Same input frequency as the chip's frequency

# BUILD variables
BOOTMAGIC_ENABLE = no
MOUSEKEY_ENABLE = yes    # To experiment with mouse inputs
EXTRAKEY_ENABLE = yes    # To experiment with audio and system control
CONSOLE_ENABLE = no      # No need
COMMAND_ENABLE = no      # For debug and config, no need
SLEEP_LED_ENABLE = no    # Can't be used with BACKLIGHT_ENABLE
NKRO_ENABLE = no         # We'll look into this later
BACKLIGHT_ENABLE = yes   # Experiment with LED backlighting
MIDI_ENABLE = no         # MIDI controls
UNICODE_ENABLE = no      # Unicode, we'll look into this later
BLUETOOTH_ENABLE = no    # Enable Bluetooth with the Adafruit EZ-Key HID
AUDIO_ENABLE = no        # Audio output, for later
RGBLIGHT_ENABLE = no     # Not RGB for now

The rest can remain unchanged. The next file that looked more like configuration than code was config.h. Let’s see what makes sense to change here.

#define VENDOR_ID 0xE0C1       // Those IDs are for USB device
#define PRODUCT_ID 0x000A      // descriptors. Any value will work.
#define DEVICE_VER 0x0001      //
#define MANUFACTURER Caveman   // 
#define PRODUCT 9pad           //
#define DESCRIPTION A custom keyboard

#define MATRIX_ROWS 3          // Making a 3 by 3 keyboard.
#define MATRIX_COLS 3 

#define MATRIX_ROW_PINS { D0, D1, D2 }  // Randomly chose pins to connect
#define MATRIX_COL_PINS { B5, B4, B3 }  // the rows and columns

#define DIODE_DIRECTION COL2ROW   // Orientation of the diodes in my
                                  // prototype: they form the rows.

#define BACKLIGHT_LEVELS 5     // Random number as well, to try
#define BACKLIGHT_PIN B7       // The pin for backlight

With this, we can already finish up the wiring. Let’s connect our rows in order to the pins D0, D1 and D2, and the columns to B5, B4 and B3. We can also add an LED and resistor connected to the ground and pin B7 to try backlighting. Breadboarding time!

IMG_20170813_124411.jpg

Ok now let’s make sure that we can send the proper signals when the keys are pressed. Looking into the new .c and .h files, now named 9pad.c and 9pad.h, we can see that the header file defines a KEYMAP() macro, which transforms a list of keys into a 2D array. There are symbols that look like they represent missing keys (due to some keys being longer than others or exotic layouts, not all columns are connected to every row, but the software needs a 2D array): KC_NO. I suppose this means “NO effect”. The keymap.c file then uses the macro to define layers with key symbols.

Let’s try and make our 9-key pad write Q, W, E, A, S, D, Z, X, and C first.

The KEYMAP macro will be rewritten this way:

#define KEYMAP(k00, k01, k02, k03, k04, k05, k06, k07, k08) \
  {{ k00, k01, k02 },\
   { k03, k04, k05 },\
   { k06, k07, k08 }}

The keymap.c file we copied from traveller/ seems to already define several layers and functions. We will remove most of this and just keep one layer.

#define _QW 0     // We keep this one QWERTY layer, and remove the others

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
/* Qwerty
 * ,-----------------.
 * |  Q  |  W  |  E  |
 * |-----+-----+-----|
 * |  A  |  S  |  D  |
 * |-----+-----+-----|
 * |  Z  |  X  |  C  |
 * `-----------------'
 */
[_QW] = KEYMAP(
 KC_Q, KC_W, KC_E,         // It seems that these define the letters
 KC_A, KC_S, KC_D,
 KC_Z, KC_X, KC_C
)
};

And let’s just remove the body of functions or structures fn_actions, action_get_macro, action_function, matrix_init_user, matrix_scan_user and completely remove LayerLEDSet.
And 9pad.c does not seem to contain anything interesting right now, so let’s leave it as is.

Flashing the firmware and testing

We’re all set!

Now, let’s build the firmware. From the folder that has QMK on the Ubuntu VM:

cd keyboards/handwired/9pad
make

I was rewarded with:

Creating load file for Flash: .build/handwired_9pad_default.hex [OK]

Now, with the connected Teensy and the Teensy Loader up, pressing the reset button on the board makes the loader show this UI:

Teensy Loader

Clicking the first button in the toolbar allows us to select the .hex file we just generated, then the second one uploads it to the board, and the third reboots the board.

With this, I have a keyboard!! A very simple one, but a working keyboard! If a text is only made up of those 9 letters, I can type it on this loosely grouped set of switches!

 

Mission accomplished! (well, the very first step…)

Custom keyboard experiments – basic electronics

The first series of experiments and findings.

First choices

In the previous post we touched on the various choices available to us to build a custom keyboard. I’ve decided to first try with:

  • Cherry MX Brown switches. They are the ones I use with my home and work keyboards and my favorite for typing. They can be readily bought from mechanicalkeyboards.com, and are available in plate-mounted or PCB-mounted flavors. Plate-mounted is especially interesting for us since we’re not planning to design a PCB yet.
  • The Teensy++ development board. Its wide community support, simple tools for firmware upload, and the fact that the powerful and widely-used QMK firmware is compatible with it makes it a great candidate.

I had some keycaps left from a previous keyboard so I could start with a simple 9-key, 3×3 matrix prototype.

The key matrix

The first instinct one would have to assemble switches and the development board would be to connect each switch to the +5V pin and to one of the I/O pins of the board. However, keyboards can have more than 100 keys, and very few controllers have that number of pins. It simply would not be possible, especially with a Teensy.

The solution is to have the keys form a matrix, and have the controller activate columns (or rows) one by one, and read the rows (or columns) to know which keys are active. Here is a very good explanation of how to make a key matrix, what ghosting is and how to get rid of it.

For the diodes, the “classic” choice for keyboards are 1N4148, which can be found dirt-cheap on Amazon or online electronic stores (my favorite: Mouser.com).

The soldering

Since I do not yet have access to a laser cutter to experiment with the plate, I decided to test making the matrix itself, free hand. Let me tell you, without a support to hold the switches together, this was no easy feat.

Here is what the underside of a Cherry MX switch looks like. I started by preparing a ball of solder on all terminals of my 9 switches to facilitate soldering the diodes and columns on later.

And here’s how the diodes are arranged to form the rows. I feel like I will need to pre-bend them when I need to solder 100 of these.

IMG_20170731_183719

And… first row done!

IMG_20170731_183922

I don’t think I’ve ever soldered components pin-to-pin before, especially with loose components…

Times 3, here are my 3 rows:

IMG_20170731_185008

Now for the columns, the wires will need to go over the rows, so they need to be insulated. I did not want to go through the trouble of cutting and stripping 9 wires, so I opted for this strategy:

IMG_20170731_190456

Unfortunately, without the proper measurements, this is not an easy solution to work with. Some segments will be too short, others too long, the plastic insulation melts, etc. Multiply this by 2 for 6 rows, it’s a bit too complicated. I may have to be more precise the next time or just use a multitude of small  wires. Anyway, here’s the final product (please don’t be too harsh on the soldering job, I hadn’t done any in a while and this is not the easiest way to work with components. But I love challenges 🙂

IMG_20170731_221758

And now we have a fully functional matrix.

IMG_20170731_221813

And here’s what it looks like from the front. I’m quite happy with it, the diodes and wires keep the switches together in a solid piece.

The Teensy’s pins

When the Teensy++ 2.0 arrives without headers, this is what is looks like:img_20170812_185242.jpg

And to make it easy to prototype on a breadboard, I soldered wires to every pin on the sides:

img_20170812_185356.jpg

Looks like a weird metallic spider…

Next up: working with the software, uploading it to the Teensy, and wiring the rows and columns accordingly.

Create your own website, free on WordPress.com.Create your own website.
Start free