3 The code is released under the GNU General Public License.
4 __________
5
6# Summary
7 This is Revision 2.0 of MAX3421E-based USB Host Shield Library for AVR's.
8
9Project main web site is: <http://www.circuitsathome.com>.
10
11Some information can also be found at: <http://blog.tkjelectronics.dk/>.
12
13The shield can be purchased at the main site: <http://www.circuitsathome.com/products-page/arduino-shields> or from [TKJ Electronics](http://tkjelectronics.com/): <http://shop.tkjelectronics.dk/product_info.php?products_id=43>.
25 * Developer of the [BTD](#bluetooth-libraries), [BTHID](#bthid-library), [SPP](#spp-library), [PS4](#ps4-library), [PS3](#ps3-library), [Wii](#wii-library), [Xbox](#xbox-library), and [PSBuzz](#ps-buzz-library) libraries
26* __Andrew Kroll__ - <xxxajk@gmail.com>
27 * Major contributor to mass storage code
28
29# How to include the library
30
31First download the library by clicking on the following link: <https://github.com/felis/USB_Host_Shield_2.0/archive/master.zip>.
32
33Then uncompress the zip folder and rename the directory to "USB\_Host\_Shield\_20", as any special characters are not supported by the Arduino IDE.
34
35Now 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.
36Now move the "USB\_Host\_Shield\_20" directory to the "libraries" directory.
37
38The final structure should look like this:
39
40* Arduino/
41 * libraries/
42 * USB\_Host\_Shield\_20/
43
44Now quit the Arduino IDE and reopen it.
45
46Now 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.
47
48For more information visit the following site: <http://arduino.cc/en/Guide/Libraries>.
49
50# How to use the library
51
52### Documentation
53
54Documentation for the library can be found at the following link: <http://felis.github.com/USB_Host_Shield_2.0/>.
55
56### Enable debugging
57
58By default serial debugging is disabled. To turn it on simply change ```ENABLE_UHS_DEBUGGING``` to 1 in [settings.h](settings.h) like so:
59
60```C++
61#define ENABLE_UHS_DEBUGGING 1
62```
63
64### Boards
65
66Currently the following boards are supported by the library:
67
68* All official Arduino AVR boards (Uno, Duemilanove, Mega, Mega 2560, Mega ADK, Leonardo etc.)
69* Arduino Due
70 * If you are using the Arduino Due, then you must include the Arduino SPI library like so: ```#include <SPI.h>``` in your .ino file.
72 * 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.
73* Balanduino
74* Sanguino
75* Black Widdow
76
77The following boards need to be activated manually in [settings.h](settings.h):
78
79* Arduino Mega ADK
80 * If you are using Arduino 1.5.5 or newer there is no need to activate the Arduino Mega ADK manually
81* Black Widdow
82
83Simply set the corresponding value to 1 instead of 0.
84
85### [Bluetooth libraries](BTD.cpp)
86
87The [BTD library](BTD.cpp) is a general purpose library for an ordinary Bluetooth dongle.
88This 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.
89Some different examples can be found in the [example directory](examples/Bluetooth).
90
91The BTD library also makes it possible to use multiple services at once, the following example sketch is an example of this:
96The [Bluetooth HID library](BTHID.cpp) allows you to connect HID devices via Bluetooth to the USB Host Shield.
97
98Currently HID mice and keyboards are supported.
99
100It 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](examples/Bluetooth/BTHID/BTHID.ino) for more information.
101
102The [PS4 library](#ps4-library) also uses this class to handle all Bluetooth communication.
103
104For information see the following blog post: <http://blog.tkjelectronics.dk/2013/12/bluetooth-hid-devices-now-supported-by-the-usb-host-library/>.
105
106### [SPP library](SPP.cpp)
107
108SPP 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.
109It has been tested successfully on Windows, Mac OS X, Linux, and Android.
110
111Take a look at the [SPP.ino](examples/Bluetooth/SPP/SPP.ino) example for more information.
112
113More information can be found at these blog posts:
118To implement the SPP protocol I used a Bluetooth sniffing tool called [PacketLogger](http://www.tkjelectronics.com/uploads/PacketLogger.zip) developed by Apple.
119It enables me to see the Bluetooth communication between my Mac and any device.
120
121### PS4 Library
122
123The PS4BT library is split up into the [PS4BT](PS4BT.h) and the [PS4USB](PS4USB.h) library. These allow you to use the Sony PS4 controller via Bluetooth and USB.
124
125The [PS4BT.ino](examples/Bluetooth/PS4BT/PS4BT.ino) and [PS4USB.ino](examples/PS4USB/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 and get the battery level.
126
127Before you can use the PS4 controller via Bluetooth you will need to pair with it.
128
129Simply 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.
130
131It should then automatically pair the dongle with your controller. This only have to be done once.
132
133For information see the following blog post: <http://blog.tkjelectronics.dk/2014/01/ps4-controller-now-supported-by-the-usb-host-library/>.
134
135Also 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>.
136
137### PS3 Library
138
139These libraries consist of the [PS3BT](PS3BT.cpp) and [PS3USB](PS3USB.cpp). These libraries allows you to use a Dualshock 3, Navigation or a Motion controller with the USB Host Shield both via Bluetooth and USB.
140
141In 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.
142
143Finally 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.
144
145__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](examples/Bluetooth/PS3BT/PS3BT.ino#L20).
146
147For more information about the PS3 protocol see the official wiki: <https://github.com/felis/USB_Host_Shield_2.0/wiki/PS3-Information>.
1571. _Richard Ibbotson_ who made this excellent guide: <http://www.circuitsathome.com/mcu/ps3-and-wiimote-game-controllers-on-the-arduino-host-shield-part>
1582. _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>
159
160Also a big thanks all the people behind these sites about the Motion controller:
184The library support one Xbox 360 via USB or up to four Xbox 360 controllers wirelessly by using a [Xbox 360 wireless receiver](http://blog.tkjelectronics.dk/wp-content/uploads/xbox360-wireless-receiver.jpg).
185
186To use it via USB use the [XBOXUSB](XBOXUSB.cpp) library or to use it wirelessly use the [XBOXRECV](XBOXRECV.cpp) library.
187
188__Note that a Wireless controller can NOT be used via USB!__
189
190Examples code can be found in the [examples directory](examples/Xbox).
206The [Wii](Wii.cpp) library support the Wiimote, but also the Nunchuch and Motion Plus extensions via Bluetooth. The Wii U Pro Controller is also supported via Bluetooth.
207
208First you have to pair with the controller, this is done automatically by the library if you create the instance like so:
209
210```C++
211WII Wii(&Btd, PAIR);
212```
213
214And then press 1 & 2 at once on the Wiimote or press sync if you are using a Wii U Pro Controller.
215
216After that you can simply create the instance like so:
217
218```C++
219WII Wii(&Btd);
220```
221
222Then just press any button on the Wiimote and it will then connect to the dongle.
223
224Take a look at the example for more information: [Wii.ino](examples/Bluetooth/Wii/Wii.ino).
230The 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](settings.h).
231
232The [WiiIRCamera.ino](examples/Bluetooth/WiiIRCamera/WiiIRCamera.ino) example shows how it can be used.
233
234
235All the information about the Wii controllers are from these sites:
241* The old library created by _Tomoyuki Tanaka_: <https://github.com/moyuchin/WiiRemote_on_Arduino> also helped a lot.
242
243### [PS Buzz Library](PSBuzz.cpp)
244
245This library implements support for the Playstation Buzz controllers via USB.
246
247It is essentially just a wrapper around the [HIDUniversal](hiduniversal.cpp) which takes care of the initializing and reading of the controllers. The [PSBuzz](PSBuzz.cpp) class simply inherits this and parses the data, so it is easy for users to read the buttons and turn the big red button on the controllers on and off.
248
249The example [PSBuzz.ino](examples/PSBuzz/PSBuzz.ino) shows how one can do this with just a few lines of code.
250
251More information about the controller can be found at the following sites:
258> When I plug my device into the USB connector nothing happens?
259
260* Try to connect a external power supply to the Arduino - this solves the problem in most cases.
261* 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);```.