diff --git a/_r_e_a_d_m_e_8md_source.html b/_r_e_a_d_m_e_8md_source.html index 1e7d0a36..3cdd8d77 100644 --- a/_r_e_a_d_m_e_8md_source.html +++ b/_r_e_a_d_m_e_8md_source.html @@ -86,7 +86,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search');
README.md
-Go to the documentation of this file.
1 # USB Host Library Rev.2.0
2 
3 The code is released under the GNU General Public License.
4 __________
5 [![Build Status](https://travis-ci.org/felis/USB_Host_Shield_2.0.svg?branch=master)](https://travis-ci.org/felis/USB_Host_Shield_2.0)
6 
7 # Summary
8 This is Revision 2.0 of MAX3421E-based USB Host Shield Library for AVR's.
9 
10 Project main web site is: <https://chome.nerpa.tech/arduino_usb_host_shield_projects/>.
11 
12 Some information can also be found at: <http://blog.tkjelectronics.dk/>.
13 
14 The shield can be purchased from [TKJ Electronics](http://tkjelectronics.com/): <http://shop.tkjelectronics.dk/product_info.php?products_id=43>.
15 
16 ![USB Host Shield](http://shop.tkjelectronics.dk/images/USB_Host_Shield1.jpg)
17 
18 For more information about the hardware see the [Hardware Manual](https://chome.nerpa.tech/usb-host-shield-hardware-manual/).
19 
20 # Developed By
21 
22 * __Oleg Mazurov - <mazurov@gmail.com>
23 * __Alexei Glushchenko, Circuits\@Home__ - <alex-gl@mail.ru>
24  * Developers of the USB Core, HID, FTDI, ADK, ACM, and PL2303 libraries
25 * __Kristian Lauszus, TKJ Electronics__ - <kristianl@tkjelectronics.com>
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
31 * __Yuuichi Akagawa__ - [\@YuuichiAkagawa](https://twitter.com/yuuichiakagawa)
32  * Developer of the [MIDI](#midi-library) library
33 
34 
35 # Table of Contents
36 
37 * [How to include the library](#how-to-include-the-library)
38  * [Arduino Library Manager](#arduino-library-manager)
39  * [Manual installation](#manual-installation)
40 * [How to use the library](#how-to-use-the-library)
41  * [Documentation](#documentation)
42  * [Enable debugging](#enable-debugging)
43  * [Boards](#boards)
44  * [Bluetooth libraries](#bluetooth-libraries)
45  * [BTHID library](#bthid-library)
46  * [SPP library](#spp-library)
47  * [PS4 Library](#ps4-library)
48  * [PS3 Library](#ps3-library)
49  * [Xbox Libraries](#xbox-libraries)
50  * [Xbox library](#xbox-library)
51  * [Xbox 360 Library](#xbox-360-library)
52  * [Xbox ONE Library](#xbox-one-library)
53  * [Wii library](#wii-library)
54  * [PS Buzz Library](#ps-buzz-library)
55  * [HID Libraries](#hid-libraries)
56  * [MIDI Library](#midi-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: <https://felis.github.io/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://chome.nerpa.tech/usb-host-shield-hardware-manual) for more information.
110  * Note native USB host is not supported on any of these platforms. You will have to use the shield for now.
111 * Teensy (Teensy++ 1.0, Teensy 2.0, Teensy++ 2.0, Teensy 3.x, and Teensy LC)
112  * 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.
113 * Balanduino
114 * Sanguino
115 * Black Widdow
116 * RedBearLab nRF51822
117 * Digilent chipKIT
118  * Please see: <https://chome.nerpa.tech/mcu/usb/running-usb-host-code-on-digilent-chipkit-board>.
119 * STM32F4
120  * 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>.
121 * ESP8266 is supported using the [ESP8266 Arduino core](https://github.com/esp8266/Arduino)
122  * Note it uses pin 15 and 5 for SS and INT respectively
123  * Also please be aware that:
124  * GPIO16 is **NOT** usable, as it will be used for some other purposes. For example, reset the SoC itself from sleep mode.
125  * 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.
126 * ESP32 is supported using the [arduino-esp32](https://github.com/espressif/arduino-esp32/)
127  * GPIO5 : SS, GPIO17 : INT, GPIO18 : SCK, GPIO19 : MISO, GPIO23 : MOSI
128 
129 The following boards need to be activated manually in [settings.h](settings.h):
130 
131 * Arduino Mega ADK
132  * If you are using Arduino 1.5.5 or newer there is no need to activate the Arduino Mega ADK manually
133 * Black Widdow
134 
135 Simply set the corresponding value to 1 instead of 0.
136 
137 ### [Bluetooth libraries](BTD.cpp)
138 
139 The [BTD library](BTD.cpp) is a general purpose library for an ordinary Bluetooth dongle.
140 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.
141 Some different examples can be found in the [example directory](examples/Bluetooth).
142 
143 The BTD library also makes it possible to use multiple services at once, the following example sketch is an example of this:
144 [PS3SPP.ino](examples/Bluetooth/PS3SPP/PS3SPP.ino).
145 
146 ### [BTHID library](BTHID.cpp)
147 
148 The [Bluetooth HID library](BTHID.cpp) allows you to connect HID devices via Bluetooth to the USB Host Shield.
149 
150 Currently HID mice and keyboards are supported.
151 
152 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.
153 
154 The [PS4 library](#ps4-library) also uses this class to handle all Bluetooth communication.
155 
156 For information see the following blog post: <http://blog.tkjelectronics.dk/2013/12/bluetooth-hid-devices-now-supported-by-the-usb-host-library/>.
157 
158 ### [SPP library](SPP.cpp)
159 
160 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.
161 It has been tested successfully on Windows, Mac OS X, Linux, and Android.
162 
163 Take a look at the [SPP.ino](examples/Bluetooth/SPP/SPP.ino) example for more information.
164 
165 More information can be found at these blog posts:
166 
167 * <http://chome.nerpa.tech/mcu/bluetooth-rfcommspp-service-support-for-usb-host-2-0-library-released>
168 * <http://blog.tkjelectronics.dk/2012/07/rfcommspp-library-for-arduino/>
169 
170 To implement the SPP protocol I used a Bluetooth sniffing tool called [PacketLogger](http://www.tkjelectronics.com/uploads/PacketLogger.zip) developed by Apple.
171 It enables me to see the Bluetooth communication between my Mac and any device.
172 
173 ### PS4 Library
174 
175 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.
176 
177 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.
178 
179 Before you can use the PS4 controller via Bluetooth you will need to pair with it.
180 
181 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 pairing mode.
182 
183 It should then automatically pair the dongle with your controller. This only have to be done once.
184 
185 For information see the following blog post: <http://blog.tkjelectronics.dk/2014/01/ps4-controller-now-supported-by-the-usb-host-library/>.
186 
187 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>.
188 
189 Several guides on how to use the PS4 library has been written by Dr. James E. Barger and are available at the following link: <https://sites.google.com/view/vbatc-engineeringtechnology2/control-system-tutorials/ps4-tutorials>.
190 
191 ### PS3 Library
192 
193 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.
194 
195 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.
196 
197 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.
198 
199 __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).
200 
201 For more information about the PS3 protocol see the official wiki: <https://github.com/felis/USB_Host_Shield_2.0/wiki/PS3-Information>.
202 
203 Also take a look at the blog posts:
204 
205 * <http://blog.tkjelectronics.dk/2012/01/ps3-controller-bt-library-for-arduino/>
206 * <http://chome.nerpa.tech/mcu/sony-ps3-controller-support-added-to-usb-host-library>
207 * <http://www.circuitsathome.com/mcu/arduino/interfacing-ps3-controllers-via-usb>
208 
209 A special thanks go to the following people:
210 
211 1. _Richard Ibbotson_ who made this excellent guide: <http://www.circuitsathome.com/mcu/ps3-and-wiimote-game-controllers-on-the-arduino-host-shield-part>
212 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>
213 
214 Also a big thanks all the people behind these sites about the Motion controller:
215 
216 * <http://thp.io/2010/psmove/>
217 * <http://www.copenhagengamecollective.org/unimove/>
218 * <https://github.com/thp/psmoveapi>
219 * <http://code.google.com/p/moveonpc/>
220 
221 ### Xbox Libraries
222 
223 The library supports both the original Xbox controller via USB and the Xbox 360 controller both via USB and wirelessly.
224 
225 #### Xbox library
226 
227 The [XBOXOLD](XBOXOLD.cpp) class implements support for the original Xbox controller via USB.
228 
229 All the information are from the following sites:
230 
231 * <https://github.com/torvalds/linux/blob/master/Documentation/input/xpad.txt>
232 * <https://github.com/torvalds/linux/blob/master/drivers/input/joystick/xpad.c>
233 * <http://euc.jp/periphs/xbox-controller.ja.html>
234 * <https://github.com/Grumbel/xboxdrv/blob/master/PROTOCOL#L15>
235 
236 #### Xbox 360 Library
237 
238 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).
239 
240 To use it via USB use the [XBOXUSB](XBOXUSB.cpp) library or to use it wirelessly use the [XBOXRECV](XBOXRECV.cpp) library.
241 
242 __Note that a Wireless controller can NOT be used via USB!__
243 
244 Examples code can be found in the [examples directory](examples/Xbox).
245 
246 Also see the following blog posts:
247 
248 * <http://www.circuitsathome.com/mcu/xbox360-controller-support-added-to-usb-host-shield-2-0-library>
249 * <http://blog.tkjelectronics.dk/2012/07/xbox-360-controller-support-added-to-the-usb-host-library/>
250 * <http://blog.tkjelectronics.dk/2012/12/xbox-360-receiver-added-to-the-usb-host-library/>
251 
252 All the information regarding the Xbox 360 controller protocol are form these sites:
253 
254 * <http://tattiebogle.net/index.php/ProjectRoot/Xbox360Controller/UsbInfo>
255 * <http://tattiebogle.net/index.php/ProjectRoot/Xbox360Controller/WirelessUsbInfo>
256 * <https://github.com/Grumbel/xboxdrv/blob/master/PROTOCOL>
257 
258 #### Xbox ONE Library
259 
260 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:
261 
262 * <https://github.com/quantus/xbox-one-controller-protocol>
263 * <https://github.com/torvalds/linux/blob/master/drivers/input/joystick/xpad.c>
264 * <https://github.com/kylelemons/xbox/blob/master/xbox.go>
265 
266 ### [Wii library](Wii.cpp)
267 
268 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.
269 
270 First you have to pair with the controller, this is done automatically by the library if you create the instance like so:
271 
272 ```C++
273 WII Wii(&Btd, PAIR);
274 ```
275 
276 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.
277 
278 After that you can simply create the instance like so:
279 
280 ```C++
281 WII Wii(&Btd);
282 ```
283 
284 Then just press any button on the Wiimote and it will then connect to the dongle.
285 
286 Take a look at the example for more information: [Wii.ino](examples/Bluetooth/Wii/Wii.ino).
287 
288 Also take a look at the blog post:
289 
290 * <http://blog.tkjelectronics.dk/2012/08/wiimote-added-to-usb-host-library/>
291 
292 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).
293 
294 The [WiiIRCamera.ino](examples/Bluetooth/WiiIRCamera/WiiIRCamera.ino) example shows how it can be used.
295 
296 All the information about the Wii controllers are from these sites:
297 
298 * <http://wiibrew.org/wiki/Wiimote>
299 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers>
300 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Nunchuck>
301 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Wii_Motion_Plus>
302 * <http://wiibrew.org/wiki/Wii_Balance_Board>
303 * The old library created by _Tomoyuki Tanaka_: <https://github.com/moyuchin/WiiRemote_on_Arduino> also helped a lot.
304 
305 ### [PS Buzz Library](PSBuzz.cpp)
306 
307 This library implements support for the Playstation Buzz controllers via USB.
308 
309 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.
310 
311 The example [PSBuzz.ino](examples/PSBuzz/PSBuzz.ino) shows how one can do this with just a few lines of code.
312 
313 More information about the controller can be found at the following sites:
314 
315 * http://www.developerfusion.com/article/84338/making-usb-c-friendly/
316 * https://github.com/torvalds/linux/blob/master/drivers/hid/hid-sony.c
317 
318 ### HID Libraries
319 
320 HID 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).
321 
322 ### [MIDI Library](usbh_midi.cpp)
323 
324 The library support MIDI devices.
325 You can convert USB MIDI keyboard to legacy serial MIDI.
326 
327 * [USB_MIDI_converter.ino](examples/USBH_MIDI/USB_MIDI_converter/USB_MIDI_converter.ino)
328 * [USB_MIDI_converter_multi.ino](examples/USBH_MIDI/USB_MIDI_converter_multi/USB_MIDI_converter_multi.ino)
329 
330 For information see the following page: <http://yuuichiakagawa.github.io/USBH_MIDI/>.
331 
332 # Interface modifications
333 
334 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.
335 
336 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!
337 
338 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.
339 
340 After that you need modify the following entry in [UsbCore.h](UsbCore.h):
341 
342 ```C++
343 typedef MAX3421e<P10, P9> MAX3421E;
344 ```
345 
346 For instance if you have rerouted SS to pin 7 it should read:
347 
348 ```C++
349 typedef MAX3421e<P7, P9> MAX3421E;
350 ```
351 
352 See the "Interface modifications" section in the [hardware manual](https://www.circuitsathome.com/usb-host-shield-hardware-manual) for more information.
353 
354 # FAQ
355 
356 > When I plug my device into the USB connector nothing happens?
357 
358 * Try to connect a external power supply to the Arduino - this solves the problem in most cases.
359 * 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);```.
360 
361 > When I connecting my PS3 controller I get a output like this:
362 
363 ```
364 Dualshock 3 Controller Enabled
365 
366 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
367 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
368 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
369 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
370 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
371 ```
372 
373 * 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.
374 
375 > When compiling I am getting the following error: "fatal error: SPI.h: No such file or directory".
376 
377 * Please make sure to include the SPI library like so: ```#include <SPI.h>``` in your .ino file.
+Go to the documentation of this file.
1 # USB Host Library Rev.2.0
2 
3 The code is released under the GNU General Public License.
4 __________
5 [![Build Status](https://travis-ci.org/felis/USB_Host_Shield_2.0.svg?branch=master)](https://travis-ci.org/felis/USB_Host_Shield_2.0)
6 
7 # Summary
8 This is Revision 2.0 of MAX3421E-based USB Host Shield Library for AVR's.
9 
10 Project main web site is: <https://chome.nerpa.tech/arduino_usb_host_shield_projects/>.
11 
12 Some information can also be found at: <http://blog.tkjelectronics.dk/>.
13 
14 The shield can be purchased from [TKJ Electronics](http://tkjelectronics.com/): <http://shop.tkjelectronics.dk/product_info.php?products_id=43>.
15 
16 ![USB Host Shield](http://shop.tkjelectronics.dk/images/USB_Host_Shield1.jpg)
17 
18 For more information about the hardware see the [Hardware Manual](https://chome.nerpa.tech/usb-host-shield-hardware-manual/).
19 
20 # Developed By
21 
22 * __Oleg Mazurov - <mazurov@gmail.com>
23 * __Alexei Glushchenko, Circuits\@Home__ - <alex-gl@mail.ru>
24  * Developers of the USB Core, HID, FTDI, ADK, ACM, and PL2303 libraries
25 * __Kristian Lauszus, TKJ Electronics__ - <kristianl@tkjelectronics.com>
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
31 * __Yuuichi Akagawa__ - [\@YuuichiAkagawa](https://twitter.com/yuuichiakagawa)
32  * Developer of the [MIDI](#midi-library) library
33 
34 
35 # Table of Contents
36 
37 * [How to include the library](#how-to-include-the-library)
38  * [Arduino Library Manager](#arduino-library-manager)
39  * [Manual installation](#manual-installation)
40 * [How to use the library](#how-to-use-the-library)
41  * [Documentation](#documentation)
42  * [Enable debugging](#enable-debugging)
43  * [Boards](#boards)
44  * [Bluetooth libraries](#bluetooth-libraries)
45  * [BTHID library](#bthid-library)
46  * [SPP library](#spp-library)
47  * [PS4 Library](#ps4-library)
48  * [PS3 Library](#ps3-library)
49  * [Xbox Libraries](#xbox-libraries)
50  * [Xbox library](#xbox-library)
51  * [Xbox 360 Library](#xbox-360-library)
52  * [Xbox ONE Library](#xbox-one-library)
53  * [Wii library](#wii-library)
54  * [PS Buzz Library](#ps-buzz-library)
55  * [HID Libraries](#hid-libraries)
56  * [MIDI Library](#midi-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: <https://felis.github.io/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://chome.nerpa.tech/usb-host-shield-hardware-manual) for more information.
110  * Note native USB host is not supported on any of these platforms. You will have to use the shield for now.
111 * Teensy (Teensy++ 1.0, Teensy 2.0, Teensy++ 2.0, Teensy 3.x, and Teensy LC)
112  * 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.
113 * Balanduino
114 * Sanguino
115 * Black Widdow
116 * RedBearLab nRF51822
117 * Digilent chipKIT
118  * Please see: <https://chome.nerpa.tech/mcu/usb/running-usb-host-code-on-digilent-chipkit-board>.
119 * STM32F4
120  * 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>.
121 * ESP8266 is supported using the [ESP8266 Arduino core](https://github.com/esp8266/Arduino)
122  * Note it uses pin 15 and 5 for SS and INT respectively
123  * Also please be aware that:
124  * GPIO16 is **NOT** usable, as it will be used for some other purposes. For example, reset the SoC itself from sleep mode.
125  * 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.
126 * ESP32 is supported using the [arduino-esp32](https://github.com/espressif/arduino-esp32/)
127  * GPIO5 : SS, GPIO17 : INT, GPIO18 : SCK, GPIO19 : MISO, GPIO23 : MOSI
128 
129 The following boards need to be activated manually in [settings.h](settings.h):
130 
131 * Arduino Mega ADK
132  * If you are using Arduino 1.5.5 or newer there is no need to activate the Arduino Mega ADK manually
133 * Black Widdow
134 
135 Simply set the corresponding value to 1 instead of 0.
136 
137 ### [Bluetooth libraries](BTD.cpp)
138 
139 The [BTD library](BTD.cpp) is a general purpose library for an ordinary Bluetooth dongle.
140 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.
141 Some different examples can be found in the [example directory](examples/Bluetooth).
142 
143 The BTD library also makes it possible to use multiple services at once, the following example sketch is an example of this:
144 [PS3SPP.ino](examples/Bluetooth/PS3SPP/PS3SPP.ino).
145 
146 ### [BTHID library](BTHID.cpp)
147 
148 The [Bluetooth HID library](BTHID.cpp) allows you to connect HID devices via Bluetooth to the USB Host Shield.
149 
150 Currently HID mice and keyboards are supported.
151 
152 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.
153 
154 The [PS4 library](#ps4-library) also uses this class to handle all Bluetooth communication.
155 
156 For information see the following blog post: <http://blog.tkjelectronics.dk/2013/12/bluetooth-hid-devices-now-supported-by-the-usb-host-library/>.
157 
158 ### [SPP library](SPP.cpp)
159 
160 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.
161 It has been tested successfully on Windows, Mac OS X, Linux, and Android.
162 
163 Take a look at the [SPP.ino](examples/Bluetooth/SPP/SPP.ino) example for more information.
164 
165 More information can be found at these blog posts:
166 
167 * <http://chome.nerpa.tech/mcu/bluetooth-rfcommspp-service-support-for-usb-host-2-0-library-released>
168 * <http://blog.tkjelectronics.dk/2012/07/rfcommspp-library-for-arduino/>
169 
170 To implement the SPP protocol I used a Bluetooth sniffing tool called [PacketLogger](http://www.tkjelectronics.com/uploads/PacketLogger.zip) developed by Apple.
171 It enables me to see the Bluetooth communication between my Mac and any device.
172 
173 ### PS4 Library
174 
175 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.
176 
177 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.
178 
179 Before you can use the PS4 controller via Bluetooth you will need to pair with it.
180 
181 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 pairing mode.
182 
183 It should then automatically pair the dongle with your controller. This only have to be done once.
184 
185 For information see the following blog post: <http://blog.tkjelectronics.dk/2014/01/ps4-controller-now-supported-by-the-usb-host-library/>.
186 
187 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>.
188 
189 Several guides on how to use the PS4 library has been written by Dr. James E. Barger and are available at the following link: <https://sites.google.com/view/vbatc-engineeringtechnology2/control-system-tutorials/ps4-tutorials>.
190 
191 ### PS3 Library
192 
193 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.
194 
195 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.
196 
197 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.
198 
199 __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).
200 
201 For more information about the PS3 protocol see the official wiki: <https://github.com/felis/USB_Host_Shield_2.0/wiki/PS3-Information>.
202 
203 Also take a look at the blog posts:
204 
205 * <http://blog.tkjelectronics.dk/2012/01/ps3-controller-bt-library-for-arduino/>
206 * <http://chome.nerpa.tech/mcu/sony-ps3-controller-support-added-to-usb-host-library>
207 * <http://chome.nerpa.tech/mcu/arduino/interfacing-ps3-controllers-via-usb>
208 
209 A special thanks go to the following people:
210 
211 1. _Richard Ibbotson_ who made this excellent guide: <http://chome.nerpa.tech/mcu/ps3-and-wiimote-game-controllers-on-the-arduino-host-shield-part>
212 2. _Tomoyuki Tanaka_ for releasing his code for the Arduino USB Host shield connected to the wiimote: <http://chome.nerpa.tech/mcu/rc-car-controlled-by-wii-remote-on-arduino>
213 
214 Also a big thanks all the people behind these sites about the Motion controller:
215 
216 * <http://thp.io/2010/psmove/>
217 * <http://www.copenhagengamecollective.org/unimove/>
218 * <https://github.com/thp/psmoveapi>
219 * <http://code.google.com/p/moveonpc/>
220 
221 ### Xbox Libraries
222 
223 The library supports both the original Xbox controller via USB and the Xbox 360 controller both via USB and wirelessly.
224 
225 #### Xbox library
226 
227 The [XBOXOLD](XBOXOLD.cpp) class implements support for the original Xbox controller via USB.
228 
229 All the information are from the following sites:
230 
231 * <https://github.com/torvalds/linux/blob/master/Documentation/input/xpad.txt>
232 * <https://github.com/torvalds/linux/blob/master/drivers/input/joystick/xpad.c>
233 * <http://euc.jp/periphs/xbox-controller.ja.html>
234 * <https://github.com/Grumbel/xboxdrv/blob/master/PROTOCOL#L15>
235 
236 #### Xbox 360 Library
237 
238 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).
239 
240 To use it via USB use the [XBOXUSB](XBOXUSB.cpp) library or to use it wirelessly use the [XBOXRECV](XBOXRECV.cpp) library.
241 
242 __Note that a Wireless controller can NOT be used via USB!__
243 
244 Examples code can be found in the [examples directory](examples/Xbox).
245 
246 Also see the following blog posts:
247 
248 * <http://chome.nerpa.tech/mcu/xbox360-controller-support-added-to-usb-host-shield-2-0-library>
249 * <http://blog.tkjelectronics.dk/2012/07/xbox-360-controller-support-added-to-the-usb-host-library/>
250 * <http://blog.tkjelectronics.dk/2012/12/xbox-360-receiver-added-to-the-usb-host-library/>
251 
252 All the information regarding the Xbox 360 controller protocol are form these sites:
253 
254 * <http://tattiebogle.net/index.php/ProjectRoot/Xbox360Controller/UsbInfo>
255 * <http://tattiebogle.net/index.php/ProjectRoot/Xbox360Controller/WirelessUsbInfo>
256 * <https://github.com/Grumbel/xboxdrv/blob/master/PROTOCOL>
257 
258 #### Xbox ONE Library
259 
260 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:
261 
262 * <https://github.com/quantus/xbox-one-controller-protocol>
263 * <https://github.com/torvalds/linux/blob/master/drivers/input/joystick/xpad.c>
264 * <https://github.com/kylelemons/xbox/blob/master/xbox.go>
265 
266 ### [Wii library](Wii.cpp)
267 
268 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.
269 
270 First you have to pair with the controller, this is done automatically by the library if you create the instance like so:
271 
272 ```C++
273 WII Wii(&Btd, PAIR);
274 ```
275 
276 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.
277 
278 After that you can simply create the instance like so:
279 
280 ```C++
281 WII Wii(&Btd);
282 ```
283 
284 Then just press any button on the Wiimote and it will then connect to the dongle.
285 
286 Take a look at the example for more information: [Wii.ino](examples/Bluetooth/Wii/Wii.ino).
287 
288 Also take a look at the blog post:
289 
290 * <http://blog.tkjelectronics.dk/2012/08/wiimote-added-to-usb-host-library/>
291 
292 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).
293 
294 The [WiiIRCamera.ino](examples/Bluetooth/WiiIRCamera/WiiIRCamera.ino) example shows how it can be used.
295 
296 All the information about the Wii controllers are from these sites:
297 
298 * <http://wiibrew.org/wiki/Wiimote>
299 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers>
300 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Nunchuck>
301 * <http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Wii_Motion_Plus>
302 * <http://wiibrew.org/wiki/Wii_Balance_Board>
303 * The old library created by _Tomoyuki Tanaka_: <https://github.com/moyuchin/WiiRemote_on_Arduino> also helped a lot.
304 
305 ### [PS Buzz Library](PSBuzz.cpp)
306 
307 This library implements support for the Playstation Buzz controllers via USB.
308 
309 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.
310 
311 The example [PSBuzz.ino](examples/PSBuzz/PSBuzz.ino) shows how one can do this with just a few lines of code.
312 
313 More information about the controller can be found at the following sites:
314 
315 * http://www.developerfusion.com/article/84338/making-usb-c-friendly/
316 * https://github.com/torvalds/linux/blob/master/drivers/hid/hid-sony.c
317 
318 ### HID Libraries
319 
320 HID 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).
321 
322 ### [MIDI Library](usbh_midi.cpp)
323 
324 The library support MIDI devices.
325 You can convert USB MIDI keyboard to legacy serial MIDI.
326 
327 * [USB_MIDI_converter.ino](examples/USBH_MIDI/USB_MIDI_converter/USB_MIDI_converter.ino)
328 * [USB_MIDI_converter_multi.ino](examples/USBH_MIDI/USB_MIDI_converter_multi/USB_MIDI_converter_multi.ino)
329 
330 For information see the following page: <http://yuuichiakagawa.github.io/USBH_MIDI/>.
331 
332 # Interface modifications
333 
334 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.
335 
336 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!
337 
338 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.
339 
340 After that you need modify the following entry in [UsbCore.h](UsbCore.h):
341 
342 ```C++
343 typedef MAX3421e<P10, P9> MAX3421E;
344 ```
345 
346 For instance if you have rerouted SS to pin 7 it should read:
347 
348 ```C++
349 typedef MAX3421e<P7, P9> MAX3421E;
350 ```
351 
352 See the "Interface modifications" section in the [hardware manual](https://chome.nerpa.tech/usb-host-shield-hardware-manual) for more information.
353 
354 # FAQ
355 
356 > When I plug my device into the USB connector nothing happens?
357 
358 * Try to connect a external power supply to the Arduino - this solves the problem in most cases.
359 * 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);```.
360 
361 > When I connecting my PS3 controller I get a output like this:
362 
363 ```
364 Dualshock 3 Controller Enabled
365 
366 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
367 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
368 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
369 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
370 LeftHatX: 0 LeftHatY: 0 RightHatX: 0 RightHatY: 0
371 ```
372 
373 * 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.
374 
375 > When compiling I am getting the following error: "fatal error: SPI.h: No such file or directory".
376 
377 * Please make sure to include the SPI library like so: ```#include <SPI.h>``` in your .ino file.
Generated by   diff --git a/index.html b/index.html index 8d7caecc..2da626ce 100644 --- a/index.html +++ b/index.html @@ -257,12 +257,12 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search');

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. -
  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
    3. +
  3. Richard Ibbotson who made this excellent guide: http://chome.nerpa.tech/mcu/ps3-and-wiimote-game-controllers-on-the-arduino-host-shield-part
    4. +
  4. Tomoyuki Tanaka for releasing his code for the Arduino USB Host shield connected to the wiimote: http://chome.nerpa.tech/mcu/rc-car-controlled-by-wii-remote-on-arduino

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