Custom MIDI Keyboard for BlackOut App

Welcome on the tutorial on how to make your own custom MIDI keyboard for Blackout and others.

First thing is to get the pcb for this project, the raw version or the pre soldered one. The raw one is yours to fully solder and assemble, and the pre soldered version has the bottom side already done leaving your with only the 3 rotary encoders to solder which are easy to do for beginners.

Here is the link to the crowdfunding.

For the supplies I found all I needed on Aliexpress but there is plenty of vendors offering the same products so choose as you see fit as long as the part reference matches up. You can find a BOM at the end with links to various vendors.

Switches on the other side can be swapped between all the various MX compatible switches for a custom fit. Generic references are included in the BOM, more about the switches at the end.

The Keyboard is made of :

1. The main board containing :
2. The circuit board ;
3. A Pi Pico W (for wireless) microcontroller that is the brain of the keyboard ;
4. 29 Kail hot-swappable PCB socket type CPG1511 ;
5. 29 Cherry MX Clone switches (look for the RGB version to get clear switches) ;
6. 29 MX Keycaps of your choosing (preferably choose backlit caps)
7. 29 Diodes 1N4148W ;
8. 29 LED SK6812 Mini-E ;
9. 3 rotary encoders : 2 with pushbutton (ref EC11E18244A5) and one without (ref EC11E1820402) for Pan/Tilt/Scroll but all 3 can be pushbutton if needed ;
10. 2 2.54 pitch 1x20 female connector .

1. The lower case, upper case and keyframe which can be 3D printed. You will also need 9* M3x20 countersunk bolt and choose between the version using threaded inserts or the one without.

1. 3 wheels for the rotary encoders. Some types are available on aliexpress and others or you can 3D print your own.

1. A usb to micro usb cable to flash the pico at the start and then to provide power to the keyboard.

If you're planning on soldering your own I strongly recommend these :

1. A good soldering iron (I used an aliexpress TS100 with a temperature of 340°C/644°F)
2. Good quality solder ;
3. Good quality solder paste (I used Aliexpress NC-223-ASM but it needed a good amount of cleaning, there is probably better references)
4. Some patience

If you got the pre soldered board you can go to step 2.

I like to start with the diodes as they are the smallest component. They are symetrical and the label is tiny so polarity mistakes can be made, if you have a doubt double check before soldering with you camera phone to zoom in or with a multimeter in continuity mode (Pic. 1b).

First I place a column of 5 diodes, apply a small drop of solder paste on each side and reposition the diodes on the tabs before soldering them. Repeat for other 5 columns.

Second on the list are the LED, since once in their square they can't go far you can place all of them and apply flux if you want to save some time. Those LED are small and sensitive to heat, to be sure not to burn them I solder two pads and then move to another one. Make sure that the ground pin (the one with the diagnol cut) is on the ground tab and the LED facing the top of the circuit board (Pic. 2c).

Then it is time for the Kailh's connector. Check the label for the orientation, placing is easy thanks to the two pins. You can skip the solder paste on this part to save time on cleaning up. Try out on a couple connector and choose to apply paste or not. You can assemble the switches on the other side in order to the connector to sit tightely before soldering but I noticed that it seems to loosen the fit between them so I advice not to, and just put a bit of downoard pressure while soldering the first pad to make sure that the connector lays flat on the board.

Last are the two 1x20 female connector. Put the connector on your Pi Pico and place them on the board (Pic. 1d). Add solder paste and solder them. (Those connectors are optionnal, you can solder your pi pico directly to the board to get a slimer profile. I chose to have them so that if the Pico fails swapping it is really easily done)

I strongly recommend cleaning the solder paste of your board when you are done as I'm not sure but I think flux can be conductive enough to get some false triggers. I use a toothbrush with isopropyl alchool and a cloth to wipe it the best I can.

Either you soldered the bottom side yourself or got a board pre soldered, there is 3 rotary encoders left to solder and we are over with it.

All 3 rotary encoders can have or not the pushbutton function depeding on the reference you decide to choose. Personally I was thinking of the left encoder and middle one to be for pan and tilt so the pushbutton would be usefull to change through coarse/fine/ultrafine, and the right one to be used for the scroll wheel so no need for a pushbutton. Choose as you see fit for your use.

Place them and solder the 3/5 pins depeding on the pushbutton or no. Don't forget to also solder the two side tabs which help with the mechanical stabilty.

If you used soldering paste don't forget to clean it up.

You're almost there!

Next step is to flash the code to the Pi Pico. For this you'll need to install Arduino IDE, add the 2 needed librairies, add the board profile and badabim badaboom.

So first install Arduino IDE :

Download and install Arduino IDE

Then add the Control Surface Library and the Neopixel Library :

Adding a library in Arduino IDE tutorial

And last thing add the Pi Pico W board profile and select it.

How to install the Pi Pico W in Arduino IDE

You'll also need to activate the bluetooth by going to menu>menu>menu and choose "option" (Pic. 3a).

Plug in your brand new Pi Pico to your computer and choose the port. If it is not working and you have multiple COM you can try choosing another one. Also if there is already a program running on your board you'll need to press the reset button for 2 seconds while plugin in the card to your computer for it to be in flash mode.

Then copy paste the latest revision of the code from this page :

Github page

Click on televerse, wait a minute or two and when complete the board should reboot by itself.

If you have the Pi Pico installed on your board, as soon as it reboots all the LED should light up to the background color (by default blue at 25%). Also, you should be able to see a MIDI board with any compatible software (like MIDI wrench). If it doesnt, refer to the FAQ.

It is a good time to check that is works correctly. While powered on, use MIDI Wrench to connect to it and check if the rotary encoder and push button function correctly. You can also quickly add a switch on the fly to any key to check for the MIDI note reponse and LED response. If you seen any problem refer to the FAQ.

Printing the case is quiet easy as it doenst need supports and just basic filaments (like pla or pla+).

It is made of the upper and lower part and a keyframe to block the light spilling out the keys.

The upper part is standard but comes in with different plays to accomodate your printer. Start with the regular play version and adapt if needed.

The bottom parts comes with two variations : one made for threaded inserts in order to be able to dis/assemble the case unlimited times and for people with ACD but it requires to have to correct inserts ; or one made to screw directly into the plastic that doesnt require insert, but arguyably a small cycle life.

You'll also need to print the wheels if you chose to, same deal here with a standard model a few different plays.

3D files repository

Now that you have your case, a top and bottom soldered board, time to assemble everything.

First take your case top and put it over your board. You can use two bolts diagnaly to align them. Align grossly the keyframe and press in a switch to secure it in place. Press in a second switch further away to firmly secure the board in place and then proceed to do all of them.

You can place your keycap before placing the switch or after it doesn't matter.

After installing all the switches and caps it is a good time for a last check on the MIDI Wrench app to make sure each key works as intended.

Then align the mounted top case to the the bottom and just screw it in. Watchout for over tightening without inserts not to strip the threads out.

Push the wheels onto the shafts, give them a spin to enjoy your work.

If required some changes can be made in the code in order to change the LED colours or intensity, the name of the device, the speed of the rotary encoders or to adjust the note channel for multiple MIDI devices.

I would advice for the beginners to start with the main code and go step by step not to make any mistake.

LED colors and intensity :

tbc

*warning about max intensity through the pi pico*

Changing the name of the keyboard :

tbc

Changing the speed multiplier of a rotary encoders :

tbc

There is a variety of switches to choose from wich gives different feedbacks.

A video is worth a thousand pictures.

If you want to use backlit keycaps make sure to get clear switches (usually called "rgb switches").

A functionnal generic switch is included in the BOM, please share your feedbacks to the community if you find something that works great for you.

Here's a link to the BOM on google docs.

You can find all the parts needed to assemble this keyboard depending on the version you choose.