protocol/usb_hid/USB_Host_Shield_2.0/README.md

   1 # USB Host Library Rev.2.0
   2
   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
   9 Project main web site is: <http://www.circuitsathome.com>.
  10
  11 Some information can also be found at: <http://blog.tkjelectronics.dk/>.
  12
  13 The 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>.
  14
  15 ![USB Host Shield](http://shop.tkjelectronics.dk/images/USB_Host_Shield1.jpg)
  16
  17 For more information about the hardware see the [Hardware Manual](http://www.circuitsathome.com/usb-host-shield-hardware-manual).
  18
  19 # Developed By
  20
  21 * __Oleg Mazurov, Circuits@Home__ - <mazurov@circuitsathome.com>
  22 * __Alexei Glushchenko, Circuits@Home__ - <alex-gl@mail.ru>
  23     * Developers of the USB Core, HID, FTDI, ADK, ACM, and PL2303 libraries
  24 * __Kristian Lauszus, TKJ Electronics__ - <kristianl@tkjelectronics.com>
  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 * __guruthree__
  29     * [Xbox ONE](#xbox-one-library) controller support
  30
  31 # Donate
  32
  33 Help 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.
  34
  35 <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&amp;business=donate@circuitsathome.com&amp;lc=US&amp;item_name=Donate%20to%20the%20USB%20Host%20Library%20project&amp;no_note=0&amp;currency_code=USD&amp;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>
  36
  37 # Table of Contents
  38
  39 * [How to include the library](#how-to-include-the-library)
  40     * [Arduino Library Manager](#arduino-library-manager)
  41     * [Manual installation](#manual-installation)
  42 * [How to use the library](#how-to-use-the-library)
  43     * [Documentation](#documentation)
  44     * [Enable debugging](#enable-debugging)
  45     * [Boards](#boards)
  46     * [Bluetooth libraries](#bluetooth-libraries)
  47     * [BTHID library](#bthid-library)
  48     * [SPP library](#spp-library)
  49     * [PS4 Library](#ps4-library)
  50     * [PS3 Library](#ps3-library)
  51     * [Xbox Libraries](#xbox-libraries)
  52         * [Xbox library](#xbox-library)
  53         * [Xbox 360 Library](#xbox-360-library)
  54         * [Xbox ONE Library](#xbox-one-library)
  55     * [Wii library](#wii-library)
  56     * [PS Buzz Library](#ps-buzz-library)
  57 * [Interface modifications](#interface-modifications)
  58 * [FAQ](#faq)
  59
  60 # How to include the library
  61
  62 ### Arduino Library Manager
  63
  64 First install Arduino IDE version 1.6.2 or newer, then simply use the Arduino Library Manager to install the library.
  65
  66 Please see the following page for instructions: <http://www.arduino.cc/en/Guide/Libraries#toc3>.
  67
  68 ### Manual installation
  69
  70 First download the library by clicking on the following link: <https://github.com/felis/USB_Host_Shield_2.0/archive/master.zip>.
  71
  72 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.
  73
  74 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.
  75 Now move the "USB\_Host\_Shield\_20" directory to the "libraries" directory.
  76
  77 The final structure should look like this:
  78
  79 * Arduino/
  80     * libraries/
  81         * USB\_Host\_Shield\_20/
  82
  83 Now quit the Arduino IDE and reopen it.
  84
  85 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.
  86
  87 For more information visit the following sites: <http://arduino.cc/en/Guide/Libraries> and <https://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use>.
  88
  89 # How to use the library
  90
  91 ### Documentation
  92
  93 Documentation for the library can be found at the following link: <http://felis.github.com/USB_Host_Shield_2.0/>.
  94
  95 ### Enable debugging
  96
  97 By default serial debugging is disabled. To turn it on simply change ```ENABLE_UHS_DEBUGGING``` to 1 in [settings.h](settings.h) like so:
  98
  99 ```C++
 100 #define ENABLE_UHS_DEBUGGING 1
 101 ```
 102
 103 ### Boards
 104
 105 Currently the following boards are supported by the library:
 106
 107 * All official Arduino AVR boards (Uno, Duemilanove, Mega, Mega 2560, Mega ADK, Leonardo etc.)
 108 * Arduino Due, Intel Galileo, Intel Galileo 2, and Intel Edison
 109     * 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.
 110 * Teensy (Teensy++ 1.0, Teensy 2.0, Teensy++ 2.0, and Teensy 3.x)
 111     * 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.
 112 * Balanduino
 113 * Sanguino
 114 * Black Widdow
 115 * RedBearLab nRF51822
 116 * Digilent chipKIT
 117     * Please see: <http://www.circuitsathome.com/mcu/usb/running-usb-host-code-on-digilent-chipkit-board>.
 118
 119 The following boards need to be activated manually in [settings.h](settings.h):
 120
 121 * Arduino Mega ADK
 122     * If you are using Arduino 1.5.5 or newer there is no need to activate the Arduino Mega ADK manually
 123 * Black Widdow
 124
 125 Simply set the corresponding value to 1 instead of 0.
 126
 127 ### [Bluetooth libraries](BTD.cpp)
 128
 129 The [BTD library](BTD.cpp) is a general purpose library for an ordinary Bluetooth dongle.
 130 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.
 131 Some different examples can be found in the [example directory](examples/Bluetooth).
 132
 133 The BTD library also makes it possible to use multiple services at once, the following example sketch is an example of this:
 134 [PS3SPP.ino](examples/Bluetooth/PS3SPP/PS3SPP.ino).
 135
 136 ### [BTHID library](BTHID.cpp)
 137
 138 The [Bluetooth HID library](BTHID.cpp) allows you to connect HID devices via Bluetooth to the USB Host Shield.
 139
 140 Currently HID mice and keyboards are supported.
 141
 142 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](examples/Bluetooth/BTHID/BTHID.ino) for more information.
 143
 144 The [PS4 library](#ps4-library) also uses this class to handle all Bluetooth communication.
 145
 146 For information see the following blog post: <http://blog.tkjelectronics.dk/2013/12/bluetooth-hid-devices-now-supported-by-the-usb-host-library/>.
 147
 148 ### [SPP library](SPP.cpp)
 149
 150 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.
 151 It has been tested successfully on Windows, Mac OS X, Linux, and Android.
 152
 153 Take a look at the [SPP.ino](examples/Bluetooth/SPP/SPP.ino) example for more information.
 154
 155 More information can be found at these blog posts:
 156
 157 * <http://www.circuitsathome.com/mcu/bluetooth-rfcommspp-service-support-for-usb-host-2-0-library-released>
 158 * <http://blog.tkjelectronics.dk/2012/07/rfcommspp-library-for-arduino/>
 159
 160 To implement the SPP protocol I used a Bluetooth sniffing tool called [PacketLogger](http://www.tkjelectronics.com/uploads/PacketLogger.zip) developed by Apple.
 161 It enables me to see the Bluetooth communication between my Mac and any device.
 162
 163 ### PS4 Library
 164
 165 The 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.
 166
 167 The [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.
 168
 169 Before you can use the PS4 controller via Bluetooth you will need to pair with it.
 170
 171 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.
 172
 173 It should then automatically pair the dongle with your controller. This only have to be done once.
 174
 175 For information see the following blog post: <http://blog.tkjelectronics.dk/2014/01/ps4-controller-now-supported-by-the-usb-host-library/>.
 176
 177 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>.
 178
 179 ### PS3 Library
 180
 181 These 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.
 182
 183 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.
 184
 185 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.
 186
 187 __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).
 188
 189 For more information about the PS3 protocol see the official wiki: <https://github.com/felis/USB_Host_Shield_2.0/wiki/PS3-Information>.
 190
 191 Also take a look at the blog posts:
 192
 193 * <http://blog.tkjelectronics.dk/2012/01/ps3-controller-bt-library-for-arduino/>
 194 * <http://www.circuitsathome.com/mcu/sony-ps3-controller-support-added-to-usb-host-library>
 195 * <http://www.circuitsathome.com/mcu/arduino/interfacing-ps3-controllers-via-usb>
 196
 197 A special thanks go to the following people:
 198
 199 1. _Richard Ibbotson_ who made this excellent guide: <http://www.circuitsathome.com/mcu/ps3-and-wiimote-game-controllers-on-the-arduino-host-shield-part>
 200 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>
 201
 202 Also a big thanks all the people behind these sites about the Motion controller:
 203
 204 * <http://thp.io/2010/psmove/>
 205 * <http://www.copenhagengamecollective.org/unimove/>
 206 * <https://github.com/thp/psmoveapi>
 207 * <http://code.google.com/p/moveonpc/>
 208
 209 ### Xbox Libraries
 210
 211 The library supports both the original Xbox controller via USB and the Xbox 360 controller both via USB and wirelessly.
 212
 213 #### Xbox library
 214
 215 The [XBOXOLD](XBOXOLD.cpp) class implements support for the original Xbox controller via USB.
 216
 217 All the information are from the following sites:
 218
 219 * <https://github.com/torvalds/linux/blob/master/Documentation/input/xpad.txt>
 220 * <https://github.com/torvalds/linux/blob/master/drivers/input/joystick/xpad.c>
 221 * <http://euc.jp/periphs/xbox-controller.ja.html>
 222 * <https://github.com/Grumbel/xboxdrv/blob/master/PROTOCOL#L15>
 223
 224 #### Xbox 360 Library
 225
 226 The 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).
 227
 228 To use it via USB use the [XBOXUSB](XBOXUSB.cpp) library or to use it wirelessly use the [XBOXRECV](XBOXRECV.cpp) library.
 229
 230 __Note that a Wireless controller can NOT be used via USB!__
 231
 232 Examples code can be found in the [examples directory](examples/Xbox).
 233
 234 Also see the following blog posts:
 235
 236 * <http://www.circuitsathome.com/mcu/xbox360-controller-support-added-to-usb-host-shield-2-0-library>
 237 * <http://blog.tkjelectronics.dk/2012/07/xbox-360-controller-support-added-to-the-usb-host-library/>
 238 * <http://blog.tkjelectronics.dk/2012/12/xbox-360-receiver-added-to-the-usb-host-library/>
 239
 240 All the information regarding the Xbox 360 controller protocol are form these sites:
 241
 242 * <http://tattiebogle.net/index.php/ProjectRoot/Xbox360Controller/UsbInfo>
 243 * <http://tattiebogle.net/index.php/ProjectRoot/Xbox360Controller/WirelessUsbInfo>
 244 * <https://github.com/Grumbel/xboxdrv/blob/master/PROTOCOL>
 245
 246 #### Xbox ONE Library
 247
 248 An 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:
 249
 250 * <https://github.com/quantus/xbox-one-controller-protocol>
 251 * <https://github.com/torvalds/linux/blob/master/drivers/input/joystick/xpad.c>
 252 * <https://github.com/kylelemons/xbox/blob/master/xbox.go>
 253
 254 ### [Wii library](Wii.cpp)
 255
 256 The [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.
 257
 258 First you have to pair with the controller, this is done automatically by the library if you create the instance like so:
 259
 260 ```C++
 261 WII Wii(&Btd, PAIR);
 262 ```
 263
 264 And 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.
 265
 266 After that you can simply create the instance like so:
 267
 268 ```C++
 269 WII Wii(&Btd);
 270 ```
 271
 272 Then just press any button on the Wiimote and it will then connect to the dongle.
 273
 274 Take a look at the example for more information: [Wii.ino](examples/Bluetooth/Wii/Wii.ino).
 275
 276 Also take a look at the blog post:
 277
 278 * <http://blog.tkjelectronics.dk/2012/08/wiimote-added-to-usb-host-library/>
 279
 280 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](settings.h).
 281
 282 The [WiiIRCamera.ino](examples/Bluetooth/WiiIRCamera/WiiIRCamera.ino) example shows how it can be used.
 283
 284 All the information about the Wii controllers are from these sites:
 285
 286 * <http://wiibrew.org/wiki/Wiimote>
 287 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers>
 288 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Nunchuck>
 289 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Wii_Motion_Plus>
 290 * <http://wiibrew.org/wiki/Wii_Balance_Board>
 291 * The old library created by _Tomoyuki Tanaka_: <https://github.com/moyuchin/WiiRemote_on_Arduino> also helped a lot.
 292
 293 ### [PS Buzz Library](PSBuzz.cpp)
 294
 295 This library implements support for the Playstation Buzz controllers via USB.
 296
 297 It 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.
 298
 299 The example [PSBuzz.ino](examples/PSBuzz/PSBuzz.ino) shows how one can do this with just a few lines of code.
 300
 301 More information about the controller can be found at the following sites:
 302
 303 * http://www.developerfusion.com/article/84338/making-usb-c-friendly/
 304 * https://github.com/torvalds/linux/blob/master/drivers/hid/hid-sony.c
 305
 306 # Interface modifications
 307
 308 The 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.
 309
 310 Note 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!
 311
 312 Furthermore 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.
 313
 314 After that you need modify the following entry in [UsbCore.h](UsbCore.h):
 315
 316 ```C++
 317 typedef MAX3421e<P10, P9> MAX3421E;
 318 ```
 319
 320 For instance if you have rerouted SS to pin 7 it should read:
 321
 322 ```C++
 323 typedef MAX3421e<P7, P9> MAX3421E;
 324 ```
 325
 326 See the "Interface modifications" section in the [hardware manual](https://www.circuitsathome.com/usb-host-shield-hardware-manual) for more information.
 327
 328 # FAQ
 329
 330 > When I plug my device into the USB connector nothing happens?
 331
 332 * Try to connect a external power supply to the Arduino - this solves the problem in most cases.
 333 * 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);```.
 334
 335 > When I connecting my PS3 controller I get a output like this:
 336
 337 ```
 338 Dualshock 3 Controller Enabled
 339
 340 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
 341 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
 342 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
 343 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
 344 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
 345 ```
 346
 347 * 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.
 348
 349 > When compiling I am getting the following error: "fatal error: SPI.h: No such file or directory".
 350
 351 * Please make sure to include the SPI library like so: ```#include <SPI.h>``` in your .ino file.