I [Lauszus] have just released a new project on Kickstarter called the Balanduino. It’s an open source balancing robot that uses several of the libraries I have created for the USB Host library. These will allow you to control the robot with a PS3, Xbox or Wii controller or even your Android phone or PC.
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.
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:
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);
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.
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.
After posting an article about interfacing USB GPS receiver to Arduino I started receiving e-mails from people asking about a decent inexpensive GPS receiver compatible with USB Host library. After some research and testing I finally found a device which I really like.
Lightweight – my scale shows 19g for the dongle without connector cover. It is possible to get weight close to 15g by removing the case, USB connector and hardwiring the module to USB Host shield.
Sensitive – SiRF Star III high sensitivity GPS chip allows this module to lock in less than a minute from my basement (!). Outdoor performance is simply amazing while power consumption stays around 50ma.
Easy to use – the module uses Prolific PL2303 USB to serial converter supported by USB Host library 2.0 and the sketch from the previous article works without any modifications. Also, the module has status LED showing when GPS position is fixed – comes in handy during field tests when serial console is not available. The dongle ships with semi-rigid USB cable which can be used as a raiser.
Overall, ND-100S is very small, sensitive and inexpensive GPS receiver. It can be used with USB Host shield using PL2303 USB to serial converter support in USB Host library rev.2.0. I have a couple of projects in mind which would use this receiver – will post as soon as I have more information about it.
Today, I’d like to show how to exchange data between USB device and ADK-capable Android phone. I will be using CueCat barcode scanner as source device; the data will be received by the phone and displayed on a screen using Arduino Terminal Android application.
A phone is USB device, too, and since two USB devices are unable to communicate to each other directly, I’m using Arduino board equipped with USB Host shield to relay data between devices. The sketch which runs on Arduino is a mix of two other pieces of code, one from ADK terminal emulator article and another one from an article explaining interfacing with a barcode scanner. Refer to these articles if you have questions about a specific piece.
Below is a full text of an Arduino sketch. It can be pasted from this page in Arduino IDE, compiled, and loaded into the board. It is also included in the examples section of USB Host library rev.2.0 distribution on gitHub. The library itself shall be installed in Arduino IDE tree as well.
To receive data from Arduino you’ll need Arduino Terminal application installed on your phone. The source code of application is also available – it is released under GPL2, if you make modifications to the code, please make them available for other people!
Finally, we will need some hardware – an Arduino board, USB Host shield, a USB hub, “declawed” CueCat or any other HID boot barcode scanner, as well as ADK-compatible Android phone. We will also need a 5V power supply capable of providing ~700ma of electrical current. I will show arrangement of all necessary pieces after explaining the sketch code.
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.