HacKeyboard, an open hardware mechanical keyboard – part VI

Hi everyone! This is the third post on building the HacKeyboard. In case you haven’t read the first ones, here are the links:

HacKeyboard, an open hardware mechanical keyboard, part I

HacKeyboard, an open hardware mechanical keyboard, part II

HacKeyboard, an open hardware mechanical keyboard, part III

HacKeyboard, an open hardware mechanical keyboard, part IV

HacKeyboard, an open hardware mechanical keyboard, part V

Connecting the USB Hub and the USB Flash Drive

USB hub

At this point the electronics part is almost done 🙂 The next thing I had to do was to prepare the USB Hub. If you’re building your own keyboard you should try to find a hub similar to the one shown in the pictures on ebay since they have a low profile and a small PCB with no soldered connectors. They’re very cheap (probably the cheapest), very common and very easy to find. Here’s the step by step of what I had to do at this point:

  1. I opened the case carefully. It was very easy with a flat screwdriver and a craft knife;
  2. Then I took a picture of it so that I could later verify where all the cables should be soldered. If you’re doing this and you don’t take a picture, it should be similar to the one you can see in the image below;
    USB hub pcb
  3. Desoldered all the wires that connect to the USB connectors;
  4. Soldered new wires, with the same colors (so that I wouldn’t go wrong) on the host side (port H);
  5. On the client side the hub has signals for 4 USB ports but I only used 3: for one of them I soldered all 4 wires with the correct colors (port A), in another I soldered all three except the red one (port B) and in the other I just soldered the green and the white (port C).  The fourth port was left without any wires. Remember the port letters H, A, B and C, since they will be referred below;
  6. Put a thin layer of hot glue just to make sure the wires wouldn’t come out.

After preparing the USB hub, I proceeded to attach it to the PCB. First I found a nice spot without any solder blobs and glued it to the PCB with hot glue.

HacKeyboard USB hub

After gluing it in place, I had to solder the wires in the right place:

  • Looking at the PCB from the microcontroller side, the 4 wires from the host side (port H) were soldered to the 4 pins near the right micro USB connector (look at the images for reference and color ordering);
  • Considering the same view, the set of wires that only has green and white (port C) should was soldered to the two pins next to the microcontroller;
    Hackeyboard usb data wires
  • The set of wires with four wires (port A) was soldered to the 4 pins near the other micro USB connector;
  • The set of wires with three wires (port B) were used to later connect the flash drive;
  • Using hot glue, I put all the cables in safe positions, glued to the PCB, except the ones from port B.

One of the photos clearly shows all the connections and you just have to do the same thing if you’re building your own HacKeyboard:)

Hackeyboard usb hub

Then I proceeded to prepare the USB Flash Drive:

Hackeyboard USB flash

  1. Using the craft knife, pliers and flat screwdrivers I opened the plastic case and removed the flash drive PCB from it;
    USB flash drive
  2. Carefully desoldered the USB connector.
    usb flash drive connector removed

Finally it was necessary to find a small spot to glue the USB drive to the PCB. In this case, since I was dealing with a double sided PCB I put a piece of electrical tape (you can also use kapton tape) in the keyboard PCB to prevent short circuits.

hackeyboard PCB tape

Then I had to:

  1. Glue the USB drive on top of the tape with hot glue and then solder the three wires from port B of the USB hub to the GND, D- and D+ pads on the USB drive;
    USB drive glued
  2. Solder the other end of the red wire that you soldered to the VCC pin of the flash drive to the pin near the Charge-pump regulator (see picture for reference);
  3. Put all the cables in safe positions and glue them to the PCB with hot glue.

Hackeyboard USB flash drive ready

The photos above clearly show where each wire should go, in case you have any doubts 🙂

And we’re done with the all the wiring and component soldering! 🙂

Developing the code to make it all work

github Hackeyboard

In this step I’ll describe how the code to make it all work was made.

I decided to use JAL to develop the firmware since I didn’t have a lot of time to get it working for Lisbon Mini Maker Faire. JAL, or Just Another Language, is a high-level language for a number of Microchip PIC microcontrollers that precedes the Arduino framework. As a curiosity, Massimo Banzi, one of the Arduino co-founders, was an early JAL developer. Another reason why I decided to try JAL was that there was a USB HID device sample code in JALlib that ended up making the first steps into developing firmware for a full keyboard much easier.

Before starting developing code I first did some research on how people usually do it in the other DIY keyboard projects. AVR-Keyboard project on Github from Fredrik Atmer was particularly helpful as inspiration. Basically I ported the code to JAL with some changes and then added all the extra functions to HacKeyboard. A funny thing is that I had to write a function to control the WS2812B LEDs from scratch… funny because I did not have an oscilloscope to measure the timings on the output pins of the PIC18F4550 and had to basically guess the timings from the MCU operating frequency and instructions per instruction cycle. After a few attempts I managed to get it working.

You can check the source code in my GitHub, including the pre-compiled .hex file.

In case you want to modify something you will need to download JALlib from the JALlib Github. To compile just use a command with the following structure:

$./(path to compiler) + (path to your .jal file) + (-s) + (path to JALlib libraries) + (options)

Example from inside the compiler directory:

./jalv2 file.jal -s ../lib/ -no-variable-reuse -no-fuse

Note: the variable -no-variable-reuse will use more PIC memory, but it will compile faster.

The command above is for the Linux command line but should be very similar for Windows.

Burning the firmware

HacKeyboard burning bootloader

At this point, the keyboard was almost complete 🙂 . It has a case, it has electronics and now it just needs the code to make it all work.

In this step a PIC Programmer was used. If you’re building your own keyboard you can get them for very cheap on ebay.

Since the microcontroller I used is not a PDIP package, I couldn’t insert it into a ZIF programming socket that some programmers have. As such, I had to use the ICSP (In-Circuit Serial Programming) interface which uses 6 pins:

  • MCLR – pin18
  • VDD – pins 7/28
  • VSS/GND – pins 6/29
  • PGD/RB7 – pin 17
  • PGC/RB6 – pin 16
  • PGM/RB3 – pin 15

Hackeyboard ICSP connection

Hackeyboard ICSP MicroPro

Since I used the Tiny Bootloader for development (.hex file also available in my Github), I only needed to upload it to the microcontroller once. Due to this and to the fact that it would make the PCB a lot more complicated, I didn’t put any direct header for this programming interface. So what I did was to solder a wire to each trace connected to each of these 6 pins and connected them to the programmer, as can be seen in the photos. You can do the same and upload the pre-compiled hex file and then desolder the wires.

Previously I mentioned a programming header near the micro USB boards. This programming header is a serial interface only meant for development using the Tiny Bootloader to program the keyboard. Why did I use Tiny Bootloader? Because it is much faster and easier to upload and debug the code using the serial interface. If you’re planning on developing or tweaking the code for the keyboard, use the procedure described above to burn the Bootloader and keep reading to find out how to use the Tiny Bootloader.

By the way, in case you’re wondering what is a bootloader, it is a very small program that sits in a specific position in the microcontroller’s memory and allows you to upload new code to the microcontroller using a standard serial interface, instead of a more complicated programming interface.

To upload code using the Tiny Bootloader, we’ll use a small program named Tinybldlin. Download it from here, install it and run it. Tinybldlin is the version for linux but there is also the version for Windows.


Then Browse to select your desired hex file.

Connect a USB to Serial TTL converter to the Serial programming header and also plug it into a USB port on your computer.

Select the 115200 bps baud rate and the correct USB port and click on Upload.

If you connected everything correctly, you have just uploaded new code into your keyboard 🙂

Hackeyboard test code

In the picture above you can see a test I did during the development of the code using the serial interface.

Are you enjoying this project? Follow the link to continue reading and for the full set of photos of the build: [HacKeyboard, an open hardware mechanical keyboard – part VII]

Did you find this post helpful? Do you wish to contribute to other projects regarding computer science, electronics, robotics or mechatronics that will be posted in this blog? If you wish to do so, you can donate via paypal using the button below. Thanks! 🙂