Keybon – Adaptive Macro Keyboard

Customizable OLED keyboard that adapts to the apps you use

Similar projects worth following
Keybon is a macro keyboard with configurable layouts and functions. Integrated into each of its nine tactile buttons is a 0.66” OLED screen. Depending on which app is active on the connected computer, Keybon switches to the suitable key layout thanks to its companion software.

Some of the key features are:
• Standalone Mode as a USB HID device
• Companion-Software for customization and app-switching
• Tactile switches
• 0.66” 64x48 px OLED displays
• Fully 3D-printed case and key mechanism

Layout files, code and STLs on Github:

How it works:

  • In Standalone mode, Keybon acts as a simple HID keyboard and shows its preconfigured buttons functions.
  • The companion software for windows allows you to create your own keyboard layouts and assign them to any application on your PC. The companion software monitors the applications in focus and changes the layouts accordingly. In this mode Keybon communicates over a virtual COM port. Layouts are sent to the device on demand which in turn sends key events back to the computer.

  • 1 × 0.66in OLED (UG-6448KLBEG03) Bought from LCSC, but must 0.66" OLEDs should be compatible
  • 1 × STM32F103C8T6 Microprocessors, Microcontrollers, DSPs / ARM, RISC-Based Microcontrollers

  • Companion App

    Max.K12/09/2020 at 20:32 20 comments

    Without the appropriate desktop software, Keybon is just a programmable keyboard. The goal was to add the ability to configure the device from windows and change keyboard layouts on the go. I decided to create a windows forms application in C#. 

    The application works like this: You connect to the keyboard via a COM port. Then you configure the icons that are displayed on the OLED screens and the macro functions for each button. This can be done via drag&drop for the images. The button commands need to be entered in a way the “sendkeys” method can interpret them. For example, +{h}{e}{l}{l}{o} prints “Hello” when pressing the corresponding button. You can create up to 8 layouts, but there is really no hardware limitation to this. As the layouts are only saved on the computer, the STM32’s memory is not the limiting factor. When a layout is activated, the application sends a command to the keyboard that disables its HID function. After that, the nine images are transferred via the COM port as a stream of bytes. This takes only a few milliseconds, so the change on the actual OLEDs is instant. To each layout a set of windows processes can be added. The software constantly checks what application is running in the foreground. If for example Google Chrome is opened, the software instantly switches to the matching layout.
    As this was is my first C# project, making the app took some time and effort. By splitting the functionality into small parts, each problem became solvable. Detecting foreground apps has fortunately been well documented. Writing images to the keyboard was just a matter of efficiently splitting bitmaps into bytes. One of the most complicated part was saving and loading settings. I decided to use the feature built into Visual Studio, that saves a single .xml file to “users/appdata/…”. This way the .exe works without an install or a visible settings folder. As .xml files are text based the bitmap information needs to be serialized first and reassembled into an image later. After all I am quite happy with the companion software. There are of course plenty of usability features that could be added, but the basic functionality is sufficient to use the keyboard productively.

  • Electronics

    Max.K12/09/2020 at 20:31 0 comments

    For connecting the keyboard to a computer, USB was the obvious choice. Not having to care about low-energy was a welcome change from my previous, mostly battery-powered projects. The first microcontroller that came to my mind was the Atmega32U4 as it has built-in USB support and does not need a separate USB to serial converter. But one problem is its small SRAM with only 2kB. When using displays their pixel values are usually saved in RAM, so that the image can be easily manipulated. For a first iteration of the keyboard, I was planning to use nine OLEDs with 64x48 pixels each. This adds up to 3456 bytes of memory. It would be possible to use the Atmega with some software trickery, like keeping only one screen in memory and cycling through them. But I did not want to risk running into performance problems later. Instead, I decided to use the ST STM32F1 as it is cheap, has USB support and upwards of 20kB RAM. It also is officially Arduino-compatible, known for being used in the Blue-Pill boards. 

    With all parts select I created a compact PCB that would hold nine OLEDs. The board contains mounting point for the 3D-printed button mechanism. On the “chin” of the device, where the levers of the last row of screen sit, there is just enough room for a USB-C connector and the STM32F1.Ultimately the wiring of this PCB is very simple. The STM32 is supplied by the USB connection and a 3.3V regulator. The regulator (AP2112K) also powers the nine LEDs, which contain internal dc-dc converters to create their working voltage of around 9V. USB-C is used for the connector, but it is wired as regular USB2.0. As the OLEDs can only assume one of two I²C addresses I had to use SPI. That means they share all data lines but they each have their own chip select.

    Assembling the board can be tricky as the OLEDs have to be soldered in first before the 3D-printed mounts are put in place. There is only enough room to get them in place in a certain order without damaging the display connectors. I did not want to leave the PCB and mechanisms exposed so designed and printed a simple case. The PCB snaps into it and the buttons get covered with a face plate. I originally planned to put transparent acrylic on the OLED panels, but it looks much nicer without them. As the screens are made from glass, scratches should not be a big issue.

    The STM32 can be programmed via USB after initially flashing the USB bootloader (stm32duino bootloader). Currently there are two different Arduino implementations for the STM32 boards. An official one by ST and the Arduino_STM32 port by Roger Melbourne. The latter contains more features, including some that are needed for this project. To make the keyboard work as a HID (human interface device) I used the STM32F1 USB composite library. With this library the STM32 cannot just mimic a HID device, but a serial port simultaneously. This enables the keyboard to be controlled over a COM port while still being an independent HID keyboard. The firmware I created is very simple as the Adafruit GFX library includes most the code needed to drive the displays. What turned out to be much more complicated was the desktop app that would be used to control the keyboard.

  • Hardware

    Max.K12/09/2020 at 20:26 4 comments

    The first task was to figure out how to build a button with an integrated display. There actually are off-the-shelf solutions: NKK switches manufacture tactile switches with color displays. But at a crazy 50€ or more per key these are out of the question. Early on I decided to use small OLED displays as they are widely available and inexpensive at under 3€. 

    I found that 0.66in OLEDs are just the right size to allow for a compact keyboard. And their 64x48 pixels provide enough resolution to display useful icons. The displays consist of a glass panel with a flex connector that can be soldered directly to the PCB. When bending the connector under the display glass, a gap of a few mm is formed, just enough to fit a thin tactile switch in it. What’s left is a mechanism that supports the display so that when the OLED is pushed, the tactile switch is pressed.
    Figuring out the key mechanism turned out to be challenging. The display has a big surface area compared to the tiny tactile switch. When pressing the button, the force needs to be evenly distributed. If not, pressing on the edge of the OLED will just rotate it around the button. I learned this when I 3D-printed my first OLED mount. It simply holds the display in place but does not limit its rotation:

    Laptop keyboards solve this by using a scissor mechanism that restricts the key to a linear motion. However, I could not think of an easy way to 3D-print this mechanism without making it unnecessarily big. The solution for me was to add a cantilever to the display mount. This lets the display rotate around the point where the levers are connected to the PCB and the motion is sufficiently linear for the tactile switch to be pressed.

    I continued to create a single button keyboard as a proof of concept. After a few iterations the mechanism was working. Whatever point on the screen was pushed, the button was actuated with a satisfying tactile click. The cantilever mechanism is very compact as it does not add to the height of the OLED itself. It also can be stacked to allow for a tight placement of multiple buttons in a keyboard. For this, the lever of one key overlaps with the screen of the next. 

    With the basics of the macro keyboard working, I went on to select the remaining electronic components.

  • Introduction

    Max.K12/09/2020 at 20:23 0 comments

    Whether you work with CAD design software or edit videos, keyboard shortcuts can really speed up your workflow. Dedicated macro keyboards take this even further by moving the most frequently used commands to individual buttons. While these keyboards are widely available both as commercial products and as DIY projects, they usually are restricted to a predefined set of functions like media controls. There are some exceptions: The Elgato Stream Deck is a keyboard with a cleverly integrated LCD touch display behind transparent buttons. Each button can be configured to have different functions and icons depending on the application you are currently using. Considering the high cost of these devices I set myself the goal of creating a cheaper DIY alternative that is fully configurable. 

View all 4 project logs

Enjoy this project?



weldoak wrote 01/04/2024 at 16:09 point

Has anybody built one of these recently and found a source for the OLED displays? They're out of stock or back ordered permanently everywhere I can find them.

  Are you sure? yes | no

szam99 wrote 05/29/2024 at 17:54 point

that one is same, i check all pins

  Are you sure? yes | no

Azuzula wrote 10/05/2022 at 06:00 point

Hi! I love this project and absolutely going to make Keybon for myself. I wonder if is possible to check what web page I'm on? Thank you.

  Are you sure? yes | no

Max.K wrote 10/06/2022 at 17:54 point

Hi, thanks! With the current software it's not possible to check the current website. But C# is very capable so this should be possible. I found this thread online:

  Are you sure? yes | no

Azuzula wrote 10/06/2022 at 19:30 point

Nice. If you can add this feature in the future version. It will be great improvement Thank you.

  Are you sure? yes | no

4gordi wrote 05/13/2022 at 08:08 point

Hi, Max. A very cool project, thank you). I repeated it (only with three screens, because the others are on their way), I had a question about the software-companion. Is it possible to switch templates like a tools menu like in Photoshop. You click on the display icon and a template opens with other icons that already lead to quick commands in the software, and button "back" for return to first screen. Is it possible to implement this? In some large CAD programs it would be useful)

  Are you sure? yes | no

Max.K wrote 05/14/2022 at 15:01 point

Hi, I think that's absolutely doable. You could have the software switch to a different preset when a specific button is pressed. 

  Are you sure? yes | no

4gordi wrote 05/15/2022 at 06:28 point

Thanks Max! Maybe for example how to switch your program template?

  Are you sure? yes | no

32162376 wrote 04/25/2022 at 02:54 point

Thanks Max! This is a great project. I finallly made myself one. 

is it possible to set a layout showing all the softwares I frequently use, then by pressing the keys to run the software?

  Are you sure? yes | no

teraz wrote 03/08/2022 at 19:57 point

is possible add knob? for volume control or orientacion object

  Are you sure? yes | no

Max.K wrote 03/09/2022 at 19:20 point

Yes, you could add an encoder like this:

Of course you would have to modify the hardware and software for that.

  Are you sure? yes | no

Rubines wrote 10/04/2021 at 11:08 point


Thank you so much for this awesome device!

Finally I managed to bring it to live without opening 1000 explorer.exe :)
There was a problem in the keybon Button init.

I had to change

Button button01(SW01, true, true, 5);


Button button01(SW01, 5, true, true);

Somehow the debounce value moved further up im my Keybon Version.

After that change it again inverts the button input and stops to act like all buttons were pressed always.

One last problem, my Keybon companion software always shows up empty without any icons. It looks like it cannot connect to the hardware.

It looks like this:

  Are you sure? yes | no

Max.K wrote 10/04/2021 at 18:48 point

Thank you! 

Are you sure there is no hardware issue, like a bad solder joint? I never had any problems with the debounce setting and I know of others that have successfully built the keyboard. 

The app always displays a blank default setup, that's normal. Only if you switch from default to some other layout you should see the screens change.

  Are you sure? yes | no

Eric wrote 09/28/2021 at 16:51 point

Hey Max,

great project I am searching for something like this since a while.

Is it possible to have the Gerber-Files for ordering at some PCB manufacturer like JLCPCB.

I am not very familiar with EAGLE, thats why I am asking :)

KR Eric

  Are you sure? yes | no

Max.K wrote 10/03/2021 at 11:30 point

I've sent you a pm :)

  Are you sure? yes | no

guillaume.hauwert wrote 07/11/2022 at 14:43 point

Hello, I just discovered the project yesterday and I found it great and it seems very complete. Is it possible too to have the Gerber Files?

Thanks for the project !

  Are you sure? yes | no

State wrote 04/15/2021 at 16:29 point

Hey! Great project!

Friend, I can't figure out where the files for creating the board are located. I want to order in China at the factory.

  Are you sure? yes | no

Max.K wrote 04/19/2021 at 16:01 point

They're on the github page:

  Are you sure? yes | no

cegan09 wrote 03/31/2021 at 19:06 point

I have a potentially dumb question. I'm working on a similar project and wanted to check out your companion app. Am I correct that there is no ready to run file in the github? I am very much not a software person. I can physically build the keybon, but I'm a bit slow on software. Any way you can nudge me in the direction of getting the app running?

  Are you sure? yes | no

Max.K wrote 04/01/2021 at 21:43 point

Hi, no problem. The compiled .exe can be found in the releases section on github:
It's easy to miss, I might add a hint to the description.

  Are you sure? yes | no

cegan09 wrote 04/02/2021 at 01:13 point

Well I feel dumb now...  Thank you for pointing me there.
I have an initial hardware prototype that sticks an 0.42" 72x40 OLED into a keycap for Kailh mechanical switches. If I can prove the whole thing out I'll share because it could pair with what you've designed really well. 

  Are you sure? yes | no

Romain wrote 03/24/2021 at 14:33 point

Just an update on Keybon12. I've made the release of v1.0 of the 12 keys version at .
I've successfully build one too! Code needs a bit more polishing, and I would like to implement a hybrid version of the control system (one where some keys sent directly a command and others are managed by the application). I also want to write a control application for Linux. The serial protocol is quite simple, so this part should not be a problem!

  Are you sure? yes | no

Romain wrote 03/24/2021 at 14:35 point

Also, I have 3 PCBs left, made by JLPCB. I can sell them at cost if anyone wants to try the 12keys version. I'll also have enough components to build one more, so if anyone wants a complete electronics kit (PCB + components including OLED), feel free to chime in!

  Are you sure? yes | no

Tompe20 wrote 07/05/2021 at 17:46 point

Hi Romain, I wrote you a private message about this.

  Are you sure? yes | no

falias4 wrote 03/23/2021 at 18:06 point

Awesome project! The combination of displays with an companion app is exactly the macro keyboard I was always looking for.

Did you ever think of using some kind of capacitive touch instead of the mechanical switches?
Maybe a transparent touch panel above all displays or single touch sensors beneath every display?

  Are you sure? yes | no

Mihail CHERCIU wrote 03/18/2021 at 11:58 point

I come with new info.
It's true that the chip that I bought is clone form the original ST chip, but the USB finally it's working.

The probable is that the Skillscreen text of C12 and R14 are inverted on the PCB. So the text C12 should be R14 and R14 should be C12. After re-solder the components at correct place everything working as expected.

  Are you sure? yes | no

Max.K wrote 03/18/2021 at 16:04 point

Thank you for confirming that your device is working. A few weeks ago someone ran into the same problem with the silkscreen, so I updated the PCB. You probably ordered your PCBs just before that.

  Are you sure? yes | no

Mihail CHERCIU wrote 03/18/2021 at 18:42 point

I made 2 other Keybon and everything work as expected.

Thank you the this project, very useful !

  Are you sure? yes | no

Mihail CHERCIU wrote 03/15/2021 at 11:31 point

Ready to assembling few Keybon and test :)

Just received the PCB and components

  Are you sure? yes | no

Mihail CHERCIU wrote 03/17/2021 at 23:02 point

Just for info, maybe someone will have the same problem like me with USB communication.

Because there is not more STM32F103C8T6 in stock to buy from distributor like Mouser, Farnell, etc., I bought from ebay few boards bleupill with STM32F103C8T6.

I de-solder the STM32F103C8T6 from Bluepill and re-solder it on keybon.

The problem is that the chips are fakes and the USB doesn't work. You can program the bootloader and the keybon firmware but PC will fail to detect the USB. I try with Windows 10, Windows 7, Ubuntu and Fedora.

The text on chip is slightly different from the original ST chip.

However, I program the keybon firmware using serial port at 0x08002000, which allow me to test and verify if OLED dislpay are working correctly.

  Are you sure? yes | no

Romain wrote 03/11/2021 at 16:23 point

Just for everyone information, I've made a 12 keys version of this. The files are available here: .
I'll have enough components to build 3 of them by the end of the month, so if anyone wants one, chime in.

  Are you sure? yes | no

Max.K wrote 03/15/2021 at 20:31 point

That's awesome! 12 is probably the ideal number of screens. Any more than that and you'd need multiplexers and software optimization.

  Are you sure? yes | no

Romain wrote 03/15/2021 at 23:39 point

Exactly why I stopped at that number! :-D I also feel that 16 is nice in terms of keys available, more than that and you spend more time looking for what you want to push!

Ah damn, now I want to work on a 16 screen version! Oh well, if I have time, I'll try something!

  Are you sure? yes | no

Daniel Thompson wrote 02/27/2021 at 17:20 point

Hi great project I'm just having some difficulties flashing the software to the chip. Are you able to explain what you mean in earlier comment about pulling to reset? I have tried shorting route one by using tweezers to bridge the pads. My computer to take to the device has an unknown USB device but then nothing further happened when trying to flash the software. Any help appreciated thanks.

  Are you sure? yes | no

Max.K wrote 02/28/2021 at 15:29 point

To get into bootloader mode you need to have the BOOT1 jumper closed while resetting the chip. To reset it, connect the RST line to GND, then disconnect it.
I recently added some instruction to the Github page, maybe these are helpful:

  Are you sure? yes | no

Daniel Thompson wrote 02/28/2021 at 16:00 point

Hi, thanks for the swift reply. That is really helpful I will follow those instructions. One final question (I hope) what/where is the RST line and how best to connect it to ground?

  Are you sure? yes | no

Max.K wrote 02/28/2021 at 18:38 point

There is a reset button on the top of the pcb that you can use. You can alternatively just power on the board while Boot1 is shorted. Whenever the STM32 boots up it checks the states of the boot 1&0 pins.

  Are you sure? yes | no

rand wrote 12/31/2020 at 02:20 point

And cannot be found anymore. artlebedev has gone on to more marketable "knick-knacks."

  Are you sure? yes | no

morganyunker wrote 12/24/2020 at 12:11 point

Great idea. I did something similar but the windows app was a python script.

Looking at the C# code, I see that there is a
SendKeys.SendWait(Layouts[currentLayout].keyCommand[keyReceived - 49]);
in the portDataReceived function.

What is that used for?

Doesn't the board send key commands to the host as a standard USB HID?


  Are you sure? yes | no

Max.K wrote 12/24/2020 at 12:53 point

When using the companion app the keyboard sends keystrokes as serial commands. These are always the same no matter which layout is selected. The app then triggers key presses based on the layout. It's just easier that way, as the key information doesn't have to be sent from the app to the keyboard and back via HID commands.

  Are you sure? yes | no

Mihail CHERCIU wrote 12/24/2020 at 11:38 point

Very nice, I will try to build one but this can be a good product. Any plans for that ?

  Are you sure? yes | no

Max.K wrote 12/24/2020 at 22:57 point

Thanks! Turning this into a commercial product requires a lot of work and I currently don't have the time or resources to do this. All the files and parts are available, you only need a soldering iron and 3D printer to build on for yourself.

  Are you sure? yes | no

Mihail CHERCIU wrote 12/25/2020 at 10:42 point

I would say that the the hard work you already made it. But it's true need same extra work to make it as a final product. However Bravo for this project, and do not hesitate to contact me if you decide to go to market, I can help you with the first series regarding PCB and product assembly through my assembling lab

  Are you sure? yes | no

Andrej Rolih wrote 12/23/2020 at 22:13 point

Awesome project. I may actually build it at some point if I have too much time on my hands and if LCSC gets the displays back in stock. Although I guess these ones from Aliexpress should probably work:

One question though... have you considered using a mechanical keyboard switches instead? Something like Kailh Low Profile switches should be suitable enough for this. They would of course add some thickness, but you get the benefit of clickiness.

  Are you sure? yes | no

Max.K wrote 12/23/2020 at 22:24 point

Thanks! The main problem with mechanical switches is the travel depth. The tactile switches I used here only move a fraction of a millimeter, so the display cable is only slightly bent. Mechanical Switches would need an entirely different mount for the screens.

  Are you sure? yes | no

Andrej Rolih wrote 12/23/2020 at 22:37 point

True that. Didn't even think of that.

Time to order some parts then I guess. Lol.

  Are you sure? yes | no

RubenFixit wrote 12/23/2020 at 17:52 point

Cool project! We had considered going with a similar design for our [Adaptive Universal Remote](, but with ePaper for ultimate power savings as our device would run off of batteries. For a number of reasons, we ended up not going that route.

  Are you sure? yes | no

Similar Projects

Does this project spark your interest?

Become a member to follow this project and never miss any updates