Skip to content
This repository

Revision 2.0 of USB Host Library for Arduino.

branch: master
Octocat-spinner-32 examples Show how to control the light and rumble inside the PS4 controller April 06, 2014
Octocat-spinner-32 .gitignore commit June 11, 2013
Octocat-spinner-32 .gitmodules Add RTClib September 02, 2013
Octocat-spinner-32 BTD.cpp Fixed debug message March 18, 2014
Octocat-spinner-32 BTD.h Remote name buffer should be a char array January 16, 2014
Octocat-spinner-32 BTHID.cpp Removed some unnecessary functions and some other cleanup February 03, 2014
Octocat-spinner-32 BTHID.h Removed some unnecessary functions and some other cleanup February 03, 2014
Octocat-spinner-32 PS3BT.cpp Simplify how PS3 printStatusString prints the string March 07, 2014
Octocat-spinner-32 PS3BT.h Added getLastMessageTime() - this is useful if you want to detect if … February 25, 2014
Octocat-spinner-32 PS3Enums.h Can now set the rumble and light on the PS4 controller February 17, 2014
Octocat-spinner-32 PS3USB.cpp Simplify how PS3 printStatusString prints the string March 07, 2014
Octocat-spinner-32 PS3USB.h Renamed getStatusString() to printStatusString() January 04, 2014
Octocat-spinner-32 PS4BT.h bigRumble and smallRumble values were swapped February 17, 2014
Octocat-spinner-32 PS4Parser.cpp Improved the way PS4 buttons are read February 17, 2014
Octocat-spinner-32 PS4Parser.h bigRumble and smallRumble values were swapped February 17, 2014
Octocat-spinner-32 PS4USB.h bigRumble and smallRumble values were swapped February 17, 2014
Octocat-spinner-32 README.md Updated PS3 paring documentation March 27, 2014
Octocat-spinner-32 SPP.cpp Fix annoying warnings and provide an optimization. December 29, 2013
Octocat-spinner-32 SPP.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 Usb.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 Usb.h HID fixes December 25, 2013
Octocat-spinner-32 UsbCore.h Some files were missing copyright section March 07, 2014
Octocat-spinner-32 Wii.cpp Can now turn LED off by calling setLedOn(OFF) for all controllers January 04, 2014
Octocat-spinner-32 Wii.h Updated some more comments January 19, 2014
Octocat-spinner-32 WiiCameraReadme.md Code for the Wii IR camera needs to be activated in settings.h now December 30, 2013
Octocat-spinner-32 XBOXOLD.cpp Can now turn LED off by calling setLedOn(OFF) for all controllers January 04, 2014
Octocat-spinner-32 XBOXOLD.h Can now turn LED off by calling setLedOn(OFF) for all controllers January 04, 2014
Octocat-spinner-32 XBOXRECV.cpp Can now turn LED off by calling setLedOn(OFF) for all controllers January 04, 2014
Octocat-spinner-32 XBOXRECV.h Updated documentation typo January 10, 2014
Octocat-spinner-32 XBOXUSB.cpp Added support for Afterglow wired Xbox controller February 16, 2014
Octocat-spinner-32 XBOXUSB.h Added support for Afterglow wired Xbox controller February 16, 2014
Octocat-spinner-32 address.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 adk.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 adk.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 avrpins.h Changed variable name from baseReg to pio February 26, 2014
Octocat-spinner-32 cdcacm.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 cdcacm.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 cdcftdi.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 cdcftdi.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 cdcprolific.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 cdcprolific.h Merge branch 'xxxajk' into arm October 05, 2013
Octocat-spinner-32 confdescparser.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 controllerEnums.h Can now set the rumble and light on the PS4 controller February 17, 2014
Octocat-spinner-32 gpl2.txt Merge my debug changes. March 28, 2013
Octocat-spinner-32 hexdump.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 hid.cpp Some files were missing copyright section March 07, 2014
Octocat-spinner-32 hid.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 hidboot.cpp fix mid button and struct December 25, 2013
Octocat-spinner-32 hidboot.h fix mid button and struct December 25, 2013
Octocat-spinner-32 hidescriptorparser.cpp Some files were missing copyright section March 07, 2014
Octocat-spinner-32 hidescriptorparser.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 hiduniversal.cpp Some files were missing copyright section March 07, 2014
Octocat-spinner-32 hiduniversal.h Some files were missing copyright section March 07, 2014
Octocat-spinner-32 hidusagestr.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 hidusagetitlearrays.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 keywords.txt Can now set the rumble and light on the PS4 controller February 17, 2014
Octocat-spinner-32 macros.h Some files were missing copyright section March 07, 2014
Octocat-spinner-32 masstorage.cpp Some files were missing copyright section March 07, 2014
Octocat-spinner-32 masstorage.h Some files were missing copyright section March 07, 2014
Octocat-spinner-32 max3421e.h compile faster September 23, 2013
Octocat-spinner-32 max_LCD.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 max_LCD.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 message.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 message.h Move Usb.h UsbCore.h and trim. Usb.h is now only includes, as it augh… September 30, 2013
Octocat-spinner-32 parsetools.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 parsetools.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 printhex.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 settings.h Forgot copyright section in settings.h in 1ebce9b March 29, 2014
Octocat-spinner-32 sink_parser.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 usb_ch9.h Move Usb.h UsbCore.h and trim. Usb.h is now only includes, as it augh… September 30, 2013
Octocat-spinner-32 usbhost.h Do not set SS pin for the Due March 07, 2014
Octocat-spinner-32 usbhub.cpp Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 usbhub.h Janitorial, whitespace fixes. No new code. December 25, 2013
Octocat-spinner-32 xboxEnums.h Can now turn LED off by calling setLedOn(OFF) for all controllers January 04, 2014
README.md

USB Host Library Rev.2.0

The code is released under the GNU General Public License.


Summary

This is Revision 2.0 of MAX3421E-based USB Host Shield Library for AVR's.

Project main web site is: http://www.circuitsathome.com.

Some information can also be found at: http://blog.tkjelectronics.dk/.

The shield can be purchased at the main site: http://www.circuitsathome.com/products-page/arduino-shields or from TKJ Electronics: http://shop.tkjelectronics.dk/product_info.php?products_id=43.

USB Host Shield

For more information about the hardware see the Hardware Manual.

Developed By

How to include the library

First download the library by clicking on the following link: https://github.com/felis/USB_Host_Shield_2.0/archive/master.zip.

Then uncompress the zip folder and rename the directory to "USB_Host_Shield_20", as any special characters are not supported by the Arduino IDE.

Now open up the Arduino IDE and open "File>Preferences". There you will see the location of your sketchbook. Open that directory and create a directory called "libraries" inside that directory. Now move the "USB_Host_Shield_20" directory to the "libraries" directory.

The final structure should look like this:

  • Arduino/
    • libraries/
      • USB_Host_Shield_20/

Now quit the Arduino IDE and reopen it.

Now you should be able to go open all the examples codes by navigating to "File>Examples>USB_Host_Shield_20" and then select the example you will like to open.

For more information visit the following site: http://arduino.cc/en/Guide/Libraries.

How to use the library

Documentation

Documentation for the library can be found at the following link: http://felis.github.com/USB_Host_Shield_2.0/.

Enable debugging

By default serial debugging is disabled. To turn it on simply change ENABLE_UHS_DEBUGGING to 1 in settings.h like so:

#define ENABLE_UHS_DEBUGGING 1

Boards

Currently the following boards are supported by the library:

  • All official Arduino AVR boards (Uno, Duemilanove, Mega, Mega 2560, Mega ADK, Leonardo etc.)
  • Arduino Due
    • If you are using the Arduino Due, then you must include the Arduino SPI library like so: #include <SPI.h> in your .ino file.
  • Teensy (Teensy++ 1.0, Teensy 2.0, Teensy++ 2.0, and Teensy 3.x)
    • Note if you are using the Teensy 3.x you should download this SPI library as well: https://github.com/xxxajk/spi4teensy3. You should then add #include <spi4teensy3.h> to your .ino file.
  • Balanduino
  • Sanguino
  • Black Widdow

The following boards need to be activated manually in settings.h:

  • Arduino Mega ADK
    • If you are using Arduino 1.5.5 or newer there is no need to activate the Arduino Mega ADK manually
  • Black Widdow

Simply set the corresponding value to 1 instead of 0.

Bluetooth libraries

The BTD library is a general purpose library for an ordinary Bluetooth dongle. This library make it easy to add support for different Bluetooth services like a PS3 or a Wii controller or SPP which is a virtual serial port via Bluetooth. Some different examples can be found in the example directory.

The BTD library also makes it possible to use multiple services at once, the following example sketch is an example of this: PS3SPP.ino.

BTHID library

The Bluetooth HID library allows you to connect HID devices via Bluetooth to the USB Host Shield.

Currently HID mice and keyboards are supported.

It uses the standard Boot protocol by default, but it is also able to use the Report protocol as well. You would simply have to call setProtocolMode() and then parse HID_RPT_PROTOCOL as an argument. You will then have to modify the parser for your device. See the example: BTHID.ino for more information.

The PS4 library also uses this class to handle all Bluetooth communication.

For information see the following blog post: http://blog.tkjelectronics.dk/2013/12/bluetooth-hid-devices-now-supported-by-the-usb-host-library/.

SPP library

SPP stands for "Serial Port Profile" and is a Bluetooth protocol that implements a virtual comport which allows you to send data back and forth from your computer/phone to your Arduino via Bluetooth. It has been tested successfully on Windows, Mac OS X, Linux, and Android.

Take a look at the SPP.ino example for more information.

More information can be found at these blog posts:

To implement the SPP protocol I used a Bluetooth sniffing tool called PacketLogger developed by Apple. It enables me to see the Bluetooth communication between my Mac and any device.

PS4 Library

The PS4BT library is split up into the PS4BT and the PS4USB library. These allow you to use the Sony PS4 controller via Bluetooth and USB.

The PS4BT.ino and PS4USB.ino examples shows how to easily read the buttons, joysticks, touchpad and IMU on the controller via Bluetooth and USB respectively. It is also possible to control the rumble and light on the controller.

Before you can use the PS4 controller via Bluetooth you will need to pair with it.

Simply create the PS4BT instance like so: PS4BT PS4(&Btd, PAIR); and then hold down the Share button and then hold down the PS without releasing the Share button. The PS4 controller will then start to blink rapidly indicating that it is in paring mode.

It should then automatically pair the dongle with your controller. This only have to be done once.

For information see the following blog post: http://blog.tkjelectronics.dk/2014/01/ps4-controller-now-supported-by-the-usb-host-library/.

Also check out this excellent Wiki by Frank Zhao about the PS4 controller: http://eleccelerator.com/wiki/index.php?title=DualShock_4 and this Linux driver: https://github.com/chrippa/ds4drv.

PS3 Library

These libraries consist of the PS3BT and PS3USB. These libraries allows you to use a Dualshock 3, Navigation or a Motion controller with the USB Host Shield both via Bluetooth and USB.

In order to use your Playstation controller via Bluetooth you have to set the Bluetooth address of the dongle internally to your PS3 Controller. This can be achieved by first plugging in the Bluetooth dongle and wait a few seconds. Now plug in the controller via USB and wait until the LEDs start to flash. The library has now written the Bluetooth address of the dongle to the PS3 controller.

Finally simply plug in the Bluetooth dongle again and press PS on the PS3 controller. After a few seconds it should be connected to the dongle and ready to use.

Note: You will have to plug in the Bluetooth dongle before connecting the controller, as the library needs to read the address of the dongle. Alternatively you could set it in code like so: PS3BT.ino#L20.

For more information about the PS3 protocol see the official wiki: https://github.com/felis/USB_Host_Shield_2.0/wiki/PS3-Information.

Also take a look at the blog posts:

A special thanks go to the following people:

  1. Richard Ibbotson who made this excellent guide: http://www.circuitsathome.com/mcu/ps3-and-wiimote-game-controllers-on-the-arduino-host-shield-part
  2. Tomoyuki Tanaka for releasing his code for the Arduino USB Host shield connected to the wiimote: http://www.circuitsathome.com/mcu/rc-car-controlled-by-wii-remote-on-arduino

Also a big thanks all the people behind these sites about the Motion controller:

Xbox Libraries

The library supports both the original Xbox controller via USB and the Xbox 360 controller both via USB and wirelessly.

Xbox library

The XBOXOLD class implements support for the original Xbox controller via USB.

All the information are from the following sites:

Xbox 360 Library

The library support one Xbox 360 via USB or up to four Xbox 360 controllers wirelessly by using a Xbox 360 wireless receiver.

To use it via USB use the XBOXUSB library or to use it wirelessly use the XBOXRECV library.

Note that a Wireless controller can NOT be used via USB!

Examples code can be found in the examples directory.

Also see the following blog posts:

All the information regarding the Xbox 360 controller protocol are form these sites:

Wii library

The Wii library support the Wiimote, but also the Nunchuch and Motion Plus extensions via Bluetooth. The Wii U Pro Controller is also supported via Bluetooth.

First you have to pair with the controller, this is done automatically by the library if you create the instance like so:

WII Wii(&Btd, PAIR);

And then press 1 & 2 at once on the Wiimote or press sync if you are using a Wii U Pro Controller.

After that you can simply create the instance like so:

WII Wii(&Btd);

Then just press any button on the Wiimote and it will then connect to the dongle.

Take a look at the example for more information: Wii.ino.

Also take a look at the blog post:

The Wii IR camera can also be used, but you will have to activate the code for it manually as it is quite large. Simply set ENABLE_WII_IR_CAMERA to 1 in settings.h.

The WiiIRCamera.ino example shows how it can be used.

All the information about the Wii controllers are from these sites:

FAQ

When I plug my device into the USB connector nothing happens?

  • Try to connect a external power supply to the Arduino - this solves the problem in most cases.
  • You can also use a powered hub between the device and the USB Host Shield. You should then include the USB hub library: #include <usbhub.h> and create the instance like so: USBHub Hub1(&Usb);.
Something went wrong with that request. Please try again.