android/README

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