8 This is Revision 2.0 of MAX3421E-based USB Host Shield Library for AVR's.
9
10Project main web site is: <http://www.circuitsathome.com>.
11
12Some information can also be found at: <http://blog.tkjelectronics.dk/>.
13
14The 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>.
26 * 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
27* __Andrew Kroll__ - <xxxajk@gmail.com>
28 * Major contributor to mass storage code
29* __guruthree__
30 * [Xbox ONE](#xbox-one-library) controller support
32 * Developer of the [MIDI](#midi-library) library
33
34# Donate
35
36Help yourself by helping us support you! Many thousands of hours have been spent developing the USB Host Shield library. Since you find it useful, please consider donating via the button below. Donations will allow us to support you by ensuring hardware that you have can be acquired in order to add support for your microcontroller board.
37
38<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=donate@circuitsathome.com&lc=US&item_name=Donate%20to%20the%20USB%20Host%20Library%20project&no_note=0&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donate_LG%2egif%3aNonHostedGuest"><img src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" alt="PayPal - The safer, easier way to pay online!" /></a>
39
40# Table of Contents
41
42* [How to include the library](#how-to-include-the-library)
69First install Arduino IDE version 1.6.2 or newer, then simply use the Arduino Library Manager to install the library.
70
71Please see the following page for instructions: <http://www.arduino.cc/en/Guide/Libraries#toc3>.
72
73### Manual installation
74
75First download the library by clicking on the following link: <https://github.com/felis/USB_Host_Shield_2.0/archive/master.zip>.
76
77Then uncompress the zip folder and rename the directory to "USB\_Host\_Shield\_20", as any special characters are not supported by the Arduino IDE.
78
79Now 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.
80Now move the "USB\_Host\_Shield\_20" directory to the "libraries" directory.
81
82The final structure should look like this:
83
84* Arduino/
85 * libraries/
86 * USB\_Host\_Shield\_20/
87
88Now quit the Arduino IDE and reopen it.
89
90Now 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.
91
92For more information visit the following sites: <http://arduino.cc/en/Guide/Libraries> and <https://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use>.
93
94# How to use the library
95
96### Documentation
97
98Documentation for the library can be found at the following link: <https://felis.github.io/USB_Host_Shield_2.0/>.
99
100### Enable debugging
101
102By default serial debugging is disabled. To turn it on simply change ```ENABLE_UHS_DEBUGGING``` to 1 in [settings.h](settings.h) like so:
103
104```C++
105#define ENABLE_UHS_DEBUGGING 1
106```
107
108### Boards
109
110Currently the following boards are supported by the library:
111
112* All official Arduino AVR boards (Uno, Duemilanove, Mega, Mega 2560, Mega ADK, Leonardo etc.)
114 * Note that the Intel Galileo uses pin 2 and 3 as INT and SS pin respectively by default, so some modifications to the shield are needed. See the "Interface modifications" section in the [hardware manual](https://www.circuitsathome.com/usb-host-shield-hardware-manual) for more information.
115 * Note native USB host is not supported on any of these platforms. You will have to use the shield for now.
117 * 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.
125 * Currently the [NUCLEO-F446RE](http://www.st.com/web/catalog/tools/FM116/SC959/SS1532/LN1847/PF262063) is supported featuring the STM32F446. Take a look at the following example code: <https://github.com/Lauszus/Nucleo_F446RE_USBHost>.
126* ESP8266 is supported using the [ESP8266 Arduino core](https://github.com/esp8266/Arduino)
127 * Note it uses pin 15 and 5 for SS and INT respectively
128 * Also please be aware that:
129 * GPIO16 is **NOT** usable, as it will be used for some other purposes. For example, reset the SoC itself from sleep mode.
130 * GPIO6 to 11 is also **NOT** usable, as they are used to connect SPI flash chip and it is used for storing the executable binary content.
131* ESP32 is supported using the [arduino-esp32](https://github.com/espressif/arduino-esp32/)
134The following boards need to be activated manually in [settings.h](settings.h):
135
136* Arduino Mega ADK
137 * If you are using Arduino 1.5.5 or newer there is no need to activate the Arduino Mega ADK manually
138* Black Widdow
139
140Simply set the corresponding value to 1 instead of 0.
141
142### [Bluetooth libraries](BTD.cpp)
143
144The [BTD library](BTD.cpp) is a general purpose library for an ordinary Bluetooth dongle.
145This 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.
146Some different examples can be found in the [example directory](examples/Bluetooth).
147
148The BTD library also makes it possible to use multiple services at once, the following example sketch is an example of this:
153The [Bluetooth HID library](BTHID.cpp) allows you to connect HID devices via Bluetooth to the USB Host Shield.
154
155Currently HID mice and keyboards are supported.
156
157It 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.
158
159The [PS4 library](#ps4-library) also uses this class to handle all Bluetooth communication.
160
161For information see the following blog post: <http://blog.tkjelectronics.dk/2013/12/bluetooth-hid-devices-now-supported-by-the-usb-host-library/>.
162
163### [SPP library](SPP.cpp)
164
165SPP 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.
166It has been tested successfully on Windows, Mac OS X, Linux, and Android.
167
168Take a look at the [SPP.ino](examples/Bluetooth/SPP/SPP.ino) example for more information.
169
170More information can be found at these blog posts:
175To implement the SPP protocol I used a Bluetooth sniffing tool called [PacketLogger](http://www.tkjelectronics.com/uploads/PacketLogger.zip) developed by Apple.
176It enables me to see the Bluetooth communication between my Mac and any device.
177
178### PS4 Library
179
180The 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.
181
182The [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.
183
184Before you can use the PS4 controller via Bluetooth you will need to pair with it.
185
186Simply 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 pairing mode.
187
188It should then automatically pair the dongle with your controller. This only have to be done once.
189
190For information see the following blog post: <http://blog.tkjelectronics.dk/2014/01/ps4-controller-now-supported-by-the-usb-host-library/>.
191
192Also 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>.
193
194### PS3 Library
195
196These 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.
197
198In 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.
199
200Finally 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.
201
202__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).
203
204For more information about the PS3 protocol see the official wiki: <https://github.com/felis/USB_Host_Shield_2.0/wiki/PS3-Information>.
2141. _Richard Ibbotson_ who made this excellent guide: <http://www.circuitsathome.com/mcu/ps3-and-wiimote-game-controllers-on-the-arduino-host-shield-part>
2152. _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>
216
217Also a big thanks all the people behind these sites about the Motion controller:
241The 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).
242
243To use it via USB use the [XBOXUSB](XBOXUSB.cpp) library or to use it wirelessly use the [XBOXRECV](XBOXRECV.cpp) library.
244
245__Note that a Wireless controller can NOT be used via USB!__
246
247Examples code can be found in the [examples directory](examples/Xbox).
263An Xbox ONE controller is supported via USB in the [XBOXONE](XBOXONE.cpp) class. It is heavily based on the 360 library above. In addition to cross referencing the above, information on the protocol was found at:
271The [Wii](Wii.cpp) library support the Wiimote, but also the Nunchuch and Motion Plus extensions via Bluetooth. The Wii U Pro Controller and Wii Balance Board are also supported via Bluetooth.
272
273First you have to pair with the controller, this is done automatically by the library if you create the instance like so:
274
275```C++
276WII Wii(&Btd, PAIR);
277```
278
279And then press 1 & 2 at once on the Wiimote or the SYNC buttons if you are using a Wii U Pro Controller or a Wii Balance Board.
280
281After that you can simply create the instance like so:
282
283```C++
284WII Wii(&Btd);
285```
286
287Then just press any button on the Wiimote and it will then connect to the dongle.
288
289Take a look at the example for more information: [Wii.ino](examples/Bluetooth/Wii/Wii.ino).
295The 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).
296
297The [WiiIRCamera.ino](examples/Bluetooth/WiiIRCamera/WiiIRCamera.ino) example shows how it can be used.
298
299All the information about the Wii controllers are from these sites:
306* The old library created by _Tomoyuki Tanaka_: <https://github.com/moyuchin/WiiRemote_on_Arduino> also helped a lot.
307
308### [PS Buzz Library](PSBuzz.cpp)
309
310This library implements support for the Playstation Buzz controllers via USB.
311
312It 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.
313
314The example [PSBuzz.ino](examples/PSBuzz/PSBuzz.ino) shows how one can do this with just a few lines of code.
315
316More information about the controller can be found at the following sites:
323HID devices are also supported by the library. However these require you to write your own driver. A few example are provided in the [examples/HID](examples/HID) directory. Including an example for the [SteelSeries SRW-S1 Steering Wheel](examples/HID/SRWS1/SRWS1.ino).
324
325### [MIDI Library](usbh_midi.cpp)
326
327The library support MIDI devices.
328You can convert USB MIDI keyboard to legacy serial MIDI.
333For information see the following page: <http://yuuichiakagawa.github.io/USBH_MIDI/>.
334
335# Interface modifications
336
337The shield is using SPI for communicating with the MAX3421E USB host controller. It uses the SCK, MISO and MOSI pins via the ICSP on your board.
338
339Note this means that it uses pin 13, 12, 11 on an Arduino Uno, so these pins can not be used for anything else than SPI communication!
340
341Furthermore it uses one pin as SS and one INT pin. These are by default located on pin 10 and 9 respectively. They can easily be reconfigured in case you need to use them for something else by cutting the jumper on the shield and then solder a wire from the pad to the new pin.
342
343After that you need modify the following entry in [UsbCore.h](UsbCore.h):
344
345```C++
346typedef MAX3421e<P10, P9> MAX3421E;
347```
348
349For instance if you have rerouted SS to pin 7 it should read:
350
351```C++
352typedef MAX3421e<P7, P9> MAX3421E;
353```
354
355See the "Interface modifications" section in the [hardware manual](https://www.circuitsathome.com/usb-host-shield-hardware-manual) for more information.
356
357# FAQ
358
359> When I plug my device into the USB connector nothing happens?
360
361* Try to connect a external power supply to the Arduino - this solves the problem in most cases.
362* 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);```.
363
364> When I connecting my PS3 controller I get a output like this:
376* This means that your dongle does not support 2.0+EDR, so you will need another dongle. Please see the following [list](https://github.com/felis/USB_Host_Shield_2.0/wiki/Bluetooth-dongles) for tested working dongles.
377
378> When compiling I am getting the following error: "fatal error: SPI.h: No such file or directory".
379
380* Please make sure to include the SPI library like so: ```#include <SPI.h>``` in your .ino file.