Files XBOXUSB.cpp and XBOXUSB.h contain the main functionality. An example sketch (a screenshot of which was used for the title picture) can be found in the examples directory. Also, check the EXTRAREADME file for additional information as well as Kristian’s github page.

I’d like to note that Kristian is a developer of support code for Sony controllers – Dualshock 3, Navigation, and Motioncontroller – in the current version of the USB Host library. The Xbox360 code
is another nice contribution. Once again – thank you Kristian!

This is a short announcement for those who might have missed a recent comment to this post. Yuuichi Akagawa developed USB MIDI driver for USB Host 2.0 library and made it available on gitHub. The repository has source code, single and multiple device examples, function reference and supported device list.

This is a short announcement about a new feature added to USB Host Shield 2.0 Library. Kristian Lauszus from TKJ Electronics developed and contributed code for interfacing to several Sony PS3 game controllers and has been working on refining it for several months. Two days ago he posted a pull request on GitHub with the following comment:

I don’t know if you could post it on your blog too, so people will know that it now also supports the controllers via USB?

Since the beginning, Kristian concentrated on Bluetooth interface for the controllers. This is the preferred way, however, the standard wired USB interface is as good as Bluetooth dongle plus it is 100% compatible. Take a look at this example showing how to initialize PS3 controller and access its buttons, joysticks and accelerometers.

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.

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 usb.org 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.

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

Today I want to show a simple USB Host Shield 2.0 modification which allows controlling power to USB peripheral. I learned this technique from Camille’s comment to one of digital camera USB control articles. In short, the idea was to cut VBUS connection between USB host and peripheral, simulating disconnect state. P-channel MOSFET, inserted into VBUS, worked as a switch. I designed this capability into USB Host Shield 2.0 but never needed the functionality therefore this useful feature was left undocumented. Recently I started working with very interesting Nikon P&S camera which can be turned on and off with VBUS power so I finally made this modification. It is very simple.

Take a look at the title picture (click on it to make it larger). The modification uses existing VBUS power select pads of the shield. Out of the box, the one labeled 5V is shorted with solder bridge. First step is to remove this bridge with a solder wick so both pads are clean.

It can be seen that a MOSFET in SOT-23 package fits nicely on those pads (I’m using FDN306P). Drain and source pins are soldered to VBUS and 5V, respectively, and gate, which hangs in the air, is routed to an unused digital pin via an 1M resistor. When digital pin is low the MOSFET conducts. When digital pin goes high the MOSFET switches off disconnecting VBUS from the peripheral.

If you are going to drive high-power peripherals, like digital cameras or phones, it is a good idea to add some capacitance to 5V. I’m using 220uF low-ESR organic polymer tantalum cap in 1210 package which fits nicely on 0.1″ spaced 5V and GND pins of the shield; an ordinary leaded 100-200uF aluminum capacitor will work as well.

I’m quite pleased to announce that ever-popular Sony PS3 game controllers are now supported by current (rev.2.0) USB Host Library. Kristian Lauszus from TKJ Electronics developed a library to interface with Dualshock 3, as well as Move Navigation and Motion controllers via a Bluetooth dongle (only CSR-based ones are supported at the moment). This library has been merged into the main code and I will start maintaining it as soon as my Dualshock 3 arrives.

Sony PS3 controllers are advanced versions of ordinary HID joysticks. They can be interfaced via USB or Bluetooth, the buttons can be read as analog or digital and controller contains rumble motor which can be activated remotely to indicate a hit, for example. The controller also contains a gyroscope and accelerometers so it is possible to control a robot by simply waving and/or rotating the controller.

Kristian got his inspiration from Richard Ibbotson’s articles, as well as works by Tomoyuki Tanaka and others (full list can be found in PS3README file). His Wiki page gives implementation details, communication protocol, differences between controllers, as well as plenty of links to other sources of PS3 controller interfacing knowledge.

Kristian developed this library as a part of his Balancing robot project. The project is very well documented – if you are interested in robots, PID or remote control, please take a look. I also enjoyed watching this video presentation, give it a shot to see balancing robot in action.

While playing with some cheap USB to RS-232 converters which use counterfeit PL2303 chips I found a bug in acm code which was sitting there from initial release. This bug was causing sluggish response from serial devices, as well as random 0x0d and 0x06 error codes. The bug is now fixed and corrected version of the library has been posted on GitHub a moment ago.

As a side effect to aforementioned bug fix some new functionality is now available. First, ACM and PL2303 classes now have isReady() method which can be used to check if certain device has been enumerated, initialized, and ready for service. This method is now used in all sample sketches, see, for example, pl2303_tinygps.pde, line 98.

Another addition is a block of code which performs proper PL2303 initialization. It is a mix of Linux pl2303.c code and Windows Prolific driver USB protocol traces. This block was added during troubleshooting; it turned out that it doesn’t make any difference on PL2303-based devices that I have – either genuine or counterfeit. However, it is tempting to be able to simulate “proper” manufacturer-recommended behaviour in the code so I decided to keep the initialization. It is turned off by default; if desired, it can be added during compilation by defining PL2303_COMPAT (see cdcprolific.h, line 41 and cdcprolific.cpp, lines 159-179 ). The block adds ~500 bytes to the binary so don’t turn it on just in case.

Please check the new code with your devices and let me know if you can see any improvements or new issues.

Fresh update of USB Host Library 2.0 has just been posted to GitHub. The primary purpose of this release is to maintain compatibility with Arduino releases – the USB Host Library is now compiles in 1.0 as well as pre-1.0 versions of Arduino IDE. Enjoy!

Several important changes have been made to the code, some related to 1.0 compatibility and some not. The library examples were all tested and corrected, the information below is intended for developers using the library in their own projects:

PL2302 driver.

Arduino 1.0 defines PL symbol internally (thank you, Paul for finding this out!), therefore, I needed to change name of Prolific class driver. The new name is PL2302; I updated library examples to compile correctly, if someone uses this class in their own development, the right way to define an instance of Prolific device is now PL2303 Pl(&Usb, &AsyncOper);

NAK handling.

A bug preventing long polls of an endpoint has been fixed. Previously, if bmNakPower member of epInfo structure was left unitialized the transfer to this endpoint would stop after receiving a single NAK. With current version, the endpoint would be polled for up to 5 seconds. This is rarely desirable, so please initialize bmNakPower with USB_NAK_DEFAULT or USB_NAK_MAX_POWER. If a single poll is desired, as is often the case with interrupt endpoints, specify USB_NAK_NOWAIT and if more than maximum number of NAKs (up to 5 seconds) is necessary, specify USB_NAK_NONAK.

Code speed.

An unnecessary delay of 20ms has been found (thank you, Alex for discovering this!) and removed from USB::setAddress() member function. As a result, every USB transfer is now 20ms faster. While generally a good thing, it could inadvertently affect data exchanges with slow endpoints. If after upgrading to the current version you start seeing more NAKs, that’s probably why.

One nice thing about Arduino 1.0 is built-in PROGMEM support for strings. It is now possible to free about 300-400 bytes of RAM by redefining USBTRACE and USBTRACE2 macros used in debugging output (thank you, John, for the tip!). For example, USBTRACE (Serial.print(F(s))) will move all USBTRACE strings to PROGMEM. The code size will increase so be careful with this feature if your code size is close to the limit for your Arduino board.

This is the end of announcement – download the code, play with it and if you have any issues please share your findings in the comments.