A library to interface Arduino with XKeys USB keyboards

XKeys backlight control

XKeys backlight control

Thomas Strausbaugh contacted me a while back with a project involving XKeys – a series of HID keyboards with extended functionality. Tom also offered to lend me XK-16 Stick; after receiving it I made a small addition to the USB Host Shield library and soon after Tom e-mailed me back asking to test his code. The picture on the left shows one of the example sketches, a “blinky” of sorts, where all backlights are sequentially turned on and off.

Xkeys can be controlled by sending proprietary (but well documented) output report which doesn’t follow standard HID report format. By sending this report it is possible to turn LED integrated into each key on or off, change light intensity, as well as switch the keyboard on the fly between mouse, joystick, and keyboard emulation modes. Larger keyboards have some additional features. In addition to that, products are very maker-friendly; for example, a manual for XK-16 Stick contains this:

The electronic design of the X-keys Stick is such that the stick may be cut off to any length after the second key. P.I. Engineering will perform this service in our lab for a fee including testing to maintain the warranty, or you may contact us for specific instructions if you wish to do it yourself.

The big disadvantage of Xkeys is price. However, if you want you project to look professional but don’t have much time to refine it, a good looking user interface can be produced very quickly with Xkeys.

Tom’s library implements programmer’s interface to extended keyboard features (sans cutting). Easy to use functions are provided enabling direct access to programmable features of each key or LED. Thank you very much, Tom!

Adding a display to a digital scale using Arduino and USB Host shield

Arduino reading digital scale

Arduino reading digital scale

I am the proud owner of Model 510 5lb digital scale. It is a nice little scale which works very well (much better than service itself) while attached to my workstation. The scale doesn’t have a display making any kind of standalone use difficult. However, since the scale is a USB HID device reading data from it should be as easy as from a joystick and Arduino board should be adequate to provide a display function for it. To test this theory I made a simple setup consisting of Arduino UNO, USB Host shield and HD44780-compatible LCD display. I also wrote a small sketch which polls the scale and outputs the weight. The secondary objective of this project was to demonstrate LCD support in USB Host shield library.

For this project I used the following:

  1. An Arduino board. Standard size board, such as UNO, Duemilanove or Leonardo, will work
  2. USB Host Shield
  3. Toshiba HD44780-compatible LCD display, in 16×1 or 16×2 configuration. If you’re planning to use this sketch for something else, like data logging, the display is optional – all output from the scale is repeated to the serial port
  4. 5lb digital scale. Scales are standard HID devices with usage table 0x8d, therefore, scales from other brands may work as well with no or minimal modifications to the code
  5. USB Host library

The example code is also hosted at github, as well as in ‘examples’ section of the library under ‘HID’. It has been tested with Arduino IDE version 1.0.5.

In this project, the LCD is connected to the shield’s GPOUT pins, as documented in max_LCD.h header file. In addition to data lines, 5V and ground must also be connected to the shield’s 5V and GND terminals; the RW pin must be grounded – I do it on the LCD itself. In order to see the characters, the display must be biased – a 5K-10K pot with wiper on Vo and other two pins on 5V and ground will provide contrast adjustment.

Continue reading Adding a display to a digital scale using Arduino and USB Host shield

Using Logitech Extreme 3D Pro joystick with Arduino HID library

Logitech joystick connected to Arduino

Logitech joystick connected to Arduino

HID report parsing explained in the previous article works pretty well with properly aligned HID reports. The analog controls are placed on a byte or word boundary and buttons occupy dedicated fields. The majority of HID devices are designed this way, however, some other devices are not that simple to interface and today I’m going to show how to handle one of those.

A Logitech Extreme 3D Pro joystick is one nice HID device. It is good looking, well-built, and have a twist handle, which adds third axis to a stick making this model popular among FPV fliers since you can control pitch, roll and yaw with one hand. Also, X and Y axis are 10 bits which gives good precision. There is one problem with this joystick – its input report.

Logitech, in its infinite wisdom, decided to pack all the high and low resolution analog controls plus 12 buttons in 6 bytes of input report. The report looks like this – 10 bits of X, 10 bits of Y, and 4 bits of hat switch. After that, things become easier – one byte of Rz AKA “twist handle”, one byte of buttons, one byte of throttle (called “slider” in the report), and finally, one partially filled byte holding the rest of the buttons. Take a look at the screenshot below – two most important controls are not byte aligned, therefore, simple straightforward parsing of the report is not possible. Also, USBHID_descr won’t show this report correctly.

To demonstrate how to deal with this report I wrote a simple Arduino sketch. It was made by modifying an example from the previous article. I also made it as simple as possible – as soon as any of the controls changes its value, new report is printed on the serial terminal. The sample output is shown below followed by code explanation.

Continue reading Using Logitech Extreme 3D Pro joystick with Arduino HID library

Developing Arduino code for HID Joystick

This article focuses on how to use the existing USB code library and HID report descriptor info to implement joystick functionality.  Human readable HID report descriptor and report information can be easily obtained using USBHID_desc.pde sketch – see previous article for details. This information will help you getting field details such as size and count info. Also, if you don’t have Arduino Mega or 2560 to run USBHID_desc, report descriptor for your device can be obtained using one of many PC tools known as USB analyzers, or even the official device verification tool. This article is written by Alex Glushchenko – a developer behind second revision of USB Host Library as well as majority of device support code.

As you may already know report is a data structure used by HID device to return the information about the certain device parameters such as joystick coordinates or button events, or receive new settings such as switching on/off LEDs on keyboard.  

Report descriptor is a data structure which describes report or reports, if there are few in number, field sequence, sizes and counts.  Each report descriptor consists of several items. Each item describes some field property. I am not going too deep into details on items, explaining only the most important ones which are absolutely necessary in writing your own report parser.  

The items usually describe type of field (input/output/feature), minimum, maximum field values, units, value meaning (usage) etc.

Continue reading Developing Arduino code for HID Joystick

Visualizing HID device reports and report descriptors

Screenshot of USBHID_desc sketch output
Human Interface Device class of USB devices has a unique property – a report descriptor which contains information about data that device is sending to the host as well as data that can be sent to the device. This property allows for variety of devices – keyboards, mice, joysticks, digital scales, uninterruptible power sources, GPS receivers, and even toy missile launchers to belong to a single class – HID. A vendor just needs to pick a usage table which contains controls similar to vendor’s device – every OS has a generic support for HID devices so in most cases specific device driver is not necessary. The report descriptor again makes this possible – it contains definitions or report fields therefore a generic parser can process reports from any arbitrary HID device. However, this generic parser will take too much space on small microcontroller systems such as Arduino due to the amount of constants that needs to be present in the program code.

It shall be noted that a HID report itself is a simple structure of fixed fields and when this structure is known a very lightweight parser can easily be developed. HID development in legacy USB library has stopped at this point; I thought people will just take a look at the spec and write report parser for their device. It soon became evident that very few are actually willing to do this and in rev.2.0 of the library the HID report parsing is semi-automatic – a report descriptor has to be analyzed first using USBHID_desc utility presented in this article and then actual reports for the device can be parsed using library facilities (an article about coding report parsing is here).

Continue reading Visualizing HID device reports and report descriptors

CueCat meets Arduino, works with HID boot code

CueCat meets Arduino

CueCat meets Arduino

Soon after posting Arduino barcode scanner article I started receiving questions about CueCat. Many of these cat-shaped devices were distributed free of charge in the US at the end of the dot com craze and even though company which developed and distributed them went out of business long time ago, the USB CueCats are still available for very reasonable price. Declawed CueCat with USB interface can be purchased for as little as $13 total in the US and non-modified ones for even less; at the same time, typical no-name handheld barcode scanner goes for around $25 on eBay and will be shipped from China.

I tested “declawed” USB CueCat with my code – it initializes as HID boot keyboard and works very well. No modifications are needed to the sketch from the previous article – just plug in the device and start scanning. CueCat reads many different barcode systems, including UPC and ISBN. Since CueCat is in constant scanning mode (no button needs to be pressed to initiate a scan), it can be used for applications like automated inventory control or as a part of a motion feedback circuit in CNC/robotics project.

One last advantage of CueCat I’d like to point out is low power consumption. As can be seen on a title picture, an Arduino, USB Host Shield, CueCat and HD44780-compatible LCD display can be run from a small LiPo boosted to 5V by Mintyboost from Adafruit Industries with its output connected to Arduino USB port.

CueCat is compact and inexpensive barcode scanner still available for sale despite being discontinued many years ago. It is implemented as USB HID boot device and supported by USB Host library. If you were living in the US in 2000, chances are you already have one or even several of these cat-shaped devices laying around – try it with my code and let me know if you have any issues.


Connecting barcode scanner to Arduino using USB Host Shield

Scanning barcodes using Arduino and USB Host Shield

Scanning barcodes using Arduino and USB Host Shield

An addition of Human Input Device Class support to USB Host Shield library 2.0, announced several days ago allows using powerful and inexpensive input devices with USB interface in Arduino projects. Sample sketches demonstrating sending and receiving data to one of the most useful HID device types – boot keyboard/mouse, has been released along with the library. The beauty of boot protocol lies in the simplicity of device report – a data packet containing information about button presses and mouse movements. However, samples were designed to demonstrate all features of the class and because of that, they are somewhat heavy. In real-life applications, it is often not necessary to implement each and every virtual function – only what is needed. In today’s article I will show practical application of HID boot device building a simple gadget.

Originally, HID boot protocol was meant to be used with keyboards and mice. When USB became popular, other keyboard-emulating devices, such as barcode scanners and magnetic card readers have been migrated from PS/2 standard to USB while keeping their keyboard-emulating property. As a result, many modern “not-so-human” input devices behave exactly like a keyboard including boot protocol support. A gadget that I demonstrate today is portable autonomous barcode scanner built using Arduino board, USB Host shield, handheld USB barcode scanner and LCD display (see title picture). The operation is simple – when handheld scanner button is pressed, it scans the barcode and sends it to Arduino symbol by symbol. Arduino then outputs these symbols on LCD display. LCD is erased before outputting each new barcode by tracking time between arrival of two consecutive symbols. To keep the code simple, I intentionally did not implement any data processing, however, since Arduino sketch for the gadget compiles in just a little over 14K, there is plenty of memory space left for expansion.

Continue reading Connecting barcode scanner to Arduino using USB Host Shield

HID support for USB Host Shield Library 2.0 released

HID r.2.0 released

HID r.2.0 released

I pleased to announce that after a long and difficult development period Human Input Device AKA HID class support has been added to USB Host Shield Library r.2.0 and is available on gitHub – I suggest downloading the whole directory, since some modifications has been also made to core files to accommodate a new class. HID devices include popular devices like keyboards, mice, joysticks, game controllers, bar code scanners, RFID and magnetic card readers, digital scales and UPSes, to name a few.

I previously wrote about interfacing to HID devices here, here, and here. The code examples in these articles were written for legacy USB Host Shield library and can’t be compiled with current revision, however, the basic principles are the same – the device is periodically polled by the host and sends back data block called report containing changes in device controls (buttons, switches, jog dials etc.) since the last poll. Even though different devices have different report formats, for a certain device, report format is stored in the device in data structure called report descriptor. Therefore, it is possible to learn about device controls from the device itself by parsing its report descriptor.

There is one special case where report format is known in advance. Almost all HID keyboards and mice support so-called boot protocol intended for communication to very simple systems like PC configuration screen when computer runs from BIOS. Keyboard boot protocol report consists of 8 bytes containing state of modifier keys (CTRL, SHIFT,etc.) in the first byte, second byte being reserved, and up to 6 key scan codes in the rest of the report. Mouse boot protocol report consists of 3 bytes, first of which contains state of left, right and middle buttons and other 2 store X and Y travel since last poll.

In many cases boot protocol capabilities are more than enough for an Arduino project; for this reason, boot protocol class is the first to be released. To demonstrate operations of this class, 2 simple sketches has been developed, one for mouse, another for keyboard.

Continue reading HID support for USB Host Shield Library 2.0 released