Quantum Mechanical Keyboard Firmware
Cortney Ruic
a keyboard firmware based on the tmk_keyboard firmware with some useful featuresfor Atmel AVR and ARM controllers, and more specifically, the OLKB product line,the ErgoDox EZ keyboard, and the Clueboard product line.
If you read this you will understand that the keyboard originally comes with 4layers. Two for windows and two for Mac. The 0 and 1 layers are toggledusing a physical switch. The rest are toggled with the Fn key.
QMK (Quantum Mechanical Keyboard[2]) is open-source firmware for microcontrollers that control computer keyboards.[3][4][5] The QMK Configurator is freely available software which facilitates designing keyboard layouts and then turning them into firmware files. The QMK Toolkit is freely available software which facilitates the flashing or application of firmware onto programmable keyboards.
Recently, I got a mechanical keyboard named KBDfans Tiger Lite as a gift (Thanks Rose!). The keyboard runs the QMK (Quantum Mechanical Keyboard) keyboard firmware, which is open source and allows easy custom modification of the keyboard. I was pretty excited to get my hands on it, since I've been wanting to be able to customize my keyboard firmware.
The first three items were fairly simple to do with QMK. However, the last item, OS detection, proved to be non-trivial. QMK doesn't have such a feature built-in, and the USB devices don't get much information about its host (i.e., PC) at all.
The idea was first described in an Arduino project called FingerprintUSBHost, and Ruslan Sayfutdinov (KapJI) implemented a working version for QMK. Without the existing examples, I wouldn't have been able to come up with this idea.
After reading the OS-detection code by KapJI, I understood that there is a function get_usb_descriptor to return whatever USB descriptor type the host requests, and that their os detection code records the frequency of the value of the wLength field for "String-type descriptors". I had a vague understanding of what a "usb descriptor" might be (that it's related to the USB device initialization) but wasn't sure how it works. I understood that this counter has to be reset but wasn't sure where to do it. There was documentation for the feature but, it did not explain to me why this works, or what the meaning of those fields were. I decided to dig deeper since I was having a slow week.
One interesting quirk that makes the OS-detection work is that the real-world OSes request the same String descriptor multiple times with different wLength, which specifies the maximum size of the String that the host is willing to accept.
So why does this particular call pattern occur? My guess is that this behaviour exists to work around defective USB devices. For Linux, I was able to find its source for querying String descriptors. First thing to note is that the behaviour that the OS-detection code looks for is consistent with the source code that we see. Linux asks, right away, for strings with wLength 255 (0xff) and never again if the device is well-behaved. Second, Below the initial String query, you can also see that Linux has different workarounds for defective devices, which didn't kick in for my keyboard.
While I can't read the source for Windows or MacOS, but based on the Linux code, it seems likely that the other OSes also have similar workarounds for different USB devices. Lucky for me, these wLength patterns occur consistently enough for the OS-detection code to work reliably.
My first attempt was to just delete the counter when the host asks for the Device descriptor, since that is the top-most logical object of the device. Unfortunately, this didn't work for a couple of reasons. First, there is no guarantee that the Device descriptor is only queried once and in fact the supported language String descriptor (index 0) can be logically queried even before the Device descriptor itself, since it's independent of the Device descriptor.
After going through the QMK source code, I found that there is an undocumented hook named notify_usb_device_state_change_user, which gets called on USB reset, which happens when the KVM switches between the host devices.
The original code also doesn't specify how long I need to wait after the USB-reset before executing the OS-detection (it just says "probably hundreds of milliseconds") but by now I knew exactly how long:
The clone is written to the qmk_firmware directory. The sub-directories include various resources for building firmware, the most important of which is /keyboards, which includes the configuration files for building firmware for each supported device.
To test the QMK installation, locate the device manufacturer in the keyboard directory. The device will have a default firmware file somewhere in the sub-directories, the exact position varying with the model. For example, you might enter:
Each keymap has a directory with a unique name. The keymap itself is contained in the config.c file inside the directory. You can create a new layout either by copying the default and immediately renaming the copy, or by entering the command:
The layers are mapped below in comma-separated lists that reproduce the rows on the keyboard. Layers are numbered from 0, and may also have a name. Keycodes designate characters, audio controls, backlights, and macros. For example, KC_A is upper and lower case A, KC_RIGHT the right arrow key, and KC_CALC the system calculator. Not every device supports every keycode, so you will either need to have documentation or be willing to experiment.
If you create multiple layers, you will want to leave keys on each layer for keycodes to move between layers, either momentarily or permanently. The documentation suggests that each layer should be able to transfer to only one layer. For instance layer 0 could switch to layer 2, layer 2 to layer 3, and layer 3 back to level 1.
If you only want a single layer, QMK devices can also be configured using the web-based Configurator (Figure 2), which is compatible with Chrome and Firefox. Some manufacturers of QMK-based devices may also have their own tools for configuration. While working with the Configurator, you will probably want to open the list of keycodes in another tab for easy reference.
Start by selecting your device from the top of the Configurator. If your device is not listed, check the manufacturer's GitHub page to see if the code is available but not integrated yet. You should also do a pull request. When you choose the device, you also see a summary of the device, which can be useful for troubleshooting.
Next, choose the keyboard closest to the layout you want in order to save some time. If no layout fits your needs, select LAYOUT_all, and be prepared to configure all the keys individually. Give the layout a unique name as well, making sure the name is not already in use.
When you have finished assigning keys, press the Export Keymap button to save the keymap to your computer, then load it by pressing the Import Key Button. To flash the keymap, press the green Compile button, followed by the green Download Firmware button. Be sure to put the device into Bootloader mode, by pressing a key or whatever other method the device uses.
An increasing number of QMK devices support special keycodes. Many of these allow a key to support multiple characters. As described in the QMK documentation, some of these keys are defined in separate files. Advanced keycodes include:
As far as most users are concerned, keyboards have changed little in the last 40 years. However, projects like QMK have radically expanded what keyboards can do. If QMK devices cost more than a keyboard that is thrown away in a year, the higher price is worth it for a device that lasts longer, can be repaired, and empowers users to work and play exactly the way they want. The next time you buy a keyboard, you could do worse than check the list of QMK devices. As in so many fields, QMK is an example of how open source is revolutionizing an established field.
This keyboard design is made from the ground up as open source and naturally is fully available as a GIT repository containing everything you need to start: PCB schematics, drawing, documentation and firmware source code.
It took me a couple of months to get all the required parts ordered and delivered. Many small envelopes with parts that seemlingly are only produced by a handful of manufacturers. But anyways: After everything had arrived and was checked for completeness my wife took the hardware parts into her hands and started soldering and assembling the keyboard.
The answer is: by default QMK assumes that you are plugging into the left half of the keyboard making the left half the master. If you prefer to use the right half you can change this behaviour in the config.h file in the firmware:
Custom keyboards are not just flashy keys and a frame that holds them in place; they are a medium of self-expression and a tool tailored to fit every keystroke you make. At the core of this personal touch are QMK (Quantum Mechanical Keyboard) and VIA firmware, which lets you customize your typing experience down to the last detail. In this article, we are going to talk about why having QMK/VIA is important if you wish to take your custom keyboard from good to great. For anyone dipping their toes into the world of custom keyboards or just wanting to finesse a setup, understanding these powerful tools is vital in the creation of a keyboard that really feels like it's yours.
A custom keyboard can fit you perfectly-the keys are just where you need them, it responds to your touch exactly how you like, and it even looks the way you want. That's what a custom keyboard is all about. It's not your average store-bought keyboard; it's built from scratch, piece by piece, to match its owner's specific desires for comfort, functionality, and aesthetics.
Firmware might sound technical, but think of it as the brain of your keyboard. Just like you need your brain to tell your hands how to move, your keyboard needs firmware to understand what to do when you press a key. QMK and VIA firmware are like two different types of brains-one offers a deep level of customization if you know how to code, while the other makes customization accessible to everyone through a user-friendly interface.
93ddb68554