Category Archives: USB

I just wanted to pass along something I learned about last year. There is an inexpensive chip that handles USB host operations, allowing you to plug in devices like keyboards, mice, joysticks, etc. The chip is about $4 in quantities of one, and much cheaper if you order in bulk.

I found a company in the UK that uses this chip on a small circuit board that lets you plug in a USB device, and then get output via serial commands. You can hook this up to an Arduino and read a modern keyboard or mouse, for example. They have various firmware loads you can put on it to handle different protocols.

These folks have a software-only implementation of USB host for the AVR chip like the Arduino uses. It allows, with software only and some wires to a USB connector, the device to read a basic USB device like a mouse or keyboard.

The only thing I noticed was it requires a 16Mhz crystal, instead of the stock 15mhz. They did it by building their own system, but someone wanting to do it on an Arduino would need to desolder and replace the crystal.

However, there are some pretty simple plans to “build a $5 Arduino” with minimal parts — so perhaps it would be very cheap to breadboard something that supports this.

Today, I picked up my Circuits@Home USB Host adapter from the post office. Now I could finally try to put together a converter that would read from a standard USB joystick and send out iCade formatted keyboard characters to my iPad. Since I had never worked with USB before, I was amazed it only took about 30 minutes to figure out. This is a testament to the work done by the folks responsible for the USB Host library code. The inclusion of functioning sample code allowed me to make quick modifications to do what I wanted.

I will post full details soon, but right now, here are some highlights.

For this project, I am using an Arduino Leonardo. Unlike the UNO and most other Arduinos, the Leonardo is capable of acting as a USB HID (human interface device) so it can appear to be a mouse or keyboard to the computer it is plugged in to. In my case, the computer would be an iPad via Apple’s Camera Connector Kit USB port adapter, and the Leonardo would be acting like a keyboard to send iCade keys,

I had previously downloaded the Arduino USB library from GitHub and extracted it in to my Arduino IDE library folder. I discussed my first experience with Arduino libraries in an earlier article when I was trying to get the iTead Studios USB shield to work.

I was able to test the USB by running various example programs that came with the library, specifically USBHidJoystick. Here is an example of that program’s output as I moved the joystick and pressed some buttons:

This example program shows values coming back from the USB joystick. The joystick and buttons seem to be contained in the Z bytes (Z1 and Z2).

The joystick I am using is a “Playtech Pro Arcade Fighting Stick” sold on Amazon.com. (As of this posting, the price is $32, but it was about $26 back in December.) Moving the joystick around seemed to change bits in the Z1 value. The four arcade buttons changed bits in Z2. This joystick has a row of seven small control buttons on the top, and four of those buttons (marked Select, Start, L3 and R3) toggled the remaining four bits in Z1.

I do not know how standard USB joysticks are, but I would hope at least the joystick directions and primary buttons would be standardized. The four buttons that were different colors and labeled like Playstation controllers (triangle, circle, X, square) were the high bits of Z2, and the grey surrounding buttons (L1, L2, R1 and R2) were the lower four bits. Perhaps these grey buttons map to the front edge buttons found on console gamepads?

The iCade has a joystick and eight buttons, so I would need to figure out which of the USB buttons I would need to use.

This sample program would be the basis of my experiment. It was made of an Arduino sketch called USBHIDJoystick.pde, and two C++ files — hidjoystickrptparser.cpp and hidjoystickrptparser.h. It seemed the sketch would initialize the USB library, and specify the name of a custom function which would parse the USB data and pull out the joystick related bits. Inside the main loop() was just a call to a task handler function in the library, which I assume is the code responsible for polling and processing incoming USB data.

Inside the hidjoystickrptparser.cpp file, there was a function called OnGamePadChanged() which would print out various values. I planned to comment the print lines out, and just have it call my own button processing code which would parse the set bits rather than read digital input pins. I would just stick the Z1 and Z2 bytes together as a 16-bit integer:

The GamePadEventData structure, defined in the .h file, contains five byte variables:

uint8_t X, Y, Z1, Z2, Rz;

I would just take the Z1, shift it to the left 8 bits, and OR in the Z2 value, creating a new 16-bit value that held both. In hex, it would look like this: 0xAABB, where AA is Z1 and BB is Z1. Now, inside my new handleJoystick() routine, I could look for those bits rather than scan digital I/O pins.

Instead of using the example sketch, I planned to just merge the USB specific items in to my existing teensy_icade sketch. This would be including some header files, and declaring some variables. The following code was lifted directly from the sample sketch:

Inside my setup(), I would need to include the USB specific items. Since I have not found any documentation on the USB library, I can only assume what these functions do. Usb.Init() seems clear enough (though this code still attempts to run even if it fails, which is bad), and the Hid.SetReportParser() seems to be where the calling program passes in a structure containing the handling functions that the USB code will call when it gets a joystick packet. Or something.

After this, the only other bit of code I would be borrowing was to put a call to the USB task handler inside my loop():

// Handle USB
Usb.Task();

Now all I needed to do was pull out my pin reading code from the loop, and make it a separate function which would now be called, not by my loop, but when the USB handler had data to process.

Since my original code used an array of bytes, each representing what pin should be read to indicate the specific direction/button was active, I decided to use the same approach with this. I would use the same button mappings, but alter the defines so that instead of containing a byte value representing a pin number, each one would be a 16-bit value representing which bit was the one for the button. It looks like this:

In my original code, I called them “BTN1_PIN” or “RIGHT_PIN”, but I wanted to change the names to be more clear, and also so a future version might mix both capabilities in the same source code. My array of these items would be updated to hold 16-bit values (instead of bytes), and use the renamed defines:

You can see that I also renamed a count #define to be “USB_BTN_COUNT” instead of “DI_PIN_COUNT”. The other defines I used in the original were removed, since they were just used to error check the user in case they tried to build a version using pins outside of the allowed range.

My iCade array remains the same, though it will need to be customized to map the eight USB buttons to the proper iCade buttons once I figure out what they should be.

Now the real work could begin. I ripped out the entire loop that went through the myPins[] array and made only a few changes. Instead of reading the status of a digital pin in the array, I already knew the status since I was being passed in the bit value. I would just set status to that specific bit:

For digital pins, you read each pin and got a LOW or HIGH value. For this, I assume multiple bits could be set at the same time (?), so I wanted to take the buttonMask passed in from the USB code and just test the specific bit pattern for the button in question. I was still looping through all 12 buttons, but now I would be checking the status of a bit pattern to a bit mask in an array, rather than reading a digital pin and storing the status of that pin.

Now status would no longer be LOW or HIGH (0 or 1), but instead would either be 0x0000 or have a specific bit set like 0x0200 or 0x8000. Instead of comparing “status==LOW” I needed to simply check against it being 0. (My Teensy wiring used “active low” so LOW meant the button was pressed, and here the bit pattern being HIGH mean it was pressed.) That change looked like this:

// If pin is Active LOW,
if (status!=0)
{

(I still need to clean up the comments.)

I believe those were the only changes I needed to make, but my first test did not work. It seems my debounce code was causing some kind of issue. Since I assumed the joystick should already be doing denounce before sending out a USB packet with the button status, I tried just commenting out my debounce check and that got everything working. Almost.

The Teensy 2.0 had to be told what kind of USB device it was at compile time. A menu setting would toggle it between USB Serial, or USB Keyboard. With the Leonardo, that option did not appear in the IDE. A quick search revealed I needed to turn on the USB keyboard support in setup():

Keyboard.begin();

Once done, I could open up a text editor (so the “typing” from the Arduino had a place to show up) and move the joystick around and see the results on the screen:

Testing on the iPad was next. Unlike the Teensy 2.0, which could run from the tiny 20mah of power the iPad USB port provided, the Leonardo and USB Host shield would be more demanding. I was not sure what the rules were with using an external power supply on an Arduino — didn’t I read somewhere that you had to change something to prevent problems if it was also connected to a computer’s USB port at the same time?

To be safe, I decided to use a powered USB hub. For testing, my setup looked like this:

JOYSTICK -> Leonardo -> USB Hub -> Mac

I figured all I would have to do is unplug the hub cable from the Mac, and plug it in to the iPad using the Apple Camera Connector kit.

It worked just fine, and I soon found myself testing it on Atari’s Greatest Hits (the first official app to support the iCade) as well as Gridlee (a free arcade game which runs on the MAME emulator).

The buttons were not where they needed to be, so I will need to fix that next.

But for now, I wanted to share my initial progress. I will clean up the code and post it soon.

Thanks to my day job, I got my first exposure to Arduino (as well as other similar devices, like the $4.30 TI 430 Launchpad). From time to time, I will post little tidbits of things I have learned.

This is one of those times. (I post this mostly so it will end up in Google search results and maybe save someone the time I wasted trying to figure this out on my own ;-)

There is a USB Host Shield sold by iTead Studio in China. Their product retails for $24.00 (currently $21.60) and it allows the Arduino to act as a “host” and read from other USB devices such as mice, keyboards, etc.

For those unfamiliar with how USB works, there are two types of USB things… USB “device” mode is for something you would plug to a computer so the computer could use it. A printer or thumb drive supports USB device mode. The computer acts as the host, so it has a USB host port. In the 90s, when I was working for Microware, we were bringing USB support to our OS-9 embedded operating system, but initially were only doing device mode. This would let a gadget running OS-9 hook up to a PC so it could talk to it. It did not let you hook up USB devices to OS-9 (though later, this support was added for flash drives and such).

But I digress.

Why would one want a USB host shield when the Arduino already has a USB port? The USB Host shield’s USB port is a “host” port, and is different than the USB “device” port found on the Arduino. The USB port on most Arduinos is just a serial device for loading programs and input/output. It makes the Arduino appear as a serial “device” to the “host” PC. There are some boards, like the Teensy 2.0 and Arduino Leonardo, that do have USB ports than can switch between device and host mode to act be seen as a USB HID (human interface device) such as a keyboard, mouse or joystick.

As part of my expansion of the iCade joystick experiment, I wanted to get a USB Host shield that would let the Arduino read a standard USB joystick (like the $14 arcade controllers found on Amazon) and then convert that in to iCade USB keyboard messages which would be sent out a the Arduino’s built-in port, configured to appear as a USB HID keyboard. This would require an Arduino that can act as a USB HID device (Leonardo), The joystick would plug in to the USB Host shield, then the USB port of the Arduino would go to the iPad.

As mentioned, the Arduino Leonardo provides USB HID support, similar to the Teensy 2.0 I previously experimented with. Unfortunately, the iTead USB Host shield will not work with the Leonardo due to some pins being moved around. The iTead Host Shield communicates over SPI, which is a communication protocol standard. The Arduino UNO has the SPI pins mixed in with the normal digital pins, but the Leonardo moves the SPI pins to a separate small header block (2×3, if I recall) located at the center edge of the board. Thus, the Leonardo does not connect those pins to the iTead Shield.

There is a Circuits at Home USB Host shield that does have this connection, so it should work with the Leonardo. This will be discussed at a later time. For now, my Arduino UNO can hook up to the iTead shield for testing and creating the program that would ultimately need to run on a Leonardo. (Or, for a few dollars and some time, there seems to be a project that lets you hook a USB port to the Arduino and use a special library that allows it to send keyboard commands.)

For now, I will just share a few things I wondered and learned…

Arduino programs are called “sketches” and they are very C-like. The ones I see have are files that use the extension .ino.

There are also Libraries that appear to be written as C or C++ files, ending with typical .c, .h, and .cpp extensions. The iTead Studio USB Host shield came with a .zip file of a USB implementation like this, but absolutely no documentation on what to do with it.

I was not sure how to compile C code, and casual searches didn’t prove helpful. The IDE refused to open a .c file, but would let you drag-and-drop one in to the editor. Building it didn’t work.

I was able to find a more current version of the USB Host library on github.com, but still didn’t know what to do with it.

Last night, after reading a reference on how to add a Library to the Arduino, I apparently figured it out. It seems all I had to do was drag the USB Host source directory in to the “library” folder of the Arduino IDE. (On a Mac, it was in ~/Documents/Arduino/library). Once I did this, I could open the included USB example sketches (.pde extension, for some reason) and build them… There were some minor problems along the way, like having to remove any spaces or special characters from the library folder name (how quaint), and then some conflicts with having the iTead library files installed (I ended up removing them), but the end result was building the test USB code and getting to try it out on an Arduino UNO using the iTead shield.