instructables

Osu! Keyboard

by Thomazzz3

I recently started playing a rhythm game called osu! Note 1: SMD components (small electronics) are used
and after seeing a video of a commercial mini so if you replicate this project soldering skills are
keyboard I thought it would be a fun project to required. maybe an easy to solder version will be
design one myself. Not long after that I decided it added but these leds don't come in trough hole
would be a good idea to put it on instructables as my package
rst project.
Note 2: I have updated the code multiple times and im
If you want to replicate this project exactly to the last up to version 3ish now. I'll leave all code online but I
instruction then be my guest, but some of the recommend you use the last version. It currently
desicions I made are not based on lowest price or best doesn't have led functionality but it should be the
quality. Some components are chosen almost purely best performing one.
because i had them lying around. If you can handle it I
would encourege you to customize your project.

Step 1: Materials and Explanations

Osu! Keyboard: Page 1

Depending on how you make your project you may are te ones I used. If you have the time and want to
need di erent components, but these components save mony, order form aliexpress and don't order the

PCB. T he s w it che s

1 Arduino pro micro + USB cable There are many mechanical switches you can use.
Linear, tactile or clicky from Kailh or Cherry MX.
3 Kailh BOX red switches Choose whichever you like. I used the Kailh switches
because they were cheap on Ailexpress. If you choose
3 10k resistor (0805 SMD) to use the PCB you'll need Kailh BOX switches. The
colour determines the feeling.
3 100nF capacitor (0805 SMD)
T he e le ct ro nic co m po ne nt s
4 APA102 rgb LED (5050 SMD)
Not much to explain about them in this chapter, but if
3 Keycaps you dont use the PCB I would recomend just normal
trough hole components for soldering ease.
1 Printed circuit board (PCB) provided in this project Unfortunately the leds used are not available in
trough hole packages. I would also not recommend to
1 3D printed case provided in this project use wires on SMD packages unless you are Very
con dent in your soldering skills. Even for SMD on a
W hy do I us e a n Arduino pro m icro ? PCB "advanced" soldering skills are equired.

Most arduino boards like the Uno (Atmega328) don't T he ho us ing

have native support for USB communication. Yes you
can program them over USB very easily and I think I do provide a housing in this project, but it is at this
there are workarounds, but I like to keep it simple moment awed. Modi cations are needed to t bolts,
when it comes to USB communication and I don't the openings for the leds are not optimal, the arduino
know if the workarounds are as responsive. Those is exposed and a part needs to be cut out for the USB
boards use an external chip to make USB to t. In the future a new housing may be added. If
communication possible whereas the Arduino pro you have a 3D printer go ahead and print it, but
micro (Atmega32U4) has it built in. please don't go out of your way to print this awed
case if you dont and just use some kind of project box.

Osu! Keyboard: Page 2

Step 2: The Schematic

Osu! Keyboard: Page 3

The schematic for this project is rather simple, but I for a rhythm game.
want to explain the components for the people who
are interested and don't know this implementation. This debounce circuit will slow down the falling edge
of the signal. The signal to the Arduino won't be able
Sw it ch co nne ct io ns t o t he Arduino to change as fast as the bouncing occurs so it will be
read as one press. Don't worry about it falling to slow
The switches are connected to Arduino pins 0, 2 and 3 for the next real press because it will.
because those pins can be used as external interrupts.
This is further explained in the code section. Advanced:

T he de bo unce circuit The Atmaga32U4 reads a digital low at 0.2Vcc - 0.1V =

0.9 volt. The voltage of the capacitor at any time in its
On the left side of the schematic is a circuit that is discharge is Vcc * e^(-t/RC). If you measure a di erent
copied 3 times. This circuit is used to debounce the debounce time on your switch you can calculate your
switch. To know what debouncing is you need to resistor and capacitor values.
understand switch bouncing and it's not hard to
understand. formula form https://www.electronics-
tutorials.ws/rc/rc_2.html
First look at this simulation to paint a rst picture
(click the switch fast and look at the signal below) T he LEDs
http://tinyurl.com/yajdtndw
The rgb LEDs are APA102 leds which are individually
When you press or release a switch it bounces and addressable using a clock and data line. No external
your signal alternates between high and low a couple components are needed to make them work. For
of times for a few milliseconds. An Arduino is really many LEDs you should use a capacitor parallel to 5
fast and reads every high and low in this short time. volt and ground but with just 4 LEDs you don't need
The program will send a key press or release every it.
time a high or low is read so with every press your
computer will receive multiple key presses. Not ideal

Step 3: The Board Design

Osu! Keyboard: Page 4

The PCB was designed in JLCPCB. I'm not sponsored after watching some video's I got the hang of it. The
by them but for cheap prototypes they make excelent only thing aw I realised is the placement of the holes
PCB's. For 2 dollar you get 10 of the same board, but is a bit too close to the switches.
shipping was about 11 dollar for me. If you don't
nessecarily want rgb lighting and plan on making just To order the PCB go to https://jlcpcb.com/ and choose
one, you should consider making your keyboard the 2 layered option. It will ask you for a Gerber le.
without PCB. download the ".zip" le and drag it to the window. You
don't need to unzip it. The settings should be ne and
The design of the board was pretty straight forward. I you can go ahead and complete the order.
only needed to add a component for the switches, but

Download

https://www.instructables.com/ORIG/FW1/QS3P/JKSZSJ7C/FW1QS3PJKSZSJ7C.zip

Step 4: Case Design and Assembly Tips

Osu! Keyboard: Page 5

De s ig n There is an order to assembling this rst version
because the switches are soldered.
As mensioned before, my design is awed but you can
still print it if you want. the design was made in Fusion 1. Solder the SMD components. these are the resistors,
360. It's a free 3D modeling software and with my capacitors and LEDs.
experience from inventor and solidworks it was pretty
easy to work with. The circles on the corners of the 2. Solder the Arduino pro micro.
case are to prevent peeling from the printbed.
3. Place the 3 switches in the 3D printed coverplate
If you make your own case only one thing is really before soldering. The coverplate can't be removed
important. Your switches need to be rmly placed and after soldering the switches. Desoldering the switches
unable to move. I've provided pictures of the square is not advised and may destroy them.
cutouts with dimensions so you can use it for your
own design assuming you use Kailh BOX switches. 4. Now solder the switches in place. Do this as quickly
as possible because the plastic switches can melt and
As s e m bly ruin them or drastically decrease their number of
clicks.
Now you have all components needed to assemble.

5. Place the assembled coverplate in the 3D printed uploading your code. The leds are nice to have if your
case and secure with tape or use bolts if they dont code doesn't upload but are not nice to look at as a
interfere with the keycaps. nished product. Skill and pointed tweezers are
required.
6. Place the keyCaps on the switches and you're done.
Also some grip feet on the bottom are nice for anti
Re co m e nda t io ns slip and let the rgb light shine through.

Desolder or mask the LEDs on the arduino after

Osu! Keyboard: Page 6

 View in 3D Download

https://www.instructables.com/ORIG/FMO/DK0R/JKSZSIOP/FMODK0RJKSZSIOP.stl

View in 3D Download

https://www.instructables.com/ORIG/F2B/3AHZ/JKSZSIOQ/F2B3AHZJKSZSIOQ.stl

Step 5: The Code V1 (hardware Debounce)

The code for this project is not beginner friendly so if Keyboard.begin() simply starts the usb connection as
you are just beginning to program in arduino then keyboard.
this code will possibly scare you a bit. However i'll try
to explain what's going on as best as i can. Some Next 3 interrupts are are linked to the switch pins.
things are explained later on in this tex so if you have Every time a change is detected on the switch pin a
questions please rst read the whole thing. tiny program will be executed. This little program will
be made further on.
Uplo a ding t he co de
Lo o p
First download all 3 ".ino" les and put them in one
folder. If you don't have the Arduino IDE just This part will continuously repeat while the arduino is
download it for free on the o cial arduino site. powered.
https://www.arduino.cc/en/Main/Software
I only use it to change and update the color of the
Connect your Arduino to your PC and open LEDs.
"OSU_Keyboard_code_V1.ino". In Tools --> Board select
"Arduino/Genuino Micro". Also in Tools select the right Int e rrupt s
COM port. This can sometimes change.To upload the
code to your Arduino just click on the arrow on the Here the little programs, which will only be executed
when a change is detected on the switch pins, are
Osu! Keyboard: Page 7
 when a change is detected on the switch pins, are
top left of the screen and wait until it tells you it
made. They are identical except for which pin they
completed in the bottom left.
react to.
O S U_ Ke y bo a rd_co de _ V1
First it checks if the button is pressed or released and
sends the correct keyboard command.
Including a nd de ning

LED (explained in a di erent order)

First you need to include the Keyboard library. This
makes it possible to use the Arduino as a keyboard.
If you are curious how the LEDs are controlled you
should look at the APA102 datasheet. https://cdn-
Next I de ne some values. De ne is just like a variable
shop.adafruit.com/datasheets/APA102.pd...
but they can't change while the program is running.
The rst 9 are for the keyboard character, arduino pin
O ne Bit
number and port bits.

This is again the direct port manipulation version of

Then the port bits of the LED data and clock.
digital write.
Also the number of leds is de ned and a variable for
First it checks if it should send a 0 or 1 and
the angle of the color wheel.
respectively pulls the data pin low or high. Then it
writes the clock pin high very short and writes it low
S e t up
again.
This part of the code will only be executed once when
O ne By t e
the arduino is plugged in.

This repeats oneBit 8 times with a "for" loop. It reads

First the clock and data pins of the LEDs are set as
the rst bit in a byte and passes its value to the oneBit
outputs and the switch pins as inputs. This is the the
function and does the same for the next 7 bits.
advanced version of pinMode(). If you are interested
search for "direct port manipulation".
Le d Da t a
https://www.arduino.cc/en/Reference/PortManipulati..
.

This repeats oneByte 4 times to provide the data

needed for one led. The rst byte starts with 111xxxxx
and a 5 bit brightness value on the place of the xxxxx.
The brightness can be set from 0 to 31 (2^5 = 32
levels) .

The next 3 bytes are for the blue, green and red
values. One byte for each color.

Co lo rW he e lT his Le d

This function calls ledData gives it the rgb colors

depending on an angle in the color wheel.

The 16 bit value is dividend in 6 equally spaced

sections of 60 degrees. Looking at the images might
help you understand better.

Osu! Keyboard: Page 8

(an 8 bit version is also provided but commented out
because it's too ickery)

St a rt End Fra m e

The start frame needs to be used every time you want

to send new colors to the leds and want to update the
actual color of the leds

I only use the start frame because the endframe is not

needed. The start frame is 4 bytes of 0. The end frame
is 4 bytes of 255 (11111111).

Download

https://www.instructables.com/ORIG/FZ8/MM1V/JKSZSFDV/FZ8MM1VJKSZSFDV.ino

Download

https://www.instructables.com/ORIG/F7F/1AXS/JKSZSF8J/F7F1AXSJKSZSF8J.ino

Download

https://www.instructables.com/ORIG/FUJ/QYMG/JKSZSF8N/FUJQYMGJKSZSF8N.ino

Step 6: The Code V2 (software Debounce With Timers)

Osu! Keyboard: Page 9

After a while of playing I noticed some double the the decounce time is not in uenced by anything
tapping problems with the hardware debounce. This happening in the loop.
could be xed with some other value resistors or
capacitors, but as the buttons and lid are not The only downside I can come up with is that the
removable I thought software debouncing would be a arduino delay functions can not be used anymore.
nice solution. The software debounce should work Because delay functions use Timer 0 and this program
wether hardware debounce is implemented or not. In uses Timer 0 to debounce.
my current setup I coundn't remove the lid so i just
left the resistors and capacitors in place. In the image you can see how the code roughly works.
The mem bit indicates if a timer is running. What is
I won't explain the code as extensively as the previous not depicted is the case that at the end of the button
version because it is a little harder to explain. press the input is low. In this case only a keypress
would be send while the button is already released.
Basically most of the code works the same and the led Which means the key will be held down as far as the
code is left untouched. what changed is the external computer is concerned. For this rare exeption a check
interrupts don't use the arduino functions anymore. will be preformed when a timer expires. If at the end
Now it works in pure C code. And now what's added is of a timer the button is not pressed, a keyrelease
the software interrupt. For this i used the AVR timers command will be send.
to wait a certain amount of time until the bouncing
has stopped. Because the timers are interrupt based

Download

https://www.instructables.com/ORIG/FL7/B6LF/JM0V7IW7/FL7B6LFJM0V7IW7.ino

Download

https://www.instructables.com/ORIG/FMG/6SVU/JM0V7IW9/FMG6SVUJM0V7IW9.ino

Download

https://www.instructables.com/ORIG/F5E/SU0M/JM0V7IWA/F5ESU0MJM0V7IWA.ino

Download

https://www.instructables.com/ORIG/FJ4/0V04/JM0V7IWM/FJ40V04JM0V7IWM.ino

Download

https://www.instructables.com/ORIG/FOS/PT9O/JM0V7IWP/FOSPT9OJM0V7IWP.ino

Step 7: The Code V3 (software Debounce With Vertical Counter) (recommended)(no LED)

Osu! Keyboard: Page 10

T his co de ALS O ha s a v e rs io n w he re y o u to debounce multiple buttons at the same time, in
do n' t ne e d pull do w n re s is t o rs . M a ke s ure parallel. All values are of type Byte( uint8_t) and
y o u co nne ct e a ch but t o n t o t he input a nd consists of 8 bits. we are not concerned what value
GRO UND! T he build- in pull- up is us e d. any of these byte contain, but rather we are interested
in the bits on their own. Every buton to be debounced
I also experienced some unregistered presses in the only uses one bit of each byte. The rst button uses
code V2. I think the code just became too complex only the rst bit of each byte, the second button uses
with its timer- and external interrupt and I may have the second bit etc.
missed some exceptions. For this reason I sterted from
scratch with searching on the internet for software All a t t he s a m e t im e
debounce methods.
By using bit math it is possible to execute these pin
(honestly, at least half of this project has become debounces in parallel. And, although bit math is
button debouncing at this point) pretty complicated, it is very e cient for the
processor.
After some searching I came across this post:
With an 8 bit data type it is thus possible to do this for
https://www.compuphase.com/electronics/debouncin 8 buttons. Using larger datatypes allows for more
g.... debounces at once.

To be honest, it took me quite some time to fully T he de bo unce

understand how it exactly works. It involves some
rather complex bit manipulations, but I'll try to make The debounce routine is executed every 1 millisecond
it as easy as possible. However my explanations will with a timer interrupt.
only be an addition to the post so you should at least
read the "vertical counters", "an annotated when the button is pressed the buttonState, which is
implementation" and "reducing latency". the debounced state, will emedeately go low,
indicating a button press. To detect a release the
My e xp l a n a t i o n button has to be high for long enough, indicating it
The timing diagram (made in WaveDrom) I added hasn't bounced for a certain time. Toggle is used to
should make this hard to understand bit math at least indicate a button change. The counter bits are used
a little more understandable. Note the image has 2 for .... counting how long there hasn't been a bounce.
counter bits, but my code has 3. This means a longer
debounce time. Delta indicates a di erence between the input and
the debounced state. Only when there is a di erence
O ne bit pe r v a lue the counter will count. the counter will be reset when
a bounce is detected (delta is 0).
With the vertical counter implementation it is possible

Download

https://www.instructables.com/ORIG/FQ6/Z19K/K39CBSWK/FQ6Z19KK39CBSWK.rar

Download

https://www.instructables.com/ORIG/FY6/M7Y7/KB52XJQD/FY6M7Y7KB52XJQD.ino

Osu! Keyboard: Page 11

Step 8: The Result

If everything went well you should now have a working keyboard to play Osu! on. I personally havn't noticed any
latency at all. If you do please let me know. Also if there are any questions feel free to ask anything.

The previous mentions about a V2 are not meant as a promise so don't postpone this project because you want to
wait for V2.

I hope you enjoy your keyboard!

Osu! name: Thomazzz3

Tro uble s ho o t ing

If you think you are having troubles with your keyboard, rst open a text editor and press each key once for a short
time.

Does one or multiple keys not work?

It is possible you destroyed a switch internally while soldering. If you have a multimeter put it on
continuity/beeping, put it parallel to the switch while the Arduino is not connected and press the key. It should
beep.

Do the characters you just typed match the keys you con gured in Osu! ?

Change the characters in the arduino code in the rst 3 #De nes ( ' ' is nessecary!).

Or change your Osu! settings to use the con gured keys.

Are one or multiple keys repeated a few times?

The debounce circuit propably doesn't work for your switches or is not correctly soldered. Check your solder
connections. If it still occurs try a capacitor value of 1uF. This will be very hard for the PCB users.

If you are having troubles with your LEDs

Do the LEDs icker?

A solder connection may be loose. If you use the PCB con rm the soldering tin realy owed on the pad on the print.

Do none of the leds work or from a certain number of LEDs stops working?

Check for shorts between the conections of the rst LED (follow tracks) and check for well connected tin on the
outputs of the Arduino and again the rst LED. If con rmed correct and still defect you may need to replace the
rst LED.

Osu! Keyboard: Page 12

If this xes it repeat for the next LEDs if needed.

https://youtu.be/hJIpuX31pac

hello to you i'm still a beginner can you help me on this one ireally want to make it idont want any
led i just want the buttons how do i do it?
Hi do you have a diagram without PCB? or PCB is needed to do this one? Thanks!

The schematic can be found in step 2. The PCB is a 'nice to have' and is not necessary

So how can I do that without PCB? Just need wires to connect them?

edit: can DIY PCB do the job?

Edit edit: even without pcb. should i get resistor and capacitors too?
Yeah with wires is possible. A diy board is also possible, but you'll need to design your own panel
because mine is 2 layers. You do need the resistors and capacitors in all cases
I did the project without any resistors and capacitors and led. I just used the pullup resistor from
Arduino. Thanks and good project btw!

How did you do it without the resistors?

In Step 7 I added code that uses the internal pull-up resistors. You can use that one

Hi, I wonder if I can use pcb breadboard for this project?

Good day! Can you share a good place to acquire keycaps for the Kaihl switches? I got the kaihl
copper. Also I would like to know, if it is necessary to add any diodes to the build. Thank you.
For the keycaps any MX compatible caps should do it i think. I got mine from AliExpress but I
wouldn't call it a "good place". I was more fucused on low price.
https://s.click.aliexpress.com/e/WZq0KN6

As for the diodes it is not clear to me where in the circuit you would need them and for what
purpose. For that I need some more information.
Love the debounce explanation and simulator. Why RGB (are they controlled by the game or
keystrokes or just for fun)?

Osu! Keyboard: Page 13

Thanks.
At the moment the RGB is just for fun. They can be programmed to respond to the keystrokes, but
for now it is just a rainbow cycle. I wrote some helper functions to controll the leds so you are free
to cusomize. The reativity of the maker is the limit. If you someone wants help creating a specific
pattern or response they should ask in the comments. I'd be glad to help!
That looks perfect! I love the lights :)

Thanks =)

Osu! Keyboard: Page 14