xref: /aosp_15_r20/external/libusb/android/README (revision 86b64dcb59b3a0b37502ecd56e119234366a6f7e) 
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
51Runtime Permissions:
52--------------------
53
54The Runtime Permissions on Android can be transferred from Java to Native
55over the following approach:
56
57  JAVA:
58
59   --> Obtain USB permissions over the android.hardware.usb.UsbManager class
60
61      usbManager = (UsbManager) getSystemService(Context.USB_SERVICE);
62      HashMap<String, UsbDevice> deviceList = usbManager.getDeviceList();
63      for (UsbDevice usbDevice : deviceList.values()) {
64          usbManager.requestPermission(usbDevice, mPermissionIntent);
65      }
66
67   --> Get the native FileDescriptor of the UsbDevice and transfer it to
68       Native over JNI or JNA
69
70      UsbDeviceConnection usbDeviceConnection = usbManager.openDevice(camDevice);
71      int fileDescriptor = usbDeviceConnection.getFileDescriptor();
72
73   --> JNA sample method:
74
75      JNA.INSTANCE.set_the_native_Descriptor(fileDescriptor);
76
77  NATIVE:
78
79   --> Initialize libusb on Android
80
81      set_the_native_Descriptor(int fileDescriptor) {
82          libusb_context *ctx;
83          libusb_device_handle *devh;
84          libusb_set_option(&ctx, LIBUSB_OPTION_NO_DEVICE_DISCOVERY, NULL);
85          libusb_init(&ctx);
86          libusb_wrap_sys_device(NULL, (intptr_t)fileDescriptor, &devh);
87      }
88      /* From this point you can regularly use all libusb functions as usual */
89
90   About LIBUSB_OPTION_NO_DEVICE_DISCOVERY:
91
92    The method libusb_set_option(&ctx, LIBUSB_OPTION_NO_DEVICE_DISCOVERY, NULL)
93    does not affect the ctx.
94    It allows initializing libusb on unrooted Android devices by skipping
95    the device enumeration.
96
97Rooted Devices:
98---------------
99
100    For rooted devices the code using libusb could be executed as root
101    using the "su" command. An alternative would be to use the "su" command
102    to change the permissions on the appropriate /dev/bus/usb/ files.
103
104    Users have reported success in using android.hardware.usb.UsbManager
105    to request permission to use the UsbDevice and then opening the
106    device. The difficulties in this method is that there is no guarantee
107    that it will continue to work in the future Android versions, it
108    requires invoking Java APIs and running code to match each
109    android.hardware.usb.UsbDevice to a libusb_device.
110
111    For a rooted device it is possible to install libusb into the system
112    image of a running device:
113
114     1. Enable ADB on the device.
115
116     2. Connect the device to a machine running ADB.
117
118     3. Execute the following commands on the machine
119        running ADB:
120
121        # Make the system partition writable
122        adb shell su -c "mount -o remount,rw /system"
123
124        # Install libusb
125        adb push obj/local/armeabi/libusb1.0.so /sdcard/
126        adb shell su -c "cat > /system/lib/libusb1.0.so < /sdcard/libusb1.0.so"
127        adb shell rm /sdcard/libusb1.0.so
128
129        # Install the samples and tests
130        for B in listdevs fxload xusb sam3u_benchmark hotplugtest stress
131        do
132          adb push "obj/local/armeabi/$B" /sdcard/
133          adb shell su -c "cat > /system/bin/$B < /sdcard/$B"
134          adb shell su -c "chmod 0755 /system/bin/$B"
135          adb shell rm "/sdcard/$B"
136        done
137
138        # Make the system partition read only again
139        adb shell su -c "mount -o remount,ro /system"
140
141        # Run listdevs to
142        adb shell su -c "listdevs"
143
144     4. If your device only has a single OTG port then ADB can generally
145        be switched to using Wifi with the following commands when connected
146        via USB:
147
148        adb shell netcfg
149        # Note the wifi IP address of the phone
150        adb tcpip 5555
151        # Use the IP address from netcfg
152        adb connect 192.168.1.123:5555
153