Arduino Uno as HID keyboard

Turin is the hometown of Arduino. I have been at the fablab multiple times but I had to come all the way to America to get my hands on a simple Arduino Uno.

For 60$ I bought a cheap (but still good!) mechanical keyboard by Qisan, a clone of the Arduino Uno and a USB host shield.

Given that is 3 years since I have been using a dvorak layout and it's a pain to change layout on every machine that you have to use. You can imagine that given this three pieces of hardware together I put together an hardware key mapper for the keyboard.

I have never had experience with Arduino before but it was not that difficult to make it do simple things like blinking the led or send signal through to a serial monitor.

It took me half an hour to wear down all my excitement: the USB Host Shield library broke all the compatibility with the similar project I found wandering online.

In particular this blog has the most precious information and the guy wrote a HID driver that allows the Uno to be seen as a HID device.

It was a noob error but I didn't checked the various arduino alternatives and I discovered late that just a few have the HID capabilities that would make this work easier. I should have bought and Arduino Due or Leonardo maybe.

Also, the various guides about flashing with a dfu tool are specific to older models of the Uno and it took me some time to figure the name of the new components so that I could flash a new firmware.

A small journey in the Arduino world

It feels pretentious to write a little guide for this kind of work, given also the fact that I have roughly 10 hours of experience with the Arduino. But the other resources are really outdated so I hope this piece can be useful to someone out there.

All the files I have used today are on my repos and I included also an outdated version of the USB Host Shield library that I used.

The original code from this blog post works like a charm but just as a simple passthrough.

It was not difficult at all to examine the code: during each loop of the iteration a char array gets read from the shield and if it is contains information Arduino with the Serial.Write method send the data to the host.

The buffer array is a simple array of length 8 and the first two positions are reserved. In particular the first one represent the various modifier keys.

The dvorak layout has the same pairs as the US layout but eventually I got used to having the '@' where at the same place of 'Q' (qwerty) and '"' over the '2'. Also, I am an avid vim user (I should thank Simone Basso for that) and I swapped some keys on the new 65 keys keyboard. The modifier bit at the beginning of the array came in handy for my code.

An hardware key remapper is a simple but long switch C statement but I decided to consider also the modifier bit: in this way certain keys like the Window (UGH!) key is mapped to a different layer of keys. I got all the codes for the HID events here.

The process of flashing the code on the Uno goes like this:

  • write the looping code;
  • push it to the Arduino using the IDE;
  • shortcircuit the board so that it goes in DFU mode;
  • flash the .hex HID firmware;
  • try your code;
  • repeat until it's right.

Everything fits in one picture

Flashing the firmware

The firmware is in my repo but I got it from (here)[]. The tool I used to flash it is dfu-programmer (version 0.62). Every time you want to flash a new firmware the Arduino must be put in DFU mode (you can see the difference with lsusb). To do that simply create a shortcircuit using a small metal wire on the two pins near the reset button and a led will blink. This video shows the method briefly (no real need for a jumper). The commands are the following and there is no risk to brick the Uno:

dfu-programmer atmega16u2 erase
dfu-programmer atmega16u2 flash Arduino-keyboard-0.2.hex
dfu-programmer atmega16u2 reset

After each flashing the device needs to be disconnected once. Of course you can flash the original firmware back. It is included in my repo or on the official ones.

Arduino and the shield

That's it, as you can see is not difficult at all. The worst part is gathering the various info that are left dormant in blogs or forums.