Update Android Readme

Add another approach for connecting USB devices on Android.

References #830
Closes #996

1 files changed, 90 insertions, 54 deletions

diff --git a/android/README b/android/README
index 32024ef..9534036 100644
--- a/android/README
+++ b/android/README
@@ -48,69 +48,105 @@ application package (APK) file, provided ndk-build is invoked before
 the package is built.
 
 
-For a rooted device it is possible to install libusb into the system
-image of a running device:
+Runtime Permissions:
+--------------------
 
- 1. Enable ADB on the device.
+The Runtime Permissions on Android can be transfered from Java to Native
+over the following approach:
 
- 2. Connect the device to a machine running ADB.
+  JAVA:
 
- 3. Execute the following commands on the machine
-    running ADB:
+   --> Obtain USB permissions over the android.hardware.usb.UsbManager class
 
-    # Make the system partition writable
-    adb shell su -c "mount -o remount,rw /system"
+      usbManager = (UsbManager) getSystemService(Context.USB_SERVICE);
+      HashMap<String, UsbDevice> deviceList = usbManager.getDeviceList();
+      for (UsbDevice usbDevice : deviceList.values()) {
+          usbManager.requestPermission(usbDevice, mPermissionIntent);
+      }
 
-    # Install libusb
-    adb push obj/local/armeabi/libusb1.0.so /sdcard/
-    adb shell su -c "cat > /system/lib/libusb1.0.so < /sdcard/libusb1.0.so"
-    adb shell rm /sdcard/libusb1.0.so
+   --> Get the native FileDescriptor of the UsbDevice and transfer it to
+       Native over JNI or JNA
 
-    # Install the samples and tests
-    for B in listdevs fxload xusb sam3u_benchmark hotplugtest stress
-    do
-      adb push "obj/local/armeabi/$B" /sdcard/
-      adb shell su -c "cat > /system/bin/$B < /sdcard/$B"
-      adb shell su -c "chmod 0755 /system/bin/$B"
-      adb shell rm "/sdcard/$B"
-    done
+      UsbDeviceConnection usbDeviceConnection = usbManager.openDevice(camDevice);
+      int fileDescriptor = usbDeviceConnection.getFileDescriptor();
 
-    # Make the system partition read only again
-    adb shell su -c "mount -o remount,ro /system"
+   --> JNA sample method:
 
-    # Run listdevs to
-    adb shell su -c "listdevs"
+      JNA.INSTANCE.set_the_native_Descriptor(fileDescriptor);
 
- 4. If your device only has a single OTG port then ADB can generally
-    be switched to using Wifi with the following commands when connected
-    via USB:
+  NATIVE:
 
-    adb shell netcfg
-    # Note the wifi IP address of the phone
-    adb tcpip 5555
-    # Use the IP address from netcfg
-    adb connect 192.168.1.123:5555
+   --> Initialize libusb on Android
 
-Runtime Permissions:
---------------------
+      set_the_native_Descriptor(int fileDescriptor) {
+          libusb_context *ctx;
+          libusb_device_handle *devh;
+          libusb_set_option(&ctx, LIBUSB_OPTION_NO_DEVICE_DISCOVERY, NULL);
+          libusb_init(&ctx);
+          libusb_wrap_sys_device(NULL, (intptr_t)fileDescriptor, &devh);
+      }
+      /* From this point you can regulary use all libusb functions as usual */
+
+   About LIBUSB_OPTION_NO_DEVICE_DISCOVERY:
+
+    The method libusb_set_option(&ctx, LIBUSB_OPTION_NO_DEVICE_DISCOVERY, NULL)
+    does not affect the ctx.
+    It allows initializing libusb on unrooted Android devices by skipping
+    the device enumeration.
+
+Rooted Devices:
+---------------
+
+    For rooted devices the code using libusb could be executed as root
+    using the "su" command. An alternative would be to use the "su" command
+    to change the permissions on the appropriate /dev/bus/usb/ files.
+
+    Users have reported success in using android.hardware.usb.UsbManager
+    to request permission to use the UsbDevice and then opening the
+    device. The difficulties in this method is that there is no guarantee
+    that it will continue to work in the future Android versions, it
+    requires invoking Java APIs and running code to match each
+    android.hardware.usb.UsbDevice to a libusb_device.
+
+    For a rooted device it is possible to install libusb into the system
+    image of a running device:
+
+     1. Enable ADB on the device.
+
+     2. Connect the device to a machine running ADB.
+
+     3. Execute the following commands on the machine
+        running ADB:
+
+        # Make the system partition writable
+        adb shell su -c "mount -o remount,rw /system"
+
+        # Install libusb
+        adb push obj/local/armeabi/libusb1.0.so /sdcard/
+        adb shell su -c "cat > /system/lib/libusb1.0.so < /sdcard/libusb1.0.so"
+        adb shell rm /sdcard/libusb1.0.so
+
+        # Install the samples and tests
+        for B in listdevs fxload xusb sam3u_benchmark hotplugtest stress
+        do
+          adb push "obj/local/armeabi/$B" /sdcard/
+          adb shell su -c "cat > /system/bin/$B < /sdcard/$B"
+          adb shell su -c "chmod 0755 /system/bin/$B"
+          adb shell rm "/sdcard/$B"
+        done
+
+        # Make the system partition read only again
+        adb shell su -c "mount -o remount,ro /system"
+
+        # Run listdevs to
+        adb shell su -c "listdevs"
+
+     4. If your device only has a single OTG port then ADB can generally
+        be switched to using Wifi with the following commands when connected
+        via USB:
 
-The default system configuration on most Android device will not allow
-access to USB devices. There are several options for changing this.
-
-If you have control of the system image then you can modify the
-ueventd.rc used in the image to change the permissions on
-/dev/bus/usb/*/*. If using this approach then it is advisable to
-create a new Android permission to protect access to these files.
-It is not advisable to give all applications read and write permissions
-to these files.
-
-For rooted devices the code using libusb could be executed as root
-using the "su" command. An alternative would be to use the "su" command
-to change the permissions on the appropriate /dev/bus/usb/ files.
-
-Users have reported success in using android.hardware.usb.UsbManager
-to request permission to use the UsbDevice and then opening the
-device. The difficulties in this method is that there is no guarantee
-that it will continue to work in the future Android versions, it
-requires invoking Java APIs and running code to match each
-android.hardware.usb.UsbDevice to a libusb_device.
+        adb shell netcfg
+        # Note the wifi IP address of the phone
+        adb tcpip 5555
+        # Use the IP address from netcfg
+        adb connect 192.168.1.123:5555