1libusb for Android
2==================
3
4Building:
5---------
6
7To build libusb for Android do the following:
8
9 1. Download the latest NDK from:
10    http://developer.android.com/tools/sdk/ndk/index.html
11
12 2. Extract the NDK.
13
14 3. Open a shell and make sure there exist an NDK global variable
15    set to the directory where you extracted the NDK.
16
17 4. Change directory to libusb's "android/jni"
18
19 5. Run "$NDK/ndk-build".
20
21The libusb library, examples and tests can then be found in:
22    "android/libs/$ARCH"
23
24Where $ARCH is one of:
25    armeabi
26    armeabi-v7a
27    mips
28    mips64
29    x86
30    x86_64
31
32Installing:
33-----------
34
35If you wish to use libusb from native code in own Android application
36then you should add the following line to your Android.mk file:
37
38  include $(PATH_TO_LIBUSB_SRC)/android/jni/libusb.mk
39
40You will then need to add the following lines to the build
41configuration for each native binary which uses libusb:
42
43  LOCAL_C_INCLUDES += $(LIBUSB_ROOT_ABS)
44  LOCAL_SHARED_LIBRARIES += libusb1.0
45
46The Android build system will then correctly include libusb in the
47application package (APK) file, provided ndk-build is invoked before
48the package is built.
49
50
51For a rooted device it is possible to install libusb into the system
52image of a running device:
53
54 1. Enable ADB on the device.
55
56 2. Connect the device to a machine running ADB.
57
58 3. Execute the following commands on the machine
59    running ADB:
60
61    # Make the system partition writable
62    adb shell su -c "mount -o remount,rw /system"
63
64    # Install libusb
65    adb push obj/local/armeabi/libusb1.0.so /sdcard/
66    adb shell su -c "cat > /system/lib/libusb1.0.so < /sdcard/libusb1.0.so"
67    adb shell rm /sdcard/libusb1.0.so
68
69    # Install the samples and tests
70    for B in listdevs fxload xusb sam3u_benchmark hotplugtest stress
71    do
72      adb push "obj/local/armeabi/$B" /sdcard/
73      adb shell su -c "cat > /system/bin/$B < /sdcard/$B"
74      adb shell su -c "chmod 0755 /system/bin/$B"
75      adb shell rm "/sdcard/$B"
76    done
77
78    # Make the system partition read only again
79    adb shell su -c "mount -o remount,ro /system"
80
81    # Run listdevs to
82    adb shell su -c "listdevs"
83
84 4. If your device only has a single OTG port then ADB can generally
85    be switched to using Wifi with the following commands when connected
86    via USB:
87
88    adb shell netcfg
89    # Note the wifi IP address of the phone
90    adb tcpip 5555
91    # Use the IP address from netcfg
92    adb connect 192.168.1.123:5555
93
94Runtime Permissions:
95--------------------
96
97The default system configuration on most Android device will not allow
98access to USB devices. There are several options for changing this.
99
100If you have control of the system image then you can modify the
101ueventd.rc used in the image to change the permissions on
102/dev/bus/usb/*/*. If using this approach then it is advisable to
103create a new Android permission to protect access to these files.
104It is not advisable to give all applications read and write permissions
105to these files.
106
107For rooted devices the code using libusb could be executed as root
108using the "su" command. An alternative would be to use the "su" command
109to change the permissions on the appropriate /dev/bus/usb/ files.
110
111Users have reported success in using android.hardware.usb.UsbManager
112to request permission to use the UsbDevice and then opening the
113device. The difficulties in this method is that there is no guarantee
114that it will continue to work in the future Android versions, it
115requires invoking Java APIs and running code to match each
116android.hardware.usb.UsbDevice to a libusb_device.
117